---
domain: capabilities
repo: activity-core
updated: "2026-05-14"
---

# 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. No `exec()`.
- **Instruction executor**: trusted-field prompt rendering, LLM call via
  llm-connect, structured output validation, optional curator review queue.
- **Task emission adapter**: abstraction over issue-core; current transport is
  REST; designed to migrate to NATS subscription without code changes.
- **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 — WP-0001 (Foundation) and WP-0002 (Triggers & Ops) complete.
- **Implementation**: core is functional. `RunActivityWorkflow`, `TaskExecutorWorkflow`
  (stub), PostgreSQL schema (activity_definitions, activity_runs, task_instances),
  Temporal Schedules (cron), NATS Event Router, FastAPI admin API, Prometheus
  metrics, and operational runbook are all implemented.
- **Next**: WP-0003 — event type registry, rule/instruction model, task emission
  adapter, webhook receiver, one-off `scheduled` trigger type, INTENT.md and
  SCOPE.md rewrite (this file). Architecture established in ACT-ADR-001/002/003.
- **Stability**: core workflow is stable; the rule/instruction layer and registry
  are not yet implemented.

---

## How It Fits

```
[NATS JetStream]  ←  publishers: state hub, Gitea webhooks, Temporal signals, cron
       ↓
[activity-core]   ←  event type registry, rule evaluator, instruction executor
       ↓
[issue-core]      ←  task lifecycle, assignment, tracking (Gitea / SQLite / GitHub)
       ↓
[repos/services]  ←  execution: actual code changes, scans, operations
```

- **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). 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; activity-core never writes to
  the state hub directly.

---

## 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 (WP-0003): `event-types/` and `activity-definitions/`
  (not yet created — coming in WP-0003).
- 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

```capability
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]
```