activity-core/SCOPE.md

domain, repo, updated

domain	repo	updated
capabilities	activity-core	2026-06-03

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not.

---

One-liner

activity-core is the org-wide Event Bridge for the Coulomb organization — a rule-governed event loop that receives time-based and domain events, evaluates declarative rules and LLM instructions against current org context, and emits structured task sets to issue-core.

---

Core Idea

An ActivityDefinition (a markdown file checked into a repo) declares a trigger (cron, one-off scheduled datetime, or named event type), context sources to resolve before evaluation, and a set of rules and instructions that determine what tasks to create. When triggered, a durable Temporal workflow loads the definition, resolves context, evaluates the rule/instruction set, and emits task creation requests to issue-core. Everything is auditable: the spawn log records the triggering event, matched rule, and resulting task references.

The two evaluation modes:

• Rule — deterministic condition (sandboxed Python-like DSL) → fixed task templates. Fast, testable, no LLM cost.
• Instruction — optional pre-filter condition → LLM prompt with trusted fields only → structured task list. For cases where the right tasks depend on context that is easier to describe than to enumerate.

---

In Scope

• ActivityDefinition model: trigger config (cron / scheduled / event), context sources, rules (condition + action), instructions (trusted-field prompt + model + output schema).
• Event type registry: publisher-declared markdown definitions with attribute schemas, example payloads, and intent documentation. Curator-gating configurable per runtime environment.
• Trigger types: 5-field cron with timezone and misfire policy; one-off scheduled datetime; event-type subscription via NATS.
• Context resolution adapters: repo-scoping (repository capability queries), state hub (domain and workstream state), extensible for other sources.
• Rule evaluator: sandboxed AST walker for Python-like boolean expressions over event attributes and resolved context. Rule actions support safe context.* / event.* interpolation and explicit for_each per-item binding. No exec().
• Instruction executor: trusted-field prompt rendering, LLM call via llm-connect, structured output validation, optional curator review queue, and deterministic report sinks.
• Task emission adapter: abstraction over issue-core; current transport is REST; designed to migrate to NATS subscription without code changes.
• Report sinks: instruction report outputs can be persisted to bounded local working memory and posted as State Hub progress events. These are reporting outputs, not task lifecycle ownership.
• Spawn audit log: every task emission recorded with rule/instruction id, triggering event id, model and prompt hash (instructions), issue-core task ref.
• Webhook receiver: HTTP endpoint normalising inbound Gitea/GitHub webhook payloads to EventEnvelope format and publishing to NATS.
• Worker and workflow infrastructure: Temporal-based durable execution — RunActivityWorkflow orchestrates load → resolve → evaluate → emit.
• REST admin API (FastAPI): CRUD for ActivityDefinitions, manual trigger, event type registry queries.
• Prometheus metrics: Temporal SDK metrics exposed for scraping.
• Operational runbook: docs/runbook.md.

---

Out of Scope

• Task lifecycle — creating, assigning, tracking, and closing tasks is issue-core's responsibility. activity-core holds a spawn audit trail only.
• Project and initiative management — phased, completion-gated, multi-step coordinated changes belong to project-core (future).
• Execution of automatable tasks — Temporal Activities that do real work (run a scan, apply a patch, call an API) live in per-repo workers, not here.
• Event broker hosting — NATS JetStream is org infrastructure; activity-core consumes it but does not own its lifecycle.
• Temporal server hosting — activity-core uses the Temporal SDK; the server runs on Railiance infrastructure (or Docker Compose for dev).
• End-user task UI — tasks land in issue-core; presentation is separate.
• Synchronous request-response patterns — Temporal is async-first.

---

Relevant When

• You need org-wide recurring maintenance automation (dependency scans, SBOM checks, staleness audits) without bespoke per-service cron jobs.
• You need reactive task generation: "when X happens across the org, create structured tasks in the right repos."
• You need one-off future task scheduling without a separate reminder system.
• You want an auditable record of what triggered what and why.
• You are replacing scattered bespoke cron jobs and manual coordination with a governed, observable automation layer.

---

Not Relevant When

• You need to track whether a task is done, blocked, or reassigned → issue-core.
• You need to coordinate a multi-phase project with dependencies → project-core.
• You need a simple system cron with no durability requirement.
• You need synchronous request-response patterns.

---

Current State

• Status: active production-backed service. Foundation, triggers/ops, event bridge, Railiance deployment, and the production service workplans are complete. The stale March WP-0002 handoff note has been reconciled and archived.
• Implementation: core is functional. RunActivityWorkflow, TaskExecutorWorkflow (stub), PostgreSQL schema, Temporal Schedules, NATS Event Router, FastAPI admin API, Prometheus metrics, event type registry, markdown ActivityDefinition parser/sync, rule evaluator, instruction executor, context resolvers, issue sink, report sinks, Kubernetes deployment, and operational runbook are all implemented.
• Operational proof: the daily State Hub WSJF triage cutover has completed far enough that activity-core is now the trusted scheduled substrate for the routine report. Recent hardening fixed the State Hub SBOM resolver contract, made slow LLM activity timeouts configurable, and added safe rule action interpolation plus explicit for_each binding for per-repo SBOM staleness tasks.
• Stability: construction risk has shifted to operational hardening risk. The full test suite passed on 2026-06-03 (125 passed, 1 skipped). The remaining work is mostly observability, status-canon adaptation, contract documentation, and broader production adoption rather than first implementation.
• Next: ACTIVITY-WP-0006 — post-triage operational hardening and scope alignment.

