@x12i/graphenix-case-format

@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