@x12i/graphenix-executable-contracts

Shared contracts for the Graphenix executable graph lifecycle: TypeScript types, constants, error codes, and lightweight utilities.

No validators, compilers, or adapters — only the shared vocabulary other lifecycle packages build on.

Naming policy: NAMING.md — npm scope @x12i/* vs JSON identifiers graphenix.*.

Who should use this

| Role | Use this package? | | ---- | ----------------- | | Library author needing types only | Yes | | Graph designer / Studio | Prefer @x12i/graphenix-authoring-format | | Engine | Prefer @x12i/graphenix-plan-format + @x12i/graphenix-trace-format |

Install

npm install @x12i/graphenix-executable-contracts @x12i/graphenix-core

Type index (primary)

| Domain | Key types / constants | | ------ | --------------------- | | Authoring | AuthoringGraphDocument, GraphProjectDocument | | Plan v2 | ExecutableGraphPlanV2, NodeExecutionPlan, ExecutionUnitPlan, EXECUTABLE_PLAN_FORMAT_V2 | | Plan v1 | ExecutableGraphPlan, EXECUTABLE_PLAN_FORMAT (legacy) | | Trace v2 | GraphExecutionTraceV2, TraceEvent, EXECUTION_TRACE_FORMAT_V2 | | Trace v1 | GraphExecutionTrace, EXECUTION_TRACE_FORMAT (legacy) | | Runtime | GraphRuntimeObject, StudioExecuteRequest | | Model config | AiModelSelection, CaseCondition, ModelConfigTriplet | | Units | ExecutionUnitKindV2, InvokeContract, ModelSlot | | Fact-guard | FactGuardStepConfig, AuditFactGuardConfig, AuthoringFactGuardConfig, FACT_GUARD_POLICY_IDS |

Example

import {
  EXECUTABLE_PLAN_FORMAT_V2,
  EXECUTION_TRACE_FORMAT_V2,
  type ExecutableGraphPlanV2,
  type GraphExecutionTraceV2,
  type NodeExecutionPlan,
  type CaseCondition,
  type AiModelSelection,
  execError
} from "@x12i/graphenix-executable-contracts";

Key exports

• Constants — format ids, TASK_NODE_KIND, AI_MODEL_SLOTS, profile namespace
• Types — authoring graph, executable plan, execution trace, case conditions, model config, runtime
• Utilities — isRecord, execError, getExecutableProfile, isExecutableTaskNode, …
• Hashing — sha256Hash, defaultHashFunction
• Schema — schema/graphenix-executable-format-1.0.0.schema.json (published with package)

Dependencies

• Peer: @x12i/graphenix-core ^2.4.0

Error codes (synthesis)

| Code | When | | ---- | ---- | | LEGACY_PRE_INPUT_STRATEGY | Authoring still has preInputStrategy / synthesisInputStrategy (warn on normalize; reject preInputStrategy on validate) | | LEGACY_SYNTHESIS_INPUT_STRATEGY_ON_PLAN | Plan unit has unitParams.synthesisInputStrategy — remove; re-compile (validation fails until removed) |

Empty invokeContract.reads and unitParams.memoryPaths on PRE synthesis units is valid — runtime applies DEFAULT_PRE_SYNTHESIS_READ_PATHS (jobVariables, taskVariables, input). Layer-1 hints (narrix, webScope) are not PRE read scope.

Synthesis unitParams (plan wire)

PRE synthesis externalPreUtility units carry paths only:

{
  "memoryPaths": [],
  "autoEnableContext": true
}

When aiTaskProfile.inputSynthesis.sources is authored, compiler emits identical paths on invokeContract.reads and memoryPaths. When omitted, both are [] and ai-tasks applies the default trio at runtime.

No plan field for synthesis template key — runtime resolves from skill catalog. Future explicit per-node override (multi-template skills, P2 FR): invokeContract.synthesisContextStrategyKey (not synthesisInputStrategy).

Related packages

Part of the Graphenix Format monorepo. Lifecycle status: GAP-ANALYSIS.md.