---

Assessment Against Intent

activity-core now matches the core intent: it answers when coordination work should happen, what work should be created from current org context, and where each work item should land. The daily WSJF triage is the clearest judgement-oriented proof point; weekly SBOM staleness is the clearest deterministic-rule proof point.

The governing boundary still matters. activity-core should keep owning trigger durability, context resolution, rule/instruction evaluation, report/task emission, and spawn/report audit. It should not become the task lifecycle database, the project planner, or a general execution worker. The local TaskExecutorWorkflow remains a stub and should stay that way unless a future workplan explicitly rehomes execution responsibility.

One boundary nuance is now explicit: activity-core may post State Hub progress events as a configured report sink. That is acceptable because it records the result of an activity-core activation; it is not ownership of State Hub state, task lifecycle, or workstream planning.

The main drift risk is convenience creep: adding direct task tracking, project-phase state, or bespoke operational scripts because the Temporal substrate is already nearby. Future work should prefer declarative ActivityDefinitions, bounded context resolvers, and outbound adapters over new one-off control paths.

---

How It Fits

[NATS JetStream]  ←  publishers: state hub, Gitea webhooks, Temporal signals, cron
       ↓
[activity-core]   ←  event type registry, rule evaluator, instruction executor
[activity-core]   →  [issue-core]  →  [repos/services]
[activity-core]   →  [report sinks]

• Upstream: NATS (event bus), Temporal (durable workflow engine), PostgreSQL (definitions and audit log), repo-scoping (context adapter), state hub (context adapter and event publisher).
• Downstream: issue-core (task management) and configured report sinks. Agents and humans pick up tasks from issue-core and do the actual work.
• Coordinates with: the state hub delegates maintenance automations to activity-core by publishing lifecycle events or by being resolved as context. activity-core may post progress events as report outputs, but it does not own State Hub task/workstream state.

---

Terminology

• ActivityDefinition — a markdown file declaring trigger, context sources, rules, and instructions. The unit of automation policy.
• EventEnvelope — the canonical internal event format; normalises all inbound events (NATS, webhooks, cron signals) to a common structure.
• Rule — deterministic condition expression + task template action. Evaluated by a sandboxed AST walker.
• Instruction — LLM-evaluated task generation with trusted-field prompt interpolation and structured output schema enforcement.
• Event type — a registered, schema-documented category of event (e.g. org.repo.registered). Publisher-declared; curator-gated per environment.
• Spawn audit trail — activity-core's local record of what tasks were emitted, to which issue-core backend, and under which rule/instruction. Not the authoritative task record.
• Potentially confusing: Activity (Temporal concept — a single executable step in a workflow) vs. ActivityDefinition (app concept — the policy record that governs what gets spawned). These are different things.

---

Related / Overlapping

• issue-core (formerly issue-facade) — downstream task management; receives all task emission from activity-core.
• repo-scoping — context adapter for repository capability queries.
• the-custodian / state hub — context adapter for domain state; delegates maintenance automation to activity-core via NATS events.
• rules-core (future extraction) — the rule evaluator and instruction executor module, currently in src/activity_core/rules/.
• project-core (future) — project and initiative management; will use activity-core to generate per-phase task sets.
• ops-bridge — SSH tunnel to remote Temporal server on Railiance.

---

Architecture Decisions

• docs/adr/adr-001-event-bridge-architecture.md — overall Event Bridge pattern, boundaries, state hub relationship, domain assignment.
• docs/adr/adr-002-definition-format.md — markdown-as-definition format, governance model, event type schema, ActivityDefinition structure.
• docs/adr/adr-003-rule-instruction-model.md — Rule DSL, Instruction safety model, evaluation semantics, audit trail, testing strategy.

---

Getting Oriented

• Start with: INTENT.md (why), this file (what), docs/adr/ (decisions).
• Key source files: src/activity_core/models.py (domain model), src/activity_core/workflows.py (RunActivityWorkflow), src/activity_core/activities.py (Temporal activities), src/activity_core/event_router.py (NATS → Temporal), src/activity_core/schedule_manager.py (Temporal Schedules), src/activity_core/api.py (FastAPI admin).
• Definition files: event-types/, activity-definitions/, and tasks/.
• Dev environment: docker-compose.dev.yml (Temporal + PostgreSQL + NATS).
• Entry points: uv run python -m activity_core.worker (Temporal worker), uv run uvicorn activity_core.api:app --port 8010 (admin API).

---

Provided Capabilities

type: data
title: Durable event-triggered task factory
description: >
  Org-wide Event Bridge that receives time-based and domain events, evaluates
  declarative rules and LLM instructions against current org context, and emits
  structured task sets to issue-core with a full spawn audit trail.
keywords: [temporal, workflow, event-bridge, task, cron, event, rule, instruction, org-automation]