# NRL to Bio-Digital Architecture Report

Project: Bio-Digital  
Source Reviewed: NRL repository native engine, language specs, architecture docs, and Python orchestration layer  
Mandate: PURE MACHINE CODE LEVEL. C-first native execution. No Python hot path. No high-level wrappers for Bio-Digital runtime.

## Amalgamation Boundary

Bio-Digital may merge native C patterns from NRL, but the merge boundary is strict:

- Use packed INT4 memory layout and nibble operations.
- Use ZPM compute avoidance and exact executed-versus-baseline accounting.
- Use Omega hierarchical sparse routing.
- Use init-time CPU feature dispatch with no hot-loop branching.
- Use stable `bio_v1_*` C ABI symbols.
- Use AVX2 and NEON kernel style with scalar reference paths for tests.
- Use native build and test flow modeled after `build.ps1` and `build.sh`.

Bio-Digital must not copy, depend on, or route execution through:

- `nrlpy`.
- Python GGUF orchestration.
- Python chat runners.
- Subprocess execution patterns.
- Manifest-first execution models.
- High-level wrapper dependencies.

The NRL native engine is a substrate and reference. It is not the runtime layer Bio-Digital extends.

## License Boundary

Bio-Digital must stay under the same repository license as NRL:

`RomanAILabs Proprietary Source-Available Evaluation License 1.0`

Do not introduce MIT, Apache, BSD, GPL, public-domain, or other permissive/open-source license terms into Bio-Digital. Bio-Digital is part of the protected RomanAILabs / Daniel Harding IP surface.

## Executive Verdict

The original NRL project contains several pieces that directly support the Bio-Digital vision, but they live mostly in the native `engine/` layer, not in `nrlpy`.

Bio-Digital should use NRL as a native engine substrate: its C ABI discipline, packed INT4 layout, CPU feature dispatch, AVX2 hot-loop style, ZPM compute-avoidance model, Omega sparse routing, locked benchmark accounting, and explicit native build flow are all useful.

Bio-Digital should not inherit the failed bottleneck pattern where GGUF chat execution and orchestration move through Python. The current NRL GGUF runner architecture intentionally routes P1 GGUF work through `nrlpy` / `llama-cpp-python`; that is useful history, but it is not the Bio-Digital target. For Bio-Digital, `.bio` must become the native orchestrator, and GGUF absorption must happen through C-level mmap and direct kernel dispatch.

## 1. What NRL Already Has That Helps Bio-Digital

### 1.1 Engine-First Contract

The strongest alignment is in `nrl-architecture.md`. Its first principles already match Bio-Digital:

- Hot paths belong in C or assembly.
- Control languages orchestrate but do not define numerics inside loops.
- CPU capability selection happens once at initialization.
- Public surfaces are versioned through a stable C ABI.
- Throughput claims must separate executed work from virtual skipped work.

This is directly compatible with Bio-Digital. The `.bio` language should be a stricter version of this philosophy: tokens map to fixed native handlers, and handlers call pre-bound machine-specific kernels.

Relevant source:

- `nrl-architecture.md`
- `engine/include/nrl/nrl.h`
- `engine/src/dispatch.c`
- `engine/src/runtime_internal.h`

### 1.2 Stable C ABI Pattern

NRL exposes a small versioned ABI through `nrl_v1_*` symbols in `engine/include/nrl/nrl.h`.

This is a good template for Bio-Digital:

- `bio_v1_init`
- `bio_v1_run_file`
- `bio_v1_absorb_gguf`
- `bio_v1_cpu_features`
- `bio_v1_active_variant`
- `bio_v1_lattice_status`

The key lesson is that Bio-Digital should have a stable native ABI from day one. Even if the first implementation is a standalone executable, the core should be buildable as a static native library.

Bio-Digital should not expose Python bindings until the native path is complete and benchmarked.

### 1.3 Init-Time Dispatch

`engine/src/dispatch.c` binds the active kernel once:

