# @x12i/graphenix-executable-format

> Umbrella package: re-exports graphenix executable lifecycle packages for convenience.

Latest version **2.17.0** (published 2026-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install @x12i/graphenix-executable-format
pnpm add @x12i/graphenix-executable-format
yarn add @x12i/graphenix-executable-format
bun add @x12i/graphenix-executable-format
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.17.0 |
| Published | 2026-07-10 |
| First published | 2026-06-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 12 |
| Unpacked size | 369.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | graph, graphenix, executable, workflow, validation, ai-profiles, profileChoice, deterministic |

## Links

- npm: https://www.npmjs.com/package/@x12i/graphenix-executable-format
- Repository: https://github.com/x12i/graphenix-format
- Homepage: https://github.com/x12i/graphenix-format/tree/master/packages/executable-format#readme
- Issues: https://github.com/x12i/graphenix-format/issues
- npm.io page: https://npm.io/package/@x12i/graphenix-executable-format

## Dependencies (12)

- [@x12i/graphenix-dot](https://npm.io/package/@x12i/graphenix-dot.md) ^2.17.0
- [@x12i/graphenix-core](https://npm.io/package/@x12i/graphenix-core.md) ^2.17.0
- [@x12i/graphenix-case-format](https://npm.io/package/@x12i/graphenix-case-format.md) ^2.17.0
- [@x12i/graphenix-plan-format](https://npm.io/package/@x12i/graphenix-plan-format.md) ^2.17.0
- [@x12i/graphenix-trace-format](https://npm.io/package/@x12i/graphenix-trace-format.md) ^2.17.0
- [@x12i/graphenix-plan-compiler](https://npm.io/package/@x12i/graphenix-plan-compiler.md) ^2.17.0
- [@x12i/graphenix-authoring-format](https://npm.io/package/@x12i/graphenix-authoring-format.md) ^2.17.0
- [@x12i/graphenix-execute-envelope](https://npm.io/package/@x12i/graphenix-execute-envelope.md) ^2.17.0
- [@x12i/graphenix-task-node-format](https://npm.io/package/@x12i/graphenix-task-node-format.md) ^2.17.0
- [@x12i/graphenix-authoring-analysis](https://npm.io/package/@x12i/graphenix-authoring-analysis.md) ^2.17.0
- [@x12i/graphenix-executable-contracts](https://npm.io/package/@x12i/graphenix-executable-contracts.md) ^2.17.0
- [@x12i/graphenix-executable-profile-format](https://npm.io/package/@x12i/graphenix-executable-profile-format.md) ^2.17.0

## Alternatives

- [apollo-link-http-common](https://npm.io/package/apollo-link-http-common.md) — 879.0K weekly downloads
- [react-relay](https://npm.io/package/react-relay.md) — 336.8K weekly downloads
- [relay-test-utils](https://npm.io/package/relay-test-utils.md) — 181.6K weekly downloads
- [@vendure/core](https://npm.io/package/@vendure/core.md) — 14.8K weekly downloads
- [@pnpm/deps.graph-sequencer](https://npm.io/package/@pnpm/deps.graph-sequencer.md) — 13.4K weekly downloads

## Recent versions

- 2.17.0 (latest) — 2026-07-10
- 2.16.0 — 2026-06-29
- 2.15.0 — 2026-06-29
- 2.14.0 — 2026-06-28
- 2.12.5 — 2026-06-28
- 2.12.4 — 2026-06-28
- 2.12.3 — 2026-06-27
- 2.12.2 — 2026-06-27
- 2.12.1 — 2026-06-27
- 2.12.0 — 2026-06-24
- 2.11.0 — 2026-06-24
- 2.10.0 — 2026-06-24
- 2.9.0 — 2026-06-23
- 2.8.1 — 2026-06-21
- 2.8.0 — 2026-06-21
- … 19 more at https://npm.io/package/@x12i/graphenix-executable-format/versions

## README

# @x12i/graphenix-executable-format

**Umbrella package** — re-exports the full Graphenix executable lifecycle for prototypes and all-in-one installs.

For production, depend on [lifecycle packages](#package-family) directly (design-only clients should not pull in plan-compiler or trace-format).

**Canonical vocabulary:** [GLOSSARY.md](../../GLOSSARY.md) · **Format scope:** [FORMAT-SCOPE.md](../../docs/FORMAT-SCOPE.md)

**Naming:** `@x12i/*` is the **npm scope only**. JSON documents use `graphenix.*` identifiers and plain node kinds (`task`, `finalizer`) — never `x12i` in saved payloads.

**Authoring interchange:** `AuthoringGraphDocument` at `formatVersion: "2.1.0"` is the sole authoring shape. Flat Exellix JSON is **import-only** (`legacyExellixGraphToGraphProject`). Engine handoff uses `authoringGraphToEngineDocument()`; compile uses `compileAuthoringGraphToExecutablePlan()` (no runtime on compile ingress).

---

## Who should use this

| Role | Prefer umbrella? | Prefer direct packages |
| ---- | :--------------: | ---------------------- |
| Prototype / spike | **Yes** | |
| Graph designer / editor | No | `@x12i/graphenix-authoring-format` + `@x12i/graphenix-case-format` |
| Compiler / execution prep | No | `@x12i/graphenix-plan-compiler` + `@x12i/graphenix-plan-format` |
| Execution engine | No | `@x12i/graphenix-plan-format` + `@x12i/graphenix-trace-format` |
| Backend host | No | `@x12i/graphenix-execute-envelope` |

---

## Install

```bash
npm install @x12i/graphenix-executable-format @x12i/graphenix-core
```

Built on [`@x12i/graphenix-core`](../core), with deterministic model cases validated against [`@x12i/ai-profiles`](https://www.npmjs.com/package/@x12i/ai-profiles).

---

## Full lifecycle (four phases)

Reference domain: **`graph:content-pipeline`** — parallel research → content package.  
Fixture: `createContentPipelineReferenceGraph()` from this package (re-exported from authoring-format).

```txt
┌─ DESIGN ─────────────────────────────────────────────────────────────┐
│ AuthoringGraphDocument + ConceptDocument (shadow, optional)          │
│ validateGraph + validateAuthoringGraph + validateConceptDocument     │
└───────────────────────────────┬──────────────────────────────────────┘
                                │ compileExecutablePlan(authoring, runtime)
┌─ COMPILE ─────────────────────▼──────────────────────────────────────┐
│ ExecutableGraphPlan                                                  │
│ validateExecutablePlan                                               │
└───────────────────────────────┬──────────────────────────────────────┘
                                │ engine runs executionUnits[] in order
┌─ EXECUTE + TRACE ─────────────▼──────────────────────────────────────┐
│ GraphExecutionTrace (append-only)                                    │
│ validateExecutionTrace                                               │
└──────────────────────────────────────────────────────────────────────┘
```

| Phase | Artifact | Validate with | Finalization brief |
| ----- | -------- | ------------- | ------------------ |
| Design | `AuthoringGraphDocument` | `validateGraph`, `validateAuthoringGraph` | [GRAPH-FORMAT-FINALIZATION.md](../../docs/GRAPH-FORMAT-FINALIZATION.md) |
| Design (shadow) | `ConceptDocument` | `validateConceptDocument` | [concept-document.md](../../docs/concept-document.md) |
| Compile | `ExecutableGraphPlan` | `validateExecutablePlan` | [COMPILE-FORMAT-FINALIZATION.md](../../docs/COMPILE-FORMAT-FINALIZATION.md) |
| Execute + trace | `GraphExecutionTrace` | `validateExecutionTrace` | [EXECUTE-TRACE-FORMAT-FINALIZATION.md](../../docs/EXECUTE-TRACE-FORMAT-FINALIZATION.md) |

**Role guides:** [docs/roles/README.md](../../docs/roles/README.md)

---

## Package family

```txt
@x12i/graphenix-core
        │
        ▼
@x12i/graphenix-executable-contracts
        │
        ├── @x12i/graphenix-case-format
        ├── @x12i/graphenix-executable-profile-format
        ├── @x12i/graphenix-task-node-format
        ├── @x12i/graphenix-authoring-format
        ├── @x12i/graphenix-authoring-analysis
        ├── @x12i/graphenix-plan-format
        └── @x12i/graphenix-trace-format
                    ▲
                    │
        @x12i/graphenix-plan-compiler
                ▲
                │
        @x12i/graphenix-execute-envelope   (optional host adapter)

@x12i/graphenix-executable-format        ← this package (re-exports all above)
```

| Package | Phase | README |
| ------- | ----- | ------ |
| `@x12i/graphenix-executable-contracts` | Shared types | [executable-contracts/README.md](../executable-contracts/README.md) |
| `@x12i/graphenix-case-format` | Design | [case-format/README.md](../case-format/README.md) |
| `@x12i/graphenix-task-node-format` | Design | [task-node-format/README.md](../task-node-format/README.md) |
| `@x12i/graphenix-executable-profile-format` | Design | [executable-profile-format/README.md](../executable-profile-format/README.md) |
| `@x12i/graphenix-authoring-format` | Design | [authoring-format/README.md](../authoring-format/README.md) |
| `@x12i/graphenix-authoring-analysis` | Design (studio save) | [authoring-analysis/README.md](../authoring-analysis/README.md) |
| `@x12i/graphenix-plan-compiler` | Compile | [plan-compiler/README.md](../plan-compiler/README.md) |
| `@x12i/graphenix-plan-format` | Compile + execute input | [plan-format/README.md](../plan-format/README.md) |
| `@x12i/graphenix-execute-envelope` | Execute prep | [execute-envelope/README.md](../execute-envelope/README.md) |
| `@x12i/graphenix-trace-format` | Execute + observability | [trace-format/README.md](../trace-format/README.md) |

---

## JSON identifiers (format payloads)

| Field | Value |
| ----- | ----- |
| Task node `kind` | `"task"` |
| Finalizer node `kind` | `"finalizer"` |
| Task `parameters.profile` | `"graphenix.task-node/v1"` |
| Finalizer `parameters.profile` | `"graphenix.finalizer-node/v1"` |
| Executable extension key | `"graphenix.executable/v1"` |
| Plan `format` | `"graphenix.executable-plan/v1"` or `v2` |
| Trace `format` | `"graphenix.execution-trace/v1"` or `v2` |
| Concept `formatVersion` | `"graphenix.concept/v1"` |

---

## Phase 1 — Design (authoring)

### Task run phases (vocabulary)

One task node = one `runTask` wave: **prePhase → mainPhase → postPhase**.  
See [GLOSSARY §1–§5](../../GLOSSARY.md).

**Explicit rule:** `aiTaskStrategies.pre: "synthesis"` (PRE-phase utility strategy) ≠ `aiTaskProfile.inputSynthesis.enabled` (skill input synthesis profile → plan `pipelinePhase`). Do not use “Synthesis PRE”.

### Two-tier validation

```ts
import { validateGraph } from "@x12i/graphenix-core";
import {
  validateAuthoringGraph,
  validateConceptDocument,
  createContentPipelineReferenceGraph
} from "@x12i/graphenix-executable-format";

const doc = createContentPipelineReferenceGraph();

validateGraph(doc);
validateAuthoringGraph(doc);

validateConceptDocument({
  formatVersion: "graphenix.concept/v1",
  graphId: doc.id,
  name: doc.name,
  graphConcept: {
    primaryIntentStatement: "Turn a campaign brief into a structured content package."
  }
});
```

### Authoring task node (JSON excerpt)

```json
{
  "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",
        "preInputStrategy": "execution-memory-only"
      }
    }
  }
}
```

### Phase model profiles (extension)

```json
"metadata": {
  "extensions": {
    "graphenix.executable/v1": {
      "profileVersion": "1.0.0",
      "modelConfig": {
        "version": "graph-model-config/v1",
        "cases": [{
          "id": "default",
          "modelConfig": {
            "preActionModel": { "kind": "profileChoice", "key": "cheap/default" },
            "skillModel": { "kind": "profileChoice", "key": "vol/default" },
            "postActionModel": { "kind": "profileChoice", "key": "cheap/default" }
          }
        }]
      }
    }
  }
}
```

### Design APIs

| API | Purpose |
| --- | ------- |
| `validateAuthoringGraph` | Executable profile + full task-node body |
| `validateConceptDocument` | Studio shadow document |
| `validateCaseCondition` / `evaluateCaseCondition` | Deterministic `when` DSL |
| `selectGraphModelCase` / `selectNodeModelCase` | Case preview at design time |
| `resolveNodeAiPlan` / `explainNodeInheritance` | Preview slot resolution |
| `normalizeExecutableGraph` | Canonical model config (non-mutating) |
| `stripDesignOnlyFieldsFromGraph` | Remove `node.layout` before plan embed |
| `createMinimalExecutableGraph` | One task + finalizer |
| `createContentPipelineReferenceGraph` | Canonical reference graph |
| `addTaskNode`, `setGraphModelConfig`, … | CRUD helpers |

### Deterministic cases (summary)

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

Allowed selectors: `runtime.mode`, `runtime.input.*`, `runtime.environment`, `graph.id`, …  
Forbidden: `ai.*`, `node.output.*`, `semanticMatch`, LLM-based conditions.

Full DSL: [case-format/README.md](../case-format/README.md).

---

## Phase 2 — Compile (authoring → plan)

### Design → plan mapping

| Authoring (design) | Plan execution unit | Run phase |
| ------------------ | ------------------- | --------- |
| `aiTaskStrategies.pre` | `externalPreUtility` | prePhase |
| `skillKey` + plain MAIN | `mainSkill` | mainPhase |
| `aiTaskProfile.inputSynthesis` | `pipelinePhase` | mainPhase |
| `aiTaskStrategies.post` | `externalPostUtility` | postPhase |
| Phase model profiles | `modelSlot` + `modelSelection` on each unit | per phase |

Content pipeline reference tasks: PRE synthesis + MAIN only (no POST unless design declares it).

### Compile flow

```ts
import {
  createContentPipelineReferenceGraph,
  compileExecutablePlan,
  validateExecutablePlan,
  buildRuntimeObject
} from "@x12i/graphenix-executable-format";

const authoring = createContentPipelineReferenceGraph();
const runtime = buildRuntimeObject({
  jobId: "job-001",
  mode: "live",
  input: { priority: "normal" }
});

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

const result = validateExecutablePlan(plan);
if (!result.valid) throw new Error("Invalid plan");
```

Internal pipeline:

```txt
validateAuthoringExecutableGraph()
normalizeExecutableGraph()
stripDesignOnlyFieldsFromGraph()     ← node.layout removed
assertNormalizedExecutableGraph()
selectGraphModelCase() → resolveNodeAiPlan() per task node
buildNodeExecutionUnits()            ← PRE / MAIN / POST from aiTaskStrategies
buildFinalizerPlans()
validateExecutablePlan()             ← recommended before handoff
```

### Compiled plan (JSON excerpt — v2)

```json
{
  "format": "graphenix.executable-plan/v2",
  "source": { "graphId": "graph:content-pipeline" },
  "nodePlans": {
    "node:audience-insights": {
      "executionUnits": [
        {
          "unitKind": "externalPreUtility",
          "order": 0,
          "strategyKey": "synthesis",
          "modelSlot": "preActionModel"
        },
        {
          "unitKind": "mainSkill",
          "order": 1,
          "skillKey": "professional-answer",
          "modelSlot": "skillModel"
        }
      ]
    }
  }
}
```

### Compile APIs

| API | Purpose |
| --- | ------- |
| `compileExecutablePlan` | Authoring + runtime → plan |
| `validateExecutablePlan` | Validate v1 or v2 plan |
| `buildDeterministicCaseContext` | Freeze pre-run context |
| `buildGraphExecutionRequestFromStudioExecute` | Host adapter: request → `{ plan, runtime }` |

Details: [plan-compiler/README.md](../plan-compiler/README.md) · [plan-format/README.md](../plan-format/README.md)

---

## Phase 3 — Execute (engine)

The engine consumes **only** `{ plan, runtime }`. It never reads authoring graphs.

### Execution order

1. `validateExecutablePlanV2(plan)` on receipt
2. Evaluate `plan.deferredGates` (entry → node → edge) before scheduling
3. Walk task nodes in topological order; parallel branches may run concurrently when policy allows
4. Per task node: PRE units → MAIN → POST; delegate unit loop to node executor via `runTask({ nodePlan })`
5. Apply mapping units in orchestrator after `runTask` returns
6. Run finalizer phase after all upstream tasks complete
7. `validateTraceAgainstPlan(trace, plan)` at run end

Each unit uses frozen `modelSelection` from the plan — no case re-selection at runtime.

**Security checklist:** never forward Studio credentials into `GraphRuntimeObject`; reject `taskConfiguration` on `RunTaskRequest` when `nodePlan` is present; set `RunTaskRequest.input` from `runtime.input` (see [run-task-data-model.md](../../docs/guides/run-task-data-model.md)).

Golden handoff: `packages/plan-format/fixtures/content-pipeline.plan.json`.

### Execute APIs (from this package)

| API | Package origin |
| --- | -------------- |
| `validateExecutablePlan` | plan-format |
| `createExecutionTrace` | trace-format |
| `appendExecutionEvent` | trace-format |

Details: [docs/roles/execution-engine.md](../../docs/roles/execution-engine.md)

---

## Phase 4 — Trace (evidence)

Traces are **append-only** and bound to `planHash`. Prefer **v2** traces when the plan is v2 (`graphenix.execution-trace/v2`).

Reference fixtures:

- `createContentPipelineReferenceTrace(plan)` — programmatic complete CP run
- `packages/trace-format/fixtures/content-pipeline.trace.json` — golden JSON (3 tasks + finalizer)

Multi-node timeline for content pipeline: `graph.started` → parallel `unit.*` on three task nodes → `node.completed` × 3 → finalizer `unit.*` → `graph.completed`.

```ts
import {
  createExecutionTrace,
  appendExecutionEvent,
  validateExecutionTrace,
  deriveGraphStatus,
  summarizeExecutionTrace
} from "@x12i/graphenix-executable-format";

const trace = createExecutionTrace(plan, runtime);

appendExecutionEvent(trace, {
  id: "evt:1",
  ts: new Date().toISOString(),
  level: "info",
  type: "graph.started",
  message: "Graph execution started."
});

appendExecutionEvent(trace, {
  id: "evt:2",
  ts: new Date().toISOString(),
  level: "info",
  type: "node.started",
  nodeId: "node:audience-insights"
});

appendExecutionEvent(trace, {
  id: "evt:3",
  ts: new Date().toISOString(),
  level: "info",
  type: "unit.started",
  nodeId: "node:audience-insights",
  unitId: "unit:node:audience-insights:pre:0",
  unitKind: "externalPreUtility"
});

validateExecutionTrace(trace, plan.nodePlans);
const status = deriveGraphStatus(trace);
```

### Trace header (JSON excerpt)

```json
{
  "format": "graphenix.execution-trace/v1",
  "traceId": "trace:job-001",
  "jobId": "job-001",
  "source": { "graphId": "graph:content-pipeline", "graphHash": "sha256:…" },
  "plan": { "planId": "plan:abc123", "planHash": "sha256:…" },
  "events": []
}
```

Details: [trace-format/README.md](../trace-format/README.md) · [docs/roles/observability.md](../../docs/roles/observability.md)

---

## Validation tiers (summary)

| When | Call |
| ---- | ---- |
| Authoring save | `validateGraph` + `validateAuthoringGraph` |
| Concept save | `validateConceptDocument` |
| After compile | `validateExecutablePlan` |
| After run | `validateExecutionTrace(trace, plan.nodePlans)` |

---

## End-to-end example (umbrella import)

```ts
import { validateGraph } from "@x12i/graphenix-core";
import {
  createContentPipelineReferenceGraph,
  validateAuthoringGraph,
  compileExecutablePlan,
  validateExecutablePlan,
  buildRuntimeObject,
  createExecutionTrace,
  appendExecutionEvent,
  validateExecutionTrace
} from "@x12i/graphenix-executable-format";

// Design
const authoring = createContentPipelineReferenceGraph();
validateGraph(authoring);
validateAuthoringGraph(authoring);

// Compile
const runtime = buildRuntimeObject({ jobId: "job-001", mode: "live", input: {} });
const plan = compileExecutablePlan(authoring, runtime);
validateExecutablePlan(plan);

// Execute + trace (engine loop abbreviated)
const trace = createExecutionTrace(plan, runtime);
appendExecutionEvent(trace, {
  id: "evt:1",
  ts: new Date().toISOString(),
  level: "info",
  type: "graph.completed",
  message: "Done."
});
validateExecutionTrace(trace, plan.nodePlans);
```

---

## Profile choice format

```json
{ "kind": "profileChoice", "key": "vol/default" }
```

Examples: `cheap/default`, `vol/default`, `vol/pro`, `deep/openai_deep`.  
Rejected: bare aliases, `kind: "profile"`, vendor slugs as profileChoice keys.

`profileChoice` resolves at compile/plan time via `@x12i/ai-profiles` — not during normalization.

---

## Model inheritance and fallback

- Graph-level `modelConfig` is **required** with full triplet per case (`preActionModel`, `skillModel`, `postActionModel`).
- Node overrides may be partial when `inherit: true`.
- Fallback is **same-slot only** on the selected graph case — never cross-slot or runtime defaults.

---

## Node kinds

| `kind` | `parameters.profile` | Purpose |
| ------ | -------------------- | ------- |
| `task` | `graphenix.task-node/v1` | Skill + phase utility strategies |
| `finalizer` | `graphenix.finalizer-node/v1` | Graph output (`finalizerType`: `aggregate`, `compose`, …) |

Design-only: `node.layout` — stripped at compile, never on plan.

---

## Development

From monorepo root:

```bash
npm install
npm run build --workspace=@x12i/graphenix-executable-format
npm run test --workspace=@x12i/graphenix-executable-format
```

## Schema

Profile JSON Schema fragment: `schema/graphenix-executable-format-1.0.0.schema.json` (structural subset; full semantics enforced by TypeScript validators).

## Further reading

| Doc | Topic |
| --- | ----- |
| [GLOSSARY.md](../../GLOSSARY.md) | Phase vocabulary |
| [FORMAT-SCOPE.md](../../docs/FORMAT-SCOPE.md) | Compliance + strict profiles |
| [NAMING.md](../../docs/NAMING.md) | npm `@x12i/*` vs JSON `graphenix.*` |
| [PUBLISHING.md](../../PUBLISHING.md) | npm publish order |
| [docs/IMPLEMENTATION-REPORT.md](./docs/IMPLEMENTATION-REPORT.md) | Acceptance test matrix |

---
_Source: https://npm.io/package/@x12i/graphenix-executable-format · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._