---
id: CUST-TFE-SCOPE-2026-000001
type: architecture-note
title: "Task Flow Engine Extraction Scope v0.1"
status: draft
owners: ["Bernd", "Custodian"]
created: "2026-05-01"
updated: "2026-05-01"
scope:
  domains: ["Custodian"]
  sensitivity: internal
tags: ["task-flow-engine", "architecture", "state-hub", "workflow"]
domain: custodian
provenance:
  workplan: CUST-WP-0035
  task: 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.