terminals-core 0.1.0

# terminals-core (`crates/terminals-core/`)

> **Parent:** [Root CLAUDE.md](../../CLAUDE.md) | **Sibling:** [crates/zero/CLAUDE.md](../zero/CLAUDE.md)

## Purpose

`terminals-core` is the shared physics substrate used by both the browser (via `crates/terminals-wasm/`) and the CLI (`crates/zero/`). It implements the L1 primitives — Kuramoto phase dynamics, sematons, projections, and signal primitives — in Rust.

Same physics runs in both WASM (browser) and native (CLI). Do not add platform-specific dependencies here.

## Module Layout

```
crates/terminals-core/src/
  lib.rs           Crate root — re-exports key modules
  phase/
    kuramoto.rs    Kuramoto model: kuramoto_step, order_parameter, wrap_to_pi/2pi
    plv.rs         Phase Locking Value: phase_locking_value
  substrate/
    thermal.rs     ThermalProjection
  primitives/      Core primitive types
  audio/           Audio signal types
  wire/            Wire/transport primitives
```

## Key APIs

### Phase dynamics (`terminals_core::phase`)

```rust
use terminals_core::phase::kuramoto::{kuramoto_step, order_parameter, Omega};
use terminals_core::phase::plv::phase_locking_value;

// Advance one simulation step
let next = kuramoto_step(&phases, omega, coupling, None, dt);
// Measure synchrony
let OrderParameter { R, psi } = order_parameter(&next);
// Measure two-agent phase lock
let plv = phase_locking_value(&hist_a, &hist_b);
```

These exact APIs are mirrored on the TypeScript side via `@terminals-tech/sdk -> Brain`.

## TypeScript Parity

| Rust | TypeScript (`Brain.*`) |
|------|------------------------|
| `kuramoto_step` | `Brain.kuramotoStep` |
| `order_parameter` | `Brain.orderParameter` |
| `phase_locking_value` | `Brain.phaseLockingValue` |
| `ThermalProjection` | `lib/drm/thrml2bend/` |

## Publishing

```
cargo publish -p terminals-core   # requires crates.io auth
```

License: BUSL-1.1. Publishable to crates.io (no compiler-specific claim material).

## Rules

- No platform-specific code (no `std::fs`, no WebSocket, no CLI parsing).
- No dependency on `crates/zero/` or `crates/terminals-sidecar/`.
- All physics functions should be pure (no side effects, no global state).
- Tests live in-module (`#[cfg(test)]`) and in `crates/zero/tests/` where integration with Zero is required.

## Related Files

| File | Purpose |
|------|---------|
| `crates/terminals-wasm/` | WASM bridge — exposes terminals-core to the browser |
| `crates/zero/` | Zero CLI — consumes terminals-core for coherence + phase state |
| `packages/sdk/src/brain.ts` | TypeScript mirror of the same phase/coherence APIs |
| `components/docs/SDKPlayground.tsx` | Browser demo running Brain SDK (TS equivalent) live |