Cruxible

cruxible.ai · quickstart · docs · kits · skills

Cruxible is a governed state engine for AI agents. It produces a Crux: an executable artifact of your domain knowledge with a code-like lifecycle — typed, reviewed, versioned, auditable, and tested against outcomes.

The problem. Code is typed, reviewed, and versioned; it executes deterministically, and tests verify it in seconds. The judgments, observations, reusable actions, and decisions agents produce land in prose — which doesn't execute, has no governed path from proposed to trusted, and puts no bounds on what gets repeated. Real decisions resolve over weeks or months, long after anything is still tracking them. And prose can't serve as shared ground: an organization running many agents needs them all acting on the same current claims, rules, and reviewed ways of acting, not on each agent's own reading of the documents.

How it works. You declare the domain ontology and its rules in YAML. Reproducible pipelines turn trusted source data into typed state. When an agent or human makes a judgment, Cruxible can require evidence and review before the claim becomes live. When an agent learns a way of acting that works, it can propose that too: a Procedure passes through the same review cycle as a claim and runs only within its declared inputs, preconditions, and limits. A decision can be required to declare, before it is accepted, what result will count as success; the outcome contract comes due on its own schedule and records what reality said. Queries and actions run against the same live state, and invalid changes are refused. No LLM runs inside the engine.

Why use it. Every agent works against the same live claims and can invoke the same reviewed, bounded Procedures. Invalid writes and actions are refused, contradictions remain visible until resolved, decisions can be checked against what happened, and computed answers, mutations, and action runs carry receipts that explain them. Snapshots capture exact config, lock, graph state, and procedure definitions at a revision for comparison, branching, and transfer; backups preserve the complete audit stores for recovery. The whole artifact outlives any single session or model.

One small example: a supplier inventory and incident feed build entities from pinned sources. An agent concludes that an incident impacts a supplier, but the relationship is declared a judgment call:

entity_types:
  Incident:
    id: incident_id
    properties:
      title: string indexed
  Supplier:
    id: supplier_id
    properties:
      name: string indexed

relationships:
  - incident_impacts_supplier: Incident -> Supplier
    write_policy: proposal_only        # judgment call: enters only through review

named_queries:
  incident_impacted_suppliers:
    mode: traversal
    entry_point: Incident
    returns: Supplier
    traverse:
      - relationship: incident_impacts_supplier
        direction: outgoing

Now the policy is part of the runtime. The direct write is refused, review admits the judgment, and a query computes its consequence:

  $ cruxible relationship add incident_impacts_supplier \
      Incident INC-TW-RAIL-2026-07 Supplier S-CN-DG-HARNESS
- Error: DirectWriteRefusedError: Direct write to relationship
- 'incident_impacts_supplier' is refused (write_policy=proposal_only).
- Use 'group propose' to stage a governed proposal. (receipt: RCP-…)

  $ cruxible propose --workflow propose_incident_impacts_supplier
  $ cruxible group resolve --group <GRP-id> --action approve \
      --rationale "Confirmed against supplier geography"

  $ cruxible query run incident_impacted_suppliers \
      --param incident_id=INC-TW-RAIL-2026-07 --json
+ { "items": [ { "entity_type": "Supplier", "entity_id": "S-CN-DG-HARNESS" } ],
+   "receipt_id": "RCP-2f61a90c84d3" }

The source facts came through deterministic ingest; the inferred edge entered through review. Queries can now traverse its consequences, guards and gates can act on it, and later observations can contradict it without silently rewriting history.

INGEST       pinned feeds -> Incident, Supplier, Product, and Shipment state
CLAIM        incident_impacts_supplier: pending -> live (evidence + reviewer)
QUERY        incident_impacted_suppliers -> [S-CN-DG-HARNESS]

PROCEDURE    hold_exposed_shipments v1: pending -> live (config + lock pinned)
DECISION     hold exposed shipments; success = zero exposed shipments released
RUN          bounded provider calls complete -> receipt RCP-run-...
OUTCOME      pinned query at check time -> satisfied -> receipt RCP-outcome-...

OBSERVATION  new evidence says the supplier was outside the incident boundary
ATTESTATION  contradict incident_impacts_supplier (claim remains live)
REVIEW       attestation upheld; separate adjudication rejects the claim
QUERY        incident_impacted_suppliers -> []

SNAPSHOT     exact config + lock + graph state + Procedure definitions captured

Cruxible uses the same boundary itself: this repository refuses a push to main until state pins an approved review (how).

pip install cruxible — the Quickstart goes install to first query; Get Started below runs the seeded demo world in ~3 minutes, with no model calls or API keys.

Inside a Crux