# @x12i/graphenix-execute-envelope

> Execute request envelope: runtime building and graph execution request adaptation.

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

## Install

```sh
npm install @x12i/graphenix-execute-envelope
pnpm add @x12i/graphenix-execute-envelope
yarn add @x12i/graphenix-execute-envelope
bun add @x12i/graphenix-execute-envelope
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality 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 | 4 |
| Unpacked size | 24.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | graph, graphenix, execute, envelope |

## Links

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

## Dependencies (4)

- [@x12i/graphenix-plan-format](https://npm.io/package/@x12i/graphenix-plan-format.md) ^2.17.0
- [@x12i/graphenix-plan-compiler](https://npm.io/package/@x12i/graphenix-plan-compiler.md) ^2.17.0
- [@x12i/graphenix-authoring-format](https://npm.io/package/@x12i/graphenix-authoring-format.md) ^2.17.0
- [@x12i/graphenix-executable-contracts](https://npm.io/package/@x12i/graphenix-executable-contracts.md) ^2.17.0

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 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
- … 10 more at https://npm.io/package/@x12i/graphenix-execute-envelope/versions

## README

# @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](../../docs/EXECUTE-TRACE-FORMAT-FINALIZATION.md) · compile: [COMPILE-FORMAT-FINALIZATION.md](../../docs/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

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

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

---

## Install

```bash
npm install @x12i/graphenix-execute-envelope
```

---

## Examples (JSON)

### Studio execute request (shape)

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

```json
{
  "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)

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

### Compile output handoff

```json
{
  "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)

```ts
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

```ts
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`](../plan-compiler) | Compilation step |
| [`@x12i/graphenix-trace-format`](../trace-format) | Run evidence after engine executes |
| [backend-host role guide](../../docs/roles/backend-host.md) | Client guide |
| [`@x12i/graphenix-executable-format`](../executable-format) | Umbrella that re-exports this package |

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