Add Harmonic after your model call.

HCS Specification Library

The Harmonic Constitutional Specification (HCS) series defines the implementation-independent constitutional architecture behind continuation governance.

HCS-000 → HCS-001 → HCS-002 → HCS-003 → HCS-004 → HCS-005 → HCS-006 → HCS-099

View the HCS Library · Download the complete HCS v1.0 ZIP

Flow

User → LLM / Agent → Harmonic → constitutional determination → execution directive → response or execution

Determination: PERMITTED / CONSTRAINED / ESCALATED / REFUSED / EMERGENCY_CONTINUITY
Directive:     ALLOW / CONSTRAIN / ESCALATE / BLOCK

Frozen V4.1 Single-Call Contract

POST /api/evaluate is the frozen V4.1 production pathway. Successful Governance+ responses identify runtime_version: "4.1.0".

Vocabulary: the constitutional determination is the canonical outcome (PERMITTED, CONSTRAINED, ESCALATED, REFUSED, or EMERGENCY_CONTINUITY). The execution directive is the corresponding downstream instruction (ALLOW, CONSTRAIN, ESCALATE, or BLOCK). These are different fields with different meanings.

The caller supplies the attributable present-state facts. Harmonic does not infer domain state from raw observations. For a material transition, use understanding_state together with state_transition.

{
  "packet_id": "case-001-v40",
  "requested_action": { "type": "clinical_order", "scope": ["care_plan"] },
  "understanding_state": {
    "current": false,
    "complete": true,
    "provenance_preserved": true,
    "applicable": true,
    "confidence": 0.96,
    "source_ids": ["obs-002"],
    "unresolved_tensions": [],
    "missing_information": [],
    "revision_status": "superseded"
  },
  "state_transition": {
    "prior_state_ref": "state-001",
    "new_observation_refs": ["obs-002"],
    "relationship": "material_contradiction",
    "prior_state_status": "superseded",
    "revalidation_required": true,
    "attributable_source": "institutional-source",
    "observed_at": "2026-08-14T14:00:00.000Z",
    "scope": ["care_plan"]
  },
  "declared_reality": {
    "current_state_claims": ["Previously declared state remains the historical baseline"],
    "last_verified_at": "2026-08-14T13:30:00.000Z"
  },
  "observed_reality": {
    "signals": [{ "statement": "New attributable observation materially conflicts with continued reliance on the prior state" }]
  },
  "authority_chain": {
    "subject": "clinical-agent-1",
    "issuer": "hospital-ops",
    "scope": ["care_plan"],
    "last_verified_at": "2026-08-14T14:00:00.000Z",
    "chain": [
      { "actor": "clinical-agent-1", "status": "active" },
      { "actor": "hospital-ops", "status": "active" }
    ]
  },
  "revocation_state": {
    "last_revocation_check_at": "2026-08-14T14:00:00.000Z",
    "known_revocations": []
  },
  "present_state_provenance": {
    "attributable_source": "institutional-source",
    "established_at": "2026-08-14T14:00:00.000Z",
    "epistemic_status": "ESTABLISHED",
    "evidence_refs": ["obs-002"]
  },
  "consequence_profile": {
    "level": "high",
    "reversibility": "reversible",
    "execution_surface": "clinical_order"
  },
  "safeguards": { "operator_review_confirmed": true }
}

Material-transition semantics: relationship: "material_contradiction" or prior_state_status: "superseded" makes reliance on the prior state non-current and produces an Understanding Continuity block until revalidation. revalidation_required: true without a superseding/material contradiction produces an explicit revalidation requirement rather than silently inferring one.

Authority revocation: populate revocation_state.known_revocations with objects containing target (or subject/actor) and/or scope. A matching subject or requested scope is treated as revoked.

Historical snapshots: prior_snapshot_ref is not part of the V4.0 single-call contract. Use the evidence-preservation/reconstruction APIs when a separately preserved historical snapshot must be referenced.

Governance Plus Secure Execution — Same API Call

No second Harmonic endpoint is required. Governance Plus Secure Execution remains inside POST /api/evaluate. Project entitlement controls whether the Secure Execution stage is available.

Caller → POST /api/evaluate → Governance Plus determination
                              ├─ non-permitting → no receipt, no executor call
                              └─ PERMIT → execution receipt → allowlisted executor

The request adds an optional secure_execution block containing the exact intent and execute payload. Executor URLs are configured server-side and cannot be supplied by the caller.

