nano: libDaScriptNano - the daslang runtime with no compiler in it

[borisbat]

Fixes a shipped-SDK regression: VECMATH_SRC never listed dag_vecMath_double.h or dag_vecMath_scalar.h, and dag_vecMath.h includes the first unconditionally - so any SDK consumer that compiled a file reaching vecmath failed to build. Nothing in the bundle smoke test compiles C++ against vecmath, which is why it went unseen.

libDaScriptNano is the daslang runtime with no compiler in it. A program that only ever runs already-compiled daslang still links the AST, the module registry, the debugger, the serializer and fmt today, because the compiler and the runtime share headers. nano breaks that sharing without forking anything: nano/include goes ahead of include/ in the search order, four headers resolve to nano's, and thirteen sources compile straight out of src/ against a minimal Context with no #ifdef anywhere in the shared tree. nano owns three sources - the Context, the seams where it ends, and a snprintf-backed string writer that replaces the one template that reached fmt.

Making those thirteen compile unmodified needed five carves, each splitting the runtime half of a file away from its compiler half. annotation_arguments.cpp, escape_string.cpp, builtin_array_ops.cpp and builtin_runtime_ops.cpp join simulate_gc_pod.cpp. Every one of them leaves the full runtime better factored: the array builtins no longer sit in the same file as their AST registration, and escapeString no longer drags fmt into the heap's diagnostics.

Four examples under examples/standalone/ cover one tier each - POD compute, the das heap, closures and generators, and output through the embedder's print sink. They build in-tree and from a bare installed SDK, and tests-cpp/big/nano_ctx links all four into a single program. A script that reaches past what nano carries fails to link rather than silently growing.

nano is NOT freestanding yet. It builds where the full runtime builds, minus the compiler. Cross-compiling for bare metal needs portability work in platform.h, smart_ptr.h, arraytype.h, vectypes.h and interop.h; ci/nano_arm_build.sh is the acceptance test for that port and is deliberately not wired into CI, because it is red today.

Where to look: the include-order trap in nano/ARCHITECTURE.md - a target that links nano from a directory holding the repo's include_directories() compiles against the full Context while linking nano's, with no diagnostic. Every such directory clears the property, and nano/REVIEW.das checks it.

Validation, claims, ledger

Validation

• ctest -L big (nano_ctx and standalone_ctx among them): 7/7 pass locally - CI runs -L small only, so nothing else proves them.
• SDK path, which CI does not exercise: cmake --install to a clean prefix, then configure examples/standalone against it with find_package(DAS) and build - all four examples build and run. This is what surfaced the vecmath install gap.
• nano/REVIEW.das: each of its four checks was negative-controlled (bogus shared source, a header shadowing nothing, the include-order guard removed from both the in-tree and the SDK CMake, a source dropped from the install list).
• Full suite 13979/13988 pass, 0 failed, 9 skipped. ctest -L small 109/109.
• Known red, unrelated and pre-existing: ctest -L big also carries style_lint_style014_long_comment and style_lint_style015_long_comment_private. utils/lint/main.das gained an unconditional skip for utils/lint/tests/ on 2026-07-11, six weeks after those tests were added, so both have been dead since. They fail on master too. Excluded with -E style_lint for the run above.

Claims - stated, not tested

• The three require $ includes in generated output are dead weight: nothing emitted names a symbol from bin_serializer.h, runtime_profile.h or performance_time.h. Verified by compiling the generated TUs with all three shadowed by empty headers. A break would look like an undeclared identifier in a generated TU on nano only.
• The five carves are behaviour-neutral: they move definitions, and every registration keeps its original bind flavor. Verified by the full suite and by src/builtin/REVIEW.das's bind-flavor scan. A break would look like a builtin resolving to a different node kind.

Not done

• The freestanding port. Five root causes are named in nano/ARCHITECTURE.md under "Ledgered cases", measured against arm-none-eabi with newlib.
• The standalone emitter still writes the three require $ includes. Shadowing them is compensation; the emitter fix rides the next nano change, and nano/ARCHITECTURE.md says so at the include contract.
• No stack-walk on panic, and no GC behind explicit delete. Both ledgered.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes an installed-SDK build regression in vecmath headers and introduces libDaScriptNano, a “runtime-only” daslang library intended for embedding precompiled standalone-AOT contexts without pulling in the compiler (AST/module system, fmt-heavy paths, etc.). To support nano’s “shadow include root” design, several runtime-only implementations are carved out of mixed compiler/runtime translation units, and a set of standalone examples + a C++ big test are added to keep the nano tiers link-tested.

Changes:

