Native ASCII CSV readers

This page describes a pair of deliberately simple native reference implementations used as integration and verification anchors for Hydra Forge.

The problem domain is intentionally unremarkable. The purpose of the example is not to demonstrate parsing techniques, but to demonstrate how native code moves through the system: from source, to compilation, to Python exposure, to verification, to documentation, without introducing fragility or hidden coupling.

The invariant-driven workflow

• Native code can be introduced without special handling
• Compilation and exposure are explicit and repeatable
• Python-facing interfaces remain stable across implementations
• Documentation is derived from the actual runtime surface
• Failures are detected early and block delivery

These invariants are enforced through a deterministic execution loop:

• Native source code is added under _native
• The Smithery phase compiles and inspects the artifact
• The exposed API surface is materialized deterministically
• The implementation becomes importable from Python
• Runtime docstrings are extracted and documented automatically

Implementations

This example exists to demonstrate a complete native integration cycle:

• Single-threaded ASCII CSV reader (C++)
• Single-threaded ASCII CSV reader (Rust)

Both implementations expose an identical Python-facing interface and are interchangeable at the call site.

The engine does not care how the code was authored. It may be written by hand, adapted from legacy systems, or produced with the assistance of automated tools. Only the exposed behavior matters.

At any point, one implementation can be replaced with another by changing a single Python import - nothing else.

Hydra Forge enforces structure, not behavior. Engineers are free to bypass, replace, or remove native components entirely - the workflow adapts, it does not constrain.

Rebuilds are derived, not fragile

Compiled native artifacts were deleted manually. No configuration files were changed.

A single engine command rebuilt, reintegrated, and re-exposed both native implementations.

Native state is derived from source, inventory, and exposure rules - not from incremental build residue.

Both are compiled and exposed through Hydra Forge, and both present the same Python-facing interface, with a subtle but intentional difference. One reader is deliberately exposed under portal.io., the other one defaults to portal.flat..

from HydraForge_Windows11.portal.io import ascii_csv_reader
from HydraForge_Windows11.portal.flat.ascii_csv_reader_rs import read_ascii_csv_rs

Python code does not import binaries, loaders, or bindings directly. It imports a stable, generated API surface.

Tested together, not separately

Both native implementations are exercised in the same test suite. They are not validated in isolation.

a = read_cpp(path)
b = read_cpp(path)
c = read_rust(path)
d = read_rust(path)

for key in a:
    np.testing.assert_array_equal(a[key], b[key], c[key], d[key])

Each implementation is invoked multiple times to assert determinism and absence of hidden state. This test enforces a stronger invariant than correctness: semantic equivalence across independent implementations.

This makes native experimentation cheap. Implementations can be replaced without changing Python code, tests, or documentation structure.

Documentation reflects runtime reality

Documentation is generated from the same artifacts used at runtime:

• Python source code (static analysis)
• Native bindings (runtime docstrings)
• Exposure manifests

There is no hand-maintained documentation layer. If a function is importable, it is documented. If it is not importable, it does not appear.

The authoritative reference for this example is the generated library documentation itself.

Inspect the generated API documentation ↗

What this example actually proves

• Native code can be introduced without refactoring Python
• Multiple languages can coexist safely
• Implementations can be swapped without destabilizing the system
• Tests enforce behavior, not implementation
• Documentation follows runtime truth

Hydra Forge does not write code or fix algorithms. It removes scaffolding, wiring, and integration friction - so engineers can focus on **their** engineering.

What you should inspect

The value of this example is not in how CSV is parsed, but in what the system produces around it.

• Native source code and bindings
• Generated exposure tree
• Python-facing import paths
• Extracted runtime docstrings
• Generated API documentation

All of these artifacts are produced automatically and can be inspected directly in the generated library. No manual wiring or duplication is required.

Why this example matters

Native integration failures typically occur at boundaries:

• Between languages
• Between build systems
• Between runtime behavior and documentation

This example exists to show that Hydra Forge makes those boundaries explicit, inspectable, and safe.

If this example fails, the system fails. There is no partial success mode.

The value of this example lies in the confidence it provides about the system that produced it.