Skip to content

FLOW-02 — local server lifecycle and verifier acceptance

Task: 37a1b087-a4a4-4924-b05f-fec31dc3f5ee. Repository: https://github.com/h8v6/heyaira. Branch: codex/flow-v1-server. Base: 9e32dc88a0dc1faa241c1b9e131149cb9ea81f23 (FLOW-01 contract). Result: the commit containing this report; the full result SHA is recorded in HeyAira's RESULT memory and task receipt. Local only; no push, merge or deployment.

Outcome

The existing server recorded a supervised process outcome but could not manage acceptance. An opted-in task can now be dispatched with frozen goals, criteria, Git references, assignment and explicit worker/verifier profile snapshots. Bridge claim, preparation and provider readiness are separate phases. Worker completion creates an independent verification offer; a complete verdict for the exact candidate atomically closes the task and writes an acceptance receipt. A failing criterion queues a fresh correction attempt, with feedback, within a maximum of two work attempts. Missing evidence, interruption and budget exhaustion block instead of claiming success. Ordinary task clients retain their legacy behavior.

The server rejects stale/missing/duplicate/unknown verdict criteria, reused or changed sessions, worker self-acceptance, late execution writes after cancellation, and legacy status changes that bypass managed acceptance. Cancellation and acceptance serialize on the task lock. Event replay cannot duplicate offers or receipts. Expiry recovery and retries are explicit; a new revision retains the old evidence/history. Current scope also prevents a legacy receipt writer from occupying managed execution/acceptance receipt identities.

The read projection includes phase, active attempt/purpose, candidate, profile versions, reason, update time and lease expiry. MCP and node-authorized HTTP use the same workflow state. Detail history is bounded and cursor-based. List reads batch their workflow lookup rather than fetching one record per row.

Changes

  • migrations/019_task_workflows.sql: opt-in revisions, event attribution/history, execution-purpose references, current-revision and session lookup indexes.
  • src/heyaira/workflow.py: frozen dispatch, lifecycle transitions, verification, correction budgets, explicit cancellation/reconciliation, read projections.
  • src/heyaira/execution.py: additive preparation/result protocol and transactional managed lifecycle hooks; legacy execution completion remains unverified.
  • src/heyaira/server.py: typed MCP dispatch/get/control, completion guards, Bridge workflow detail and shared task projections.
  • scripts/export_mcp_contract.py: exported imported/inherited model fields, field bounds and correct defaults so new clients discover the complete spec.
  • MCP/OpenAPI/reference docs, smoke tool inventories, integration/schema tests, design status and PROJECT_STATE.md updated together.

Validation

Disposable, loopback-only PostgreSQL 16; actual server/uvicorn, MCP transport, Bridge HTTP, authentication and transactions. Provider processes, Git candidate SHAs and evidence paths in these tests are synthetic.

Final commands and raw result summaries:

python scripts/test_postgres.py
278 passed in 21.21s
postgres_acceptance=passed: complete suite, zero skipped tests

pytest -q tests/test_workflow_e2e.py tests/test_mcp_runtime_contract.py
37 passed in 10.67s

python scripts/export_mcp_contract.py --check
MCP contract is up to date
python scripts/check_docs_contract.py
documentation contract passed: 21 MCP tools covered
python scripts/validate_runtime.py
runtime_validation=passed
node --test tests/site-consent.test.cjs
12 tests, 12 pass, 0 fail, 0 skipped
git diff --check
no output (pass)

The full suite includes legacy behavior, cold-client continuity, permissions and concurrent migrations. New workflow coverage includes success, invalid verdicts, correction exhaustion, cancellation/acceptance races, lease expiry, explicit new-revision recovery, independent sessions, missing evidence/verdict, ownership checks, replay and list/detail isolation. Initial test harness cleanup and two smoke scripts' fixed tool inventories were corrected before the final green run.

Read performance

Hardware: Apple M5 Pro. Python 3.12, local PostgreSQL 16, loopback MCP. Fixture sizes are total tasks, each with a current workflow; fixtures use compact synthetic profile/contract records. Each call opens an MCP client, so transport setup is included. Page size is at most 100. One first read is followed by 20 samples; p95 is the 19th ordered warm sample. Database pages are not forcibly flushed; the first read is not an OS/disk cold-start measurement.

FLOW_PERF rows=50 page=100 cold_ms=16.79 warm_p95_ms=20.14 samples=20 transport=real-MCP-loopback
FLOW_PERF rows=500 page=100 cold_ms=16.02 warm_p95_ms=16.64 samples=20 transport=real-MCP-loopback
FLOW_PERF rows=5000 page=100 cold_ms=19.34 warm_p95_ms=13.90 samples=20 transport=real-MCP-loopback
3 passed, 22 deselected in 2.37s

All measured p95 values are below the 250 ms fixture target. Different sizes' small differences are normal run-to-run variance; this does not establish that more data improves performance. This is neither a public-network SLA nor a native UI/profile-payload stress result.

Remaining delivery and confidence

Confidence is high for the tested server contract and transaction boundaries. These tests do not establish a real provider's readiness, filesystem integrity, artifact contents or semantic correctness. The server validates an attributable verifier verdict and bounded references; Bridge must check the actual candidate and run the worker/verifier. Reads expose an expired lease flag while retaining the last reported phase until an event or explicit reconciliation records the block. There is no hidden background re-execution.

FLOW-03 must integrate the protocol into the performance-fixed Bridge base 0ae1fadd6ceb0d1e13a897d75fc55f6db318191a: node-side workspace/runtime opt-in, truthful preparation/readiness, fresh provider sessions, clean immutable result checks and complete bound verdict delivery. FLOW-04 consumes the shared read projection without UI polling/sorting regressions. FLOW-05 proves the integrated real-provider flow and prepares a separately authorized release. Catalog CRUD and automatic catalog resolution remain separate work. Installed Bridge and production server were not changed by FLOW-02.