flowgraph/AGENTS.md

@alkdev/flowgraph — Agent Guide

Project-specific context for AI agents working on this codebase.

What This Is

DAG-based workflow orchestration library. Wraps graphology DirectedGraph, enforces DAG invariants, provides ujsx template composition and reactive signal-driven execution. Sits between @alkdev/operations (what can be called) and @alkdev/alkhub (what was called) — defines how calls are orchestrated.

Build & Test Commands

npm run build          # tsup (ESM + CJS + dts + sourcemaps)
npm run build:tsc      # tsc type-check only
npm run lint           # tsc --noEmit
npm run test           # vitest run
npm run test:watch     # vitest watch
npm run test:coverage  # vitest run --coverage

Always run npm run lint && npm run test after making changes.

Source Structure

src/
  index.ts              # Barrel — re-exports all sub-modules
  component/            # ujsx workflow components (Operation, Sequential, Parallel, Conditional, Map)
  host/                 # HostConfig implementations (GraphologyHostConfig, ReactiveHostConfig)
  schema/               # TypeBox schemas, enums, node/edge attribute types
  graph/                # FlowGraph class (construction, mutation, query, serialization)
  reactive/             # WorkflowReactiveRoot, signal-driven status, event log projection
  analysis/             # Pure functions: typeCompat, validate, topologicalOrder, parallelGroups, criticalPath
  error/                # FlowgraphError hierarchy

Subpath Exports

The package has 8 export subpaths. Root @alkdev/flowgraph re-exports everything. Subpath imports make dependencies explicit:

Subpath	Key Exports
/graph	FlowGraph, FlowGraphOptions, OperationSpec, CallEventMapValue
/schema	CallStatus, NodeStatus, EdgeType, OperationType, all node/edge attribute types
/component	Operation, Sequential, Parallel, Conditional, Map
/host	GraphologyHostConfig, ReactiveHostConfig
/analysis	typeCompat, buildTypeEdges, validateGraph, validateSchema, validate, validateTemplate, topologicalOrder, parallelGroups, criticalPath
/reactive	WorkflowReactiveRoot, EventLogProjection, WorkflowNode, FailurePolicy
/error	FlowgraphError, ConstructionError, CycleError, InvalidInputError, InvalidTransitionError

Key Patterns

• TypeBox schema + Static type pairs: Every schema is exported as both a const (runtime) and an inferred type. const FooSchema = Type.Object({...}); type Foo = Static<typeof FooSchema>;
• Delegation model: FlowGraph wraps a graphology DirectedGraph (does not extend it). flowGraph.graph is an escape hatch that bypasses validation.
• DAG enforcement: addEdge() throws CycleError if the edge would create a cycle. fromJSON() validates DAG invariants on deserialization.
• Event log as source of truth: Call protocol events (call.requested, call.responded, call.error, call.aborted, call.completed) are appended to WorkflowReactiveRoot. Status/results are derived projections.
• Signal-driven execution: @preact/signals-core powers WorkflowReactiveRoot. preconditions, canStart, blockedByFailure are ReadonlySignal<boolean> computed from predecessor status.
• dispose() is mandatory: WorkflowReactiveRoot.dispose() must be called to release signal subscriptions.

Architecture Docs

docs/architecture/ contains detailed specs (all status: reviewed):

• README.md — overview, relationship to sibling packages, design decisions
• flowgraph-api.md — FlowGraph class full API
• consumer-integration.md — end-to-end integration walkthrough (5 phases)
• schema.md — TypeBox Module, all node/edge attribute schemas
• operation-graph.md — static graph from OperationSpecs
• call-graph.md — dynamic graph from call events
• workflow-templates.md — ujsx components, composition rules, template→DAG hydration
• host-configs.md — GraphologyHostConfig, ReactiveHostConfig
• reactive-execution.md — signal-driven status propagation, lifecycle, error boundaries
• analysis.md — type-compatibility checking, precondition validation, execution ordering
• error-handling.md — FlowgraphError hierarchy
• build-distribution.md — package structure, exports map
• decisions/ — ADRs 001–006

Consult these for anything non-trivial. The README is surface-level; architecture docs are the specification.

Constraints for Agent Modifications

• Never add cycles — this is a DAG-only library. Any edge that would create a cycle must throw CycleError.
• Never mutate operation graphs after construction — fromSpecs() graphs are conventionally immutable.
• Keep schema as pure data — src/schema/ contains TypeBox schemas and types only, no runtime logic.
• Keep analysis as pure functions — src/analysis/ functions take a FlowGraph or DirectedGraph as input and return results without side effects.
• Maintain the delegation model — FlowGraph delegates to graphology. Don't expose raw graphology methods that could violate DAG invariants without explicit validation.
• tsup builds all subpath entries — tsup.config.ts lists every subpath. If you add a new top-level module, add the entry there and update package.json exports.