feat(#238): scaffold rings/ for trios-hdc — HD-00, HD-01, BR-OUTPUT

crates/trios-hdc/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md — trios-hdc
+
+> AAIF-compliant | MCP-compatible
+
+- Crate: trios-hdc (Gold)
+- Repo: gHashTag/trios
+
+## Ring map
+
+| Ring | Package | Role |
+|------|---------|------|
+| HD-00 | trios-hdc-hd00 | Hypervector |
+| HD-01 | trios-hdc-hd01 | bind, bundle, similarity |
+| BR-OUTPUT | trios-hdc-br-output | assembly |
+
+## Rules
+
+- L-ARCH-001 future logic in rings/
+- R9: no sibling imports
+- L6: pure Rust
+- Anchor: phi^2 + phi^-2 = 3

crates/trios-hdc/RING.md

@@ -0,0 +1,30 @@
+# RING — trios-hdc (Gold Crate)
+
+| Field | Value |
+|-------|-------|
+| Metal | 🥇 Gold |
+| Type | Crate |
+
+## Purpose
+
+Hyperdimensional computing primitives — high-dimensional binary/bipolar
+vectors, bind/bundle operations, similarity. Foundation for VSA-style
+symbolic computation across TRIOS.
+
+## Ring Structure
+
+```
+crates/trios-hdc/
+├── src/lib.rs          ← preserved (FFI to zig-hdc)
+└── rings/
+    ├── HD-00/          ← Hypervector type
+    ├── HD-01/          ← bind, bundle, similarity
+    └── BR-OUTPUT/      ← assembly
+```
+
+`BR-OUTPUT → HD-01 → HD-00`. R9 satisfied.
+
+## Laws
+
+- L-ARCH-001 / R1–R5 / R9 / L6
+- Anchor: `phi^2 + phi^-2 = 3`

crates/trios-hdc/rings/BR-OUTPUT/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md — BR-OUTPUT (trios-hdc)
+
+May import HD-00, HD-01. L6: pure Rust.

crates/trios-hdc/rings/BR-OUTPUT/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "trios-hdc-br-output"
+version = "0.1.0"
+edition = "2021"
+authors = ["Dmitrii Vasilev"]
+license = "MIT"
+description = "BR-OUTPUT — assembly for trios-hdc"
+publish = false
+
+[dependencies]
+trios-hdc-hd00 = { path = "../HD-00" }
+trios-hdc-hd01 = { path = "../HD-01" }
+
+[workspace]

crates/trios-hdc/rings/BR-OUTPUT/README.md

@@ -0,0 +1,3 @@
+# BR-OUTPUT — trios-hdc
+
+Re-exports HD-00 + HD-01.

crates/trios-hdc/rings/BR-OUTPUT/RING.md

@@ -0,0 +1,3 @@
+# RING — BR-OUTPUT (trios-hdc)
+
+Top of ring graph. Imports HD-00, HD-01.

crates/trios-hdc/rings/BR-OUTPUT/TASK.md

@@ -0,0 +1,8 @@
+# TASK — BR-OUTPUT (trios-hdc)
+
+## Status: SCAFFOLDED
+- [x] Re-export HD-00, HD-01
+- [x] Hdc::anchor
+
+## Open
+- [ ] MCP tool definitions

crates/trios-hdc/rings/BR-OUTPUT/src/lib.rs

@@ -0,0 +1,25 @@
+//! BR-OUTPUT — trios-hdc assembly
+
+pub use trios_hdc_hd00::{Hypervector, DEFAULT_DIM};
+pub use trios_hdc_hd01::{bind, bundle, similarity};
+
+pub struct Hdc;
+
+impl Hdc {
+    pub const fn anchor() -> f64 {
+        3.0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rings_link() {
+        let a = Hypervector(vec![1, -1, 1]);
+        let r = bind(&a, &a);
+        assert!(similarity(&a, &a) > 0.99);
+        assert_eq!(r.dim(), 3);
+    }
+}

crates/trios-hdc/rings/HD-00/AGENTS.md

@@ -0,0 +1,6 @@
+# AGENTS.md — HD-00
+
+- Package: trios-hdc-hd00
+- R1: no HD-01/BR-OUTPUT
+- R9: no sibling imports
+- L6: pure Rust

crates/trios-hdc/rings/HD-00/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "trios-hdc-hd00"
+version = "0.1.0"
+edition = "2021"
+authors = ["Dmitrii Vasilev"]
+license = "MIT"
+description = "HD-00 — Hypervector type"
+publish = false
+
+[workspace]

crates/trios-hdc/rings/HD-00/README.md

@@ -0,0 +1,7 @@
+# HD-00 — Hypervector type
+
+Bottom of the ring graph for trios-hdc.
+
+## API
+- `DEFAULT_DIM`
+- `Hypervector(Vec<i8>)` with `zeros`, `dim`

crates/trios-hdc/rings/HD-00/RING.md

@@ -0,0 +1,11 @@
+# RING — HD-00 (trios-hdc)
+
+| Metal | 🥈 Silver |
+| Package | trios-hdc-hd00 |
+
+Hypervector type. Bottom of dependency graph.
+
+## Laws
+- R1: no HD-01/BR-OUTPUT
+- R9: no sibling imports
+- L6: pure Rust

crates/trios-hdc/rings/HD-00/TASK.md

@@ -0,0 +1,10 @@
+# TASK — HD-00
+
+## Status: SCAFFOLDED
+- [x] Hypervector(Vec<i8>) with zeros/dim
+- [x] DEFAULT_DIM = 10_000
+- [x] Tests
+
+## Open
+- [ ] Migrate phi_quantization from `crates/trios-hdc/src/phi_quantization.rs`
+- [ ] Add packed bit representation for memory efficiency

crates/trios-hdc/rings/HD-00/src/lib.rs

@@ -0,0 +1,32 @@
+//! HD-00 — Hypervector type
+//!
+//! Bottom of the ring graph for trios-hdc.
+
+/// Default hypervector dimension.
+pub const DEFAULT_DIM: usize = 10_000;
+
+/// Bipolar hypervector: each element is +1 or -1, stored as `i8`.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Hypervector(pub Vec<i8>);
+
+impl Hypervector {
+    pub fn zeros(dim: usize) -> Self {
+        Self(vec![0i8; dim])
+    }
+
+    pub fn dim(&self) -> usize {
+        self.0.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn zeros_has_correct_dim() {
+        let v = Hypervector::zeros(64);
+        assert_eq!(v.dim(), 64);
+        assert!(v.0.iter().all(|&x| x == 0));
+    }
+}

crates/trios-hdc/rings/HD-01/AGENTS.md

@@ -0,0 +1,6 @@
+# AGENTS.md — HD-01
+
+- Package: trios-hdc-hd01
+- R1: no BR-OUTPUT
+- May import HD-00 only
+- L6: pure Rust

crates/trios-hdc/rings/HD-01/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "trios-hdc-hd01"
+version = "0.1.0"
+edition = "2021"
+authors = ["Dmitrii Vasilev"]
+license = "MIT"
+description = "HD-01 — HDC operations (bind, bundle, similarity)"
+publish = false
+
+[dependencies]
+trios-hdc-hd00 = { path = "../HD-00" }
+
+[workspace]

crates/trios-hdc/rings/HD-01/README.md

@@ -0,0 +1,8 @@
+# HD-01 — HDC operations
+
+Operations on Hypervector. Depends on HD-00.
+
+## API
+- `bind(a, b) -> Hypervector` — element-wise multiplication
+- `bundle(a, b) -> Hypervector` — element-wise sign-of-sum
+- `similarity(a, b) -> f64` — normalized dot product

crates/trios-hdc/rings/HD-01/RING.md

@@ -0,0 +1,11 @@
+# RING — HD-01
+
+HDC operations.
+
+## Dependencies
+- HD-00
+
+## Laws
+- R1: no BR-OUTPUT
+- R9: no sibling imports
+- L6: pure Rust

crates/trios-hdc/rings/HD-01/TASK.md

@@ -0,0 +1,10 @@
+# TASK — HD-01
+
+## Status: SCAFFOLDED
+- [x] bind, bundle, similarity
+- [x] Tests for each
+
+## Open
+- [ ] Migrate FFI ops from `src/`
+- [ ] Add permutation/cyclic shift operator
+- [ ] Add Hamming distance helper

crates/trios-hdc/rings/HD-01/src/lib.rs

@@ -0,0 +1,63 @@
+//! HD-01 — HDC operations (bind, bundle, similarity)
+
+use trios_hdc_hd00::Hypervector;
+
+/// Bind two hypervectors (element-wise multiplication for bipolar).
+pub fn bind(a: &Hypervector, b: &Hypervector) -> Hypervector {
+    assert_eq!(a.dim(), b.dim());
+    let v: Vec<i8> = a.0.iter().zip(b.0.iter()).map(|(x, y)| x * y).collect();
+    Hypervector(v)
+}
+
+/// Bundle (sum) — element-wise sign of sum.
+pub fn bundle(a: &Hypervector, b: &Hypervector) -> Hypervector {
+    assert_eq!(a.dim(), b.dim());
+    let v: Vec<i8> = a
+        .0
+        .iter()
+        .zip(b.0.iter())
+        .map(|(x, y)| {
+            let s = (*x as i32) + (*y as i32);
+            if s > 0 {
+                1
+            } else if s < 0 {
+                -1
+            } else {
+                0
+            }
+        })
+        .collect();
+    Hypervector(v)
+}
+
+/// Cosine-like similarity: dot product / dim.
+pub fn similarity(a: &Hypervector, b: &Hypervector) -> f64 {
+    assert_eq!(a.dim(), b.dim());
+    let dot: i64 = a.0.iter().zip(b.0.iter()).map(|(x, y)| (*x as i64) * (*y as i64)).sum();
+    dot as f64 / a.dim() as f64
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bind_self_is_ones() {
+        let a = Hypervector(vec![1, -1, 1, -1]);
+        let r = bind(&a, &a);
+        assert_eq!(r, Hypervector(vec![1, 1, 1, 1]));
+    }
+
+    #[test]
+    fn similarity_self_is_one() {
+        let a = Hypervector(vec![1, -1, 1, -1]);
+        assert_eq!(similarity(&a, &a), 1.0);
+    }
+
+    #[test]
+    fn bundle_works() {
+        let a = Hypervector(vec![1, 1, -1]);
+        let b = Hypervector(vec![1, -1, -1]);
+        assert_eq!(bundle(&a, &b), Hypervector(vec![1, 0, -1]));
+    }
+}