resolve mechanical architecture review issues (C-01,C-02,C-03,W-01,W-09,W-10,W-12)

- C-01: fix broken README link (call-graph-runtime.md → call-graph.md)
- C-02: add CallEdgeAttrs union type alias in schema.md
- C-03/W-12: rename TypedEdgeAttrs → OperationEdgeAttrs for consistent
  {GraphType}EdgeAttrs naming pattern, update all references
- W-01: standardize terminology — prerequisites=structural/graph,
  preconditions=reactive/computed, rename WorkflowNode.prerequisites
  to preconditions, rename computePrerequisites to computePreconditions
- W-09: update ADR-001/002/003 status from Proposed to Accepted
- W-10: clarify call graph mutation API — addCall creates triggered
  edges automatically, addDependency creates depends_on edges
- update review checklist with resolved items
This commit is contained in:
2026-05-19 11:09:06 +00:00
parent 037dfec44b
commit c5e649cc9f
11 changed files with 47 additions and 35 deletions

View File

@@ -172,7 +172,7 @@ interface WorkflowNode {
key: string; // Operation name or structural container ID
type: "operation" | "sequential" | "parallel" | "conditional" | "map";
status: Signal<NodeStatus>; // Reactive status signal
prerequisites: Computed<boolean>; // Computed: true when all prerequisites are met
preconditions: Computed<boolean>; // Computed: true when all preconditions are met
operationId?: string; // For operation nodes: the fully qualified ID
output?: Signal<unknown>; // For operation nodes: the call result (when completed)
children: WorkflowNode[]; // Child nodes (structural containers have children)
@@ -181,7 +181,7 @@ interface WorkflowNode {
Each `WorkflowNode` holds:
- A `signal<NodeStatus>` that tracks the call's lifecycle (`idle``waiting``ready``running``completed`/`failed`/`aborted`/`skipped`)
- A `computed` that derives `prerequisites` from parent nodes' statuses
- A `computed` that derives `preconditions` from parent nodes' statuses
- An optional `output` signal that holds the call result when completed
### ReactiveContext
@@ -204,7 +204,7 @@ createInstance(tag: WorkflowTag, props, ctx: ReactiveContext, parent?: WorkflowN
key,
type: tag,
status,
prerequisites: computed(() => computePrerequisites(node, ctx)),
preconditions: computed(() => computePreconditions(node, ctx)),
children: [],
};
@@ -222,14 +222,14 @@ createInstance(tag: WorkflowTag, props, ctx: ReactiveContext, parent?: WorkflowN
### Prerequisite Computation
The `prerequisites` computed signal for each node derives from its structural context:
The `preconditions` computed signal for each node derives from its structural context:
- **Sequential child**: prerequisites = previous sibling is `completed`
- **Parallel child**: prerequisites = parent's prerequisites are met
- **Conditional child**: prerequisites = parent's prerequisites are met AND condition evaluates to true
- **Sequential child**: preconditions = previous sibling is `completed`
- **Parallel child**: preconditions = parent's preconditions are met
- **Conditional child**: preconditions = parent's preconditions are met AND condition evaluates to true
```typescript
function computePrerequisites(node: WorkflowNode, ctx: ReactiveContext): boolean {
function computePreconditions(node: WorkflowNode, ctx: ReactiveContext): boolean {
// Sequential: previous sibling must be completed
// Parallel: parent must be ready
// Conditional: condition must evaluate to true
@@ -243,11 +243,11 @@ function computePrerequisites(node: WorkflowNode, ctx: ReactiveContext): boolean
### Status Propagation
When a node's `status` signal changes, its dependents' `prerequisites` computed automatically re-evaluate. If prerequisites are met, the node transitions to `ready`:
When a node's `status` signal changes, its dependents' `preconditions` computed automatically re-evaluate. If preconditions are met, the node transitions to `ready`:
```typescript
effect(() => {
if (node.prerequisites.value) {
if (node.preconditions.value) {
node.status.value = "ready";
}
});
@@ -314,7 +314,7 @@ For flowgraph, this is acceptable in v1 because:
The current design where `Sequential`, `Parallel`, and `Conditional` don't create graph nodes is clean for the DAG, but creates complexity for the reactive engine — the "previous sibling" precondition depends on understanding the structural context, which isn't stored on the node itself.
Alternative: Create "virtual" nodes for structural containers that hold `signal<NodeStatus>` but don't correspond to graph nodes. This makes the reactive engine simpler (every node has a status and prerequisites) at the cost of a slightly larger node tree.
Alternative: Create "virtual" nodes for structural containers that hold `signal<NodeStatus>` but don't correspond to graph nodes. This makes the reactive engine simpler (every node has a status and preconditions) at the cost of a slightly larger node tree.
### Conditional Test Evaluation
@@ -331,7 +331,7 @@ The `Conditional.test` prop can be a function or a string. At the template level
## Open Questions
1. **Should structural containers create "virtual" nodes in the reactive engine?** This would simplify prerequisite computation (every node has a status) but adds nodes that don't correspond to calls or operations.
1. **Should structural containers create "virtual" nodes in the reactive engine?** This would simplify precondition computation (every node has a status) but adds nodes that don't correspond to calls or operations.
2. **Should the GraphologyHostConfig produce a separate graph for edge types?** Currently all edge types (`sequential`, `conditional`, `typed`) share the same graph. An alternative is a separate graph per edge type, enabling type-specific queries without filtering.