@x12i/graphenix-executable-format 1.0.0 → 2.0.0

package/README.md

@@ -1,341 +1,512 @@
-# @x12i/graphenix-executable-format
-
-Strict **X12i executable graph profile** built on [`@x12i/graphenix-core`](../core), with deterministic model configuration cases validated against [`@x12i/ai-profiles`](https://www.npmjs.com/package/@x12i/ai-profiles).
-
-Graphenix core defines the structural graph format. This package defines the X12i executable lifecycle: authoring graphs, compiled executable plans, execution traces, model inheritance, fallback, and the studio adapter.
-
-## Install
-
-```bash
-npm install @x12i/graphenix-executable-format @x12i/graphenix-core
-```
-
-`@x12i/ai-profiles` is installed automatically as a dependency (profile registry and `profileChoice` key validation).
-
-## Relationship
-
-```txt
-@x12i/graphenix-core
-  generic graph document format (2.0.0)
-
-@x12i/ai-profiles
-  profile/choice registry (cheap/default, vol/pro, deep/openai_deep, …)
-
-@x12i/graphenix-executable-format
-  strict runnable profile + compile + trace
-```
-
-A valid authoring graph is always a valid Graphenix document, but not every Graphenix document is executable.
-
-## Lifecycle artifacts
-
-```txt
-AuthoringGraphDocument          ← Studio saves this (source of truth)
-        ↓ compileExecutablePlan()
-ExecutableGraphPlan             ← Engine consumes this
-        ↓ executeGraph()
-GraphExecutionTrace             ← Append-only run evidence
-```
-
-| Artifact | Purpose | Saved? | Used by engine? |
-| -------- | ------- | -----: | --------------: |
-| **AuthoringGraphDocument** | Human/studio source of truth | Yes | No, not directly |
-| **ExecutableGraphPlan** | Normalized, deterministic, run-ready plan | Optional cache / per run | Yes |
-| **GraphExecutionTrace** | What happened during one run | Yes, append-only | No |
-
-## Extension namespace
-
-```txt
-graph.metadata.extensions["x12i.executable/v1"]
-```
-
-## Key rule: deterministic cases
-
-```txt
-Cases may choose stronger or weaker AI profiles.
-AI may not choose the case.
-```
-
-Allowed case selectors:
-
-```txt
-runtime.mode = "simulate"
-runtime.input.riskLevel = "high"
-runtime.environment = "prod"
-runtime.input.analysisDepth = "deep"
-```
-
-Forbidden:
-
-```txt
-Ask AI whether input is high risk, then pick a model case
-LLM classification as a case condition
-semanticMatch / function / script selectors
-node.output.* / ai.* / executionMemory.ai.*
-```
-
-## Profile choice format
-
-Use explicit `profile/choice` composite keys from `@x12i/ai-profiles`:
-
-```json
-{
-  "kind": "profileChoice",
-  "key": "vol/default"
-}
-```
-
-Examples: `cheap/default`, `sum/default`, `vol/default`, `vol/pro`, `deep/openai_deep`.
-
-Rejected:
-
-```txt
-kind: "profile" with bare names (economy, balanced)
-bare keys (cheap, default, strong)
-vendor slugs as profileChoice (openai/gpt-4o-mini → unknown key)
-```
-
-Direct concrete model (separate from profiles):
-
-```json
-{
-  "kind": "model",
-  "provider": "openai",
-  "modelId": "gpt-4o-mini"
-}
-```
-
-`profileChoice` is **not** resolved to vendor/model during normalization — only at invocation/planning via `@x12i/ai-profiles`.
-
-## Model configuration cases
-
-### Graph-level (`modelConfig`)
-
-Authoring form may use `default` shorthand or explicit `cases[]`:
-
-```json
-{
-  "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" }
-      }
-    },
-    {
-      "id": "simulate",
-      "when": { "path": "runtime.mode", "op": "eq", "value": "simulate" },
-      "modelConfig": {
-        "preActionModel": { "kind": "profileChoice", "key": "cheap/default" },
-        "skillModel": { "kind": "profileChoice", "key": "sum/default" },
-        "postActionModel": { "kind": "profileChoice", "key": "cheap/default" }
-      }
-    }
-  ]
-}
-```
-
-Rules:
-
-- Evaluate conditional cases in order; select the first match.
-- If none match, use case `id: "default"`.
-- Exactly one default graph case required.
-- Every graph case must define the full triplet: `preActionModel`, `skillModel`, `postActionModel`.
-
-### Node-level (`taskConfiguration.modelConfig`)
-
-Node cases may be partial when `inherit: true`. Missing slots inherit from the **selected graph case**.
-
-```json
-{
-  "inherit": true,
-  "cases": [
-    {
-      "id": "high-risk-input",
-      "when": {
-        "path": "runtime.input.riskLevel",
-        "op": "eq",
-        "value": "high"
-      },
-      "modelConfig": {
-        "skillModel": { "kind": "profileChoice", "key": "deep/openai_deep" }
-      }
-    }
-  ]
-}
-```
-
-## Case condition DSL
-
-```ts
-type CaseCondition =
-  | { all: CaseCondition[] }
-  | { any: CaseCondition[] }
-  | { not: CaseCondition }
-  | {
-      path: string;
-      op: "eq" | "neq" | "in" | "notIn" | "exists" | "notExists"
-        | "gt" | "gte" | "lt" | "lte" | "matches";
-      value?: string | number | boolean | null | string[] | number[];
-    };
-```
-
-Allowed path roots: `runtime.mode`, `runtime.environment`, `runtime.job.*`, `runtime.input.*`, `runtime.variables.*`, `runtime.flags.*`, `runtime.context.*`, `graph.id`, `graph.revision`.
-
-## Validate authoring graph
-
-```ts
-import {
-  validateAuthoringGraph,
-  validateExecutableGraph,
-  createMinimalExecutableGraph
-} from "@x12i/graphenix-executable-format";
-import { validateGraph } from "@x12i/graphenix-core";
-
-const doc = createMinimalExecutableGraph();
-
-validateGraph(doc);            // Graphenix structure
-validateAuthoringGraph(doc);   // authoring profile semantics
-validateExecutableGraph(doc);  // alias for authoring validation
-```
-
-## Normalize and preview resolution
-
-```ts
-import {
-  normalizeExecutableGraph,
-  resolveNodeAiPlan,
-  explainNodeInheritance,
-  buildDeterministicCaseContext,
-  evaluateCaseCondition,
-  validateCaseCondition
-} from "@x12i/graphenix-executable-format";
-
-const normalized = normalizeExecutableGraph(doc); // non-mutating
-
-const context = buildDeterministicCaseContext(doc, {
-  mode: "live",
-  input: { analysisDepth: "deep", riskLevel: "high" }
-});
-
-const plan = resolveNodeAiPlan(normalized, "node:professional-answer", context);
-console.log(explainNodeInheritance(plan));
-// Graph case selected: deep-live
-// Node case selected: high-risk-input
-// ...
-```
-
-## Compile executable plan
-
-```ts
-import {
-  compileExecutablePlan,
-  validateExecutablePlan,
-  buildRuntimeObject
-} from "@x12i/graphenix-executable-format";
-
-const runtime = buildRuntimeObject({
-  jobId: "wg-1780698714844-8q8izhb",
-  mode: "live",
-  input: { analysisDepth: "deep" }
-});
-
-const plan = compileExecutablePlan(authoringGraph, runtime, {
-  profileRegistry: { version: "3.2.0" },
-  environment: "prod"
-});
-
-validateExecutablePlan(plan);
-```
-
-Flow inside `compileExecutablePlan`:
-
-```txt
-validateAuthoringExecutableGraph()
-normalizeExecutableGraph()
-assertNormalizedExecutableGraph()
-selectGraphModelCase() → resolveNodeAiPlan() per task node
-buildNodeExecutionUnits()
-```
-
-The engine should consume only `ExecutableGraphPlan`.
-
-## Studio → engine adapter
-
-```ts
-import { buildGraphExecutionRequestFromStudioExecute } from "@x12i/graphenix-executable-format";
-
-const { plan, runtime } = buildGraphExecutionRequestFromStudioExecute(
-  studioRequest,
-  { agentId: "agent-1" }
-);
-```
-
-The engine receives only `{ plan, runtime }`. Credentials and request-level model defaults are never copied.
-
-## Model inheritance and fallback
-
-- Graph-level `modelConfig` is **required** with a complete model triplet per case.
-- Node overrides may be partial; missing slots inherit from the **selected graph case**.
-- Fallback is same-slot only: `node.skillModel → graph.skillModel` from the selected graph case (never cross-slot, another case, or runtime defaults).
-
-## Execution trace
-
-```ts
-import {
-  createExecutionTrace,
-  appendExecutionEvent,
-  validateExecutionTrace
-} from "@x12i/graphenix-executable-format";
-
-const trace = createExecutionTrace(plan, runtime);
-const withStart = appendExecutionEvent(trace, {
-  id: "evt:1",
-  ts: new Date().toISOString(),
-  level: "info",
-  type: "graph.started",
-  message: "Graph execution started."
-});
-
-validateExecutionTrace(withStart, plan.nodePlans);
-```
-
-## Public APIs (case selection)
-
-| API | Purpose |
-| --- | ------- |
-| `validateCaseCondition(condition)` | Validate deterministic `when` DSL |
-| `evaluateCaseCondition(condition, context)` | Evaluate against runtime/graph context |
-| `selectGraphModelCase(modelConfig, context)` | Pick graph case |
-| `selectNodeModelCase(nodeModelConfig, context)` | Pick node case |
-| `resolveNodeAiPlan(doc, nodeId, context)` | Full resolved plan with `caseSelection` |
-| `isProfileChoiceKeyFormat(key)` | From `@x12i/ai-profiles` |
-| `isKnownProfileChoice(key)` | Bundled registry lookup |
-
-## Node kinds
-
-| Kind | Purpose |
-| ---- | ------- |
-| `x12i:task` | Run a skill with optional per-node model overrides and pre/post actions |
-| `x12i:finalizer` | Produce final graph output |
-
-## 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).
-
-## Implementation report
-
-See [`docs/IMPLEMENTATION-REPORT.md`](./docs/IMPLEMENTATION-REPORT.md) for the full CR/FR gap analysis and acceptance test matrix.
+# @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.
+
+---
+
+## 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-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-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
+
+For each task node in topological order:
+
+1. `validateExecutablePlan(plan)` on receipt
+2. PRE-phase units (`externalPreUtility`) → MAIN (`mainSkill`, `pipelinePhase`, …) → POST if present
+3. Each unit uses frozen `modelSelection` from the plan — no case re-selection at runtime
+
+### 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`.
+
+```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 |