@nexart/governed-execution

NexArt's SDK for sealing and locally verifying governed-execution evidence. The envelope is profile-dispatched; the first supported profile is cage-governance-v1 version 1, for the CAGE provider_02 AttestationBundle.

CAGE AttestationBundle
  → @nexart/governed-execution
  → cer.governed.execution.v1
  → local verification
  → optional NexArt Node attestation

Profile selection is explicit. Unknown profiles fail closed: there is no evidence-shape inference, arbitrary-JSON profile, fallback, or best-effort verification.

Install

npm install @nexart/governed-execution

The CAGE profile does not require @nexart/ai-execution or @nexart/consequential-execution.

Quick start

import {
  CAGE_GOVERNANCE_PROFILE,
  sealGovernedExecution,
  verifyGovernedExecution,
  type AttestationBundle,
  type GraphTopology,
} from '@nexart/governed-execution';

declare const bundle: AttestationBundle;
declare const topology: GraphTopology | undefined;

const cer = sealGovernedExecution(
  {
    profile: CAGE_GOVERNANCE_PROFILE,
    evidence: { bundle, ...(topology ? { topology } : {}) },
  },
  { createdAt: '2026-09-15T00:00:00.000Z' },
);

const result = verifyGovernedExecution(cer);
if (!result.ok) {
  throw new Error(`${result.code}: ${result.errors.join('; ')}`);
}

Async sealing and verification are available as sealGovernedExecutionAsync() and verifyGovernedExecutionAsync().

bundle is the complete typed CAGE AttestationBundle; topology is optional. The SDK does not claim that supplied topology is complete.

Certificate contract

The exact envelope members are:

bundleType
createdAt
version
profile
evidence
protectedSet
certificateHash

The envelope uses:

bundleType: cer.governed.execution.v1
version: 0.1
protectedSet.protectedSetId:
  nexart.governed.execution.v1.protected-set.v1

The protected CER version remains 0.1; it is independent of the npm package version.

@nexart/[email protected] also provides explicit 0.2 constructors: sealGovernedExecutionV2() and sealGovernedExecutionV2Async(). They retain the same cer.governed.execution.v1 family and CAGE evidence, and use nexart.governed.execution.v1.protected-set.v2. The legacy sealGovernedExecution() APIs always continue to emit 0.1.

An optional identity adjacent to evidence is protected with the following PII-safe shape:

{
  "provider": "issuer",
  "sub": "subject",
  "assertionHash": "sha256:<64 lowercase hex>",
  "verified": true
}

The SDK binds this representation; it does not authenticate people, verify assertions, or turn identity presence into producer authentication.

Confidential 0.2 commitments

sealGovernedExecutionConfidential() and its async equivalent explicitly commit selected leaf paths under a step's signals or metadata, and may commit the complete identity object with confidentialIdentity: true. Commitments use hmac-sha256-v1; salts are exactly 32 random bytes represented as lowercase hex, returned only in openings, and never placed in the CER. The commitment domain binds the family, Governed version, scheme, stable stepId, section, and an RFC 6901-compatible path. This is commitment, not encryption.

The exact commitment bytes are:

HMAC-SHA256(key = 32-byte salt)
  over UTF-8(JCS(domain)) || 0x00 || UTF-8(JCS(plaintext))

The exact JCS domain object is {"family":"cer.governed.execution.v1","version":"0.2","scheme":"hmac-sha256-v1","domain":"identity"} for identity, and {"family":"cer.governed.execution.v1","version":"0.2","scheme":"hmac-sha256-v1","stepId":"<stable stepId>","section":"signals"|"metadata","path":"<RFC6901 path>"} for a leaf. The output is lowercase hexadecimal prefixed with hmac-sha256:. The 32-byte salt is the HMAC key, is returned in opening material only, and is never included in the domain or CER. The complete byte-level CERs, salts, and frozen hashes are in fixtures/golden-v2/; those vectors are the compatibility anchors for this algorithm.

Selective disclosure is performed with verifyGovernedExecutionV2(cer, openings) (or its async equivalent), returning AUTHENTIC, VERIFIED, UNVERIFIABLE, or INVALID. Base verification never requires openings. Unknown versions fail closed; the generic verifyGovernedExecution() dispatches 0.1 and 0.2 without normalizing either record.

validateConfidentialEnvelope(value) is a public structural check returning { valid, errors }; it does not accept internal error-collector arguments.

The CAGE profile descriptor is:

{
  "id": "cage-governance-v1",
  "version": "1",
  "contract": "urn:cage:governance:v1:attestation-bundle",
  "source": {
    "system": "CAGE",
    "profile": "provider_02"
  }
}

evidence contains the complete bundle and optional complete topology. certificateHash is sha256: plus lowercase SHA-256 of UTF-8 JCS over every protected projection member except certificateHash, including the complete received profile, evidence, and protected set. Verification validates constants and shape separately while hashing the received protected values.

Deterministic sealing

createdAt is optional and defaults to the wall clock at issuance. It is part of certificate identity, so deterministic repeatability requires the same explicit createdAt and identical evidence.

Verification and resource boundaries

