diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..219ba88 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,94 @@ +# 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