ChronoSeal Third-Party Wrapper & Integration Guide (WRAPPER_GUIDE)

This document provides stable guidance for developers building third-party integration wrappers, clients, or SDKs around the chronoseald daemon.

1. Public Contract & Stability Guarantees

As a protocol-first Unix daemon, chronoseald guarantees stability on the public network interface.

Endpoints: POST /init and POST /hb.
JSON Fields: The structure and naming of request and response keys.
VM Instruction Set: The behavior and encoding of the 10 core VM opcodes (0x00..=0x09).
Signature Serialization: Alphabetical key-sorting rules using BTreeMap serialization.
Hash Progression: Blake3 chain folding rules.

Database Engines & Schemas: SQLite table structure, Valkey key formatting, and indexes.
Daemon CLI Flags: Internal metrics query formats.
Memory Structures: Thread boundaries, session caches, and synchronization locks.

Version Format: API endpoints do not contain version prefixes (e.g., /v1/hb). Instead, protocol versioning is coupled to the daemon release version.
Breaking Protocol Changes: Any change to the core hash function (Blake3) or the VM instruction set will trigger a major release (e.g., v2.0.0).
Deprecation Cycle: Deprecated features will be supported for at least one minor release cycle, documented in docs/PROTOCOL_STABILITY.md.

To build a client-side wrapper or application adapter for chronoseald:

Handshake: Send POST /init with the hex-encoded Ed25519 public key. Save the returned session_id, salt, opcodes_b64, and mutation_order_b64.
VM Execution: Run the math VM program (decoded from opcodes_b64) using the client wasm runtime to get the target stack_state.
Gene Mutation: Decode mutation_order_b64, apply the mutation steps to the local gene buffer, and compute the new commitment hash.
Signing: Build the canonical alphabetical JSON message, sign it, and send POST /hb.
Chain Advancement: On success, extract next_salt and next_mutation_order_b64 to prepare the next heartbeat request.