Certificate integrity, schema validity, causal validity, optional topology validity, canonicalization, and resource safety are independent results. Absent topology is reported as not-supplied and does not prevent successful verification. Warnings such as TERMINAL_PATH_UNKNOWN are non-fatal.

CAGE profile graph semantics

Both the generic cage-governance-v1 profile and the native CAGE path enforce the same contracted concrete-edge rules. Static topology may contain cycles, including self-edges and bounded workflow loops, because it describes possible control flow. Concrete parentStepIds must form an acyclic, causally ordered execution graph with no dangling, future, self, or duplicate parents.

Concrete parents record actual executed relationships and may be a subset of legal topology candidates. A relationship may contract across omitted static nodes to the nearest prior recorded attestation boundary, using its latest concrete step instance. Supplied topology is enforced: any selected edge outside all legal direct or contracted candidates is rejected with ILLEGAL_EXECUTED_EDGE. Unresolvable contraction cycles remain invalid. Topology is preserved verbatim, not normalized. See CAGE profile validation for the detailed contract.

The SDK limits include:

• 256 CAGE steps
• JSON depth 32
• 4,096 array items or object keys
• 1,024 topology nodes
• 4,096 topology edges
• 1 MiB canonical UTF-8 evidence

Canonical-size preflight is bounded. Resource-rejected evidence is not canonicalized or hashed.

Successful verification still reports:

stateHashVerification: not-performed
producerAuthentication: not-performed
completeness: not-claimed

Integrity does not establish execution truth, producer identity, authentication, authorization, policy correctness, legal compliance, safety, fairness, model truth, or completeness.

Scope and non-claims

Version 0.2.0 adds commitment-based confidentiality and protected identity. It does not provide encryption, producer authentication, or identity-provider verification.

Local verification is provided by this package. Optional NexArt Node attestation is a separate downstream operation; this SDK does not attest a Node or Canonical Node and has no network, runtime, CLI, or other NexArt evidence-family dependency.

Future profiles require an explicit registry entry, closed typed schema and validator, independent resource and semantic tests, deterministic vectors, and reviewed compatibility-manifest admission. Profiles are never admitted by data shape or runtime fallback.

This package is not endorsed, sponsored, certified, partnered with, or affiliated with Google or CAGE.

Native CAGE step CERs

The @nexart/governed-execution/cage subpath accepts an AttestationBundle and optional GraphTopology directly. It emits one cer.governed.execution.step.v1 record per executed ProjectBundleStepEntry; it does not emit an AI Execution CER or a bundle-level composite CER.

Native UUID validation follows the mechanically enforced upstream contract: bundleId accepts generic JSON Schema format: "uuid" syntax because current canonical CAGE vectors include non-v4 bundle UUIDs. stepId and every parentStepId remain strict RFC 4122 UUIDv4 identities.

The node record has exactly these semantic members:

bundleType: "cer.governed.execution.step.v1"
version: "1"
schema: {
  step: "urn:cage:governance:v1:step-entry"
  bundle: "urn:cage:governance:v1:attestation-bundle"
}
bundleId
threadId
step: { stepId, nodeName, parentStepIds, timestampUtc, durationMs,
        signals, metadata, stateHash }
protectedSet
certificateHash

startedAt, completedAt, and terminalPath are bundle-level values and are never copied into a node record. parentStepIds remains the native DAG relationship; no parentCertificateHashes or synthetic stepIndex is introduced.

When topology is supplied, native validation checks parentStepIds using CAGE's nearest-recorded-ancestor contraction semantics. Parent IDs refer only to recorded steps and may skip intermediate non-attestation nodes. GraphTopology.parentEdges describes possible legal parent relationships, while concrete parentStepIds records the actual causal edges selected during one execution. The concrete IDs may therefore be a subset of the legal contracted parent candidates. Every selected parent is still validated fail-closed against the topology and ancestor contraction; this does not claim graph completeness or execution truth.

GraphTopology describes possible control flow and may contain cycles or self-edges. AttestationBundle.steps describes one concrete execution DAG: its parent references must be closed, earlier-only, and acyclic.

At bundle-validation and sealing time, supplied topology also enables semantic verification of the declared terminalPath using the fail-closed CAGE precedence ladder. Standalone node CER verification cannot independently derive terminalPath, because neither the bundle outcome nor topology is part of a node CER.

stateHash is an opaque producer commitment to CAGE's private AgentState: NexArt verifies that the submitted value is cryptographically bound into the CER. NexArt does not receive or independently verify the private AgentState preimage, so stateHashVerification remains not-performed.

The current native wire schemas contain no typed provider signature, kid, algorithm, or signed envelope. Producer authentication therefore remains explicitly unclaimed; signals.governanceSignature is not interpreted as a provider signature.

The exact certificate projection is the object formed by the first seven members above plus protectedSet (excluding certificateHash), canonicalized with RFC 8785 JCS. The identity is:

certificateHash = sha256:<lowercase SHA-256 of UTF-8(JCS(projection))>

No clock, sealing time, ingestion time, or generated timestamp participates in this projection. The schemas/provider_02/manifest.json file pins the exact CAGE schema assets, URNs, upstream commit, and source SHA-256 values.