activity-core/SCOPE.md

domain	repo	updated
capabilities	activity-core	2026-08-23

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, report, and evidence outputs without owning downstream task lifecycle.

---

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 work or evidence to produce. When triggered, a durable Temporal workflow loads the definition, resolves context, evaluates the rule/instruction set, and emits outputs via configured sinks:

• Coordination outputs — task specs through IssueSink (rest → issue-core, state-hub progress, or null dry-run), plus claimable ops_runs for automation executors when the queue is enabled.
• Reports — instruction reports to working memory and/or State Hub progress.
• Evidence — compact non-secret summaries from selected resolvers (ops inventory, package prune, legacy-meter, etc.).

Everything is auditable at the orchestration boundary: activity_runs records the activation and context snapshot; task_spawn_log records emission facts; ops_runs records claim/lease/outcome evidence; report sinks leave progress/working-memory artifacts. LLM audit stores the model and prompt hash, not raw prompts or provider payloads.

The two evaluation modes:

• Rule — deterministic condition (sandboxed Python-like DSL) → fixed task templates. Fast, testable, no LLM cost.
• Instruction — optional pre-filter → LLM or deterministic report path (model: deterministic / none / unused) → structured tasks and/or reports. LLM reserved for genuine judgement; deterministic for pure context summaries.

---

In Scope

• ActivityDefinition model: trigger config (cron / scheduled / event), context sources, rules (condition + action), instructions (trusted-field prompt + model + output schema + report sinks).
• 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; manual one-shot API trigger; one-shot schedule smoke tests for recurring definitions.
• Schedule reconcile: Temporal Schedule upsert/pause with per-row error isolation (sync_schedules continues after ScheduleAlreadyRunningError).
• Context resolution adapters: repo-scoping, State Hub, hub-core, reuse-surface, event payloads, Kaizen agent metadata, SBOM Nexus, shell queries, CNPG backup, Forgejo package prune, and ops inventory probes. The resolver registry is extensible.
• Rule evaluator: sandboxed AST walker; for_each binding; no exec().
• Instruction executor: trusted-field rendering, llm-connect, structured validation, item-granular recovery, deterministic report path, report sinks.
• Task emission adapter: IssueCoreRestSink, StateHubProgressSink, NullSink selected by ISSUE_SINK_TYPE. Production railiance01 currently uses state-hub as the safe default for internal findings (see ACTIVITY-WP-0021/0022); restore rest only when issue-core→Forgejo is healthy and policy allows external issues.
• Report / evidence sinks: working memory, State Hub progress (daily_triage, sbom_staleness, forgejo_package_prune, ops_inventory_probe, activity_task_spawn, etc.).
• Spawn audit log: task_spawn_log with rule/instruction id and sink ref.
• Automation execution queue: durable ops_runs with idempotent insertion, concurrent claim (FOR UPDATE SKIP LOCKED), leases, heartbeat, retry/reopen, terminal outcome, and operator visibility. This is machine-run delivery state, not the authoritative lifecycle of a workplan task or tracker issue.
• Profile-driven execution contract: structurally validate a pinned harness_profile_ref, pass through allowlisted attribution refs, and retain normalized non-secret Glas execution evidence. Glas selects the rein/model/ sandbox constellation; activity-core does not.
• Webhook receiver: Gitea/GitHub → EventEnvelope → NATS, with HMAC verification when the corresponding shared secret is configured.
• Worker and workflow infrastructure: Temporal RunActivityWorkflow (load → resolve → evaluate → report → log_run → emit). Emit failures no longer skip activity_runs rows.
• REST admin API (FastAPI): basic ActivityDefinition row CRUD, manual trigger, admin sync, event-type approval, and dependency health. Full rules/instructions authoring remains markdown-and-sync driven; the row CRUD schema is not a complete replacement for the file format.
• Operator automation console (ACTIVITY-WP-0024): /ops inventory, status window, run history, Run now / enable / disable / pause with operator-token auth (fail-closed), plus thin HTML UI at /ops/ui.
• Automation status surface: make automation-status and make prod-automation-status / scripts/prod_automation_status.sh for railiance01 evidence without LLM authority (same contract as /ops/automations/status).
• Review CLI: the activity command merges repository commits with activity/ops-run evidence across configured services, supports checkpoints, and reports automation definitions and recent runs. It is an evidence review client, not a task tracker.
• Operational runbook: docs/runbook.md, emission boundary docs.

---

Out of Scope

