@x12i/graphenix-task-node-format

Task node authoring contract: substance, bindings, phase utility strategies, conditions, knowledge, and metadata validation.

Canonical vocabulary: GLOSSARY.md at monorepo root (do not use “Synthesis PRE”).
When task run phase terms change, update this README per GLOSSARY § README sync policy.

Install

npm install @x12i/graphenix-task-node-format @x12i/graphenix-core

Task node design shape

Task node (design authoring)
│
├─ taskVariable.*              task substance (question, output contract)
├─ inputs / inputsConfig       input bindings
├─ smartInput                  render-time path config (smart-inputs token)
├─ executionMapping            output into execution memory
│
├─ taskConfiguration
│   ├─ prePhase (legacy: aiTaskStrategies.pre — path-driven synthesis reads)
│   ├─ mainPhase (legacy: executionStrategies — `[]` = explicit plain MAIN)
│   │     └─ skillProfile.inputSynthesis (legacy: aiTaskProfile.inputSynthesis)
│   └─ postPhase (legacy: aiTaskStrategies.post)
│
└─ model override (graphenix.executable/v1) — see @x12i/graphenix-executable-profile-format
    └─ preActionModel / skillModel / postActionModel  (phase model profiles)

Three layers (do not conflate)

| Layer | What it answers | Legacy fields | | ----- | --------------- | ------------- | | Phase topology | pre / main / post run shape | runtime only | | Phase utility strategies | What utility runs in pre/post; MAIN wrappers | aiTaskStrategies, executionStrategies | | Skill input synthesis profile | Synthesis inside MAIN (synthesized-context UI) | aiTaskProfile.inputSynthesis | | Phase model profiles | Which AI profile runs each phase | preActionModel, skillModel, postActionModel |

An empty executionStrategies: [] means explicit plain MAIN. Omitting the field is not the same as [] for strict graphs.

Critical: aiTaskStrategies.pre: "synthesis" is a PRE-phase utility strategy key. aiTaskProfile.inputSynthesis.enabled is the skill input synthesis profile — a different feature. SubNets uses the former, not the latter.

Plan output: preActions[] / postActions[] are compiled execution units (plan artifact) — not synonyms for aiTaskStrategies.pre.

TypeScript types (canonical names)

Legacy JSON keeps aiTaskStrategies for migration. Prefer these names in code and validator messages:

| Type | Legacy JSON | | ---- | ----------- | | PrePhaseUtilityConfig | aiTaskStrategies.pre (PRE reads from inputSynthesis.sources or runtime default trio) | | PostPhaseUtilityConfig | aiTaskStrategies.post | | MainPhaseConfig | executionStrategies only | | SkillInputSynthesisProfile | aiTaskProfile.inputSynthesis (skillProfile.inputSynthesis) |

Examples (JSON)

SubNets-style PRE-phase utility (§2)

"taskConfiguration": {
  "executionStrategies": [],
  "aiTaskStrategies": {
    "pre": "synthesis",
    "post": "validate"
  }
}

PRE-phase utility strategy synthesis enables the PRE unit; read scope from aiTaskProfile.inputSynthesis.sources or runtime default trio (jobVariables, taskVariables, input). inputsConfig and smartInput.paths are MAIN only. preInputStrategy is rejected on new graphs (LEGACY_PRE_INPUT_STRATEGY).

Skill input synthesis profile (§3 — not SubNets)

"taskConfiguration": {
  "executionStrategies": [],
  "aiTaskProfile": {
    "inputSynthesis": {
      "enabled": true,
      "synthesisMode": "contextual",
      "contextSourcePolicy": "execution-memory-only"
    }
  }
}

No aiTaskStrategies.pre — different code path from PRE-phase utility synthesis.

Optional fact-guard (authoring — sub-actions only)

"taskConfiguration": {
  "aiTaskStrategies": { "pre": "synthesis", "post": "polish" },
  "factGuard": {
    "preSynthesis": {
      "enabled": true,
      "policyId": "prompt-context-synthesizer",
      "onViolation": "fallback"
    }
  }
}

Opt-in only — absent or enabled: false leaves compile unchanged. Validator requires policyId when enabled: true. See GLOSSARY §6.

Full task node parameters (substance + bindings + strategies)

{
  "profile": "graphenix.task-node/v1",
  "nodeType": "task",
  "skillKey": "professional-answer",
  "taskVariable": {
    "question": "What is the professional answer?",
    "outputContract": { "type": "object" }
  },
  "inputsConfig": {
    "record": { "path": "input.record" }
  },
  "smartInput": {
    "paths": [{ "path": "input.record", "label": "Record" }]
  },
  "executionMapping": {
    "path": "executionMemory.steps.node:answer",
    "mode": "replace"
  },
  "taskConfiguration": {
    "executionStrategies": [],
    "aiTaskStrategies": {
      "pre": "synthesis"
    }
  },
  "conditions": {
    "jsonConditions": [{ "path": "runtime.mode", "eq": "live" }]
  }
}

Phase model profiles (preActionModel, skillModel, postActionModel) are validated by @x12i/graphenix-executable-profile-format — see that README.

API

import { validateTaskNode } from "@x12i/graphenix-task-node-format";

const errors = validateTaskNode(node, graphDocument);

Typically called via validateAuthoringGraph() from @x12i/graphenix-authoring-format.

Related

• GLOSSARY.md
• @x12i/graphenix-authoring-format
• @x12i/graphenix-executable-profile-format — phase model profiles