\

.gitlab-ci.yml

@@ -67,13 +67,14 @@ mix-audit:
   stage: security
   image: elixir:latest
   script:
+    - cd beam
     - mix local.hex --force
     - mix archive.install hex mix_audit --force
     - mix deps.get
     - mix deps.audit
   rules:
     - exists:
-        - mix.exs
+        - beam/mix.exs
   allow_failure: true
 
 # ==================
@@ -105,21 +106,23 @@ mix-format:
   stage: lint
   image: elixir:latest
   script:
+    - cd beam
     - mix format --check-formatted
   rules:
     - exists:
-        - mix.exs
+        - beam/mix.exs
 
 credo:
   stage: lint
   image: elixir:latest
   script:
+    - cd beam
     - mix local.hex --force
     - mix deps.get
     - mix credo --strict
   rules:
     - exists:
-        - mix.exs
+        - beam/mix.exs
   allow_failure: true
 
 # ==================
@@ -139,12 +142,13 @@ mix-test:
   stage: test
   image: elixir:latest
   script:
+    - cd beam
     - mix local.hex --force
     - mix deps.get
     - mix test
   rules:
     - exists:
-        - mix.exs
+        - beam/mix.exs
 
 # ==================
 # Build
@@ -167,9 +171,10 @@ mix-build:
   stage: build
   image: elixir:latest
   script:
+    - cd beam
     - mix local.hex --force
     - mix deps.get
     - MIX_ENV=prod mix compile
   rules:
     - exists:
-        - mix.exs
+        - beam/mix.exs

READINESS.md

@@ -30,9 +30,9 @@ Zig FFI + zig API + Elixir BEAM NIFs.
 ## Gaps preventing higher grades
 
 ### Blocks C (works reliably + annotated)
-- No EXPLAINME.adoc, TEST-NEEDS.md, PROOF-NEEDS.md at repo root.
+- ~~No EXPLAINME.adoc, TEST-NEEDS.md, PROOF-NEEDS.md at repo root.~~ *(Added)*
 - Julia server code has no docstrings.
-- Elixir BEAM layer has no dedicated test coverage documented here.
+- ~~Elixir BEAM layer has no dedicated test coverage documented here.~~ *(Added Unit, P2P, Aspect, and Benchmark coverage)*
 - No integration tests spanning the full Idris2 → Zig → V → Julia → Elixir stack.
 - No dogfooding evidence — has anyone actually driven this end-to-end?
 - Only 4 commits in history before absorption into nextgen-databases monorepo.
@@ -42,9 +42,8 @@ Zig FFI + zig API + Elixir BEAM NIFs.
 
 ## What to do for C
 
-1. Add EXPLAINME.adoc explaining the polyglot architecture and its intended
-   users.
-2. Add TEST-NEEDS.md documenting what's tested at each language layer and what isn't.
+1. ~~Add EXPLAINME.adoc explaining the polyglot architecture and its intended users.~~ *(Done)*
+2. ~~Add TEST-NEEDS.md documenting what's tested at each language layer and what isn't.~~ *(Done)*
 3. Write docstrings for `server/serve.jl`, `server/quandle_semantic.jl`.
 4. Add per-language READMEs at `src/abi/`, `src/ffi/`, `src/api/`, `beam/`
    explaining what each layer contributes.

beam/benches/nif_bench.exs

@@ -0,0 +1,9 @@
+# benches/nif_bench.exs
+Benchee.run(
+  %{
+    "semantic_lookup (stub/nif)" => fn -> QuandleDBNif.semantic_lookup("3_1") end,
+    "semantic_equivalents (stub/nif)" => fn -> QuandleDBNif.semantic_equivalents("3_1") end
+  },
+  time: 2,
+  memory_time: 1
+)

beam/mix.exs

@@ -22,8 +22,8 @@ defmodule QuandleDBNif.MixProject do
   # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
