# JacqOS

JacqOS is a model-theoretic runtime and architecture for building, securing, and operating autonomous AI agents. It replaces workflow graphs with a continuous observation-evaluation-effect loop.

## Core Architecture

JacqOS operates on a deterministic "physics engine" model for business logic:
- **Observation Log:** All inputs (API responses, user text, LLM outputs) are recorded as immutable, append-only JSON events.
- **Mappers (Rhai):** Pure, deterministic scripts extract raw observations into typed semantic **Atoms**.
- **Evaluator (.dh):** A Datalog-based engine processes atoms to derive **Facts** (current belief) and **Intents** (proposed actions).
- **Fixed-Point Evaluation:** The evaluator reaches a mathematical fixed point before any external effect is executed.
- **Structural Safety:** AI outputs are quarantined in reserved relay namespaces. **`candidate.*`** is for fallible-sensor evidence (voice, vision, extraction) that requires explicit promotion. **`proposal.*`** is for suggested actions that require explicit ratification. Only authorized decisions can derive an executable intent.
- **Intent/Effect Runtime:** The JacqOS shell implements a continuous reconciliation loop. It admits derived intents, executes them as capability-gated **Effects**, records the results as new observations, and feeds them back into the next evaluation cycle until the system reaches quiescence.
- **Named Invariants:** Catastrophic backstops (e.g., `count booking_confirmed <= 1`) that halt execution if business logic is violated.

## Developer Experience (AI-Native BDD)

JacqOS is designed for an era where AI agents write the majority of code:
- **Golden Fixtures:** BDD-style observation scenarios define the expected behavior.
- **Invariants over Implementation:** Developers focus on defining safety goals and scenarios; the engine guarantees alignment.
- **Exact Replay:** Any historical state can be replayed exactly for debugging and provenance tracing.
- **Instant Feedback:** Re-evaluation of the entire observation log occurs in <250ms upon logic changes.

## Key Resources

- [Full Documentation Corpus](https://jacqos.com/llms_full.txt) - Single-file compiled corpus for reading the documentation in one pass.
- [Documentation](https://jacqos.com/docs) - Full guides and reference.
- [Key Concepts](https://jacqos.com/docs/getting-started/concepts/) - The observation-first mental model.
- [.dh Reference](https://jacqos.com/docs/dh-language-reference/) - The logic language for ontologies and invariants.
- [CLI Reference](https://jacqos.com/docs/reference/cli/) - Tools for dev, replay, and verification.
- [Examples](https://jacqos.com/docs/examples/) - Validated patterns for refund guardrails, incident response, and more.