2.17.0 • Published 2 weeks ago

@x12i/graphenix-trace-format

Licence

MIT

Version

2.17.0

Deps

Size

240 kB

Vulns

Weekly

Summary Dependency Versions

@x12i/graphenix-trace-format

GraphExecutionTrace format — append-only run evidence for a single graph execution.

Covers node traces, execution unit traces, model invocation attempts, fallback events, and final output. Does not depend on authoring graphs.

Canonical vocabulary: GLOSSARY.md — task run phases map to trace unit.* events in plan order.
Finalization brief: EXECUTE-TRACE-FORMAT-FINALIZATION.md.

Do not use “Synthesis PRE” in trace docs — use PRE-phase utility / externalPreUtility with strategyKey.

Who should use this

Role	Use this package?
Execution engine	Yes — create and append events during a run
Run history / observability / analytics	Yes — validate and read traces
Graph designer / Studio	No (unless displaying run history)

Lifecycle position

ExecutableGraphPlan + GraphRuntimeObject
        │  engine executes executionUnits[] (prePhase → mainPhase → postPhase)
        ▼
GraphExecutionTrace              ← THIS PACKAGE

Reference domain: content pipeline plan (graph:content-pipeline) — three parallel tasks with PRE synthesis + MAIN skill, no POST on reference tasks.

Install

npm install @x12i/graphenix-trace-format

Trace document shape

GraphExecutionTrace
  ├─ traceId, jobId, status, createdAt, completedAt
  ├─ source — graphId, graphHash (from plan)
  ├─ plan — planId, planHash (bind trace to frozen plan)
  ├─ runtime — mode, environment, inputHash (no credentials)
  ├─ events[] — append-only audit log
  ├─ unitExecutions{} — indexed unit lifecycle records
  ├─ modelInvocations{} — indexed model invocation records
  └─ nodeExecutions{} — per-node rollups derived from unit terminal state

Normative dual-write: When appending unit.* or model.invocation.* events, also update unitExecutions / modelInvocations through the lifecycle API. Events alone do not satisfy analytics or plan validation consumers.

Examples (JSON)

Trace header (bound to content pipeline plan)

{
  "format": "graphenix.execution-trace/v1",
  "traceId": "trace:job-001",
  "jobId": "job-001",
  "createdAt": "2026-06-06T12:00:00.000Z",
  "status": "running",
  "source": {
    "graphId": "graph:content-pipeline",
    "graphRevision": "1.0.0",
    "graphHash": "sha256:…"
  },
  "plan": {
    "planId": "plan:abc123",
    "planHash": "sha256:…"
  },
  "runtime": {
    "mode": "live",
    "environment": "prod",
    "inputHash": "sha256:…"
  },
  "events": [],
  "nodeExecutions": {}
}

Unit events for one content-pipeline task (PRE + MAIN)

After node:audience-insights runs PRE-phase utility synthesis then MAIN skill:

"events": [
  {
    "id": "evt:1",
    "ts": "2026-06-06T12:00:01.000Z",
    "level": "info",
    "type": "node.started",
    "nodeId": "node:audience-insights"
  },
  {
    "id": "evt:2",
    "ts": "2026-06-06T12:00:01.100Z",
    "level": "info",
    "type": "unit.started",
    "nodeId": "node:audience-insights",
    "unitId": "unit:node:audience-insights:pre:0",
    "unitKind": "externalPreUtility"
  },
  {
    "id": "evt:3",
    "ts": "2026-06-06T12:00:02.500Z",
    "level": "info",
    "type": "model.invocation.completed",
    "nodeId": "node:audience-insights",
    "unitId": "unit:node:audience-insights:pre:0",
    "modelSlot": "preActionModel"
  },
  {
    "id": "evt:4",
    "ts": "2026-06-06T12:00:02.600Z",
    "level": "info",
    "type": "unit.started",
    "nodeId": "node:audience-insights",
    "unitId": "unit:node:audience-insights:main:1",
    "unitKind": "mainSkill"
  },
  {
    "id": "evt:5",
    "ts": "2026-06-06T12:00:05.000Z",
    "level": "info",
    "type": "node.completed",
    "nodeId": "node:audience-insights"
  }
]

