nucleus-substrate-core 0.1.0

Categorical core of the Nucleus substrate: Session (the agent action), Projection (the verifiable record functor — Identity, Capability, Flow, Economic, …), and Receipt (the Ed25519-signed colimit). Lightweight, no runtime deps. See docs/architecture/substrate.md.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# nucleus-substrate-core

[![Crates.io](https://img.shields.io/crates/v/nucleus-substrate-core.svg)](https://crates.io/crates/nucleus-substrate-core)
[![Docs.rs](https://docs.rs/nucleus-substrate-core/badge.svg)](https://docs.rs/nucleus-substrate-core)

The **categorical core** of the Nucleus substrate. Three load-bearing
types and one signed envelope:

- [`Session`] — the agent-action object every projection projects from
- [`Projection`] — sealed, adjacently-tagged sum: `Identity`,
  `Capability`, `Flow`, `Economic` (`#[non_exhaustive]`)
- [`Receipt`] — Ed25519-signed colimit envelope binding a session to
  any subset of its projections

The categorical claim is proved in Lean 4 — see
[`receipt_factors_through_projections`][lean-theorem] in
`formal/Nucleus/Substrate/Colimit.lean`.

## Quick example

```rust
use nucleus_substrate_core::{Session, Receipt, Projection};
use ed25519_dalek::SigningKey;

let sk = SigningKey::from_bytes(&[7u8; 32]);
let session = Session {
    session_id: "spiffe://test/agent-x".into(),
    issuer_kid: "test-kid".into(),
    issued_at_micros: 1_717_000_000_000_000,
    parent_chain: vec![],
};
let projection = Projection::Identity(serde_json::json!({
    "sub": "spiffe://test/agent-x",
    "aud": "nucleus-substrate-test",
}));
let receipt = Receipt::sign(session, vec![projection], &sk);
let vk: [u8; 32] = sk.verifying_key().to_bytes();
receipt.verify(&vk).expect("self-built receipt verifies");
```

## Position in the substrate

This crate is the **only required dependency** for projection-lifter
crates and the SDK. Server-side hub crates depend on it for the
typed VCG wire shapes in `mechanism::vcg`. Everything else in the
substrate stack composes on top of these three types.

| Layer | Crate | Depends on |
|---|---|---|
| Core | `nucleus-substrate-core` (you are here) | std + serde + ed25519 + blake3 |
| Identity lifter | `nucleus-identity-projection` | core |
| Flow lifter | `nucleus-flow-projection` | core |
| VCG lifter | `nucleus-mechanism-vcg` | core |
| SDK | `nucleus-substrate-sdk` | core + 3 lifters + reqwest |
| CLI | `nucleus-substrate-cli` | sdk |

## License

Dual-licensed under MIT OR Apache-2.0. See
[`LICENSE-MIT`](./LICENSE-MIT) and [`LICENSE-APACHE`](./LICENSE-APACHE).

[`Session`]: https://docs.rs/nucleus-substrate-core/latest/nucleus_substrate_core/struct.Session.html
[`Projection`]: https://docs.rs/nucleus-substrate-core/latest/nucleus_substrate_core/enum.Projection.html
[`Receipt`]: https://docs.rs/nucleus-substrate-core/latest/nucleus_substrate_core/struct.Receipt.html
[lean-theorem]: https://github.com/coproduct-private/spiffy/blob/main/formal/Nucleus/Substrate/Colimit.lean