• Task lifecycle — create/assign/track/close remains issue-core (or fleet work-record connectors). activity-core holds spawn evidence and machine-run delivery state, not the authoritative human/work-item record.
• Project and initiative management — project-core (future).
• General execution workers — agent loops, repository changes, arbitrary scans, and privileged API writes belong to Glas/reins, per-repo workers, or platform tools. The ops_run API dispatches and observes this work; it does not perform it.
• General ops control plane — Kubernetes, SSH, tunnels, secret custody, OpenBao policy administration.
• Event broker / Temporal server hosting — consume, do not own lifecycle.
• End-user task UI — tracking human work items. The operator automation console (/ops) is in scope; it manages ActivityDefinitions and schedules, not task lifecycle.
• Coding assistant schedulers as production authority.

Boundary note (ACT-ADR-007): Context resolution is read-only. A small code-owned registry permits explicit bounded operations (currently controlled SBOM ingest, Forgejo package prune, and CNPG backup) in a separate workflow phase. Unknown operations or incomplete mutation/evidence declarations are not an extension mechanism and must fail definition admission.

---

Relevant When

• Org-wide recurring maintenance (SBOM, package prune, legacy-meter, Binky rhythm, consistency sweeps) without bespoke per-service cron.
• Reactive task/report generation from org events and context.
• One-off future scheduling.
• Auditable activation history (runs, spawn log, progress).
• Answering “how did automations go since Sunday?” from deterministic repo-native / prod evidence.

Not Relevant When

• Tracking task completion/reassignment → issue-core / work records.
• Multi-phase project orchestration → project-core.
• Simple host cron with no durability or evidence needs.

---

Current State (2026-08-23)

Status

Production runs on railiance01 in the activity-core namespace with PostgreSQL, Temporal Schedules, a Temporal worker, API, and NATS event router. The checked-in surface contains 12 ActivityDefinitions plus publisher-declared event types. The schema is at migration 0008, including the ops-run queue and Glas profile/attribution fields.

No open task is independently actionable on 2026-08-23:

Workplan	State	Current gate
ACTIVITY-WP-0031	wait	OpenRouter account owner must replace the rejected provider key; external routing handoffs remain with their named owners
ACTIVITY-WP-0032	wait	GLAS-IN-0002: managed consumer namespace plus rein/model runtime and egress contract before a successful commit proof
ACTIVITY-WP-0034	progress	Observe the first unassisted weekday controlled-source SBOM fire; do not substitute another manual trigger

Live posture (railiance01)

• Image: activity-core:railiance01-prod (locally built/imported deployment).
• ISSUE_SINK_TYPE=state-hub (internal findings → State Hub progress, not Forgejo issues).
• The daily SBOM catch-up is enabled at weekday 09:15 Europe/Berlin, limit 3. It freezes Repo Manager's full-SHA forgejo-archive-v1 source reference, reuses it across Nexus retries, and reports only allowlisted provenance.
• The old weekly SBOM fan-out is disabled in source, DB, and Temporal.
• ops_runs are claimable by rein-aharness and carry pinned Glas profile refs; production has proven normalized fail-closed evidence and sandbox teardown, but not yet a successful profiled commit.
• Weekly prune: worker has FORGEJO_TOKEN + hostPath /opt/railiance-platform
  • live_images_file (kubectl absent in pod).
• The deterministic status surface distinguishes schedule fires, emitted tasks, ops-run states, and bounded failures.

Definitions (repo files + prod DB)

Definition	Role
daily-sbom-catchup	Bounded oldest-N Nexus ingestion with immutable controlled source refs
weekly-sbom-staleness	Disabled legacy fan-out; retained as deterministic report definition
weekly-forgejo-package-prune	Sunday 03:30 UTC apply prune + evidence
weekly-legacy-meter-review / legacy-meter-8h-capture	Meter evidence
weekly-coding-retro	Present; enablement depends on coding_retro feed
Binky daily / mail / review-prep	Rhythm tasks via IssueSink
daily-cnpg-option-a-backup	Declared bounded CNPG backup plus evidence
monthly-secrets-elevation-review	Scheduled governance review task
glas-profile-pilot	Disabled low-risk profile-contract proof definition

Task emission posture

• Canonical REST sink to issue-core remains implemented and documented.
• Production default is state-hub after Forgejo PAT/backend failures and fleet policy against silent Forgejo issues (WP-0021 path B, WP-0022).
• Restoring rest requires healthy issue-core→Forgejo and explicit policy opt-in per definition.

---

Assessment Against Intent

The detailed review is preserved in history/2026-08-23-scope-against-intent-assessment.md.

Alignment

INTENT promise	Status
Answers when / what / where	Met — Temporal schedules/NATS/webhooks, rules/instructions, and explicit sinks/targets
Markdown definitions	Met — activity-definitions/, event-types, external ConfigMaps
Rules before instructions	Met — deterministic rule/report paths dominate; LLM is optional
Durable recurring automation	Met — Temporal schedules plus deterministic status evidence
Audit trail	Met as a bounded, non-secret audit projection — activation, definition/version, context projection, prompt hash/model, validation, emission, queue, and normalized execution evidence; raw prompts/provider payloads are intentionally absent
Does not own task lifecycle	Met — ops_run claim/lease/outcome state is runtime delivery state, not work-item lifecycle
Does not own project phases	Met

