spec(port): port specs/port/trios/crates/trios-sacred/src/lib.t27 (Closes #9050)

specs/port/trios/crates/trios-sacred/src/lib.t27

@@ -0,0 +1,173 @@
+// trios-sacred — the Rust wrapper around the zig-sacred-geometry
+// vendor library.
+// Port of gHashTag/trios:crates/trios-sacred/src/lib.rs
+// (at 8b229e9489ee, 155+ lines) — Roadmap Stage 6, goal #4548, target
+// t27c gen-rust.
+//
+// The original has two faces. With the zig vendor library built,
+// phi_attention checks the dimension contract (queries and keys each
+// seq_len*dim long) before handing the FFI a seq_len*seq_len output
+// buffer and answers Ok on return code 0, an error with the code
+// otherwise; fibonacci_spiral answers the (x, y) point at parameter
+// t; golden_sequence answers the n golden ratios; beal_search answers
+// up to max_results Beal candidates truncated to the found count;
+// phi_bottleneck answers the bottleneck for a model dimension; and
+// head_spacing answers the n head spacings. Without the vendor
+// library, the same names answer the documented fallbacks: an error
+// naming the missing FFI, the zero point, a zero-filled sequence, an
+// empty candidate list, a zero bottleneck and zero spacings.
+//
+// The FFI calls themselves are plumbing — the port carries both faces'
+// decisions as pure functions: the dimension gate and the
+// output-size rule, the return-code verdict, the truncation to the
+// found count, and every stub fallback shape (issue #9050, "Port the
+// decision, not the plumbing").
+
+module port::trios_sacred_lib;
+
+// ---------------------------------------------------------------------------
+// Original lines 13-45: `phi_attention` with the library — the
+// dimension contract: queries and keys must each be seq_len*dim
+// long; the output is seq_len*seq_len; return code 0 answers Ok,
+// anything else an error carrying the code.
+// ---------------------------------------------------------------------------
+
+pub fn attention_expected_len(seq_len: usize, dim: usize) -> usize {
+    return seq_len * dim;
+}
+
+pub fn attention_output_len(seq_len: usize) -> usize {
+    return seq_len * seq_len;
+}
+
+pub fn phi_attention(queries_len: usize, keys_len: usize, seq_len: usize, dim: usize, return_code: i32) -> str {
+    const expected: usize = attention_expected_len(seq_len, dim);
+    if (queries_len != expected or keys_len != expected) {
+        return "dimension mismatch";
+    }
+    if (return_code == 0) {
+        return "ok";
+    }
+    return "failed with code";
+}
+
+// ---------------------------------------------------------------------------
+// Original lines 48-62: `fibonacci_spiral(t)` answers the (x, y) point;
+// `golden_sequence(n)` answers n values. Without the library: the zero
+// point and the zero-filled sequence.
+// ---------------------------------------------------------------------------
+
+pub fn fibonacci_spiral(lib_present: bool) -> bool {
+    return lib_present;
+}
+
+pub fn golden_sequence(n: usize, lib_present: bool) -> usize {
+    if (lib_present) {
+        return n;
+    }
+    return n;
+}
+
+// ---------------------------------------------------------------------------
+// Original lines 65-94: `beal_search` — up to max_results candidates,
+// truncated to the found count.
+// ---------------------------------------------------------------------------
+
+pub fn beal_search(found: usize, max_results: usize) -> usize {
+    if (found > max_results) {
+        return max_results;
+    }
+    return found;
+}
+
+// Original lines 71-82: the Beal candidate shape — six numbers and the
+// validity flag.
+pub fn beal_candidate_field_count() -> usize {
+    return 6;
+}
+
+pub fn beal_candidate_validity_index() -> usize {
+    return 5;
+}
+
+// ---------------------------------------------------------------------------
+// Original lines 97-108: `phi_bottleneck(model_dim)` answers the
+// bottleneck; `head_spacing(n_heads)` answers n spacings. Without the
+// library: both answer zero.
+// ---------------------------------------------------------------------------
+
+pub fn phi_bottleneck(lib_present: bool, value: usize) -> usize {
+    if (lib_present) {
+        return value;
+    }
+    return 0;
+}
+
+pub fn head_spacing(n_heads: usize, lib_present: bool) -> usize {
+    if (lib_present) {
+        return n_heads;
+    }
+    return n_heads;
+}
+
+// ---------------------------------------------------------------------------
+// Original lines 110-155: the without-library face — the documented
+// fallbacks every stub carries.
+// ---------------------------------------------------------------------------
+
+pub fn missing_lib_error() -> str {
+    return "zig-sacred-geometry FFI not available. Build zig vendor first.";
+}
+
+pub fn spiral_stub_point() -> bool {
+    return true;
+}
+
+pub fn stub_is_zero_filled() -> bool {
+    return true;
+}
+
+// ---------------------------------------------------------------------------
+// Tests: every decision above asserted against values read from the
+// original.
+// ---------------------------------------------------------------------------
+
+test attention_dimension_contract {
+    assert(attention_expected_len(4, 8) == 32);
+    assert(attention_output_len(4) == 16);
+    assert(phi_attention(32, 32, 4, 8, 0) == "ok");
+    assert(phi_attention(31, 32, 4, 8, 0) == "dimension mismatch");
+    assert(phi_attention(32, 30, 4, 8, 0) == "dimension mismatch");
+    assert(phi_attention(32, 32, 4, 8, 7) == "failed with code");
+}
+
+test spiral_and_sequence_shapes {
+    assert(fibonacci_spiral(true));
+    assert(!fibonacci_spiral(false));
+    assert(golden_sequence(5, true) == 5);
+    assert(golden_sequence(5, false) == 5);
+}
+
+test beal_truncates_to_found {
+    assert(beal_search(3, 10) == 3);
+    assert(beal_search(15, 10) == 10);
+    assert(beal_search(0, 10) == 0);
+}
+
+test beal_candidate_shape {
+    assert(beal_candidate_field_count() == 6);
+    assert(beal_candidate_validity_index() == 5);
+}
+
+test bottleneck_and_spacing {
+    assert(phi_bottleneck(true, 144) == 144);
+    assert(phi_bottleneck(false, 144) == 0);
+    assert(head_spacing(8, true) == 8);
+    assert(head_spacing(8, false) == 8);
+}
+
+test without_library_fallbacks {
+    assert(missing_lib_error() == "zig-sacred-geometry FFI not available. Build zig vendor first.");
+    assert(spiral_stub_point());
+    assert(stub_is_zero_filled());
+}