# Governed CER Schema

URL: https://docs.nexart.io/docs/governed-execution/schema

The exact cer.governed.execution.v1 envelope, the cage-governance-v1 profile, CAGE bundle and step fields, topology and certificate hash construction.

Source of truth: the type declarations and schemas shipped in `@nexart/governed-execution@0.4.2` (`dist/index.d.ts`, `schemas/provider_02/`).

## Envelope

| Member | Value / type | Role |
| --- | --- | --- |
| bundleType | "cer.governed.execution.v1" | Evidence family. |
| createdAt | RFC 3339 string | Issuance time. Part of certificate identity; pin it for deterministic repeats. |
| version | "0.1" | Protected container version. 0.2 is the confidential variant. |
| profile | object | Explicit profile descriptor. Unknown profiles fail closed. |
| evidence | { bundle, topology? } | Complete CAGE AttestationBundle and optional GraphTopology. |
| protectedSet | object | Declares the stability scheme and the protected fields. |
| certificateHash | sha256:<64 hex> | SHA-256 over UTF-8 JCS of every other member. |

## AttestationBundle

| Field | Type | Rule |
| --- | --- | --- |
| bundleId | string | Any syntactically valid UUID (generic format: uuid). |
| threadId | string | Thread or session identifier. |
| steps | Step[] | Ordered concrete execution steps. Maximum 256. |
| startedAt | RFC 3339 | Execution start. |
| completedAt | RFC 3339 | Execution end. |
| terminalPath | enum | happy_path, nemo_block, cbf_block, loop_breaker, unknown. Validated by profile semantics when topology is supplied. |

## Step

| Field | Type | Rule |
| --- | --- | --- |
| stepId | string | Strict RFC 4122 UUIDv4. Unique within the bundle. |
| nodeName | string | Workflow node. Repeats are allowed when step IDs are unique. |
| parentStepIds | string[] | UUIDv4 IDs of actual parents. Earlier-only, no self, no duplicates. |
| timestampUtc | RFC 3339 | Must not precede any parent's timestamp. |
| durationMs | number | Execution duration. |
| signals | object | Governance signals. Open extension point. |
| metadata | object | Node metadata. Open extension point. |
| stateHash | string | Lowercase 64-character hex producer commitment. See State Commitments. |

## GraphTopology

| Field | Type | Rule |
| --- | --- | --- |
| nodes | string[] | Declared node names. Maximum 1,024. |
| parentEdges | Record<string, string[]> | Possible parents per node. May contain cycles and self-edges. Maximum 4,096 edges. |
| terminalNode | string | Canonical success terminal node. |
| interruptNode | string \| null (optional) | HITL interrupt node. |
| attestationNodes | string[] (optional) | Recorded boundaries used by contraction. If omitted, submitted node names serve as boundaries. |

## Certificate hash

```
certificateHash = "sha256:" + lowercase_hex(SHA-256(UTF-8(JCS(projection))))
projection = { bundleType, createdAt, version, profile, evidence, protectedSet }
```

The producer SDK creates `certificateHash`. The Node does not create, replace or mutate it; it independently recomputes the protected canonical projection to confirm the submitted hash before signing.

## Receipt and verification envelope

Attestation does not modify the CER. `POST /api/attest` returns a separate `receipt` (signed as a whole with Ed25519 over canonical JSON) and a `nexart.verification.envelope.v2` whose signature covers the projection `{ attestation, bundle }`, where `bundle` holds `bundleType`, `version`, `createdAt`, `profile`, `evidence` and `protectedSet`. Exact fields and procedures: Governed Attestation Contract.

## Complete example

Sealed with `@nexart/governed-execution@0.4.2` and verified by the production Node `POST /v1/cer/verify` (`status: verified`). Illustrative evidence, not a partner fixture. It shows a cyclic static topology with an acyclic concrete execution and a repeated `nodeName`.

cer.governed.execution.v1 (0.1)

```
{
  "bundleType": "cer.governed.execution.v1",
  "createdAt": "2026-10-01T09:00:06.000Z",
  "version": "0.1",
  "profile": {
    "id": "cage-governance-v1",
    "version": "1",
    "contract": "urn:cage:governance:v1:attestation-bundle",
    "source": {
      "system": "CAGE",
      "profile": "provider_02"
    }
  },
  "evidence": {
    "bundle": {
      "bundleId": "0b5f1c2a-8e3d-4f6a-9b7c-1d2e3f4a5b6c",
      "threadId": "thread-demo-001",
      "startedAt": "2026-10-01T09:00:00.000Z",
      "completedAt": "2026-10-01T09:00:05.000Z",
      "terminalPath": "happy_path",
      "steps": [
        {
          "stepId": "3f2b8c1e-4d5a-4b6c-8d7e-9f0a1b2c3d4e",
          "nodeName": "execution_analyst",
          "parentStepIds": [],
          "timestampUtc": "2026-10-01T09:00:01.000Z",
          "durationMs": 120,
          "signals": {},
          "metadata": {},
          "stateHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        },
        {
          "stepId": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
          "nodeName": "evaluator",
          "parentStepIds": [
            "3f2b8c1e-4d5a-4b6c-8d7e-9f0a1b2c3d4e"
          ],
          "timestampUtc": "2026-10-01T09:00:02.000Z",
          "durationMs": 120,
          "signals": {},
          "metadata": {},
          "stateHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
        },
        {
          "stepId": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
          "nodeName": "execution_analyst",
          "parentStepIds": [
            "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d"
          ],
          "timestampUtc": "2026-10-01T09:00:03.000Z",
          "durationMs": 120,
          "signals": {},
          "metadata": {},
          "stateHash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
        },
        {
          "stepId": "9e0f1a2b-3c4d-4e5f-a6b7-c8d9e0f1a2b3",
          "nodeName": "evaluator",
          "parentStepIds": [
            "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f"
          ],
          "timestampUtc": "2026-10-01T09:00:04.000Z",
          "durationMs": 120,
          "signals": {},
          "metadata": {},
          "stateHash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
        }
      ]
    },
    "topology": {
      "nodes": [
        "execution_analyst",
        "evaluator",
        "finalizer"
      ],
      "parentEdges": {
        "execution_analyst": [
          "evaluator"
        ],
        "evaluator": [
          "execution_analyst"
        ],
        "finalizer": [
          "evaluator"
        ]
      },
      "terminalNode": "finalizer"
    }
  },
  "protectedSet": {
    "stabilitySchemeId": "jcs-v1",
    "protectedSetId": "nexart.governed.execution.v1.protected-set.v1",
    "protectedFields": [
      "bundleType",
      "createdAt",
      "version",
      "profile",
      "evidence"
    ]
  },
  "certificateHash": "sha256:56cda47867d79166757d8c645990acde5a1cc938eaa325d94fb0ea32a659c70c"
}
```