-      # {:dep_from_hexpm, "~> 0.3.0"},
-      # {:dep_from_git, git: "https://github.com/elixir-lang/my_dep.git", tag: "0.1.0"}
+      {:stream_data, "~> 1.1", only: :test},
+      {:benchee, "~> 1.3", only: [:dev, :test]}
     ]
   end
 

beam/mix.lock

@@ -0,0 +1,6 @@
+%{
+  "benchee": {:hex, :benchee, "1.5.1", "b95cbc36c4b98969a5c592a246e171041eb683c56bad1cb4f49a3b081ba66087", [:mix], [{:deep_merge, "~> 1.0", [hex: :deep_merge, repo: "hexpm", optional: false]}, {:statistex, "~> 1.1", [hex: :statistex, repo: "hexpm", optional: false]}, {:table, "~> 0.1.0", [hex: :table, repo: "hexpm", optional: true]}], "hexpm", "a539301f8dfd4efc5c5123bfb9d47ebde20092a863a5b5b16c2a60d2243dfce7"},
+  "deep_merge": {:hex, :deep_merge, "1.0.2", "476aa7ea61c54de96220051b998d893869069094da65b96101aebf79416f8a1e", [:mix], [], "hexpm", "737a53cdc9758fedbb608bdc213969e65729466c4ef3cd8e8726d0335dff116c"},
+  "statistex": {:hex, :statistex, "1.1.1", "73612aa7f79e53c30569be065fd121e380f1cf57bc4c2da5b41be9246da18df9", [:mix], [], "hexpm", "310c4b49b34adf683de3103639006bed233ab54c08a4add65a531448e653857c"},
+  "stream_data": {:hex, :stream_data, "1.4.0", "026f929db613aabea6208012ae9b8970d3fd5f88b3bdf26831bc536f98c42036", [:mix], [], "hexpm", "2b0ee3a340dcce1c8cf6302a763ee757d1e01c54d6e16d9069062509d68b1dc9"},
+}

beam/test/aspect_test.exs

@@ -0,0 +1,26 @@
+defmodule QuandleDBNifAspectTest do
+  use ExUnit.Case
+
+  @moduledoc """
+  Aspect-based tests for the QuandleDB BEAM NIF boundary.
+  Asserts resilience against adversarial or extreme inputs.
+  """
+
+  test "resists extreme length inputs" do
+    huge_str = String.duplicate("A", 1_000_000)
+    result = QuandleDBNif.semantic_lookup(huge_str)
+    assert match?({:ok, _}, result) or match?({:error, _}, result)
+  end
+
+  test "resists null bytes and control characters" do
+    nasty_str = "abc\0def\n\r\t\x1b"
+    result = QuandleDBNif.semantic_equivalents(nasty_str)
+    assert match?({:ok, _}, result) or match?({:error, _}, result)
+  end
+
+  test "resists invalid unicode" do
+    invalid_str = <<0xFFFF::utf16>>
+    result = QuandleDBNif.semantic_lookup(invalid_str)
+    assert match?({:ok, _}, result) or match?({:error, _}, result)
+  end
+end

beam/test/property_test.exs

@@ -0,0 +1,23 @@
+defmodule QuandleDBNifPropertyTest do
+  use ExUnit.Case
+  use ExUnitProperties
+
+  @moduledoc """
+  Property-based (P2P) tests for the QuandleDB BEAM NIF boundary.
+  Asserts that arbitrary string inputs are handled safely without crashing the VM.
+  """
+
+  property "semantic_lookup handles arbitrary strings safely" do
+    check all(str <- string(:printable)) do
+      result = QuandleDBNif.semantic_lookup(str)
+      assert match?({:ok, _}, result) or match?({:error, _}, result)
+    end
+  end
+
+  property "semantic_equivalents handles arbitrary strings safely" do
+    check all(str <- string(:printable)) do
+      result = QuandleDBNif.semantic_equivalents(str)
+      assert match?({:ok, _}, result) or match?({:error, _}, result)
+    end
+  end
+end