generated from coulomb/repo-seed
tegwick
30598fd1ad
Add safe action interpolation and for_each binding for rule fan-out, update the weekly SBOM definition, cover the new evaluation path, and reconcile activity-core scope/workplans for the State Hub sync.
270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
---
|
|
domain: capabilities
|
|
repo: activity-core
|
|
updated: "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
|
|
|
|
```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]
|
|
```
|