the-custodian/canon/projects/custodian/task_flow_engine_scope_v0.1.md

id, type, title, status, owners, created, updated, scope, tags, domain, provenance

id	type	title	status	owners	created	updated	scope	tags	domain	provenance
CUST-TFE-SCOPE-2026-000001	architecture-note	Task Flow Engine Extraction Scope v0.1	draft	Bernd Custodian	2026-05-01	2026-05-01	domains sensitivity Custodian internal	task-flow-engine architecture state-hub workflow	custodian	workplan task CUST-WP-0035 CUST-WP-0035-T06

Task Flow Engine Extraction Scope v0.1

Purpose

The task flow engine is currently co-located in state-hub/ so it can replace hardcoded lifecycle logic where the need is immediate. Its core model is more general than State Hub, so it should become a standalone Python package once the API has stabilized through real use.

Standalone Package Boundary

The future task-flow-engine package should contain only pure computation:

• models.py: dataclasses for assertions, workstations, flows, and results
• evaluator.py: target path resolution and assertion evaluation
• engine.py: reachable workstation and exit-blocking derivation
• builtins.py: built-in operations such as all_eq, any_eq, none_eq, exists, and count_gte

The package must not depend on State Hub, SQLAlchemy, FastAPI, MCP, Custodian canon files, or any specific database schema.

State Hub Integration Boundary

State Hub should retain the domain-specific integration layer:

• YAML flow definitions in state-hub/flows/
• conversion from ORM entities into plain information-object dictionaries
• Alembic migrations and status-column storage choices
• API routers and MCP tools
• custom assertion callables that query State Hub data
• progress events, timestamps, notifications, and other side effects

This keeps the reusable engine small while allowing State Hub to remain the place where Custodian-specific lifecycle semantics are declared and exposed.

Extraction Path

1. Keep state-hub/task_flow_engine/ in-tree until at least one non-trivial flow definition runs in normal State Hub use.
2. Stabilize the dataclass and result shapes around real consumers: State Hub API, MCP tools, and repo-facing workflows.
3. Extract the pure package into a new task-flow-engine repository.
4. Publish it as an internal pip package.
5. Replace the in-tree package with a dependency import in State Hub.

The extraction should preserve the current import surface where practical: FlowDef, WorkstationDef, AssertionDef, FlowResult, AssertionResult, FlowEngine, and resolve_target.

Managed Repo Concept

When extraction starts, register a managed repository concept:

• slug: task-flow-engine
• domain: custodian
• purpose: reusable declarative workstation/assertion engine
• primary capability: workflow.evaluate
• secondary capabilities: workflow.define, workflow.explain

Extension Point

An extension point is registered in State Hub to keep this extraction visible:

• type: architecture
• title: task-flow-engine extraction as standalone package
• status: open
• priority: low

Description:

task_flow_engine/ is currently co-located in the State Hub. Extract it to its own repository and pip package once the API is stable after at least one non-trivial flow definition has been running in production.