Model profiles were resolved at compile time — trace records which modelSlot was invoked, not a re-selected case.

Example (API)

import {
  createEmptyExecutionTrace,
  appendTraceEvent,
  appendUnitLifecycleEvent,
  markUnitCompleted,
  recordModelInvocationStarted,
  recordModelInvocationCompleted,
  validateTraceAgainstPlan,
  deriveGraphStatus,
  summarizeExecutionTrace
} from "@x12i/graphenix-trace-format";

const trace = createEmptyExecutionTrace({ traceId, plan, runtime });

appendTraceEvent(trace, {
  id: "evt:1",
  ts: new Date().toISOString(),
  sequence: 1,
  level: "info",
  type: "graph.started"
}, { mutate: true });

const unit = plan.nodePlans["node:audience-insights"].executionUnits[0];
appendUnitLifecycleEvent(trace, "unit.started", unit);

recordModelInvocationStarted(trace, {
  invocationId: "inv:pre:1",
  unitId: unit.unitId,
  nodeId: unit.nodeId,
  modelSlot: unit.modelSlot,
  plannedModelSelection: unit.modelSelection
});
recordModelInvocationCompleted(trace, "inv:pre:1", { durationMs: 1200 });

appendUnitLifecycleEvent(trace, "unit.completed", unit, { durationMs: 1500 });

const result = validateTraceAgainstPlan(trace, plan);
const status = deriveGraphStatus(trace);
const summary = summarizeExecutionTrace(trace);

Key exports

API	Purpose
`createEmptyExecutionTrace`	Initialize v2 trace with seeded unit/node indexes
`appendTraceEvent`	Append-only event mutation
`markUnitStarted` / `markUnitCompleted` / `markUnitFailed`	Update `unitExecutions` + `graphExecution` indexes
`recordModelInvocationStarted` / `Completed` / `Failed`	Update `modelInvocations` + link to units
`appendUnitLifecycleEvent`	Append `unit.*` event and update indexes in one call
`rollupNodeExecution`	Roll up unit terminal state to node indexes and append `node.completed` / `node.failed`
`appendFallbackAppliedEvent`	Append `fallback.applied` and update unit fallback index
`reconcileTraceIndexesFromEvents`	Best-effort rebuild of indexes from legacy event-only traces
`validateTraceAgainstPlan`	Validate trace against frozen v2 plan
`deriveGraphStatus`	Overall run status from indexes
`deriveNodeStatusFromUnits`	Per-node status from unit indexes
`summarizeExecutionTrace`	Compact summary for dashboards
`createContentPipelineReferenceTrace(plan, options?)`	Build completed CP trace for tests and golden fixtures

Trace event types include graph/node lifecycle, execution unit lifecycle (unit.started / unit.completed), model invocation, fallback applied, validation failures, and warnings.

Event catalog (required fields per type): execution-logs.md · golden trace: fixtures/content-pipeline.trace.json

Validation tier

When	API
Run end (engine)	`validateExecutionTrace(trace, plan.nodePlans)`
Index / analytics	`validateExecutionTrace` before storing
Dashboards	`deriveGraphStatus`, `summarizeExecutionTrace`

Store planHash (or full plan snapshot) with each trace for strict replay validation.

Format identifiers

EXECUTION_TRACE_FORMAT     // v1 — @x12i/graphenix-executable-contracts
EXECUTION_TRACE_FORMAT_V2  // v2 — when plan is v2

Dependencies

@x12i/graphenix-executable-contracts ^1.1.0

Package	Role
GLOSSARY.md	Phase vocabulary for unit events
`@x12i/graphenix-plan-format`	Plan shape traces reference
`@x12i/graphenix-plan-compiler`	Produces the plan a trace is bound to
EXECUTE-TRACE-FORMAT-FINALIZATION.md	Execute + trace phase brief
observability role guide	Run history client guide

README sync policy

When documenting task run phases at execution/trace layer, update together:

Layer	README / doc
Compiled plan units	plan-format/README.md
Trace events	this file
Execute + trace brief	EXECUTE-TRACE-FORMAT-FINALIZATION.md
Terms of record	GLOSSARY.md

Keywords

graph graphenix trace execution