THIRD_PARTY_GUIDE

HELM Third-Party Implementation Guide

How to build a HELM-conformant implementation from scratch.

1. Architecture Overview

A conformant HELM implementation requires these components:

┌─────────────────┐     ┌──────────────┐     ┌──────────────┐
│  Your Runtime   │────▶│  Effect      │────▶│  Policy      │
│  (Agent/App)    │     │  Boundary    │     │  Decision    │
│                 │◀────│              │◀────│  Point       │
└─────────────────┘     └──────────────┘     └──────────────┘
                              │
                        ┌─────▼──────┐
                        │  Receipt   │
                        │  Store     │
                        └────────────┘

2. Step-by-Step

Step 1: Implement EffectBoundary

Implement the EffectBoundaryService interface from either:

gRPC: protocols/proto/helm/kernel/v1/helm.proto
REST: protocols/specs/effects/openapi.yaml

Required operations:

Submit(effect) → verdict + receipt + intent
Complete(result) → completion receipt

Step 2: Implement Policy Decision Point

Evaluate policy rules against submitted effects. Options:

Use the HELM PDP library (Go)
Implement PolicyDecisionPointService from the proto
Write a custom PDP that returns PDPResponse

Step 3: Generate Receipts

Every governance decision MUST produce a Receipt per protocols/specs/rfc/receipt-format-v1.md:

Content-addressed receipt_id (SHA-256)
Monotonic lamport clock
Ed25519 or ECDSA signature

Step 4: Run Conformance Vectors

helm conform run \
  --vectors protocols/conformance/v1/test-vectors.json \
  --endpoint http://your-server:4001 \
  --level 4

Step 5: Submit to Compatibility Registry

Open a PR adding your implementation to protocols/conformance/v1/compatibility-registry.json.

3. Reference Materials

Document	Path
Receipt Format RFC	`protocols/specs/rfc/receipt-format-v1.md`
Reason Codes RFC	`protocols/specs/rfc/reason-codes-v1.md`
Identifier URN RFC	`protocols/specs/rfc/identifier-urn-v1.md`
Versioning RFC	`protocols/specs/rfc/artifact-versioning-v1.md`
OpenAPI Spec	`protocols/specs/effects/openapi.yaml`
Proto IDL	`protocols/proto/helm/kernel/v1/helm.proto`
Conformance Guide	`protocols/conformance/v1/CONFORMANCE_GUIDE.md`

4. Certification

See CONFORMANCE.md for gate levels and profile verification.