Supersedes: rtr-clearinghouse/PLUGIN_API.md (pre-AGTS; retained as historical reference)
Overview
The AGTS Clearinghouse Plugin API allows any governance vertical to integrate with the shared clearinghouse infrastructure. A plugin provides domain-specific governance logic; the clearinghouse provides:
- Cryptographic identity management (Ed25519 / ECDSA P-256, full 64-char node_id)
- Policy Validator network (BFT, 3-of-4 quorum, AGTS_VOTE_V1 protocol)
- Governance Envelope assembly (Proof Bundle → Certificate → Envelope → Canonical Leaf)
- Transparency Log submission and verification
- Merkle-chained measurement evidence accumulation
- HCE trust observable state machine
- ACTIVE / QUARANTINE / LOCKBOX lifecycle management
- Settlement receipt generation (AGTS_SETTLEMENT_V1)
The plugin provides: domain-specific G1–G5 gate evidence, policy-relevant metadata for validators, and domain-specific observable nudges (optional override).
Plugin Interface Contract
A plugin is a JavaScript object implementing five mandatory properties:
const agtsPlugin = {
// 1. Unique domain identifier
get name() { return 'myDomain'; },
// 2. Called once on registration.
// onMeasurement(m) — call to push events into the clearinghouse.
async initialize(onMeasurement) {
this._emit = onMeasurement;
onMeasurement({
type: 'plugin_registered',
measurement_source: 'PLUGIN',
plugin: this.name,
timestamp: new Date().toISOString(),
});
},
// 3. Returns current plugin status — synchronous, non-throwing.
getStatus() {
return {
name: this.name,
initialized: true,
lifecycleState: 'ACTIVE',
};
},
// 4. Handle messages from the clearinghouse or other plugins.
async onMessage(msg, sender) { return null; },
// 5. Called on clearinghouse shutdown.
destroy() { this._emit = null; },
};
// Registration:
await clearinghouse.pluginRegistry.register(agtsPlugin);
// Calls initialize(onMeasurement) automatically.
// If initialize() throws, plugin is not registered.
Measurement Object Shape
Every call to onMeasurement(m):
- Adds a domain-separated leaf to the local Merkle tree (
SHA256("AGTS_LEAF_V1" || canonical_json(m))) - Updates H/C/E trust observables via the nudge table
- Updates metering counters if a governance event type is detected
- Triggers a dashboard refresh
Required fields
onMeasurement({
type: '<measurement type — see table below>',
measurement_source: 'PLUGIN',
plugin: this.name,
timestamp: new Date().toISOString(),
// + any additional domain fields
});
Standard measurement types
| Type | HCE effect | When to use |
|---|---|---|
plugin_registered | H↑ | Plugin initialization complete |
plugin_error | H↓ | Internal plugin error |
gate_pass | H↑ C↑ E↓ | Any single RTR gate (G1–G5) passes |
gate_fail | H↓ C↓ E↑ | Any single RTR gate fails |
agts_governance_evidence | H↑ C↑ E↓ | Full G1–G5 evidence set ready for Proof Bundle assembly |
agts_envelope_admitted | H↑ C↑ E↓ | Governance Envelope successfully admitted to Transparency Log |
agts_envelope_rejected | H↓ C↓ E↑ | Governance Envelope rejected by log or validator network |
receipt_submitted | H↑ | AGTS_SETTLEMENT_V1 successfully submitted |
receipt_error | H↓ | Settlement receipt submission failed |
plugin_analyzed | H↑ | Plugin code analysis complete |
plugin_admitted | H↑ | Plugin admitted to registry |
plugin_revoked | H↓ | Plugin revoked from registry |
Emitting Governance Evidence
When a plugin has collected all five gate results for a governed action, it emits an agts_governance_evidence measurement. This triggers the clearinghouse to assemble a AGTS_PROOF_BUNDLE_V1 and initiate the validator network round.
this._emit({
type: 'agts_governance_evidence',
measurement_source: 'PLUGIN',
plugin: this.name,
timestamp: new Date().toISOString(),
subject_id: 'myDomain:model-update:v2.1',
capability_certificate_id: '<64-char hex>',
deployment_artifact_hash: '<64-char hex>',
gate_results: {
G1: { result: 'PASS', confidence_interval_lower: 0.72, confidence_interval_upper: 0.89, bootstrap_iterations: 10000 },
G2: { result: 'PASS', causal_attribution: true, ablation_delta: 0.043 },
G3: { result: 'PASS', protected_metrics: { accuracy_on_holdout: 0.923 } },
G4: { result: 'PASS', evidence_class: 'HOOKED' },
G5: { result: 'PASS', operator_id: 'alice@example.com' },
},
evidence: {
dataset_provenance_hash: '<64-char hex>',
evaluation_trace_hash: '<64-char hex>',
ablation_execution_log_hash: '<64-char hex>',
capability_certificate_hash: '<64-char hex>',
},
state_before_hash: '<64-char hex>',
state_after_hash: '<64-char hex>',
replay_seed: '<hex-or-URI>',
});
G4 evidence class definitions
| Class | Meaning | Validation rule |
|---|---|---|
HOOKED | Evidence from instrumented external harness | Dataset provenance hash MUST be commitment from the harness, not the evaluated system |
ATTESTED | Evidence from attested execution environment (TEE/secure enclave) | Attestation certificate MUST be included in capability_certificate_hash |
INSTRUMENTED | Evidence from internal instrumentation with independent audit log | Ablation execution log MUST be retrievable at a durable URI |
Validators MUST reject Proof Bundles with evidence_class: "SELF_REPORTED" or any class not in this table.
Iframe-Hosted Plugins (postMessage bridge)
If your domain's UI is a standalone HTML page hosted in an iframe, bridge events via postMessage:
// From inside the iframe:
window.parent.postMessage({
type: 'AGTS_GOVERNANCE_EVIDENCE',
payload: {
plugin: 'myDomain',
timestamp: new Date().toISOString(),
subject_id: 'myDomain:action:id',
gate_results: { G1: {...}, G2: {...}, G3: {...}, G4: {...}, G5: {...} },
evidence: { dataset_provenance_hash: '...', ... },
state_before_hash: '...',
state_after_hash: '...',
replay_seed: '...',
},
}, '*');
| Type | Payload | Effect |
|---|---|---|
AGTS_GOVERNANCE_EVIDENCE | Full evidence object | Triggers Proof Bundle assembly + validator round |
AGTS_GATE_RESULT | { gate, pass, ...result_fields } | Increments individual gate counter |
AGTS_GET_STATUS | — | Clearinghouse responds with current status |
AGTS_SUBMIT_SETTLEMENT | { counters } | Triggers manual settlement receipt submission |
Pre-AGTS types RTR_GOV_BUNDLE_V1, RTR_GATE_RESULT — not recognized by the AGTS clearinghouse. Do not use.
Validator Evaluation Rules
Policy Validators evaluate each Proof Bundle against these mandatory rules. Verify locally before emitting to avoid unnecessary validator round failures:
| Rule | Check |
|---|---|
| All gates pass | gate_results.G1.result == "PASS" through G5.result == "PASS" |
| Evidence class valid | gate_results.G4.evidence_class ∈ {HOOKED, ATTESTED, INSTRUMENTED} |
| All G4 hashes present | evidence.dataset_provenance_hash, evaluation_trace_hash, ablation_execution_log_hash, capability_certificate_hash all non-null |
| G5 operator_id present | gate_results.G5.operator_id is a non-empty string |
| Replay seed present | replay_seed is non-null |
generated_at in window | Within 30-day replay window, ≤ 5-minute future skew |
| G1 CI is valid | confidence_interval_lower > 0 and ≤ confidence_interval_upper |
Lifecycle State Reference
| State | Meaning | What happens |
|---|---|---|
PROPOSED | Registered, waiting for first successful gate pass | No Governance Envelope issuance |
ACTIVE | Operating normally | Full pipeline: evidence → validators → envelope → log |
QUARANTINE | Degraded — 3+ consecutive gate failures | Evidence accumulates; validator rounds suspended; alert emitted |
LOCKBOX | Suspended — 10+ consecutive failures | Read-only forensic state; no new measurements accepted |
REJECTED | Permanent policy violation | Cannot be reactivated without full restart and new registration |
Key differences from rtr-clearinghouse Plugin API
| Pre-AGTS (rtr-clearinghouse) | AGTS (agts-clearinghouse) |
|---|---|
RTR_GOV_BUNDLE_V1 message type | AGTS_GOVERNANCE_EVIDENCE message type |
| G4 evidence hashes as flat fields in receipt body | G4 evidence hashes in structured evidence object |
nodeId (16-char truncation) | node_id (64-char, full SHA256 of DER SPKI) |
lastBundleHash | parent_bundle_hash |
| camelCase fields | snake_case fields |
Signing: Sign(UTF8(hex(SHA256(body)))) | Signing: Sign(SHA256(canonical_json(body))) |
| Leaf hash: no prefix | Leaf hash: SHA256("AGTS_LEAF_V1" || canonical_json(m)) |
| No Sovereign Authority | Governance Envelope requires authority_signature before log admission |