- AVX2 when available.
- Scalar reference otherwise.
- No CPU feature branch inside the inner loop.

Bio-Digital should copy this pattern, but expand it into two dispatch tables:

1. Opcode dispatch table:
   - `.bio` token to native C handler.
   - Example: `PULSE -> bio_pulse`.

2. Kernel dispatch table:
   - Native handler to architecture-specific hot loop.
   - Example: `bio_pulse -> bio_pulse_int4_avx2` or `bio_pulse_int4_neon`.

This preserves the core Bio-Digital rule: direct dispatch with no AST, no bytecode VM, and no high-level runtime.

### 1.4 Packed INT4 Lattice Foundation

NRL already has packed INT4 semantics:

- Two 4-bit values per byte.
- Low nibble = even index.
- High nibble = odd index.
- Threshold/reset dynamics.
- Scalar reference and AVX2 optimized path.

Relevant source:

- `engine/src/braincore_int4_scalar.c`
- `engine/src/braincore_int4_avx2.c`
- `engine/include/nrl/nrl.h`

This helps Bio-Digital because the `.bio` memory model also depends on packed INT4 lattice addressing. The existing NRL kernels are not full GGUF tensor kernels, but they prove the repository already has the correct low-level direction: packed memory, direct nibble operations, SIMD lanes, scalar parity, and native error codes.

Bio-Digital should reuse the layout discipline, not blindly reuse the current braincore update as the final GGUF inference kernel.

### 1.5 ZPM Compute Avoidance

`engine/src/zpm_int4_static.c` is directly relevant. It implements exact static-input acceleration by building tiny 4-bit transition maps and applying a collapsed update rather than every baseline iteration.

This is a useful model for Bio-Digital `ZPM_SKIP`:

- Avoid compute through certified structure.
- Keep exact accounting of executed work versus baseline-equivalent work.
- Preserve a scalar correctness reference.
- Do not pretend skipped work was physically executed.

For Bio-Digital, ZPM should evolve from INT4 state-transition collapse into GGUF tensor block skipping:

- Skip zero-point-dominated INT4 blocks.
- Skip blocks below activation threshold.
- Skip route-inactive regions.
- Skip cached prefix/KV regions.
- Report both executed work and virtual equivalent work honestly.

### 1.6 Omega Sparse Routing

`engine/src/zpm_omega_router.c` already partitions a lattice into sub-lattices, applies wake/prune flags, enforces a minimum active floor, and collects stats.

This directly maps to Bio-Digital opcodes:

- `OMEGA_ROUTE`
- `PRUNE`
- `ZPM_SKIP`
- `PULSE`

The current NRL router is still small and benchmark-oriented, but the design shape is valuable:

- Fixed-size sub-lattices.
- Active frontier selection.
- Pruned block accounting.
- Hybrid mode that keeps enough active work to avoid fake throughput claims.

Bio-Digital should generalize this into a route-mask engine for GGUF layers, heads, KV cache spans, and feed-forward blocks.

### 1.7 Native Build Flow

`build.ps1` already builds the C engine into `libnrl.a` and `nrl.exe` using Zig as the C compiler driver on Windows.

This helps Bio-Digital because the new project can start with the same practical model:

- C11.
- Static library.
- Single native executable.
- Explicit source list.
- AVX2 flags on Windows.
- Native tests.

Bio-Digital should start simple with this model before adding CMake or a more complex build generator.

## 2. What Bio-Digital Should Avoid From NRL

### 2.1 Avoid `nrlpy` in the Hot Path

The Python layer is useful for packaging, demos, tests, and high-level orchestration, but it conflicts with Bio-Digital's mission.

Avoid for Bio-Digital runtime:

- `nrlpy` GGUF chat orchestration.
- Python subprocess calls into `nrl`.
- Python parsing of manifests for native execution.
- Python wrappers around GGUF inference.
- Python object graphs for route state, memory state, or token loops.

