RC2 Developer PreviewProduction Governance Hardening II

Get Started with NEES Core Engine V2

Route AI requests through NEES before model, tool, API or action execution. The hardened RC2 path evaluates contextual legitimacy, separates governance assessment from execution lifecycle, protects retry identity, and exposes privacy-preserving evidence for review.

Hardening II validation: 676 tests passed with zero failures, benchmark 29/29, replay consistency 1.0. Current validated deployment boundary is bounded single-host integration review.

Request API Access Test Governance Lab

A. Integration Boundary

Your App

→

Your Backend

→

NEES Core Engine

→

Model / Tool / API

→

Governed Result

Keep credentials and external side-effect execution on your backend. NEES should sit before the action boundary, not after it. Direct ungated side-effect paths fall outside the governed boundary.

B. Chat Request Contract

bash

curl -X POST https://api.nees.cloud/chat \
  -H "Authorization: Bearer YOUR_NEES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Help me prepare a customer refund request.",
    "input": "Help me prepare a customer refund request.",
    "mode": "public",
    "session_id": "demo_session_001",
    "user_id": "demo_user_001",
    "metadata": {
      "source": "your_app",
      "public_safe": true
    }
  }'

Field	Meaning
message	Primary natural-language request sent for governance and execution reasoning.
input	Compatibility field carrying the same governed request text for the current public RC2 transport.
mode	Use a Core-supported mode. This public guide uses public; use only the mode assigned or documented for your access.
session_id	Stable session/workflow identifier used to preserve the correct context boundary. It is not a business-budget reset mechanism.
user_id	Application-level user or actor identifier. Do not substitute a different user's identity.
metadata	Optional structured context such as source, workflow labels or public-safe flags. Never place secrets here.

C. JavaScript

javascript

const response = await fetch("https://api.nees.cloud/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NEES_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Help me prepare a customer refund request.",
    input: "Help me prepare a customer refund request.",
    mode: "public",
    session_id: "demo_session_001",
    user_id: "demo_user_001",
    metadata: {
      source: "your_app",
      public_safe: true,
    },
  }),
});

