HC Coherence Protocol

npm package: hc-coherence

HC Coherence Protocol is a coherence-first control-plane standard for agent systems. It does not choose answers, tools, or plans. It exposes degraded execution conditions, maps them to bounded controls, and records what happened in a backend-neutral way.

Value

• Keep agent systems stable without rewriting semantic output.
• Give humans and runtimes a shared vocabulary for degraded conditions.
• Make control actions inspectable through schemas, specs, examples, and deterministic validation.

Limits

• HC Coherence Protocol is not a planner, policy engine, workflow engine, or backend API.
• HC Coherence Protocol does not define business logic or product goals.
• Adapter-specific primitive names live only under adapters/.

Requirements

• Node.js 20 or 22 with npm 10 or newer.
• Python 3.11 or newer.
• make and a POSIX shell.

Package Quickstart

Install the published package:

npm i hc-coherence

Use it to access canonical schema URLs, local artifact paths, and public TypeScript types:

const { canonicalUrls, localArtifacts } = require("hc-coherence");

console.log(canonicalUrls.conditionAlert);
console.log(localArtifacts.controlResult);

import { canonicalUrls, localArtifacts, type ConditionAlert } from "hc-coherence";

const alertSchemaUrl = canonicalUrls.conditionAlert;
const localResultSchema = localArtifacts.controlResult;

The npm package publishes contracts, schemas, reference types, examples, and artifact paths. It does not ship a full runtime loop. If you want a runnable integration scaffold, start from templates/ts-coherence-starter/.

Repository Development

1. Install Node dependencies:

   make bootstrap

2. Run the full conformance suite from a clean checkout:

   make test

3. Inspect an end-to-end runtime cycle fixture:

   python3 reference/python/runtime_reference_cases.py cycle cycle-retry-thrash

That fixture emits a deterministic aggregate payload containing alerts, control_sequences, control_results, governor_decision, and execution_controls.

Release Surface

• Canonical JSON Schema IDs resolve under https://tbl369.github.io/hc-coherence-protocol/.
• GitHub Releases attach a packaged artifact bundle containing schemas, specs, docs, validation assets, examples, and reference TypeScript types.
• The npm package hc-coherence mirrors the same artifact layout for offline consumers.
• require("hc-coherence") exposes canonical schema URLs and local artifact paths through canonicalUrls and localArtifacts.
• The repository slug and canonical schema base URL remain hc-coherence-protocol; only the installable npm package name is hc-coherence.

Stability and Support

• The normative protocol surface is stable at 1.0.0.
• specs/, schemas/, validation/, and interfaces/ are the change-controlled public contract.
• reference/ and adapters/ remain implementation aids and portability examples.
• Security reporting guidance lives in SECURITY.md.

Repository Map

• specs/ normative contracts and change-controlled vocabulary.
• interfaces/ implementation-agnostic runtime and data interfaces.
• schemas/ published bundle artifacts plus control-plane JSON schemas.
• validation/ deterministic text-validation profile and conformance vectors.
• docs/ audience-oriented explanatory documents.
• examples/ generic JSON examples plus adapter-specific traces.
• reference/ helper scripts and reference type definitions.
• adapters/ backend-specific mapping notes and examples.
• templates/ starter scaffolds for fast protocol integration.

Protocol Flow

Condition Alert -> Control Mapping -> Control Sequence -> Control Result

This is the public control surface:

1. ConditionAlert describes a degraded execution condition.
2. The Control Mapping Layer translates that alert into abstract control types.
3. ControlSequence carries the ordered control instructions.
4. ControlResult records bounded application outcomes from the backend.

Learning Paths

Fast orientation

1. docs/overview/documentation-guide.md
2. docs/overview/foundation.md
3. docs/concepts/hc-coherence-technical-paper.md
4. specs/core-semantics.spec.md

Runtime integration

1. specs/agent-runtime.spec.md
2. interfaces/agent-runtime.interface.md
3. docs/integration/agent-runtime-blueprint.md
4. docs/integration/portability-patterns.md
5. adapters/openclaw/README.md

Starter template

• templates/ts-coherence-starter/ provides a full TypeScript scaffold with: analyzer, mapping, resolver, governor, loop orchestration, AJV validation, tests, and a runnable sample app.

Reference Runtime

• Python reference runtime: reference/python/agent_runtime_reference.py
• TypeScript reference runtime: reference/typescript/runtime-reference.ts
• Shared parity fixtures: reference/fixtures/runtime-reference-cases.json
• Adapter trace schema: adapters/openclaw/openclaw-trace.schema.json

These references demonstrate the deterministic runtime loop, one control sequence per alert, normalized control results, and parity between the Python and TypeScript implementations.

Data Contracts and Validation

1. specs/condition-alerts.spec.md
2. specs/control-types.spec.md
3. specs/control-mapping.spec.md
4. schemas/control-plane/*.json
5. validation/text-validation-profile.json

Validation

• Full repo checks: make test
• TypeScript parity checks: npm run ts-check and npm run ts-test
• Runtime reference checks: make runtime-check
• Runtime parity fixture runner: python3 reference/python/runtime_reference_cases.py cycle <case-name>
• Artifact schema checks: python3 reference/python/check_schemas.py
• Example integrity checks: python3 reference/python/check_examples.py
• Naming and documentation checks: make docs-lint and make naming-lint
• Release-surface checks: python3 reference/python/check_release_surface.py
• Publishable package smoke test: make pack-dry-run
• Text validation conformance: python3 reference/python/run_text_validation_conformance.py