Bio-Digital can optionally expose a Python binding later, but only after the native `.bio` runtime exists and remains independent.

### 2.2 Avoid the Current GGUF Runner Split

`docs/nrl_gguf_runner_architecture.md` documents a three-plane design:

- L0 numerics through `libllama` / `llama-cpp-python`.
- L1 gating lattice through NRL.
- L2 orchestrator through `nrlpy`.

That was reasonable for the old NRL direction, but it is not acceptable for Bio-Digital as the final architecture.

Bio-Digital should keep the conceptual split but move orchestration into native C:

- L0: GGUF mmap, tensor access, dequant, attention, FFN, sampler.
- L1: ZPM and Omega gating.
- L2: `.bio` opcode runner, native chat loop, telemetry, learn scheduler.

The key correction is this: Bio-Digital cannot leave L2 in Python. The `.bio` runner is L2, and it must be native.

### 2.3 Avoid Subprocess-Based Runtime Semantics

NRL currently allows Python to shell out to native commands for stable CLI behavior. That is acceptable for tooling, but it is not acceptable for Bio-Digital execution.

Bio-Digital should not run the engine by spawning command-line processes from Python or another high-level supervisor.

The execution path should be:

```text
.bio file
  -> native lexer
  -> opcode function pointer
  -> C handler
  -> pre-bound AVX2 / NEON / scalar validation kernel
  -> mapped GGUF lattice
```

No subprocess boundary belongs in the neural hot path.

## 3. Direct Design Transfers Into Bio-Digital

### 3.1 Use NRL's C ABI Discipline

Bio-Digital should define its own `bio_v1_*` ABI, separate from `nrl_v1_*`, while still allowing internal linkage to NRL kernel pieces.

Recommended starting ABI:

```text
bio_v1_init
bio_v1_version
bio_v1_cpu_features
bio_v1_active_variant
bio_v1_run_file
bio_v1_absorb_gguf
bio_v1_lattice_status
bio_v1_shutdown
```

Keep this ABI small. Add new symbols only when the native runtime proves it needs them.

### 3.2 Split Dispatch Into Opcode and Kernel Binding

NRL already has kernel binding. Bio-Digital needs an additional layer above it:

```text
BIO_OPCODE_ABSORB_GGUF -> bio_op_absorb_gguf
BIO_OPCODE_MANIFOLD_ADDR -> bio_op_manifold_addr
BIO_OPCODE_ZPM_SKIP -> bio_op_zpm_skip
BIO_OPCODE_OMEGA_ROUTE -> bio_op_omega_route
BIO_OPCODE_PULSE -> bio_op_pulse
BIO_OPCODE_INFER_CHAT -> bio_op_infer_chat
BIO_OPCODE_LEARN_CYCLE -> bio_op_learn_cycle
BIO_OPCODE_HALT -> bio_op_halt
```

Then each handler calls a native kernel table:

```text
bio_kernel_int4_dot
bio_kernel_zpm_scan
bio_kernel_omega_route
bio_kernel_kv_update
bio_kernel_delta_apply
```

This gives Bio-Digital true direct dispatch while keeping CPU-specific logic out of the lexer.

### 3.3 Reuse INT4 Packing as the Physical Lattice Format

NRL's two-nibbles-per-byte representation should become the physical base of the Bio-Digital lattice.

Bio-Digital should extend it with GGUF tensor metadata:

- Tensor span base pointer.
- Tensor byte length.
- Quantization type.
- Group size.
- Scale pointer.
- Zero-point pointer.
- Folded 16000D coordinate mapping.
- Route mask pointer.
- Delta sidecar pointer.

The current NRL INT4 format is a useful primitive. Bio-Digital's lattice view must be richer because GGUF tensors have quantization groups, tensor shapes, metadata, and per-layer structure.

### 3.4 Reuse ZPM and Omega as Verified Compute-Avoidance Concepts

