# Isis Custom Node Contracts

This document defines the canonical Isis contract for custom ComfyUI nodes in
workflow definitions validated through `@isis/workflows`.

## Scope

The contract has three layers:

1. Workflow-level manifest (`custom_nodes_required`).
2. Per-node shape (`nodes.<id>` schema).
3. Runtime compatibility expectations (provider/node availability).

## Workflow Manifest Contract

`custom_nodes_required` is optional, but when present it must be an array of
strings.

```json
{
  "custom_nodes_required": [
    "ComfyUI-AnimateDiff-Evolved",
    "ComfyUI-Impact-Pack@>=1.5.0 <2.0.0",
    "IPAdapterPlus"
  ]
}
```

### Required behavior

- Each entry must identify a required custom node pack or node capability.
- Entries must be stable IDs (do not use free-form prose).
- Version pinning is recommended for reproducibility (`<id>@<semver-range>`).
- If `custom_nodes_required` is declared, workflows must not reference missing
  capabilities during execution.

## Node Contract (`nodes.<id>`)

Each node in the canonical object-map must match:

```json
{
  "class_type": "SomeNodeClass",
  "inputs": {
    "input_a": "value",
    "input_b": ["10", 0]
  },
  "outputs": ["IMAGE"],
  "_comment": "optional",
  "_condition": "optional"
}
```

### Required fields

- `class_type` (`string`, required): ComfyUI/custom node class identifier.
- `inputs` (`object`, required): keyed input payload; each value must be one of:
  - scalar (`string`, `number`, `boolean`, `null`)
  - node reference tuple (`[nodeId: string, outputIndex: number]`)
- `outputs` (`string[]`, required): declared output channels.

### Optional fields

- `_comment` (`string`)
- `_condition` (`string`)

### Strictness

- Additional node keys are rejected by schema validation.
- Array-based legacy graph format (`nodes[]` + `links[]`) is non-canonical and
  must be normalized through the legacy adapter before validation.

## Canonical Required Top-Level Fields

For schema `1.0.0`, compatibility checks require:

- `schema_version`
- `workflow_info`
- `inputs`
- `nodes`
- `prompt_construction`
- `output_spec`

## Validation and Enforcement Points

- Authoring/CI:
  - `pnpm nx run @isis/workflows:workflow:validate`
  - `pnpm nx run @isis/workflows:lint` (includes schema validation dependency)
- Registry ingestion:
  - `POST /api/v1/workflows/validate`
  - `POST /api/v1/workflows`
- Compatibility helper:
  - `validateWorkflowCompatibility(...)`
  - legacy workflows without `schema_version` are migrated to schema `1.0.0` via
    the shared schema migration registry.

## Authoring Checklist

- Include every external/custom dependency in `custom_nodes_required`.
- Use canonical node object-map format (`nodes.<id>`), not array graphs.
- Ensure every node has `class_type`, `inputs`, and `outputs`.
- Keep node keys strict; move extra metadata to top-level passthrough fields if
  needed.
- Pin custom node pack versions for production workflows.
