Metadata-Version: 2.4
Name: mirra-core-contract
Version: 1.0.0
Summary: Frozen v1 interface + schemas for the MIRRA agent platform (interfaces only, no logic).
Author-email: Shawn Cohen <shawn@universalmediaus.com>
License: Apache-2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# mirra-core-contract

**The frozen v1 interface of the MIRRA agent platform.** Interfaces and schemas
only — zero logic, zero dependencies. Every core component implements it; every
deployment edge depends only on it.

```
AgentIdentity · Scroll · ExecutionIntent · DecisionRecord · VerificationResult
IdentityResolver.resolve_identity(principal)        -> AgentIdentity
MemoryStore.remember / recall / verify              -> signed Scrolls, verify-on-read
ExecutionAuthorizer.authorize(intent, identity)     -> signed DecisionRecord
CapabilityProvider.enrich_identity / verify_epistemic   (optional, runtime-injected)
```

## Rules baked into the contract

- **Frozen.** This is `v1`. It never breaks without a major version bump; the
  freeze-guard tests (`tests/test_contract_frozen.py`) fail on any signature or
  schema drift.
- **Fail-closed.** Missing engine, missing signing secret, or failed
  verification means deny/reject — never silent degradation.
- **Real cryptography.** `verified: true` always reflects an actual signature
  check, never a proxy like "the record exists." Signed artifacts declare their
  scheme (`hmac-sha256` for same-owner memory, `ed25519` for distributable proofs).
- **Generic vocabulary.** Capability providers are named generically; the
  contract is the only shared vocabulary between public packages and any private
  implementation. `scripts/check_public_private_boundary.py` is the CI gate that
  keeps it that way.

## Who implements what

| Component | Contract surface |
|---|---|
| `mvar-security` | `ExecutionAuthorizer` (+ the canonical QSEAL signing primitive) |
| `clawseal` | `MemoryStore` (sign-on-write, verify-on-read) |
| `mirra-sdk` | all three edges (SDK / gateway / on-device) speak only these types |
| private providers | `CapabilityProvider`, injected at runtime |

## Tests

```bash
python3 -m pytest tests/ -q     # 9 freeze-guards
```

## License

Apache-2.0 — see [LICENSE](LICENSE).
