# @x12i/graphenix-core

> Graphenix core tier: format 2.1.0 JSON schema, validation, and CRUD helpers.

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

## Install

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

## 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 | 1 |
| Unpacked size | 112.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | graph, workflow, json-schema, validation, graphenix |

## Links

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

## Dependencies (1)

- [ajv](https://npm.io/package/ajv.md) ^8.20.0

## Alternatives

- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads
- [@oridune/validator](https://npm.io/package/@oridune/validator.md) — 16 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.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
- 2.7.3 — 2026-06-20
- 2.7.2 — 2026-06-20
- … 8 more at https://npm.io/package/@x12i/graphenix-core/versions

## README

# @x12i/graphenix-core

Core tier of the Graphenix ecosystem — **Format 2.1.0** JSON wire layout (`@x12i/graphenix-core@^2.3.0` on npm).

Execution-neutral graph description: JSON schema, TypeScript types, validation, and CRUD helpers. Profile packages build strict subtypes on top of this core via generic metadata, typed parameters, and `validateGraphWithProfile()`.

## Install

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

## Validate a graph document

```ts
import {
  validateGraph,
  GRAPHENIX_FORMAT_VERSION,
  type GraphDocument
} from "@x12i/graphenix-core";

const doc: GraphDocument = {
  formatVersion: GRAPHENIX_FORMAT_VERSION,
  id: "graph:auth/user-signup",
  graph: {
    nodes: [],
    edges: [],
    inputs: [],
    outputs: []
  }
};

const result = validateGraph(doc);
if (!result.valid) {
  console.error(result.errors);
}
```

Each error is a `GraphValidationError`:

- **`message`** — human-readable message
- **`path`** — JSON Pointer to the failing instance
- **`keyword`** / **`params`** — from AJV when applicable
- **`source`** — `'graphenix'` or `'profile'`
- **`code`** — optional profile-specific error code

---

## Document fields

| Field | Required | Description |
| ----- | -------- | ----------- |
| `formatVersion` | yes | Must be `"2.1.0"` — export `GRAPHENIX_FORMAT_VERSION`. Persist validators reject `2.0.0`, `2.1.1`, and other drift (`AUTHORING_FORMAT_VERSION_UNSUPPORTED`); use legacy import adapters for uplift, not silent migration. |
| `id` | yes | Globally unique graph identifier |
| `revision` | no | Version of this graph document (not the format version) |
| `graph` | yes | Structural graph (nodes, edges, inputs, outputs) |
| `metadata` | no | Document metadata, extensions, summary contracts |
| `types` | no | Custom type definitions |
| `subgraphs` | no | Inlined reusable graphs |

---

## Graph metadata (format 2.1.0)

Executable-profile graphs use first-class graph metadata fields. Core validates object shape; profile packages validate semantics.

```txt
graph.metadata
├── graphEntry      entry contract, execution schema
├── graphResponse   response shape, final output schema
├── modelConfig     graph-wide AI model cases (profile packages validate)
└── data            optional client keys (variables, presets, …)
```

```json
{
  "graph": {
    "metadata": {
      "modelConfig": { "cases": [] },
      "data": { "variables": {} }
    }
  }
}
```

Do not emit `metadata.extensions` on new authoring graphs. Migration from 2.0.0 layout: [docs/guides/migration-tier-1-authoring.md](../../docs/guides/migration-tier-1-authoring.md).

---

## Generic types for profile subtypes

```ts
import type { GraphDocument, GraphMetadata, GraphenixMetadata } from "@x12i/graphenix-core";

interface X12iGraphMetadata extends GraphMetadata {
  modelConfig: { cases: unknown[] };
  data?: { variables?: Record<string, unknown> };
}

type X12iNodeParameters = { skillKey: string };

type X12iExecutableGraphDocument = GraphDocument<
  GraphenixMetadata,
  X12iGraphMetadata,
  X12iNodeParameters,
  GraphenixMetadata
>;
```

Aliases: `GraphNode`, `GraphEdge`, `GraphPort`, `GraphType`, `Subgraph`.

---

## Profile validation

```ts
import {
  validateGraphWithProfile,
  type GraphProfileValidator,
  type GraphValidationError
} from "@x12i/graphenix-core";

const validateX12iProfile: GraphProfileValidator = (doc) => {
  const errors: GraphValidationError[] = [];
  const modelConfig = doc.graph.metadata?.modelConfig;
  if (!modelConfig || typeof modelConfig !== "object") {
    errors.push({
      source: "profile",
      code: "GRAPHENIX_MODEL_CONFIG_MISSING",
      message: "Executable profile is missing modelConfig.",
      path: "/graph/metadata/modelConfig"
    });
  }
  return { valid: errors.length === 0, errors };
};

validateGraphWithProfile(doc, validateX12iProfile);
```

Base validation runs first; profile validation runs only when base validation passes.

---

## Input and output contracts

**Per-port input contract** — `graph.inputs[].contract`:

```json
{
  "id": "rawRecord",
  "type": "object",
  "target": { "nodeId": "q1", "portId": "record" },
  "contract": {
    "semanticKind": "record",
    "required": true,
    "schema": { "type": "object" }
  }
}
```

**Per-port output contract** — `graph.outputs[].contract`:

```json
{
  "id": "graph-output:final",
  "type": "builtin:object",
  "source": { "nodeId": "node:finalizer", "portId": "out:final" },
  "contract": {
    "semanticKind": "final-output",
    "required": true,
    "schema": { "type": "object" }
  }
}
```

**Graph-level summary contracts** — complement per-port contracts:

| Layer | Purpose |
| ----- | ------- |
| `graph.inputs[].contract` | Contract for a specific graph input port |
| `metadata.graphEntry` | Summary contract for graph invocation |
| `graph.outputs[].contract` | Contract for a specific graph output port |
| `metadata.graphResponse` | Summary contract for final graph result |

Optional AJV checks against `executionSchema` / `finalOutputSchema`:

```ts
import {
  validateExecutionAgainstContract,
  validateFinalOutputAgainstContract
} from "@x12i/graphenix-core";
```

See [`docs/interop-worox-graph.md`](./docs/interop-worox-graph.md) for worox-graph interop notes.

---

## CRUD helpers

Immutable by default; pass `{ mutate: true }` to modify in place.

```ts
import { addNode, updateNode, removeNode, addEdge } from "@x12i/graphenix-core";
```

- **Nodes**: `getNode`, `addNode`, `updateNode`, `removeNode`
- **Edges**: `getEdge`, `addEdge`, `updateEdge`, `removeEdge`
- **Types**: `getType`, `addType`, `updateType`, `removeType`
- **Subgraphs**: `getSubgraph`, `addSubgraph`, `updateSubgraph`, `removeSubgraph`

---

## Test Utilities (Golden Fixtures)

The core package provides utilities for maintaining "golden" fixtures. This is particularly useful during the **authoring stage** to ensure the generated documents match a stable reference, helping the user understand the structure of what they have.

```ts
import { assertGoldenFixture } from "@x12i/graphenix-core/test-utils";

const actual = { /* ... your generated graph ... */ };
const fixturePath = "./fixtures/my-graph.json";

// Asserts that 'actual' matches the JSON in 'fixturePath'.
// If the file is missing or differs, it throws an error.
// Set UPDATE_FIXTURES=true to create or update the fixture automatically.
assertGoldenFixture(actual, fixturePath, {
  graphenixMasks: true // Automatically mask dynamic fields like planId, createdAt, etc.
});
```

| Option | Purpose |
| --- | --- |
| `update` | If true, creates/updates the fixture file. |
| `graphenixMasks` | If true, masks common dynamic fields (`planId`, `createdAt`, `*Hash`, etc.). |
| `mask` | Array of additional keys to mask recursively. |
| `scrub` | Custom function to transform data before comparison. |

| API | Purpose |
| --- | --- |
| `matchGoldenFixture` | Returns a structured result (`pass`, `wrote`, `actual`, `expected`, `message`) |
| `assertGoldenFixture` | Throws an `AssertionError` if the match fails (and update is not enabled) |
| `maskKeys` | Recursive helper to replace keys with placeholders |

---

## JSON Schema

Published at `schema/graphenix-format-2.1.0.schema.json` (`$id`: `https://graphenix.dev/schema/graphenix-format-2.1.0.json`). Legacy `2.0.0` schema retained for reference only.

Full field reference: [`GRAPHENIX-FORMAT.md`](./GRAPHENIX-FORMAT.md).

---

## Development

From the monorepo root:

```bash
npm install
npm run build
npm test
```

Or from this package:

```bash
npm run build
npm test
```

---

## Notes

- **Execution-agnostic** — core defines structure only.
- Profile packages enforce execution semantics via `metadata.modelConfig`, typed node parameters, and profile validators.
- Client-specific fields live in `metadata.data`; core validates object type only.
- Task-node field names and phase vocabulary: [GLOSSARY.md](../../GLOSSARY.md) (monorepo root).

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