@x12i/graphenix-plan-compiler

@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 (optional)                 → mainSkill invokeContract.reads (MAIN only; default ["input"] when absent)
  + 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