fix build/distribution spec: npm deps not workspace, align configs with sibling projects, resolve review issues

- Replace workspace:* deps with published npm semver ranges (^0.34.49, ^0.1.0)
- Expand package.json: add description, publishConfig, scripts, engines,
  devDependencies, conditional exports with types/default for import+require
- Fix tsup entry names (path-prefixed like ujsx), add target: es2022,
  remove splitting:true (not used by sibling projects)
- Align tsconfig with sibling projects: add lib, noUncheckedIndexedAccess,
  noUnusedLocals, noUnusedParameters, erasableSyntaxOnly, etc.
- Expand vitest.config.ts with include, coverage, and path alias
- Clarify @preact/signals-core as direct dep (not just transitive via ujsx)
- Clarify @alkdev/pubsub is a consumer dependency, not flowgraph's dep
- Fix edge key convention: document composite key format for call graph's
  multi-edge-type scenario (triggered + depends_on between same pair)
- Align OperationEdgeAttrs field naming: use detail+mismatches consistently
  instead of compatibilityDetail
- Add InvalidInputError to error hierarchy (referenced in flowgraph-api but
  was missing)
- Fix undefined attrs.category reference in reactive-execution.md
- Remove internal drafting note from host-configs.md
- Fix ReactiveHostConfig constructor signature inconsistency across docs
- Constrain TemplateEdgeAttrs.edgeType to sequential|conditional only
This commit is contained in:
2026-05-20 03:09:57 +00:00
parent eaeba38e71
commit da2973e2a6
9 changed files with 251 additions and 92 deletions

View File

@@ -25,7 +25,8 @@ FlowgraphError # Base class for all flowgraph errors
│ ├── DuplicateNodeError # Duplicate node key
│ ├── DuplicateEdgeError # Duplicate edge key
│ ├── NodeNotFoundError # Referenced node doesn't exist
── CycleError # Adding an edge would create a cycle
── CycleError # Adding an edge would create a cycle
│ └── InvalidInputError # Invalid input to fromJSON() or constructor
├── ValidationError # Schema validation failed (single field)
├── GraphValidationError # Graph-level validation issue
│ ├── CycleValidationError # Cycle detected in the graph
@@ -117,6 +118,19 @@ Thrown when adding an edge would create a cycle. The `cycles` field contains the
Note: `CycleError` is flowgraph's cycle error, thrown by `addEdge()` during construction. Taskgraph uses a different error name (`CircularDependencyError`, thrown by `topologicalOrder()`). The two are distinct errors for distinct contexts — flowgraph prevents cycles at construction time, taskgraph allows cycles and detects them later.
### InvalidInputError
```typescript
class InvalidInputError extends ConstructionError {
constructor(public readonly errors: ValidationError[]) {
super(`Invalid input: ${errors.length} validation error(s)`);
this.name = "InvalidInputError";
}
}
```
Thrown by `fromJSON()` when the input data fails schema validation. The `errors` field contains the array of `ValidationError` objects describing which fields failed validation. This is distinct from `ValidationError` (which is a returned result) — `InvalidInputError` is thrown because `fromJSON()` enforces that deserialized data is structurally valid.
### ValidationError
```typescript
@@ -231,6 +245,7 @@ The distinction between thrown errors and returned errors:
| `addNode(key, attrs)` | Throws `DuplicateNodeError` on duplicate key | Adding a duplicate is a programmer error |
| `addEdge(source, target)` | Throws `NodeNotFoundError` on missing endpoint | Edge without endpoints is invalid |
| `addEdge(source, target)` | Throws `CycleError` if edge creates cycle | DAG invariant must be maintained |
| `fromJSON(data)` | Throws `InvalidInputError` on validation failure | Deserialized data must be structurally valid |
| `updateNodeStatus(id, status)` | Throws `InvalidTransitionError` on invalid transition | State machine must be enforced |
| `validateSchema()` | Returns `ValidationError[]` | Schema issues are validations, not crashes |
| `validateGraph()` | Returns `GraphValidationError[]` | Graph issues are validations, not crashes |