Module hive 

LeanCTX | Hive engine↔service wire contract, protocol major 1.

The engine connector and the Hive service build against these types and the golden fixtures in tests/fixtures/hive/. A contract change is a fixture change that both sides review.

Conventions shared by every module:

• Base URL https://hive.leanctx.com/v1; a self-hosted Hive may use any https URL (loopback may use http).
• Every HTTP body carries schema (leanctx.hive.<area>/v1). The one exception is the error body {"error":{...}}, which proxies may also emit.
• Request types refuse unknown fields (the service rejects them with invalid_request); response types accept unknown fields, so the service can add fields in a minor version without breaking older engines.
• Timestamps are YYYY-MM-DDTHH:MM:SSZ ([UtcTimestamp]); unix seconds appear only where a value is signed as text (iat).
• Keys, nonces, signatures and ciphertext are standard base64 with padding.
• vault_id is 32 lowercase hex characters: the engine API renders the vault UUID in simple form (no dashes) while the web API keeps hyphenated UUIDs.
• Signatures are Ed25519 over domain || canonical_json(value), see canonical_json. Signed objects are verified over the raw JSON that was received, never over a re-serialized typed value, so additive fields stay covered by the signature.

Re-exports

pub use error::HiveErrorBody;

pub use error::HiveErrorCode;

pub use error::HiveErrorDetailV1;

pub use error::HiveUploadKind;

Modules

anchor

Code anchors (C0 1.9): where in the code a fact, or a piece of task evidence, applies.

bus

Bus leases (C5): one holder per resource across the machines of an organization, decided by the service clock.

codegraph

The published code graph (C0 1.9, section 8; plan N1).

ctxpkg

The ctxpkg object mapping (C0 1.9, section 7; plan O1).

effective_policy

Unified Control: the signed effective policy of one engine (Release B, C0 2.x schemas/policy.schema.json).

enroll

Device-flow enrollment and instance access tokens.

error

Error body of every non-2xx Hive response: {"error":{...}}.

facts

Fact states (C0 1.9, section 3).

gate

G6, the test gate of process v1 (leanctx-hive docs/process-v1.md §5, contracts/process-v1/gate-record.schema.json): what the Instance checks and records on submit (E47) and again before verify (E48).

graph

The vault graph view (C0 1.9, section 3).

knowledge

Vault knowledge: the ctxpkg.research-context.v1 document, its revisions, and draft proposals streamed from engine sessions.

lease

Instance lease and the Hive signing key set.

managed

leanctx.managed-config/v1: what an organisation preconfigures on a machine through MDM (contract: docs/contracts/managed-config-v1.md).

metrics_v2

Engine metrics v2 (C0 2.0 schemas/metrics.schema.json, telemetry SPEC).

optin

Engine opt-in (C0 1.9, section 4; owner decision O1).

policy

Filter packs.

profiles

Agent profiles and reputation (C0 1.9, section 5).

receipts_v2

Engine receipts v2 (C0 2.5 schemas/receipts.schema.json, K2 review M3).

root_cert

Self-host root certificates (1.7): LeanCTX vouches for the root of a self-hosted Hive.

status

lean-ctx hive status --json: the one shape the local cockpit reads.

tasks

Tasks, claims and results (C0 1.9, section 1).

telemetry

Cockpit metrics and receipts.

vault

Vault resolution: the engine never sends a path, remote or name, only an org-salted digest of its git repository’s stable identity. One git repository maps to exactly one vault.

Constants

FILTER_PACK_SIGNATURE_DOMAIN

Domain of a filter-pack statement signature (Hive signing key).

HEADER_IDEMPOTENCY_KEY

Client-chosen ULID on every POST; replays return the first response.

HEADER_INSTANCE

Instance id on authenticated requests.

HEADER_MIN_ENGINE

Lowest engine version the service accepts; sent with 426.

HEADER_NAMES

1.9 VA (until the 3.12 release day): an engine that speaks the vault names sends NAMES_VAULT here on every request, the bus WebSocket upgrade included. Hive then answers in the vault form (vault_id, vault: channels); without it, in the earlier project form. Hive takes both forms as input. From the release day only the vault form remains and the header is ignored.

HEADER_PROTOCOL

major.minor the sender speaks; sent on every request and response.

HIVE_API_PREFIX

Path prefix of every engine-facing route.

HIVE_DEFAULT_URL

Hosted Hive origin.

HIVE_ENGINE_CLIENT_ID

OAuth-style client id the engine sends in the device flow.

HIVE_PROTOCOL_MAJOR

Major protocol version; a different major is incompatible.

HIVE_PROTOCOL_MINOR

Minor protocol version; minors only add optional response fields or routes.

KEYSET_SIGNATURE_DOMAIN

Domain of the key-set signature (Hive root key).

LEASE_SIGNATURE_DOMAIN

Domain of the lease signature (Hive signing key).

MAX_BODY_BYTES

Largest request or response body either side accepts, except knowledge documents (knowledge::MAX_KNOWLEDGE_BODY_BYTES).

NAMES_VAULT

The HEADER_NAMES value of the vault form.

REPO_IDENTITY_DOMAIN

Domain of the stable repository identity digest input. The bytes keep their 1.0 name: a different domain would change every digest and unbind every linked vault.

TOKEN_ASSERTION_DOMAIN

Domain of the instance token assertion (instance key).

Functions

canonical_json

Canonical JSON encoding used under every Hive signature.

invisible

1.9 R3-3e-1: characters that make a text read differently from what it is, or hide text a person reviewing it cannot see: bidi marks, embeddings, overrides and isolates, zero-width space, the invisible operators, a byte-order mark, tag characters and the variation selector supplement; and (1.9 erratum) the soft hyphen, the Mongolian vowel separator, the combining grapheme joiner, the Hangul fillers, the Khmer inherent vowels and the line and paragraph separators (not controls, so they would break a one-line text), the whole block U+2060–U+206F (with the deprecated format controls), the interlinear annotation characters (they hide annotation text) and the invisible format controls of Egyptian hieroglyphs, shorthand and musical notation. Every text field refuses them; engines strip them from foreign content. The joiners U+200C/U+200D and U+FE00–FE0F stay: emoji and Persian need them; the visible Arabic and Syriac signs (U+0600–0605, U+06DD, U+070F, U+08E2) too.

parse_protocol_header

Parse an Hive-Protocol header into (major, minor).

protocol_compatible

Whether a peer’s Hive-Protocol header is compatible with this crate.

protocol_header_value

Hive-Protocol value this crate speaks.

signing_input

domain || canonical_json(value): the exact bytes an Ed25519 key signs.

signing_input_without_signature

Signing input of an object that carries its own signature field: the canonical form of the object without that field.

validate_origin

Validate an origin: https://host[:port], or http:// for localhost/127.0.0.1/[::1]; no path, query, credentials or trailing slash.

validate_vault_id

Validate a Hive vault_id: 32 lowercase hex characters (128 random bits), the same form leanctx.cloud-metrics/v1 requires of vault.id. The engine API renders the vault UUID in simple form (no dashes) while the web API keeps hyphenated UUIDs.