if (!response.ok) {
  throw new Error(`NEES request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

D. Python

python

import os
import requests

payload = {
    "message": "Help me prepare a customer refund request.",
    "input": "Help me prepare a customer refund request.",
    "mode": "public",
    "session_id": "demo_session_001",
    "user_id": "demo_user_001",
    "metadata": {
        "source": "your_app",
        "public_safe": True,
    },
}

response = requests.post(
    "https://api.nees.cloud/chat",
    json=payload,
    headers={
        "Authorization": f"Bearer {os.environ['NEES_API_KEY']}",
        "Content-Type": "application/json",
    },
    timeout=45,
)
response.raise_for_status()
print(response.json())

E. Response Contract

json

{
  "answer": "I can help prepare the refund request, but I need the customer order ID before any refund action can proceed.",
  "trace_id": "trace_abc123",
  "engine_source": "nees_core_engine",
  "governance": {
    "policy_decision": "CLARIFY",
    "enforcement_action": "NO_ACTION",
    "authorization_required": true,
    "request_understanding": {
      "request_kind": "action_oriented",
      "operation": "refund",
      "access_type": "mutate",
      "side_effect_level": "material"
    }
  }
}

Field	Meaning
answer / reply	The governed response text when the runtime returns one. Clients should tolerate compatible response aliases.
trace_id	Governance trace identifier for debugging, review and evidence collection.
engine_source	Runtime source that handled the request.
governance.policy_decision	Structured governance outcome such as ALLOW, CLARIFY, ESCALATE, REFUSE or BLOCK.
governance.enforcement_action	Execution instruction such as execute, no-action, stop or another controlled action.
governance.request_understanding	Structured interpretation of request kind, operation, access type, sensitivity or side-effect level when returned.
governance_outcome	Action evidence can preserve the governance assessment independently from a later execution-time BLOCK or lifecycle result.
execution_status	Execution lifecycle state. Treat it separately from the governance assessment; unknown does not mean no execution.

Consume structured governance fields defensively. Response aliases may exist for compatibility, but governance decisions, lifecycle status and trace context must not be guessed from free-form text.

F. Decision Semantics

Decision	Required Client Behavior
ALLOW	The approved response/action path may continue within the returned governance boundary.
CLARIFY	NO ACTION. Collect the required clarification before any side effect continues.
ESCALATE	Do not auto-execute. Route the request to the required controlled or higher-authority step.
REFUSE	NO ACTION. The request is explicitly refused by governance policy and must not execute.
BLOCK	NO ACTION. Stop the disallowed path and surface a safe explanation or alternative when appropriate.

Unknown or malformed governance result = fail closed. Never silently treat it as ALLOW.

G. Operation Identity & Retry Safety

json

{
  "action_ref": "trusted-host-reference",
  "session_id": "session-reference",
  "operation_key": "stable-business-operation-key",
  "wait": {
    "permitted": true,
    "max_wait_seconds": 120
  }
}

Reuse the same operation_key for network retries of the same canonical business operation.

Same key + same canonical request returns the existing operation status/result and does not start a new effect.

Same key + conflicting canonical request returns 409.

Do not create a new key to retry an uncertain effect. Reconcile provider state first.

Omitting the key preserves older per-submission operation behavior; stable keys are recommended where retry identity matters.

H. Execution Lifecycle & Recovery

Status	Meaning
succeeded	The governed operation completed with a confirmed result.
aborted	The operation stopped before completing.
expired	The execution window expired. Late approval cannot turn expiry into permission.
failed	The operation failed and the effect cannot be classified as safely absent.
failed_no_effect	Failure is known to have produced no external effect.
reconciliation_required	External effect is uncertain. Query trusted provider state before any retry or new effect.

Approval must be valid before required execution. Deadline checks repeat at resume and execution.

Expiry cannot become permission. A late approval does not revive an expired operation.

Continue CLARIFY/ESCALATE through the existing validated resume path with trusted clarification or host-issued approval.

Do not keep a browser or HTTP request spinning while waiting for human approval.

I. Decision Evidence & Comparison

http

GET /audit/lab-evidence/{request_id}?compare_to={other_request_id}
GET /governance/actions/{action_id}/evidence?compare_to={other_action_id}

These authenticated readers are read-only evidence surfaces. They do not execute providers, tools or persistence simulation.

Exports use governance-lab/v1. Decision-input commitments are opaque keyed digests: they support comparison without exposing raw prompts, authority identities or secret policy values.

Missing evidence is reported as insufficient evidence rather than silently treating two runs as equivalent.

Classification	Meaning
relevant_state_changed	A governed state commitment changed between the compared decisions.
semantic_interpretation_changed	The semantic interpretation commitment changed.
inconsistent_policy_outcomes	Comparable evidence indicates a policy-outcome inconsistency.
unexplained_difference	A difference exists but the available commitments do not explain it.
insufficient_evidence_to_establish_equivalence	Required historical context, groups or compatible evidence are missing. Do not claim equivalence.
equivalent_resolved_inputs	The available resolved-input commitments establish equivalence for the compared evidence.

J. Error Handling

Status	Meaning
400 / 422	Invalid request shape or validation failure. Fix the integration contract; do not retry blindly.
401	Missing, invalid or revoked API key.
403	Access or policy restriction. Do not bypass the governance result.
404	Evidence reference is missing or outside the authenticated tenant/owner scope.
409	The same operation_key was reused with a conflicting canonical request. Do not generate a new key to bypass the conflict.
429	Rate limit reached. Apply backoff before retrying.
5xx	Runtime/provider unavailable or internal failure. Fail safely and avoid ungoverned fallback execution.

K. Production Checklist

Keep NEES API keys and approval credentials server-side only.

Use stable user_id and session_id values from your authenticated application context.

Log trace_id and action_id with your own application request or business-operation reference.

Reuse the same operation_key for network retries of the same business operation.

Never generate a new operation_key to retry an uncertain external effect.

Treat CLARIFY, ESCALATE, REFUSE and BLOCK as non-execution outcomes unless a later validated resume authorizes execution.

Do not hold an HTTP request open waiting for approval; resume through the assigned validated continuation path.

Treat reconciliation_required as a recovery state, not as permission to retry blindly.

Never convert an unknown or malformed governance decision into ALLOW.

Test cross-session, wrong-authority, ambiguous-resource, policy-override, retry and reconciliation scenarios before production use.

Keep external tool/API execution behind the NEES decision boundary.

Use explicit timeouts, durable state, backups and safe failure behavior when the runtime or provider is unavailable.

L. Validated Scope & Boundaries

What Hardening II proves — and what it does not.

Validated Hardening II topology is bounded single-host. Multi-host coherent governance state is not yet a supported release topology.

The reference refund adapter used for validation is local/mock; the validation is not proof of a live external financial integration.

NEES does not claim exactly-once external execution. Uncertain effects require trusted provider reconciliation.

Chat evidence comparison can remain insufficient across process restarts until a future host key-retention integration persists the chat evidence key.

The public Governance Lab is a synthetic test surface, not a universal security, safety or compliance certification.

Developer Preview Access

Integrate against an assigned RC2 access path.

Developer Preview credentials, approved mode, action endpoints and resume paths may be assigned per tester or application. The public examples use the supported public chat mode; use only the routes and authority model documented for your access.

Request API Access Contact info@nees.cloud