@x12i/graphenix-plan-compiler

Plan compiler — transforms AuthoringGraphDocument + GraphRuntimeObject into an immutable ExecutableGraphPlan.

Handles normalization, deterministic case selection, phase model profile resolution, run-phase execution unit building, profile registry attachment, and plan hashing.

Canonical vocabulary: GLOSSARY.md.
Finalization brief: COMPILE-FORMAT-FINALIZATION.md.
When compile output for task run phases changes, update this README, plan-format/README.md, and GLOSSARY.md together.

Who should use this

| Role | Use this package? | | ---- | ----------------- | | Compiler / execution prep service | Yes | | Backend host | Often via @x12i/graphenix-execute-envelope | | Engine | No — receive the compiled plan, do not compile at runtime | | Graph designer / Studio | Only for compile preview |

Design → plan (phase mapping)

Authoring (task-node-format)              Plan (plan-format)
────────────────────────────              ────────────────────
prePhase.strategyKey                      PRE-phase execution units
  aiTaskStrategies.pre                      externalPreUtility / preAction
  + aiTaskProfile.inputSynthesis.sources    → invokeContract.reads + unitParams.memoryPaths (PRE only)

mainPhase.executionStrategies             MAIN-phase execution units
  + inputsConfig                            → mainSkill invokeContract.reads (MAIN only)
  + aiTaskProfile.inputSynthesis.enabled    pipelinePhase (MAIN skill input synthesis profile)

postPhase.strategyKey                       POST-phase execution units
  aiTaskStrategies.post                       externalPostUtility / postAction

graphenix.executable/v1 model cases              Resolved modelSlots on nodePlans
  preActionModel / skillModel / postActionModel

See GLOSSARY §5: preActions[] on design is optional; compiler may expand strategy keys into plan action lists.

Optional fact-guard: when taskConfiguration.factGuard is present, the compiler pass-through copies preSynthesis / postPolish / postAudit / postAuditMerge into the matching unit unitParams (never sets enabled: true implicitly). executionStrategy stays request-level — graph-engine maps to RunTaskRequest.executionStrategies[].factGuard. See GLOSSARY §6.

Examples (JSON)

Authoring input (design — phase utility strategies)

{
  "id": "node:audience-insights",
  "kind": "task",
  "layout": { "x": 120, "y": 200 },
  "parameters": {
    "profile": "graphenix.task-node/v1",
    "nodeType": "task",
    "skillKey": "professional-answer",
    "taskConfiguration": {
      "executionStrategies": [],
      "aiTaskStrategies": {
        "pre": "synthesis"
      }
    }
  }
}

Fixture: createContentPipelineReferenceGraph() — graph:content-pipeline. When authoring declares aiTaskStrategies.post, the compiler appends POST-phase units.

Graph-level phase model profiles live in graph.metadata.extensions["graphenix.executable/v1"].modelConfig (see executable-profile-format README).

Compiled plan output (excerpt — PRE + MAIN only)

Content pipeline reference tasks declare PRE synthesis + plain MAIN — no POST unless design sets aiTaskStrategies.post:

"nodePlans": {
  "node:audience-insights": {
    "executionUnits": [
      {
        "unitKind": "externalPreUtility",
        "order": 0,
        "strategyKey": "synthesis",
        "modelSlot": "preActionModel"
      },
      {
        "unitKind": "mainSkill",
        "order": 1,
        "skillKey": "professional-answer",
        "modelSlot": "skillModel"
      }
    ]
  }
}

Design prePhase.strategyKey → plan PRE-phase execution unit. Not the same JSON field as preActions[] on authoring.

Runtime object (compile input)

{
  "jobId": "job-001",
  "mode": "live",
  "environment": "prod",
  "input": { "riskLevel": "low" }
}

Install

npm install @x12i/graphenix-plan-compiler @x12i/graphenix-plan-format

Example

import { compileExecutablePlan } from "@x12i/graphenix-plan-compiler";
import { validateExecutablePlan } from "@x12i/graphenix-plan-format";

const plan = compileExecutablePlan(authoringGraph, runtime, {
  profileRegistry: { package: "@x12i/ai-profiles", version: "3.2.0" }
});

validateExecutablePlan(plan);
// → hand { plan, runtime } to the engine

Compile pipeline

validateAuthoringExecutableGraph()
normalizeExecutableGraph()
assertNormalizedExecutableGraph()
selectGraphModelCase() → resolveNodeAiPlan() per task node
buildNodeExecutionUnits()     ← PRE / MAIN / POST phase units
buildFinalizerPlans()
validateExecutablePlan()      ← recommended before handoff

Key exports

| API | Purpose | | --- | ------- | | compileExecutablePlan | Authoring + runtime → v1 plan (legacy) | | compileExecutablePlanV2 | Authoring + runtime → v2 plan (canonical) | | createContentPipelineReferencePlan | Compile graph:content-pipeline reference fixture | | buildNodeExecutionUnits | Build PRE / MAIN / POST execution units for a node | | resolveGraphModelConfig / resolveNodeModelConfig | Case selection + inheritance | | resolveNodeModelSlot | Resolve a single phase model profile slot | | resolveNodeAiPlan / resolveAllNodeAiPlans | Full node AI plan | | buildDeterministicCaseContext | Freeze pre-run context for case selection | | explainNodeInheritance | Explain graph/node case and slot provenance |

Important rules

• Case selection uses pre-run context only. In-run node output cannot change model case selection unless explicitly modeled as a separate compile stage.
• Design-only fields (e.g. node.layout) are stripped from the embedded normalized graph via stripDesignOnlyFieldsFromGraph() at compile time.
• Do not describe compile output using “Synthesis PRE”; use PRE-phase utility strategy vs skill input synthesis profile per GLOSSARY.md.

Dependencies

• @x12i/graphenix-authoring-format ^1.0.0
• @x12i/graphenix-case-format ^1.0.0
• @x12i/graphenix-executable-contracts ^1.0.0
• @x12i/graphenix-core ^2.3.0 (peer)
• @x12i/ai-profiles ^3.2.0

Related packages

| Package | Role | | ------- | ---- | | GLOSSARY.md | Canonical vocabulary | | @x12i/graphenix-plan-format | Validate compiled plans | | @x12i/graphenix-execute-envelope | Host adapter that calls this compiler | | Compiler role guide | Client guide |