# @x12i/graphenix-authoring-format

> Authoring graph format: Design/Edit validation, CRUD helpers, and profile-choice validation.

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

## Install

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

## Health

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

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance 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 | 6 |
| Unpacked size | 277 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | graph, graphenix, authoring, validation |

## Links

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

## Dependencies (6)

- [@x12i/ai-profiles](https://npm.io/package/@x12i/ai-profiles.md) ^4.2.1
- [@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-task-node-format](https://npm.io/package/@x12i/graphenix-task-node-format.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.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
- … 19 more at https://npm.io/package/@x12i/graphenix-authoring-format/versions

## README

# @x12i/graphenix-authoring-format

**Authoring graph format** — the Design/Edit document editors and generators validate in memory before save.

Validates `AuthoringGraphDocument`, `ConceptDocument` (shadow), deterministic model cases, task/finalizer nodes, phase utility strategies, and `profileChoice` keys via `@x12i/ai-profiles`.

**Task-node vocabulary:** [GLOSSARY.md](../../GLOSSARY.md) · **Format scope:** [FORMAT-SCOPE.md](../../docs/FORMAT-SCOPE.md) · **Design brief:** [GRAPH-FORMAT-FINALIZATION.md](../../docs/GRAPH-FORMAT-FINALIZATION.md)

**Naming:** `@x12i/*` is npm scope only. JSON uses `graphenix.*` profiles and plain kinds `task` / `finalizer`.

---

## Task node design shape

```txt
Task node (design authoring)
│
├─ taskVariable.*              task substance
├─ inputs / inputsConfig       input bindings
├─ smartInput / executionMapping
│
├─ taskConfiguration
│   ├─ prePhase (aiTaskStrategies.pre + preInputStrategy)
│   ├─ mainPhase (executionStrategies — `[]` = explicit plain MAIN)
│   │     └─ skillProfile.inputSynthesis (aiTaskProfile.inputSynthesis)
│   └─ postPhase (aiTaskStrategies.post)
│
└─ graphenix.executable/v1 → preActionModel / skillModel / postActionModel
```

`preActions[]` / `postActions[]` are plan-phase action lists — not synonyms for `aiTaskStrategies.pre`.

---

## Example authoring graph (JSON)

Content pipeline task with PRE-phase utility strategy `synthesis` + plain MAIN:

```json
{
  "formatVersion": "2.0.0",
  "id": "graph:content-pipeline",
  "revision": "1.0.0",
  "name": "Content pipeline",
  "graph": {
    "nodes": [
      {
        "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"
            }
          }
        }
      },
      {
        "id": "node:finalizer:package",
        "kind": "finalizer",
        "parameters": {
          "profile": "graphenix.finalizer-node/v1",
          "nodeType": "finalizer",
          "finalizerType": "aggregate",
          "config": { "sections": [] }
        }
      }
    ],
    "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" }
              }
            }]
          }
        }
      }
    }
  }
}
```

Fixtures: `createMinimalExecutableGraph()`, `createContentPipelineReferenceGraph()` (canonical).

---

## Who should use this

| Role | Use this package? |
| ---- | ----------------- |
| Graph designer / editor / generator | **Yes** |
| Compiler service | Upstream validation (also depends on this) |
| Engine at runtime | **No** — engine receives compiled plans |

---

## Install

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

---

## Example (API)

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

const doc = createContentPipelineReferenceGraph();
validateGraph(doc);
validateAuthoringGraph(doc);

validateConceptDocument({
  formatVersion: "graphenix.concept/v1",
  graphId: doc.id,
  name: doc.name
});

const normalized = normalizeExecutableGraph(doc);
const forPlan = stripDesignOnlyFieldsFromGraph(normalized);
```

---

## Two-tier validation

| Validator | Scope |
| --------- | ----- |
| `validateGraph()` | Topology, ports, task body, layout |
| `validateAuthoringGraph()` | `graphenix.executable/v1` + task-node body |
| `validateConceptDocument()` | Paired shadow document (separate API) |

---

## Key exports

| Category | APIs |
| -------- | ---- |
| Validation | `validateAuthoringGraph`, `validateConceptDocument`, `validateNormalizedExecutableGraph`, `validateGraphJobMemory`, `validateGraphJobPipeline` |
| Normalization | `normalizeExecutableGraph`, `stripDesignOnlyFieldsFromGraph`, `normalizeGraphJobMemory`, `normalizeGraphJobPipeline` |
| CRUD helpers | `addTaskNode`, `addFinalizerNode`, `setGraphModelConfig`, `setNodeModelConfig`, `connectTaskToTask` |
| Profile choice | `validateAiModelSelection`, `isKnownProfileChoice` |
| Model config authoring | `readGraphJobModelDefaults`, `mergeEffectiveModelConfig`, `normalizeNodeOverrideForPersist`, `validateNodeModelConfigOverride`, `legacyModelConfigToAuthoring` |
| Fixtures | `createMinimalExecutableGraph`, `createContentPipelineReferenceGraph`, `createPlainGraphenixGraph` |
| Task node (re-export) | `validateTaskNode`, phase config types from `@x12i/graphenix-task-node-format` |

---

## Strict profiles

| Node `kind` | `parameters.profile` |
| ----------- | -------------------- |
| `task` | `graphenix.task-node/v1` |
| `finalizer` | `graphenix.finalizer-node/v1` |

Extension: `graph.metadata.extensions["graphenix.executable/v1"]`

Design-only: `node.layout` — stripped via `stripDesignOnlyFieldsFromGraph()` at compile.

---

## Knowledge scope

| Field | Scope |
| ----- | ----- |
| `parameters.taskKnowledge` | Task node — forwarded on `RunTaskRequest.taskMemory.knowledge` |
| `parameters.taskPagentiKnowledge` | Task node — same scope as `taskKnowledge`; Pagenti task refs (parallel to `jobPagentiKnowledge` at graph level) |
| `graph.metadata.jobKnowledge` | Graph-run — forwarded on `RunTaskRequest.jobMemory.knowledge` |
| `graph.metadata.jobPagentiKnowledge` | Graph-run — Pagenti job refs (via `graphenix.knowledge/v1` promote path) |
| Any other `taskKnowledge` / misplaced pagenti path | **Rejected** (`TASK_KNOWLEDGE_GRAPH_SCOPE_FORBIDDEN`, `TASK_KNOWLEDGE_WRONG_PLACEMENT`) |
| Finalizer nodes | No `taskKnowledge` — finalizers do not invoke AI tasks |

Document root `taskKnowledge` and `jobKnowledge` are deprecated — use the paths above.

---

## Job memory defaults

Graph-level declarative context queries live on `graph.metadata.jobMemory.context[]` (not document root — root `jobMemory` is deprecated like `jobKnowledge`).

| Field | Role |
| ----- | ---- |
| `graph.metadata.jobMemory.context[]` | Default Memorix context queries resolved by the host into `runtime.jobMemory.context[]` before execute |

Each context entry requires `alias`, `contentType`, and `filter[]`. Duplicate aliases within one graph are rejected. Filters with `source: "input"` emit a non-fatal warning when `inputField` is empty (`validateAuthoringGraphForPersist`).

Normalization strips runtime-populated fields (`rows`, nested runtime `query` echoes) from persisted model entries.

```json
{
  "graph": {
    "metadata": {
      "jobMemory": {
        "context": [
          {
            "alias": "peer-subnets",
            "contentType": "subnet",
            "target": "entity",
            "filter": [
              { "key": "tenantId", "source": "input", "inputField": "tenantId" }
            ],
            "limit": 10
          }
        ]
      }
    }
  }
}
```

Host merge convention: `runtime.jobMemory.context = [...(resolved graph defaults), ...(resolved job contextQueries)]` with job-level entries overriding the same `alias`.

---

## Job pipeline metadata

Graph-level job identity and pipeline position live on `graph.metadata.jobPipeline` (not document root — root `jobPipeline` is deprecated like `jobMemory`).

| Field | Role |
| ----- | ---- |
| `jobTypeId` | Logical job classification — many graph implementations may share one job type |
| `upstream[]` / `downstream[]` | Job-type dependency refs (cross-entity upstream may include `entity` + `relationKey`) |
| `context[]` | Default linked-entity pulls for work-factory / `jobMemory.context` at enqueue |
| `reprocessing` | Operator-facing reprocessing policy keyed by job type |

**Identity (do not conflate):**

| Field | Meaning | Authored? |
| ----- | ------- | --------- |
| `jobId` | Per-run correlation id | Runtime only |
| `jobTypeId` | Logical job classification | `graph.metadata.jobPipeline.jobTypeId` |
| `graphId` | Pipeline implementation id | Document `id` |

Deprecated wire aliases accepted at validation: `jobType` → `jobTypeId`, `relationshipKey` → `relationKey`. Use `resolveGraphJobPipelineContract()` for canonical resolver output.

```json
{
  "graph": {
    "metadata": {
      "jobPipeline": {
        "jobTypeId": "content-pipeline.analyze",
        "label": "Analyze content",
        "upstream": [
          { "jobTypeId": "content-pipeline.ingest" }
        ],
        "context": [
          {
            "relationKey": "sourceRecord",
            "targetEntity": "content",
            "target": "entity",
            "contentTypes": ["article"],
            "limit": 5
          }
        ],
        "reprocessing": {
          "mode": "ttl",
          "ttl": { "value": 7, "unit": "days" }
        }
      }
    }
  }
}
```

---

## Related packages

| Package | Role |
| ------- | ---- |
| [GLOSSARY.md](../../GLOSSARY.md) | Phase vocabulary |
| [`@x12i/graphenix-authoring-analysis`](../authoring-analysis) | Studio save/import: `GraphProjectDocument`, purity, model-config merge |
| [`@x12i/graphenix-task-node-format`](../task-node-format) | Task body validation |
| [`@x12i/graphenix-executable-profile-format`](../executable-profile-format) | Phase model profiles |
| [`@x12i/graphenix-case-format`](../case-format) | Case condition DSL |
| [`@x12i/graphenix-plan-compiler`](../plan-compiler) | Compile authoring → plan |

**v1.2.0:** Model-config authoring APIs (`readGraphJobModelDefaults`, `mergeEffectiveModelConfig`, `normalizeNodeOverrideForPersist`, etc.) are canonical in this package. See [model-config authoring semantics](../../docs/format/guides/graphenix-model-config-authoring-semantics.md).

**v1.1.0:** Legacy flat-graph migration helpers were removed. Studio envelope validation lives in `@x12i/graphenix-authoring-analysis`.

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