{
  "packet_id": "refund-001",
  "requested_action": { "type": "payments:refund" },
  "secure_execution": {
    "requested": true,
    "service": "payments",
    "idempotency_key": "refund-001",
    "intent": {
      "actor": { "id": "agent-17" },
      "intent": "issue_refund"
    },
    "execute": {
      "action": "payments:refund",
      "transaction_id": "tx-123",
      "amount": 250,
      "currency": "USD"
    },
    "policy_state": { "policy_version": "refunds-7" },
    "authority_schema_hash": "<SAC schema hash>"
  }
}

After a permitting determination has been persisted, Harmonic signs a short-lived receipt binding the intent, exact execute payload, policy state, authority state/schema, constitutional determination, project/tenant context, service, and idempotency key. Harmonic then forwards to the server-configured executor. The executor must verify the receipt before performing the side effect.

Receipt header: x-harmonic-execution-receipt. A legacy-compatible x-solace-receipt header is also sent so existing Solace Adapter executor patterns can migrate without a second control-plane hop.

SAC binding: when authority_schema is supplied, Harmonic uses SAC-compatible deterministic normalization and hashing. If an expected authority_schema_hash is also supplied and does not match, execution fails closed.

The existing response_binding remains scoped to the governed-response contract. Secure Execution is exposed separately as secure_execution; the two are not conflated.

Integration Contract: Representation, Standing & Evidence

Core rule: adapters may translate representation. They may not manufacture standing.

External systems may express the same supplied fact in different schemas, field names, or transport envelopes. An integration layer may normalize those supplied facts into Harmonic's canonical request contract. It must not invent missing domain state, infer a positive predicate from ambiguous prose, create provenance that was not supplied, or treat the absence of contrary evidence as affirmative present standing.

External representation → adapter / normalizer → canonical Harmonic packet → Harmonic evaluation

Allowed:    translate an explicitly supplied revocation into revocation_state
Allowed:    preserve supplied timestamps, source IDs, scope, and evidence references
Not allowed: infer that authority is current because no revocation was supplied
Not allowed: invent provenance, evidence, attribution, or a positive predicate

UNKNOWN and fail-closed semantics

Historical validity does not automatically confer present execution authority. Where a consequence requires a positive predicate, missing, ambiguous, stale, unsupported, or otherwise insufficient input must not silently inherit a prior YES. Harmonic preserves unknown or not-established state as distinct from an adverse finding; downstream execution must not convert that uncertainty into authority.

Runtime state is not evidentiary provenance

Harmonic evaluates the constitutional facts supplied to it. A runtime packet can therefore support a determination about the supplied state without independently proving that the supplied state is an externally attributable fact. If an integration requires audit, qualification, regulatory, or independent-assessment evidence, provide the relevant attributable source, establishment time, evidence references, and authority provenance at the boundary.

Synthetic fixtures and external evidence

A synthetic test fixture may deliberately supply T₀, ΔN, authority, revocation, or present-state facts to test runtime behavior. That can establish how Harmonic behaves for the supplied fixture. It does not, by itself, establish those fixture facts as externally proven events. Do not relabel a synthetic assertion as independent provenance.

Builder requirement: define the positive predicates required for each consequential execution surface, map supplied domain facts into the canonical contract without semantic invention, preserve provenance when externally defensible standing is required, and bind execution so that a non-permitting directive cannot be bypassed.

cURL

curl -X POST "https://www.solace-harmonic.com/api/evaluate" \
  -H "Authorization: Bearer hs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"response":"The assistant recommends stopping medication immediately.","consequence_level":"high"}'

Node

async function evaluateWithHarmonic(response) {
  const result = await fetch("https://www.solace-harmonic.com/api/evaluate", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.HARMONIC_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      response,
      consequence_level: "medium",
    }),
  });

  if (!result.ok) throw new Error(await result.text());
  return result.json();
}

Python

import os
import requests

def evaluate_with_harmonic(response):
    r = requests.post(
        "https://www.solace-harmonic.com/api/evaluate",
        headers={
            "Authorization": f"Bearer {os.environ['HARMONIC_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "response": response,
            "consequence_level": "medium",
        },
        timeout=20,
    )
    r.raise_for_status()
    return r.json()

Decision Handling

if (decision.recommended_action === "deny") halt();
if (decision.recommended_action === "escalate") requestHumanReview();
if (decision.recommended_action === "constrain") applySafeCompletion();
if (decision.recommended_action === "allow") continueNormally();