Esc
  • SuggestedWhat is HCP?
  • SuggestedBuild a pack
  • SuggestedPack classes
  • SuggestedSpecification
  • SuggestedCLI reference
.md

Runtime conformance

The executable vectors a runtime must pass, the checklist behind them, what the suite does not cover yet, and how to run it against your driver.

On this page

A runtime conforms when it passes the vectors and meets the checklist, and both are executable. Point the vectors at your own driver, work through the checklist for what they do not test yet, then report the result.

Vectors#

The protocol's vectors ship in the SDK and use transit and ledger as fixtures:

Terminal
cd hcp/packages/sdk && bun test src/conformance.test.ts
VectorPasses when
Linttransit, ledger, and the composite echo lint clean
Readtransit find runs through the sandboxed runtime and returns the stop it resolved
Confirmtransfer without confirm → { ok: false, error: "confirm required" }; with confirm: true → ok: true
Grant denyWith no grants, a read → ok: false, error contains denied

The suite does not yet compare the twin faces, run a bin that is not allow-listed, or lint a wrap with neither named commands nor pass_through. The checklist still requires all three; the twin-face check and the sandbox deny show how to test them.

Running them against your driver#

Pointing Hcp at your driver runs the same tests:

TypeScript
import { Hcp, loadPackFromDir } from '@harnesscontextprotocol/sdk'

const packs = await Promise.all([loadPackFromDir(transitDir), loadPackFromDir(ledgerDir)])
const hcp = await Hcp.create({ runtime: createAcmeRuntime({ packs, … }), grants })
await hcp.activate(['transit', 'ledger'])

expect((await hcp.exec('ledger', 'transfer', { amount: '2.80', payee: 'demo-transit' })).error).toBe('confirm required')

Runtime checklist#

Loading#

  • Loads surface.json, policy.json, HARNESS.md from a directory
  • Rejects a pack with any lint issue at install
  • Checks id = surface_id = pack_id
  • Rejects an unsupported hcp protocol affinity and reports it

Authorisation#

  • Exactly one Principal per exec, from the session
  • Five capability axes; none collapsed in multi-tenant deployments
  • brain land requires project scope
  • Tenant never taken from envelope args
  • Denials carry a reason string
  • No default-allow path

Gates and Binding#

  • confirm: true enforced before any adapter; confirm / apply in args satisfies it
  • confirm: "always" gated at least like confirm: true (draft RFC 0006)
  • Mint fail-closed; no env-token fallback
  • mock only when explicit in the envelope
  • mothership Binding unreachable from a non-operator Principal without an elevation grant
  • connect requires pack.connect, not verb.exec.write

Execution#

  • Wrap argv rendered from cli[] / argv_template; no shell interpolation
  • The JSON flag appended (--json unless json_flag says otherwise); result parsed when possible
  • Non-zero exit → ok: false with stderr or exit N
  • Sandbox default; unknown bin denied; cwd fixed
  • native-local requires explicit opt-in

Reporting#

  • Availability per pack: installed, activated, connected
  • Availability per command: executable with reason when false
  • Skill exposed on activate (copied to skills/<id>/SKILL.md or equivalent)

Sense (if implemented)#

  • Activation independent of Execute
  • sense.enable checked before any sink write; off → drop
  • Undeclared refs dropped and reported
  • Sink records inert and attributable
  • Wake path goes through Execute grants
  • binding.degraded produced by the hub

Audit#

  • Writes attributed with Principal + tenant (+ project) + Binding + pack_id + verb_key + operation

Reporting conformance#

State the protocol version (HCP/1.1), the vector suite commit, and which optional parts you implement (Sense, MCP export, the openapi adapter), then follow Implementations to be listed.