# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Event-driven task factory backbone using Temporal — defines ActivityDefinitions that spawn TaskInstances when triggered by cron schedules or domain events, with durable execution and PostgreSQL persistence.

---

## Core Idea

Activity-core replaces ad-hoc cron jobs and Celery tasks with a durable Temporal-based workflow engine. An `ActivityDefinition` declares what triggers it (cron or event), how to resolve context, and what task templates to spawn. When triggered, a `RunActivityWorkflow` executes durably, creating `TaskInstance` records and run logs. Server crashes replay automatically from Temporal's event log.

---

## In Scope

- Domain model: ActivityDefinition, EventEnvelope, CronTriggerConfig, EventTriggerConfig, RunActivityWorkflow, TaskInstance
- Trigger types: 5-field cron (with timezone, jitter, misfire policy) or event-based (EventEnvelope type + payload filters)
- EventEnvelope normalization: standard internal event format for all inbound events
- Context resolution: load definition from DB, resolve context sources, evaluate rules
- Task spawning: generate TaskInstance records as child workflows/activities
- Run logging: audit trail of activity executions, task creation, completion

---

## Out of Scope

- Temporal server hosting/operations (activity-core consumes Temporal SDK; infra is separate)
- End-user task UI (TaskInstance records are created; presentation is a separate concern)
- Event broker integration (upstream router delivers EventEnvelopes; activity-core receives them)
- Synchronous request-response workflows (Temporal is async-first)

---

## Relevant When

- Need durable, time-triggered or event-triggered task generation with crash resilience
- Want an audit trail of activity runs and spawned task instances
- Replacing unreliable cron + Celery patterns with replay-safe Temporal workflows

---

## Not Relevant When

- Simple system cron jobs with no durability requirement
- Synchronous request-response patterns
- Existing Celery infrastructure is working (migration is non-trivial)

---

## Current State

- Status: concept → planning (pre-alpha)
- Implementation: ~30% — domain model defined (EventEnvelope, ActivityDefinition, trigger configs); PostgreSQL schema planned; Temporal workflows.py + activities.py not yet scaffolded
- Stability: unstable — models are valid but untested in real workflows
- Usage: none yet; proto-planning phase

---

## How It Fits

- Upstream dependencies: Temporal (orchestration engine), PostgreSQL (persistence), ops-bridge (network tunnel to remote Temporal server)
- Downstream consumers: Custodian State Hub tracks activity-core workstreams; tasks spawned feed into other systems
- Often used with: kaizen-agentic (project scaffolding), the-custodian (workstream tracking), railiance (Temporal server may run on Railiance infrastructure)

---

## Terminology

- Preferred terms: ActivityDefinition, EventEnvelope, RunActivityWorkflow, TaskInstance, trigger, misfire policy
- Also known as: "the task factory", "activity backbone"
- Potentially confusing terms: "Activity" is a Temporal concept (a single executable step); "ActivityDefinition" is the app-level record that configures what gets spawned

---

## Related / Overlapping Repositories

- `the-custodian` — tracks activity-core workstreams in State Hub (domain: custodian)
- `ops-bridge` — provides network tunnel to remote Temporal server
- `railiance-cluster` / `railiance-platform` — may host Temporal server

---

## Getting Oriented

- Start with: `CLAUDE.md` (session protocol, repo boundary), `wiki/ActivityCorePlan_chtgpt.md` (proto-architecture)
- Key files / directories: `src/activity_core/models.py` (EventEnvelope, ActivityDefinition), `workplans/` (roadmap), `docker-compose.dev.yml` (local Temporal + PostgreSQL)
- Entry points: models.py is the current starting point; workflows.py does not yet exist