Coil compiler

developer

compileCoil outputs, determinism guarantees, and versioning.

One Coil in, every artifact out

compileCoil(coil, options) is the single entry point that turns a validated Coil into all of its artifacts in one deterministic pass. Paper Coils compile a runbook and share card only; non-paper Coils additionally compile an Execution Capsule with its own receipt.

compileCoil

import { compileCoil } from "@hiss/core";

const compiled = compileCoil(coil, {
  nowIso: "2026-07-07T00:00:00.000Z", // pinning the clock pins the output
  maxTotalNotionalUsd: 1000,          // optional budget ceiling (default 1000)
  userAcknowledgedAgenticMode: false, // required true only for agentic_mcp_enabled
  shareUrlBase: "https://www.hiss.finance", // optional; enables shareCard.shareUrl
});

Outputs (CompiledCoil)

CompiledCoil fields
Field	Type	Required	Description
runbook	{ title, markdown }	yes	The session-protocol markdown: whisper, mode, targets, policy, triggers, fuses, steps.
capsule	ExecutionCapsule?	no	Only for non-paper modes; paper_only Coils never produce one.
mcpInstructionBlock	string?	no	Convenience alias for capsule.robinhoodMcpInstructions — the paste-ready text block.
toolCallPlan	string[]	yes	The ordered MCP tool sequence an agent should run each session (see below).
fuseChecklist	string[]	yes	Every fuse rendered through describeFuse() — human- and agent-readable.
receipt	CoilReceipt	yes	The coil_manifest receipt for this compile.
capsuleReceipt	CoilReceipt?	no	The robinhood_capsule receipt, when a capsule compiled.
shareCard	ShareCardPayload	yes	The proof-artifact payload — see Share cards.

The tool-call plan

Every compile emits the pre-flight sequence agents should replay against the HISS MCP server (paper Coils swap the capsule step for a report-only hiss_drift_check):

toolCallPlan

[
  "hiss_validate_coil — confirm the manifest still validates",
  "hiss_score_coil — recompute Coil Health",
  "hiss_risk_audit — walk every fuse against current account state",
  "hiss_compile_robinhood_capsule — refresh the capsule before any session",
  "hiss_create_receipt — write the session receipt"
]

Determinism

The clock is an input. Every compile takes nowIso explicitly; the same Coil and the same timestamp produce byte-identical artifacts, receipts included. Replays are exact.
No network, no randomness. Compilation is a pure function over the Coil — registry lookups and hashing only.
Checksums close the loop. manifestHash, fuseChecksum, and capsuleChecksum are canonical-JSON SHA-256 hashes; verifyCoilReceipt recomputes them from scratch to prove nothing drifted.

Versioning

COIL_SCHEMA_VERSION = "coil-1.0.0" — the Coil manifest shape. Validation rejects any other value (COIL_SCHEMA).
COIL_COMPILER_VERSION = "coil-compiler-1.0.0" — stamped into every capsule (capsuleVersion) and every receipt (compilerVersion), so an artifact always names the compiler that produced it.
A Coil’s own version is a monotonic integer, bumped on any content change; receipts record it as coilVersion.

Failure modes

CapsuleCompileError with the validation error list when the Coil fails capsule validation (missing required fuses, bad weights, symbol-space confusion…).
MODE_PAPER_ONLY — paper Coils refuse capsule compilation by design.
AGENTIC_ACK_REQUIRED — agentic_mcp_enabled without the explicit userAcknowledgedAgenticMode flag.

$HISS is independent research software in paper mode — not investment advice, and not affiliated with Robinhood, Bankr, or Chainlink.