@x12i/graphenix-case-format

Deterministic case condition DSL for executable graphs: validate conditions, evaluate them against pre-run context, and select graph/node model cases.

Case evaluation is pure, deterministic, bounded, and non-AI. Forbidden selectors (ai.*, node.output.*, semanticMatch, etc.) are rejected at validation time.

Canonical vocabulary: GLOSSARY.md §4 — phase model profiles (preActionModel, skillModel, postActionModel).
Design brief: GRAPH-FORMAT-FINALIZATION.md · Compile brief: COMPILE-FORMAT-FINALIZATION.md.

Cases are selected at compile time only — the engine uses frozen modelSlots on the plan.

Who should use this

| Role | Use this package? | | ---- | ----------------- | | Graph designer / Studio (case editor) | Yes | | Compiler service | Usually via @x12i/graphenix-plan-compiler | | Engine at runtime | No — cases are resolved at compile time |

Content pipeline example (graph-level cases)

From createContentPipelineReferenceGraph() / contentPipelineModelConfig():

"cases": [
  {
    "id": "default",
    "modelConfig": {
      "preActionModel": { "kind": "profileChoice", "key": "cheap/default" },
      "skillModel": { "kind": "profileChoice", "key": "vol/default" },
      "postActionModel": { "kind": "profileChoice", "key": "cheap/default" }
    }
  },
  {
    "id": "rush",
    "when": { "path": "runtime.input.priority", "op": "eq", "value": "rush" },
    "modelConfig": {
      "preActionModel": { "kind": "profileChoice", "key": "vol/default" },
      "skillModel": { "kind": "profileChoice", "key": "deep/openai_deep" },
      "postActionModel": { "kind": "profileChoice", "key": "vol/default" }
    }
  }
]

When runtime.input.priority === "rush" at compile time, the rush case is selected and frozen on the plan.

Node-level override example

Partial override of MAIN-phase model profile only:

"taskConfiguration": {
  "modelConfig": {
    "inherit": true,
    "cases": [{
      "id": "high-risk",
      "when": { "path": "runtime.input.riskLevel", "op": "eq", "value": "high" },
      "modelConfig": {
        "skillModel": { "kind": "profileChoice", "key": "deep/openai_deep" }
      }
    }]
  }
}

Install

npm install @x12i/graphenix-case-format

Example (API)

import {
  validateCaseCondition,
  evaluateCaseCondition,
  selectGraphModelCase,
  selectNodeModelCase
} from "@x12i/graphenix-case-format";
import type { DeterministicCaseContext } from "@x12i/graphenix-executable-contracts";

const context: DeterministicCaseContext = {
  runtime: { mode: "live", input: { priority: "rush" } },
  graph: { id: "graph:content-pipeline" }
};

validateCaseCondition({
  path: "runtime.input.priority",
  op: "eq",
  value: "rush"
});

const matched = evaluateCaseCondition(
  { path: "runtime.input.priority", op: "eq", value: "rush" },
  context
);

const graphCase = selectGraphModelCase(
  {
    version: "graph-model-config/v1",
    cases: [
      { id: "default", modelConfig: { skillModel: { kind: "profileChoice", key: "vol/default" } } },
      {
        id: "rush",
        when: { path: "runtime.input.priority", op: "eq", value: "rush" },
        modelConfig: { skillModel: { kind: "profileChoice", key: "deep/openai_deep" } }
      }
    ]
  },
  context
);
// → "rush" when priority is rush, else "default"

Key exports

| API | Purpose | | --- | ------- | | validateCaseCondition | Structural + security validation of a condition | | evaluateCaseCondition | Evaluate a condition against deterministic context | | explainMatchedCondition | Human-readable match explanation | | selectGraphModelCase | Pick graph-level model case | | selectNodeModelCase | Pick node-level model case | | isAllowedCasePath / isForbiddenCasePath | Path guardrails |

Allowed path roots

runtime.mode, runtime.environment, runtime.job.*, runtime.input.*,
runtime.variables.*, runtime.flags.*, runtime.context.*,
graph.id, graph.revision

Forbidden: ai.*, node.output.*, semanticMatch, LLM-based selectors.

Critical rule

Cases may choose stronger or weaker AI profiles.
AI may not choose the case.

Dependencies

• @x12i/graphenix-executable-contracts ^1.0.0

Related packages

| Package | Role | | ------- | ---- | | @x12i/graphenix-authoring-format | Validates cases inside authoring graphs | | @x12i/graphenix-plan-compiler | Selects cases when compiling plans | | @x12i/graphenix-executable-profile-format | Phase model profile slots on extension |