flow-to-plan-compiler-spec · supabase_json

Bezel Workflow flow-to-plan-compiler-spec

flow-to-plan-compiler-spec artifact · for Bezel Workflow · status draft

Planning Surface

Use this to decide what happens next.

Status

draft

Agent Handoff

Start Here

flow-to-plan-compiler-spec artifact · for Bezel Workflow · status draft

Completion Evidence

No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.

Artifact Shape

kind: flow-to-plan-compiler-spec
repo: /Users/justinking/Vaults/Projects/bezel-api
input: FLOW.json
tests: 7 items
project: Bezel Workflow
purpose: Translate human-authored FLOW.json into the agent-readable runtime plan accepted by Bezel API/local runtime.
output v1: PlanIntake-compatible graph: { name, tasks: [{ id, title, role_id, input, depends_on }] } plus safe runtime metadata where supported.
created by: atlas-codex
updated at: 2026-05-09T13:17:30.522Z
schema version: compiler-spec.v1
compiler stages: 5 items
source memory id: 99edd8d2-5780-43a2-bbd0-03982353768a

Structured Payload

Machine-readable source fields

kind

flow-to-plan-compiler-spec

repo

/Users/justinking/Vaults/Projects/bezel-api

input

FLOW.json

tests

compiles a sequential two-step flow
compiles trigger -> extraction -> three-way fan-out -> fan-in summary
rejects duplicate step ids
rejects missing dependencies
rejects unresolved connector action
emits credential requirements without secret values
emits PlanIntake accepted by existing validatePlanIntake

project

Bezel Workflow

purpose

Translate human-authored FLOW.json into the agent-readable runtime plan accepted by Bezel API/local runtime.

output v1

PlanIntake-compatible graph: { name, tasks: [{ id, title, role_id, input, depends_on }] } plus safe runtime metadata where supported.

created by

atlas-codex

updated at

2026-05-09T13:17:30.522Z

schema version

compiler-spec.v1

compiler stages

stage	checks	actions
parse	- valid JSON - schema version supported - required fields present
semantic validation	- unique step ids - dependency targets exist - no cycles unless loop construct explicitly supported - connector/action exists - credential refs declared - role names resolvable or provisionable
normalization		- expand templates - normalize role names - attach connector/action metadata - derive task titles - mark redaction policy
graph compilation		- map steps to tasks - map depends_on to task_dependencies - represent fan-out as sibling tasks - represent fan-in as downstream task depending on all fan-out siblings
runtime packaging		- emit PlanIntake payload - emit timeline metadata - emit credential reference requirements - emit warnings for human review

source memory id

99edd8d2-5780-43a2-bbd0-03982353768a

runtime metadata needed

flow_id
flow_version
step_id
step_type
connector
action
credential_ref
human_label
redaction_policy
self_heal_policy

architecture decision ref

3a1bb081-67f9-41ae-9600-a91fbb14ecda

compatibility with existing api

current gap

Existing PlanIntake task input can carry connector/action metadata, but first-class metadata columns would improve run timeline and avoid mixing runtime inputs with product metadata.

low risk start

Compile metadata into task.input.__bezel initially, then migrate to explicit task metadata columns once the behavior is proven.

preferred production path

Add explicit task metadata JSONB or workflow_step metadata columns after the schema is stable.