@0xhoneyjar/loa-hounfour

Documentation current as of v7.5.0

Constitutional protocol contracts for an AI agent economy. TypeBox schemas with dual JSON Schema 2020-12 output.

What This Is

loa-hounfour is a constitutional protocol library for an AI agent economy. It defines the wire format, governance rules, and economic constraints for services coordinating AI agents, gateways, and runtimes. Every TypeBox schema compiles to a standalone JSON Schema 2020-12 file, enabling cross-language validation in Python, Go, Rust, or any JSON Schema-compliant environment.

What it does: Typed schemas, runtime validation, cross-field invariant checks, constraint DSL with evaluator builtins, formal conservation properties, governance layer.

What it does NOT do: No runtime, no transport, no HTTP server, no model invocation. Schemas and validation only.

Reference consumers include loa-finn (runtime) and loa-freeside (gateway). Any service needing typed AI coordination contracts can consume this package independently.

Why

• Schema drift: Without a shared contract, services diverge silently.
• Protocol divergence: Typed schemas catch incompatibilities at build time, not in production.
• Cross-language validation: JSON Schema 2020-12 output works in any language ecosystem.
• Constraint DSL: Formal rules (conservation laws, temporal ordering, state machine transitions) enforced by an evaluator with 36 builtins.

Inventory

Installation

# npm
npm install @0xhoneyjar/loa-hounfour

# pnpm
pnpm add @0xhoneyjar/loa-hounfour

Module Map

All 10 package export paths and what they contain:

Source: package.json exports field, src/*/index.ts barrel files.

Usage

Import from Sub-Packages

// Targeted imports — tree-shakeable
import { AgentDescriptorSchema, ConversationSchema } from '@0xhoneyjar/loa-hounfour/core';
import { BillingEntrySchema, EscrowEntrySchema } from '@0xhoneyjar/loa-hounfour/economy';
import { CompletionRequestSchema, EnsembleRequestSchema } from '@0xhoneyjar/loa-hounfour/model';
import { SanctionSchema, GovernanceProposalSchema } from '@0xhoneyjar/loa-hounfour/governance';
import { evaluateConstraint, EVALUATOR_BUILTINS } from '@0xhoneyjar/loa-hounfour/constraints';
import { computeReqHash, deriveIdempotencyKey } from '@0xhoneyjar/loa-hounfour/integrity';
import { buildSchemaGraph } from '@0xhoneyjar/loa-hounfour/graph';
import { BridgeTransferSagaSchema } from '@0xhoneyjar/loa-hounfour/composition';

// Or import everything from the root
import { validate, validators, CONTRACT_VERSION } from '@0xhoneyjar/loa-hounfour';

Validation

import { validate } from '@0xhoneyjar/loa-hounfour';
import { BillingEntrySchema } from '@0xhoneyjar/loa-hounfour/economy';

const result = validate(BillingEntrySchema, data);

if (result.valid) {
  // result.warnings may contain advisory messages
  console.log('Valid', result.warnings ?? []);
} else {
  // result.errors contains validation failures
  // Cross-field invariants (e.g., conservation checks) are included automatically
  console.error('Invalid', result.errors);
}

Constraint Evaluation

Constraint files in constraints/*.constraints.json define cross-field rules using a PEG-based expression language (see constraints/GRAMMAR.md). The evaluator runs these against data objects:

import { evaluateConstraint } from '@0xhoneyjar/loa-hounfour/constraints';

// Evaluate a constraint expression against a data object
const satisfied = evaluateConstraint(data, 'bigint_gte(limit_micro, spent_micro)');
// Returns true if the constraint passes, false if violated

The constraint DSL supports 36 evaluator builtins (src/constraints/evaluator.ts): BigInt arithmetic (bigint_sum, bigint_add, bigint_sub, bigint_gte, bigint_gt, bigint_eq), delegation chain validation (all_links_subset_authority, delegation_budget_conserved, links_temporally_ordered, links_form_chain), ensemble capability checks, temporal operators (changed, previous, delta), type introspection (type_of, is_bigint_coercible), v7.0.0 coordination/governance builtins (saga_amount_conserved, saga_steps_sequential, outcome_consensus_valid, monetary_policy_solvent, permission_boundary_active, proposal_quorum_met, saga_timeout_valid, proposal_weights_normalized), timestamp comparison (is_after, is_before, is_between), and temporal governance (is_stale, is_within).

Cross-Language JSON Schema Usage

Pre-generated JSON Schema 2020-12 files enable validation from any language:

// TypeScript — import static schema
import schema from '@0xhoneyjar/loa-hounfour/schemas/billing-entry.schema.json';

# Python — load the schema file
import json
from jsonschema import validate

with open("node_modules/@0xhoneyjar/loa-hounfour/schemas/billing-entry.schema.json") as f:
    schema = json.load(f)

validate(instance=data, schema=schema)

// Go — load and validate with any JSON Schema library
schemaBytes, _ := os.ReadFile("schemas/billing-entry.schema.json")

Golden Test Vectors

Cross-language conformance vectors live in vectors/. Each file contains valid and/or invalid test cases with expected outcomes.

Vector runners validate that non-TypeScript implementations produce identical results:

• vectors/runners/go/ — Go test runner
• vectors/runners/python/ — Python test runner
• vectors/runners/rust/ — Rust test runner

Scripts

pnpm run build              # Compile TypeScript (tsc)
pnpm run test               # Run all 3,908 tests (vitest)
pnpm run typecheck           # Type-only check (tsc --noEmit)
pnpm run schema:generate     # Regenerate JSON schemas from TypeBox
pnpm run schema:check        # Validate schema integrity
pnpm run semver:check        # Check for breaking changes
pnpm run vectors:check       # Validate golden test vectors
pnpm run schemas:validate    # Validate all schema files
pnpm run check:constraints   # Validate constraint files
pnpm run check:all           # Run all integrity checks

Versioning Policy

Strict semver with N/N-1 support window. Source: src/version.ts:13-14.

Compatibility

Consumers must support versions N and N-1 minor for a 30-day overlap window.

Breaking Change Process

1. Open RFC issue with proposed change
2. Update schemas in loa-hounfour with version bump
3. Add conformance vectors for new behavior
4. CI: semver:check validates no accidental breaks
5. Both consumers update within overlap window

Further Documentation

Maintainer

@janitooor

License

AGPL-3.0 — Use, modify, distribute freely. Network service deployments must release source code.

Commercial licenses are available for organizations that wish to use loa-hounfour without AGPL obligations.

Ridden with Loa