activity-core/SCOPE.md

domain, repo, updated

domain	repo	updated
capabilities	activity-core	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

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]