Gaps and tensions (INTENT ↔ practice)

Gap	Severity	Notes
G3. Live LLM execution	High (operational, external)	The implementation is present, but production provider requests fail with a sanitized upstream 401 until the account owner replaces the key.
G4. Profiled execution proof	Medium (operational, external)	Profile selection, failure evidence, and teardown are proven; a successful commit waits on GLAS-IN-0002.
G5. State Hub retirement	Medium (integration)	hub-core adapters exist, but production task/report progress still defaults to the State Hub compatibility path.
G6. Definition REST parity	Low	Basic REST row administration intentionally cannot author or round-trip full rules/instructions; markdown source sync is authoritative.

Drift risks

1. Convenience execution — growing the bounded side-effect allowlist into a general ops runner.
2. Silent sink restore — flipping ISSUE_SINK_TYPE=rest without policy + healthy Forgejo backend reintroduces issue spam / 503s.
3. Protection file staleness — weekly prune with apply: true depends on fresh live-image lists.
4. Queue/task conflation — treating an ops_run as the authoritative human task record rather than a delivery instance.

---

How It Fits

[NATS JetStream / Temporal Schedules / manual trigger]
       ↓
[activity-core]  Event type registry · rules · instructions · context resolvers
       ↓
[IssueSink: rest | state-hub | null]  →  issue-core  or  hub-core progress (State Hub until cutover)
[report/evidence sinks]               →  hub-core / working memory
[ops_run claim queue + Glas profile]  →  rein-aharness / other approved reins
[bounded operation stage]             →  code-registered platform tools

• Upstream: NATS, Temporal, PostgreSQL, repo-manager / hub-core (State Hub until retirement), repo-scoping, llm-connect.
• Downstream: issue-core (optional), State Hub/hub-core progress, SBOM Nexus and bounded platform tools, Glas/reins claiming ops_runs.
• Orientation (not runtime): info-tech-canon (task/org/governance vocabulary), policy-nexus (publication of ADRs/canon — not authored here).
• Ops: railiance01 k3s; workstation status via SSH helper.

---

Terminology

• ActivityDefinition — markdown policy unit (trigger + context + rules/instructions).
• EventEnvelope — canonical inbound event shape.
• Rule / Instruction — deterministic vs judgement (or deterministic report) paths.
• IssueSink — task emission adapter (rest / state-hub / null).
• Report sink / Evidence sink — non-task activation outputs.
• Spawn audit trail — local emission record; not authoritative task state.
• Activity (Temporal) vs ActivityDefinition (app policy) — different concepts.

---

Related / Overlapping

• info-tech-canon — task / organization / governance vocabulary; repository layout.
• policy-nexus — publishes ADRs/canon; does not author them.
• repo-manager — repo registry, consistency engine, work-record index.
• hub-core — messages, progress projections, extension ports (core-hub absorbed later).
• state-hub — compatibility read model until STATE-WP-0079 retirement.
• issue-core — task connector / external tracker mapping (not fleet work-record origin).
• repo-scoping, reuse-surface, sbom-nexus, llm-connect, glas-harness, rein-aharness, sand-boxer.
• railiance-platform — Forgejo package prune tool and credential lanes.
• ops-warden — credential routing (not secret vending for non-SSH).
• ops-bridge tunnels.

---

Architecture Decisions

• docs/adr/adr-001-event-bridge-architecture.md
• docs/adr/adr-002-definition-format.md
• docs/adr/adr-003-rule-instruction-model.md
• docs/adr/adr-004-producer-trust-boundary.md
• docs/adr/adr-005-ops-runs-vs-dev-work-records.md
• docs/adr/adr-006-glas-profile-execution.md
• docs/adr/adr-007-bounded-operations.md

---

Getting Oriented

• Start: INTENT.md, this file, docs/adr/, docs/runbook.md.
• Key code: workflows.py, activities.py, issue_sink.py, report_sinks.py, context_resolvers/, automation_status.py, sync_schedules.py.
• Definitions: activity-definitions/, event-types/, Railiance ConfigMaps.
• Status: make automation-status SINCE=sunday · make prod-automation-status SINCE=sunday.

---

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, emits
  task/report/evidence outputs, and offers a leased ops-run delivery queue with
  normalized execution evidence while leaving work-item lifecycle downstream.
keywords: [temporal, workflow, event-bridge, ops-run, glas, task, report, evidence, cron, event, rule, instruction, org-automation]