(CODUX-216) Define canonical Graph v2 and node registry

[numnx]

🧩 Task: Define canonical Graph v2 and node registry

Automated task PR opened by Code UX for T01.

📋 Summary

Sprint: Sprint 216 · Nodes Full Integration · Task: T01

Turn the existing project-scoped node-flow foundation and browser-local canvas into a canonical, secure, versioned automation control plane with registry-driven nodes, encrypted credentials, durable execution, governed integrations, isolated custom nodes, agent authoring, dashboard integration, and authenticated headless readiness.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-12 04:00:18 UTC
Finished	2026-07-12 04:07:15 UTC
Duration	6m 57s

📊 Token Usage

Metric	Value
Input tokens	178,587
Cached input tokens	6,809,856
Output tokens	32,091
Total tokens	7,020,534
Invocations	4
Tool calls	67
Active time	14m 34s

Included usage estimate (subscription/local login): $5.26

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Introduce the canonical Graph v2 contract, node-definition registry, and deterministic migrations required for the backend, MCP surface, runtime, and dashboard to share one workflow model.

## Scope
- `src/contracts/node-flow-types.ts`
- New `src/contracts/node-definition-types.ts`
- `src/domain/node-flows/node-flow-validation.ts`
- New `src/domain/node-flows/node-definition-registry.ts`
- New `src/domain/node-flows/node-flow-migrators.ts`
- `src/repositories/node-flow-repository.ts`
- `src/services/node-flow-service.ts`
- `src/repositories/db/app-db-migrations.ts`
- `dashboard/src/v2/lib/nodes-canvas-state.ts`
- `dashboard/src/v2/lib/nodes-agent-surface.ts`
- `tests/backend/domain/node-flows/`, `tests/backend/repositories/node-flow-repository.test.ts`, and related dashboard tests
- `docs/architecture/node-flow-foundation.md`, `docs/architecture/node-flows.md`, `docs/dashboard/node-flows.md`, `docs/dashboard/nodes-canvas.md`, and matching `docs-web/content/docs/` pages

## Implementation Requirements
1. Extend the shared graph contract with `schemaVersion`, stable node-definition type/version references, typed ports, credential bindings, retry and timeout policies, side-effect and capability metadata, disabled state, flow schemas, and immutable publication metadata without permitting raw secrets or custom source code in graph JSON.
2. Create a typed node-definition manifest and registry with schema, UI, port, credential, capability, side-effect, retry, timeout, documentation, deprecation, and execution-kind metadata; register the currently executable six node types without advertising future handlers as executable before they exist.
3. Make validation resolve definitions and validate configuration, ports, policies, graph limits, and cycles while preserving field-level issues and deterministic execution ordering.
4. Add deterministic migrators for persisted backend Graph v1 records and browser `NodeCanvasGraph` v1 records, preserving legacy snapshots and creating a new immutable version when migration is persisted.
5. Add focused contract, migration, registry, validation, and backward-compatibility tests, then document the canonical contract and explicitly distinguish implemented nodes from planned catalog entries.

## Constraints
- Preserve existing project ownership, cascade behavior, API compatibility, and secret-shaped-key redaction.
- Do not make the dashboard or runtime maintain a second canonical graph representation.
- Do not store credentials, generated source, or plaintext secret values in graph data, defaults, metadata, or fixtures.

## Verification
- Run `pnpm exec vitest run tests/backend/domain/node-flows tests/backend/repositories/node-flow-repository.test.ts tests/dashboard/lib/nodes-canvas-state.test.ts tests/dashboard/lib/nodes-agent-surface.test.ts`.
- Run `pnpm run typecheck` and `pnpm run typecheck:dashboard`.
- Confirm legacy backend and local-canvas fixtures migrate deterministically and retain their original snapshots.
- Run `pnpm run check:docs-web` and confirm documentation does not claim unimplemented node types are executable.

🌿 Branch Info

Base: feature/CODUX-216-nodes-full-integration
Head: task/feature-codux-21-t01-codex-da97c952-mrh9aujz

---

🤖 Generated by Code UX