Nano v1.0: CLI, static typing, look-ahead protection, indicators + pre-production hardening

[AetherAI3]

Ships Nano v1.0, then hardens it. Two phases in one branch, plus a merge reconciling with the docs overhaul that landed on main in parallel.

Tests 173 → 339. All 21 .nano/_ir.json corpus pairs remain byte-identical.

---

Part 1 — Nano v1.0

The CLI

nano installs as a console script with zero dependencies:

Command	Does
nano check	type-checks; silent on success, like a linter
nano compile	emits the IR document, resolved types, or the execution plan
nano replay	runs a strategy against recorded market data (CSV/JSON)
nano visualize	renders the execution graph as ascii, mermaid, dot, or json
nano indicators	lists the 33 computable indicators and their warm-up
nano version	component versions and supported IR versions

One correction worth making explicit: replay replays a strategy against recorded bars, not previous runs. There is no run history to replay — --data bars.csv --date 2026-01-15 selects a UTC day from a file you supply. --verify runs it twice and fails if the two results differ.

Look-ahead protection

Offsets count backwards only, and must fold to a non-negative compile-time constant:

close[t+1] > close   ->  4:19  Series offset must be a compile-time non-negative integer
close[-1]  > close   ->  4:18  Series offset -1 reads into the future
close[1]   > close   ->  legal - the previous bar

close[t+1] is rejected because t is not a compile-time constant, so the offset cannot be bounded — not because it names a future bar. There is no forward-indexing syntax at all, which is what makes look-ahead unrepresentable rather than merely detected. Warm-up is never fabricated either: a bar without enough history yields no value, and the VM will not emit an intent from it.

The version-inference decision

The compiler emits the lowest IR version that can express the program. A v0.1.0-era strategy still compiles to byte-identical 0.1.0 output — so the corpus, the strategy library, and Aether Code's pinned snapshot are untouched. Reach a v1.0 feature and the document becomes 1.0.0, where that feature has a representation. --ir-version forces the choice.

Also: static typing with series<T>, 33 deterministic indicator kernels, IR v1.0 as a flat typed DAG, and one VM for both IR versions — with a conformance test asserting the reference interpreter and the VM agree bar-for-bar across the whole corpus.

---

Part 2 — Hardening sweep

Four read-only audits in parallel, then a mutation sweep that disabled each safety guard in turn to see whether any test noticed.

The finding that mattered

nano/ir/module.py opens by claiming manifest violations, tier violations, cycles, and future-reading offsets are "enforced at load time, not discovered at run time". Six of those guards could be disabled with all 280 tests still passing. The checks worked; nothing would have told us if they stopped.

Worse, the boundary was reachable around. NanoModule is a frozen dataclass, so in-process code could construct one and skip from_dict — the audit built a module whose manifest granted only log.append and ran three BUY intents through the VM.

Fixed by making the claim true rather than softening it: validate() re-runs load-time validation and run_module calls it before executing. One pass over the nodes, against an evaluation that is nodes × bars.

Two asymmetries closed alongside: compile_to_dict did not round-trip through the loader while compile_module did — so nano compile -o ir.json wrote a document the validator never saw, contradicting a comment three lines above it. And StrategyGraph.to_module() built a module directly.

Nine CLI defects

The worst two:

• nano compile --emit types -o out.txt reported success and created nothing — the flag was accepted, ignored, and the command exited 0.
• nano check abandoned remaining files at the first unreadable one, so the exit code depended on argument order.

Also: replay/visualize caught only NanoCompileError while compile_module round-trips through the loader, so an IRValidationError escaped as a traceback; a non-UTF-8 file crashed (UnicodeDecodeError is a ValueError, not an OSError); Ctrl-C tracebacked; a broken pipe raised at shutdown; and exit codes conflated usage errors with I/O errors.

Documentation

Three documented examples had not compiled for months, including the README's headline strategy (observe market — the grammar requires observe()). tests/test_docs.py now compiles every fenced nano block in the repo, so this class of drift fails CI.

---

Part 3 — Merge reconciliation

origin/main gained 7 commits while this branch was open: a documentation overhaul (README 380 → 113 lines, new docs/{architecture,language,status}.md, all 17 papers edited), issue and PR templates, and setuptools package-data.

That rewrite is newer and better structured than the corrections drafted here, so it was adopted wholesale and only the v0.1.0 claims v1.0 actually invalidates were patched on top:

Upstream claim	Now
"Nano does not calculate indicators"	two forms: RSI(14) is a host feed signal, RSI(close, 14) is computed. Nano still never fetches data.
"Number literals cannot be negative"	the grammar supports unary minus; the constraint survives only as what baseline IR can carry
"one schedule and one rule per strategy"	reframed as the subset library entries stay inside to keep IR fixtures byte-stable

nano/__init__.py keeps upstream's framing — "does not include an LLM runtime, live-action connector, or general agent executor" — because it is still true under v1.0: a reasoning provider is a protocol the host implements.

---

Known gaps, named not hidden

docs/status.md now marks these honestly rather than leaving a reader to discover them:

• Risk-limit enforcement is Partial. risk { max_daily_loss 0.02 } parses, range-checks (fractions, not percentages), and reaches the IR — but nothing enforces the limits at run time yet. A strategy declaring a 2% cap is not stopped at 2%.
• No audit/provenance chain. moduleHash and sourceHash exist and are separable, but there is no hash-linked decision history.
• No live connectivity, deliberately. No broker API, no market feed, no order execution. There is no socket, subprocess, eval, or credential handling anywhere in nano/ — which is what makes "a Nano program cannot act on the world" structural rather than a policy.
• Six files exceed 500 lines, nano/types/checker.py worst at 945. It splits cleanly into three passes; deferred because a refactor that size at the end of a hardening pass trades a known-good state for a rushed one.
• LOOP-14 / LOOP-15 did not run — both need a governance ledger and benchmark suite this repo does not have, and reporting trends from absent data would be fabrication.

Full detail: docs/HARDENING-2026-07-26.md.

Test plan

• pytest -q → 339 passed, 2 skipped (optional aether-protocol-c extra; README no longer advertises a count)
• Mutation sweep: every safety guard now killed by a test
• Chaos inputs: empty, truncated, non-UTF-8 source and data, directory-as-file, permission error, malformed date, unknown flag/subcommand, broken pipe, Ctrl-C
• All 21 corpus pairs byte-identical; baseline interpreter and v1.0 VM agree bar-for-bar
• Capability bypass closed: a hand-built module with an ungranted intent.emit is refused

🤖 Generated with Claude Code