NRL already has the right honesty model: virtual throughput is allowed only when the skipped baseline is explicitly accounted for.

Bio-Digital should inherit that rule.

For every `ZPM_SKIP` and `OMEGA_ROUTE` path, telemetry should record:

- Baseline-equivalent blocks.
- Executed blocks.
- Pruned blocks.
- Route-active blocks.
- Skip ratio.
- Kernel variant.
- Whether the skip actually affected GGUF inference or was advisory only.

This avoids the failure mode where huge virtual numbers are claimed without proof that the model work was actually elided.

### 3.5 Keep Scalar Reference Paths for Tests Only

NRL's scalar and AVX2 parity model is valuable. Bio-Digital should keep scalar reference kernels, but only for validation and debugging.

Production execution should bind to:

- AVX2 on x86-64 where available.
- AVX-512 later if benchmarked honestly.
- NEON on AArch64.
- Scalar only for tests, fallback diagnostics, or unsupported development systems.

## 4. Bio-Digital Design Adjustments After Reviewing NRL

### 4.1 Change "16000D" to a Folded Manifold Over 16,384 Native Tiles

NRL already references a canonical 16,384-unit planning shape. Bio-Digital's 16000D manifold should stay as the language-level vision, but the engine should physically prefer 16,384-aligned tiling for SIMD and power-of-two block decomposition.

Recommendation:

- Keep `.bio` syntax as `dims=16000` if desired for identity.
- Internally map it to 16,384-aligned tile space.
- Document the distinction clearly.

This gives the architecture both the desired symbolic manifold and a practical native memory layout.

### 4.2 Treat GGUF Assimilation as a New Native Subsystem

NRL does not yet provide the direct GGUF mmap tensor engine Bio-Digital needs. Existing GGUF work is mostly in the Python orchestrator path.

Bio-Digital must therefore build a new native module:

```text
bio_gguf_mmap.c
bio_gguf_parse.c
bio_lattice_map.c
bio_quant_int4.c
```

This should not be copied from `nrlpy`. It must parse GGUF directly in C, map tensor spans directly, and fail closed on unsupported quantization formats.

### 4.3 Make `.bio` the Native Replacement for `.nrl` Manifest Execution

`.nrl` v0 is a minimal key-value control surface. That is useful as history, but `.bio` should not be another broad manifest.

Recommended rule:

- `.nrl` remains a human-friendly config/manifest format.
- `.bio` becomes a direct neural opcode stream.

The `.bio` lexer should not build a document model. It should scan, parse fixed operands, and dispatch immediately.

### 4.4 Do Not Start With Full Chat Inference

The old architecture failed partly because GGUF/chat became a large orchestration problem before the native path was complete.

Bio-Digital should build in this order:

1. Native `.bio` lexer and opcode dispatch.
2. Native GGUF mmap and tensor directory.
3. INT4 lattice view and packed addressing.
4. ZPM/Omega route masks.
5. PULSE kernels.
6. KV cache arena.
7. Native tokenizer/sampler.
8. `INFER_CHAT`.
9. `LEARN_CYCLE`.

This keeps the machine-level foundation real before adding chat behavior.

## 5. Proposed Bio-Digital Folder Direction

Recommended native layout inside `Bio-Digital`:

```text
Bio-Digital/
  Bio-Digital-Architecture.MD
  NRL-Bio-Digital-Report.md
  include/
    bio/
      bio.h
      bio_opcode.h
      bio_lattice.h
      bio_gguf.h
  src/
    bio_main.c
    bio_capi.c
    bio_lexer.c
    bio_dispatch.c
    bio_cpuid.c
    bio_gguf_mmap.c
    bio_gguf_parse.c
    bio_lattice.c
    bio_zpm.c
    bio_omega.c
    bio_pulse_scalar.c
    bio_pulse_avx2.c
    bio_learn.c
    bio_chat.c
  examples/
    boot.bio
  tests/
    test_lexer.c
    test_gguf_header.c
    test_lattice.c
    test_zpm_omega.c
  build.ps1
  build.sh
```

