@x12i/graphenix-execute-envelope

@x12i/graphenix-execute-envelope

Execute request envelope — host-level adaptation for graph execution requests.

Validates incoming execute requests, builds the runtime object (excluding credentials), compiles the authoring graph into a plan, and returns { plan, runtime } for the engine.

Optional package: engines and compilers do not need it; backend hosts and API gateways do.

Finalization brief: EXECUTE-TRACE-FORMAT-FINALIZATION.md · compile: COMPILE-FORMAT-FINALIZATION.md.

---

Who should use this

Role	Use this package?
Backend host / API gateway / Studio backend	Yes
Compiler service (already owns compile)	Usually No
Engine	No

---

Lifecycle position

Studio execute request (authoring + input)
        │  validateStudioExecuteRequest()
        │  buildRuntimeObject()
        │  compileExecutablePlanV2()
        │  validateExecutablePlanV2()
        ▼
{ plan, runtime }  →  engine
        │
        ▼
GraphExecutionTrace  (@x12i/graphenix-trace-format)

Reference authoring: createContentPipelineReferenceGraph() — graph:content-pipeline.

---

Install

npm install @x12i/graphenix-execute-envelope

---

Examples (JSON)

Studio execute request (shape)

Use createContentPipelineReferenceGraph() for real node ids — not an empty "graph": {} placeholder.

{
  "mode": "graph",
  "jobId": "job-001",
  "graph": {
    "id": "graph:content-pipeline",
    "formatVersion": "2.0.0",
    "graph": {
      "id": "graph:content-pipeline",
      "nodes": [
        { "id": "node:audience-insights", "type": "task" },
        { "id": "node:competitor-angles", "type": "task" },
        { "id": "node:seo-keywords", "type": "task" },
        { "id": "node:content-package", "type": "finalizer" }
      ]
    }
  },
  "runtime": {
    "input": {
      "brief": "Launch campaign for eco-friendly water bottles",
      "priority": "normal"
    }
  }
}

Full authoring JSON: packages/authoring-format/fixtures/graph-content-pipeline.authoring.json.

Credentials stay on the request boundary — never copied into GraphRuntimeObject.

Runtime object (compile input)

{
  "jobId": "job-001",
  "mode": "live",
  "environment": "prod",
  "input": {
    "brief": "Launch campaign for eco-friendly water bottles",
    "priority": "normal"
  }
}

Compile output handoff

{
  "plan": {
    "format": "graphenix.executable-plan/v2",
    "source": { "graphId": "graph:content-pipeline" },
    "nodePlans": {
      "node:audience-insights": {
        "executionUnits": [
          { "unitKind": "externalPreUtility", "order": 0, "strategyKey": "synthesis" },
          { "unitKind": "mainSkill", "order": 1, "skillKey": "professional-answer" }
        ]
      }
    }
  },
  "runtime": { "jobId": "job-001", "mode": "live", "input": { "priority": "normal" } }
}

Embedded normalized graph in the plan has no node.layout — stripped at compile.

---

Example (API)

import { createContentPipelineReferenceGraph } from "@x12i/graphenix-authoring-format";
import { buildGraphExecutionRequestFromStudioExecute } from "@x12i/graphenix-execute-envelope";

const authoring = createContentPipelineReferenceGraph();
const { plan, runtime } = buildGraphExecutionRequestFromStudioExecute(
  {
    mode: "graph",
    jobId: "job-001",
    graph: authoring,
    runtime: { input: { priority: "normal" } }
  },
  { profileRegistry: { version: "3.2.0", registryHash: "sha256:profiles-cp" } }
);
// forward { plan, runtime } to engine

Lower-level building blocks

import {
  validateStudioExecuteRequest,
  buildRuntimeObject,
  validateRuntimeObject
} from "@x12i/graphenix-execute-envelope";
import { compileExecutablePlanV2 } from "@x12i/graphenix-plan-compiler";
import { validateExecutablePlanV2 } from "@x12i/graphenix-plan-format";

validateStudioExecuteRequest(request);
const runtime = buildRuntimeObject(request.input, request.options);
validateRuntimeObject(runtime);

const plan = compileExecutablePlanV2(request.authoringGraph, runtime, {
  profileRegistry: { version: "3.2.0", registryHash: "sha256:profiles-host" }
});
validateExecutablePlanV2(plan);

---

Key exports

API	Purpose
buildGraphExecutionRequestFromStudioExecute	Full pipeline: validate → runtime → compile → validate plan
validateStudioExecuteRequest	Request envelope validation
buildRuntimeObject	Build GraphRuntimeObject from host input
validateRuntimeObject	Runtime shape + forbidden fields

---

Security rules

• Credentials are never copied into the runtime object
• Request-level forbidden fields (e.g. graphDefaultModel in runtime) are rejected
• Runtime must not carry authoring-only config like modelConfig
• Engine receives only { plan, runtime } — no Studio envelope, no API keys in runtime

---

Dependencies

• @x12i/graphenix-authoring-format ^1.0.2
• @x12i/graphenix-plan-compiler ^1.1.0
• @x12i/graphenix-plan-format ^1.1.0
• @x12i/graphenix-executable-contracts ^1.1.0

---

Related packages

Package	Role
@x12i/graphenix-plan-compiler	Compilation step
@x12i/graphenix-trace-format	Run evidence after engine executes
backend-host role guide	Client guide
@x12i/graphenix-executable-format	Umbrella that re-exports this package