• Fix SDK install list for vecmath by adding missing headers that dag_vecMath.h includes unconditionally.
• Add nano/ (headers + sources + docs) and wire it into the build/install, plus standalone-AOT example targets and a nano_ctx C++ big test.
• Refactor (“carve”) runtime-only code into new src/simulate/* translation units to decouple runtime code from compiler dependencies.

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests-cpp/big/nano_ctx/test_nano_ctx.cpp	New big C++ test linking four standalone-AOT tiers into one nano-linked binary.
tests-cpp/big/nano_ctx/CMakeLists.txt	Build rules for generating AOT contexts and linking them against libDaScriptNano.
src/simulate/runtime_string.cpp	Removes escapeString implementation from this TU as part of runtime/compiler decoupling.
src/simulate/escape_string.cpp	New TU containing escapeString implementation for reuse by both full runtime and nano.
src/simulate/builtin_runtime_ops.cpp	New TU containing runtime-only builtin implementations used by AOT output.
src/simulate/builtin_array_ops.cpp	New TU containing runtime-only array builtin implementations used by AOT output.
src/simulate/annotation_arguments.cpp	New TU moving AnnotationArgumentList option helpers out of AST module code.
src/builtin/module_builtin_runtime.cpp	Removes runtime-only builtin bodies now moved to src/simulate/builtin_runtime_ops.cpp.
src/builtin/module_builtin_array.cpp	Removes runtime-only array builtin bodies now moved to src/simulate/builtin_array_ops.cpp.
src/ast/ast_module.cpp	Removes AnnotationArgumentList helper implementations now moved to simulate/.
skills/cpp_integration.md	Documents embedding via libDaScriptNano and include-order requirements.
nano/src/nano_stubs.cpp	New nano “seams” TU: print sink plumbing and fail-closed stubs for unsupported features.
nano/src/nano_string_writer.cpp	New nano StringWriter/TextPrinter implementation using snprintf instead of fmt.
nano/src/nano_context.cpp	New nano Context implementation for standalone-AOT execution (no compiler).
nano/REVIEW.md	New nano-specific code review checklist.
nano/REVIEW.das	New mechanical review gate for nano invariants (install list, include-order guard, etc.).
nano/README.md	New user-facing overview and build instructions for nano.
nano/include/daScript/simulate/simulate.h	New nano shadow header providing a minimal Context/runtime surface for standalone AOT.
nano/include/daScript/simulate/runtime_profile.h	Empty nano shadow header to satisfy require $ includes without pulling profiler.
nano/include/daScript/simulate/bin_serializer.h	Empty nano shadow header to satisfy require $ includes without pulling serializer.
nano/include/daScript/nano_print.h	Public nano embedder hook for routing all runtime output to one sink.
nano/include/daScript/misc/performance_time.h	Empty nano shadow header to satisfy require $ includes without pulling timing APIs.
nano/include/daScript/das_config.h	Nano shadow config header redirecting runtime output and disabling compiler-adjacent features.
nano/include/daScript/ast/ast.h	Nano shadow header providing a minimal subset of AST-facing types needed by reused runtime code.
nano/CMakeLists.txt	Defines libDaScriptNano as a static lib built from nano-owned + shared runtime sources.
nano/ARCHITECTURE.md	Documents the shadow-include-root mechanism, tiers, and fail-closed seams.
install/CLAUDE.md	Updates skill index entry to include nano in skills/cpp_integration.md.
include/daScript/simulate/annotation_arguments.h	Fixes default values for numeric option getters to be 0 instead of false.
examples/standalone/CMakeLists.txt	Adds in-tree build targets for nano standalone-AOT examples (generated via daslang).
examples/standalone/CMakeLists.standalone.cmake	Adds SDK-consumer build entrypoint using find_package(DAS) + building nano from sources.
examples/standalone/04_c_binding/main.cpp	New standalone example: C-owned loop + das decision + nano print sink.
examples/standalone/04_c_binding/blinker.das	New .das example for tier “output” via print.
examples/standalone/03_closures/main.cpp	New standalone example exercising lambdas/function pointers/generators.
examples/standalone/03_closures/closures.das	New .das example for tier C behaviors (closures/generators).
examples/standalone/02_heap/main.cpp	New standalone example exercising heap usage and delete path.
examples/standalone/02_heap/heap_demo.das	New .das example for tier B behaviors (arrays/tables/new/delete).
examples/standalone/01_pure/pure_math.das	New .das example for tier A (pure POD compute, no heap).
examples/standalone/01_pure/main.cpp	New standalone example driver for tier A.
CMakeLists.txt	Fixes vecmath install list; wires nano + standalone examples into build; installs nano and shared sources.
CLAUDE.md	Updates skill index and directory overview to mention nano.
ci/nano_arm_build.sh	Adds a (currently red) acceptance script for future freestanding cross-compile work.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/simulate/builtin_array_ops.cpp:29

• Same issue as builtin_array_size(): the capacity guard is against INT32_MAX but the message says INT_MAX. Align the message with the enforced limit so a panic is actionable and not confusing.

[Copilot]

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/simulate/builtin_array_ops.cpp:104

• builtin_array_erase_i64 uses (index+1) where index is int64_t. If pArray.size > INT64_MAX, a valid index == INT64_MAX passes the bounds check, but index+1 overflows signed int64 (UB) in the pointer arithmetic. Mirror the range-erase implementation: convert to uint64_t after the index<0 check and do all arithmetic in unsigned.