This keeps Bio-Digital independent from `nrlpy` and gives it a native identity.

## 6. Priority Reuse List

Reuse as design or code reference:

1. `engine/include/nrl/nrl.h`
   - Stable C ABI pattern.
   - CPU feature symbols.
   - INT4 packed byte contract.

2. `engine/src/dispatch.c`
   - Init-time kernel binding.
   - No CPU feature branch inside hot loops.

3. `engine/src/runtime_internal.h`
   - Internal function pointer contracts.
   - Dispatch table pattern.
   - Omega stats shape.

4. `engine/src/braincore_int4_avx2.c`
   - AVX2 packed nibble operations.
   - Branch-minimized SIMD update.

5. `engine/src/zpm_int4_static.c`
   - Exact compute collapse model.
   - Baseline versus executed accounting.

6. `engine/src/zpm_omega_router.c`
   - Sparse sub-lattice routing.
   - Wake/prune flags.
   - Minimum active floor.

7. `build.ps1`
   - Practical Windows-native C build path using Zig.
   - Static library plus executable flow.

Use only as conceptual history, not as Bio-Digital runtime foundation:

1. `nrlpy/src/nrlpy/gguf.py`
2. `nrlpy/src/nrlpy/gguf_chat.py`
3. `nrlpy/src/nrlpy/runtime.py`
4. Python subprocess execution paths.
5. `llama-cpp-python` orchestration.

## 7. Risks and Required Corrections

### Risk: "Pure Machine Code" Can Become Unmaintainable

Writing raw machine code by hand for every path is not the right first step. The practical interpretation should be:

- C-level runtime.
- Explicit CPU intrinsics.
- Precompiled architecture-specific kernels.
- Optional handwritten assembly only where profiling proves it matters.
- No Python, no VM, no AST, no high-level tensor runtime.

This still satisfies the Bio-Digital mandate while remaining buildable and reviewable.

### Risk: GGUF Is More Than INT4 Bytes

GGUF carries metadata, tensor names, tensor shapes, quantization variants, tokenizers, and model architecture details.

Bio-Digital cannot simply mmap bytes and call them a neural lattice. It must build a strict native GGUF parser and only register tensor spans whose quantization and shape are supported by native kernels.

### Risk: Chat Requires Tokenizer and Sampler Ownership

`INFER_CHAT` cannot be real until Bio-Digital owns:

- Tokenization.
- Prompt formatting.
- KV cache.
- Attention loop.
- Sampler.
- Stop conditions.

This should be phased after mmap, lattice mapping, and route kernels are stable.

### Risk: Learn Mode Can Corrupt the Base Model

The base GGUF mmap should remain read-only. Learn mode should write only to a sidecar delta lattice until `DELTA_COMMIT` is explicitly supported.

This matches the Bio-Digital architecture and avoids unsafe mutation of model weights.

## 8. Final Recommendation

NRL can help Bio-Digital most as a native kernel and discipline source, not as a Python runtime.

Keep:

- C ABI.
- Init-time dispatch.
- Packed INT4 memory.
- AVX2 kernel style.
- ZPM compute avoidance.
- Omega sparse routing.
- Honest throughput accounting.
- Native build and test flow.

Replace:

- Python GGUF orchestration.
- Python chat runner.
- Subprocess runtime semantics.
- Manifest-first execution.
- High-level wrapper dependency.

Bio-Digital should become the pure native control layer that NRL was pointing toward: a `.bio` opcode stream that directly drives mapped GGUF tensors, INT4 lattice memory, sparse routing, and precompiled machine-specific kernels.

The next build step should be Phase 1 from `Bio-Digital-Architecture.MD`: create the native C project skeleton, `.bio` lexer, direct opcode dispatch table, stub native handlers, and sample `.bio` file. Do not touch `nrlpy`.
