feat(schema/graph-schemas): define TaskGraphNodeAttributes, TaskGraphEdgeAttributes, and SerializedGraph generic

Implements graph attribute schemas and the SerializedGraph generic factory
parameterized with <N, E, G> following the graphology JSON format.

- TaskGraphNodeAttributes: name + optional categorical enums (scope, risk,
  impact, level, priority, status) — analysis-relevant metadata only
- TaskGraphNodeAttributesUpdate: Type.Partial(TaskGraphNodeAttributes)
- TaskGraphEdgeAttributes: optional qualityRetention number
- SerializedGraph<N, E, G>: generic factory for graphology JSON format
- TaskGraphSerialized: concrete instantiation with empty graph attributes
- No schema version field per spec

35 new tests covering validation, rejection, and compile-time type safety.
This commit is contained in:
2026-04-27 11:03:07 +00:00
parent 8725a26b43
commit d2eaa0dd77
3 changed files with 318 additions and 16 deletions

View File

@@ -1,7 +1,7 @@
---
id: schema/graph-schemas
name: Define TaskGraphNodeAttributes, TaskGraphEdgeAttributes, and SerializedGraph
status: pending
status: completed
depends_on:
- schema/enums
scope: narrow
@@ -16,17 +16,17 @@ Define graph attribute schemas and the serialized graph generic in `src/schema/g
## Acceptance Criteria
- [ ] `src/schema/graph.ts` exports:
- `TaskGraphNodeAttributes` schema: `name: Type.String()`, optional categorical enums (scope, risk, impact, level, priority, status) — **not** nullable on the graph (absent = not stored)
- `type TaskGraphNodeAttributes` derived
- `TaskGraphNodeAttributesUpdate = Type.Partial(TaskGraphNodeAttributes)` and type alias
- `TaskGraphEdgeAttributes` schema: `qualityRetention: Type.Optional(Type.Number())`
- `type TaskGraphEdgeAttributes` derived
- `SerializedGraph` generic factory parameterized with `<N extends TSchema, E extends TSchema, G extends TSchema>`
- `TaskGraphSerialized = SerializedGraph(TaskGraphNodeAttributes, TaskGraphEdgeAttributes, Type.Object({}))` and type alias
- [ ] `SerializedGraph` generic follows graphology JSON format: `attributes`, `options: { type: "directed", multi: false, allowSelfLoops: false }`, `nodes: [{ key, attributes }]`, `edges: [{ key, source, target, attributes }]`
- [ ] No schema version field on `TaskGraphSerialized` per spec
- [ ] Re-exported from `src/schema/index.ts`
- [x] `src/schema/graph.ts` exports:
- [x] `TaskGraphNodeAttributes` schema: `name: Type.String()`, optional categorical enums (scope, risk, impact, level, priority, status) — **not** nullable on the graph (absent = not stored)
- [x] `type TaskGraphNodeAttributes` derived
- [x] `TaskGraphNodeAttributesUpdate = Type.Partial(TaskGraphNodeAttributes)` and type alias
- [x] `TaskGraphEdgeAttributes` schema: `qualityRetention: Type.Optional(Type.Number())`
- [x] `type TaskGraphEdgeAttributes` derived
- [x] `SerializedGraph` generic factory parameterized with `<N extends TSchema, E extends TSchema, G extends TSchema>`
- [x] `TaskGraphSerialized = SerializedGraph(TaskGraphNodeAttributes, TaskGraphEdgeAttributes, Type.Object({}))` and type alias
- [x] `SerializedGraph` generic follows graphology JSON format: `attributes`, `options: { type: "directed", multi: false, allowSelfLoops: false }`, `nodes: [{ key, attributes }]`, `edges: [{ key, source, target, attributes }]`
- [x] No schema version field on `TaskGraphSerialized` per spec
- [x] Re-exported from `src/schema/index.ts`
## References
@@ -35,8 +35,11 @@ Define graph attribute schemas and the serialized graph generic in `src/schema/g
## Notes
> To be filled by implementation agent
Follows the architecture spec in docs/architecture/schemas.md and the generic schema factory pattern from docs/research/typebox-patterns.md section 6. The `SerializedGraph` generic factory uses the recommended graphology JSON format with `Type.Literal("directed")`, `Type.Literal(false)`, and `Type.Literal(false)` for the options. No `default` on `qualityRetention` in the graph schema (unlike `DependencyEdge` which has `Type.Number({ default: 0.9 })`) — the graph schema keeps it simple with `Type.Optional(Type.Number())`.
## Summary
> To be filled on completion
Implemented graph attribute schemas and serialized graph generic factory per spec.
- Created: `src/schema/graph.ts` (TaskGraphNodeAttributes, TaskGraphNodeAttributesUpdate, TaskGraphEdgeAttributes, SerializedGraph generic, TaskGraphSerialized, and all type aliases)
- Modified: `test/schema.test.ts` (35 new tests for graph schemas: TaskGraphNodeAttributes, TaskGraphNodeAttributesUpdate, TaskGraphEdgeAttributes, SerializedGraph, and compile-time type verification)
- Tests: 121 total, all passing; `tsc --noEmit` clean