Metadata-Version: 2.4
Name: sagrada-engine
Version: 0.3.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
License-File: LICENSE
Summary: Deterministic belief-revision operator for AI agents — hash-chained, replayable, verifiable
Keywords: belief-revision,agent-memory,agm,provenance,merkle,receipts,deterministic
Author-email: Mars Ausili <mars@cruxia.ai>
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Cruxia-Labs

# sagrada-engine

A deterministic belief-revision operator for AI agents. Every change to what an
agent believes — assert, revise, retract, merge, split — goes through one
operator that records it in a hash-chained, replayable log. The model proposes;
the operator writes; the record replays — so what was believed, and when, is
something you recompute rather than something you are told.

No network, no telemetry, no model calls. The wheel is a single compiled
extension (Rust core, PyO3 binding) with zero Python dependencies.

```
pip install sagrada-engine
```

## Sixty seconds

```python
>>> import sagrada
>>> state = sagrada.PyKnowledgeState()
>>> state = state.apply_assert("deploy-rule", "production deploys require two approvals")
>>> state = state.apply_retract("deploy-rule")
>>> state = state.apply_assert("deploy-rule", "production deploys require one approval")

>>> [(h['operation_type'], h['definition']) for h in state.concept_history('deploy-rule')]
[('assert', 'production deploys require two approvals'), ('retract', None), ('assert', 'production deploys require one approval')]

>>> state.verify_chain()
True
```

The rule was asserted, retracted, and quietly replaced with a weaker one. The
history shows all three events — including the retraction — and the chain
verifies. A memory that only stored the current value would show one clean
assert of the weaker rule, with no sign a stricter policy had ever existed.

## What it guarantees

- **Deterministic, canonical state.** States serialize to a canonical byte
  form and hash with SHA-256. Determinism is over the *record*, not the call:
  hand the same record log to any wheel in this release and the state hash
  comes back byte-identical. Measured on all four shipped platforms — Linux
  x86_64, Linux aarch64, macOS arm64, macOS x86_64 — by replaying one log
  emitted on another; the empty state is
  `01ea42171f2295cbb54a24c017724becb37a712b2fcd5b9f525d1e9ea045650a` on each.
  Re-running the same `apply_*` calls does not reproduce a hash, and shouldn't:
  each write mints a fresh concept id and timestamp, so it is a genuinely
  different history. 0.3.0 ships no Windows wheels.
- **Hash-chained history.** Each operation appends a record chained by
  SHA-256. `verify_chain()` recomputes the chain: tampering with any record, or
  its order, fails it. `reconstruct()` goes further and replays the operations,
  checking that the records still produce the state they claim to.
- **Revision with postulates.** The nine operations (assert, refine, revise,
  retract, relate, restructure, merge, split, reinforce) are classified against
  AGM-style belief-revision postulates; every record carries its classification,
  and `agm_report()` re-derives it for any transition. Write-time invariants —
  closure, status, finiteness — are enforced and refused at the boundary. The
  postulates themselves are reported, not enforced: read the report; silence is
  not compliance.
- **Temporal queries.** `state_at(n)`, per-term history, range diffs, and
  provenance (W3C PROV) export — questions a current-state snapshot cannot
  answer.

Immutability is the API: every `apply_*` returns a new state; the old one is
untouched.

## What the record does and does not establish

Replay a record log and you recompute the same state hash, so an edit to any
record — or to their order — shows up. That is tamper-evidence, and it is not
authorship: the chain is unsigned, so a party who rewrites the whole log and
recomputes every hash produces a chain that verifies. Binding a record to a
signer is what [ER1 receipts](https://pypi.org/project/er1-verify/) are for.

And today this operator is the only implementation, so "recompute" means running
this wheel. A published canonical-form spec — so anyone can write a verifier in
any language, against golden vectors, the way `er1-verify` already works — is
what this package owes you next. Until it exists, verification is reproducible
but not yet independent, and you should read the claim above with that scope.

## What it is not

It is not a database, a vector store, or an LLM framework. It is the small
deterministic organ those systems lack: the one place writes go, so that reads
can be trusted. Pair it with any model, any retrieval stack, any framework.

## Part of Sagrada

The Sagrada system, published by [Cruxia Labs](https://github.com/Cruxia-Labs):

- [`er1-verify`](https://pypi.org/project/er1-verify/) — offline verifier for
  ER1 action receipts; three conformant implementations on disjoint stacks
  (Python, Node, browser WebCrypto).
- `sagrada-mcp` — MCP server that mounts this operator as governed agent
  memory.
- [`sagrada-linter`](https://pypi.org/project/sagrada-linter/) — coherence
  linter for prompts and agent transcripts.

License: Apache-2.0.

