> For the complete documentation index, see [llms.txt](https://dsg-3.gitbook.io/dsg-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dsg-3.gitbook.io/dsg-docs/agi-simulation/rust-core.md).

# rust-core

DSG Core Canonical v1 — deterministic Rust control-plane primitive with deterministic execution evidence.

## What this repo provides

```
GO: deterministic execution evidence
GO: bounded integer-only decision path
GO: fail-closed transition behavior
GO: Z3/Kani-ready structure
NO-GO: formal proof claim until Z3/Kani logs exist
```

This repository is intentionally split into two layers:

1. `src/core.rs` — deterministic primitive
   * no randomness
   * no floating point
   * no unordered hash maps/sets
   * no network
   * no filesystem
   * no wall-clock time
   * no unsafe code
   * fixed-size canonical state/policy
   * integer-only fixed-point stability
   * fail-closed behavior
2. `src/evidence.rs` — deterministic execution evidence
   * canonical byte encoding
   * SHA-256 hashes
   * replay-run transition hash check
   * JSON evidence output
   * explicit note that this is execution evidence, not formal proof

## Quick start

```bash
cargo test
cargo run --bin rust-core-evidence
```

Write evidence to a file:

```bash
cargo run --bin rust-core-evidence > evidence.json
```

## Expected result

The CLI emits deterministic JSON evidence like:

```json
{
  "schema_version": "deterministic-execution-evidence-v1",
  "core_version": "dsg-core-canonical-v1",
  "evidence_kind": "deterministic_execution_evidence",
  "claim": "same canonical input + same core version => same transition hash",
  "proof_status": "EXECUTION_EVIDENCE_ONLY"
}
```

## Truth boundary

This repository proves only deterministic execution behavior for the bounded primitive.

It does **not** claim:

* Z3 verified
* Kani verified
* production certified
* Google Cloud certified
* mathematically complete proof

Those claims require attached artifacts:

```
cargo test log
kani proof log
z3 SMT proof/result artifact
replay evidence manifest
binary/source hash manifest
```

## Decision semantics

```
Decision mapping:
  0 = Allow
  1 = Stabilize
  2 = Block

Fail-closed rule:
  invalid state       => Block
  invalid policy      => Block
  arithmetic overflow => Block
```

## Canonical boundaries

```
B1  field_count <= N
B2  forbidden_count <= M
B3  active fields sorted ascending by key_id
B4  no duplicate key_id
B5  forbidden_state_ids sorted ascending
B6  no duplicate forbidden_state_id
B7  key_len <= MAX_KEY_LEN
B8  value_len <= MAX_VALUE_LEN
B9  threshold_scaled <= 1_000_000
B10 invalid canonical input => Block
B11 forbidden state overrides stability
B12 Allow advances state
B13 Stabilize holds current state
B14 Block holds current state
```

## Core formula

```
stability = SCALE / (1 + drift)
threshold = threshold_scaled / SCALE

stability < threshold
=> SCALE < threshold_scaled * (1 + drift)
```

No floating point is used in the decision path.

## Create a new GitHub repo

Using GitHub CLI:

```bash
git init
git add .
git commit -m "init rust-core deterministic evidence primitive"
gh repo create rust-core --private --source=. --remote=origin --push
```

Or public:

```bash
gh repo create rust-core --public --source=. --remote=origin --push
```