DOCSEARCHbyAlgolia
Submit Docs

Ant Runtime

repository·master·Indexed 21 days ago

https://github.com/themackabu/ant

A lightweight, high-performance JavaScript runtime built with the Ant Silver engine, optimized for minimal binary size and fast cold starts in edge and serverless environments. The ecosystem includes the antland CLI for package management via ants.land, the Colony CLI for deploying applications to ants.page, and Ant Desktop for building macOS applications using a native Apple Silicon payload.

Tokens
39.7K
Snippets
121
Records
190
Agent score
75%

What's inside ant

  1. Overview of Ant performance and characteristics

    master

    Ant is a lightweight, high-performance JavaScript runtime designed for environments where binary size and startup time are critical, such as serverless functions, edge computing, embedded systems, and CLI tools.

    Key characteristics include:

    • Small Binary Size: Approximately ~9 MB.
    • Fast Cold Start: Approximately ~5 ms.
    • Custom Engine: Uses the 'Ant Silver' engine (not a wrapper around V8 or JSC) with a JIT compiler based on a fork of MIR.
    • Spec Compliance: Targets the WinterTC Minimum Common API specification and achieves 100% pass rate on the compat-table suite (ES1 through ESNext).

  2. Overview of Active Plans

    master
    The Active Plans repository serves as a central store for in-progress execution plans within the Ant project. These plans document ongoing technical investigations, performance optimizations, and feature implementations. Each plan typically follows a structured format including Goal, Scope, Constraints, Task list, Decision log, Validation status, and Follow-ups.

  3. Use the antland CLI

    master

    The antland CLI is the command-line interface for ants.land, the package registry for the Ant runtime. It is compatible with standard package managers including npm, yarn, pnpm, and bun. You can use it via npx to manage packages, publish content, and run binaries safely.

    npx antland login        # authorize this device
npx antland add thing    # install a package
npx antland publish      # publish the current package

  5. Understand Process and Child Stream Unification

    master

    Ant unifies EventEmitter, Process, and Child Stream handling by moving process and child-process event handling onto a shared EventEmitter implementation. This unification ensures Node-compatible child stdio backpressure and closes compatibility gaps for real-world packages.

    Key Behaviors

    • Event Keys: Both string and Symbol event keys are supported on process.
    • Process Exit: When a process exits, stdin is closed, but stdout and stderr are allowed to reach EOF (End of File) to ensure data integrity.
    • Child Process Exit/Close: These events follow the Node.js signal shape, providing a null code and a symbolic signal name, along with exitCode and signalCode properties.
    • URL Parsing: Global URL.parse follows the WHATWG standard. For legacy Node-style behavior (including relative request targets like /), use the node:url export.

  6. Acceptance gates for adopting upstream Node shims

    master

    An upstream shim should only be adopted if it meets all of the following criteria:

    • Reproducibility: Its upstream revision and complete dependency closure are reproducible.
    • Security/Isolation: Its private binding surface is explicit, allowlisted, and inaccessible to application code.
    • Compatibility: Focused compatibility tests pass, with any intentional deviations documented.
    • Invariants: It does not weaken Ant's resource ownership, sandbox, or GC invariants.
    • Performance: Cold-start, memory, binary-size, and representative runtime costs are measured and accepted.
    • Maintainability: The upstream source plus adapters is easier to maintain than the existing Ant-owned implementation.

  7. Nanos Sandbox Backend Requirements

    master

    When implementing a backend for the Nanos Sandbox, the backend must expose a standardized Nanos-compatible machine shape rather than using platform-specific conventions.

    Required Backend Capabilities:

    • Kernel/Disk: Load the cached Nanos kernel and attach the cached Ant/Nanos disk image as virtio-blk.
    • Console: Provide console output in a Nanos-compatible way (e.g., guest console/PL011) for debug and failure output.
    • Transport: Provide a single transport mechanism for request, result, stdout, and stderr (typically length-prefixed frames via virtio-vsock).
    • Filesystem: Provide a Nanos-compatible file mount for /workspace (using virtio-9p for read-only host mounts or an attached input volume).

    Platform Specifics:

    • The Darwin backend must use Hypervisor.framework directly to boot the cached Nanos kernel and disk image, exposing only devices that the generic Nanos image understands.

  8. Execution Plans directory layout

    master

    The Execution Plans directory is organized into the following structure to separate active work from historical records and technical debt:

    • Active plans: Located in active/README.md.
    • Completed plans: Located in completed/README.md.
    • Technical debt tracker: Located in tech-debt.md.

    Note: The todo/ directory may be used for temporary scratch notes, but durable execution history must be stored within this structured layout.

  9. Understand for-of JIT ineligibility in Ant

    master

    In the Ant runtime, the presence of a synchronous for...of loop (including arrays, Maps, Sets, strings, generators, and user-defined Symbol.iterator objects) currently acts as a 'function-level veto' for the JIT compiler.

    When a for...of loop is detected, the entire enclosing function is disqualified from JIT compilation, forcing every statement within that function—including property reads, arithmetic, and stores—to run in the interpreter. This results in significant performance penalties compared to indexed for loops, which are JIT-compilable.

    Key Performance Impact:

    • Indexed for loops: Highly efficient as they compile to machine code.
    • for...of loops: Significantly slower (e.g., ~3.7x slower than indexed loops in Ant) because they trigger the ITER_NEXT and ITER_CLOSE opcodes, which currently lack the SV_OPF_JIT_ELIGIBLE flag.

  10. Understand the Ant Runtime Layers

    master

    Ant's architecture is organized into distinct layers that separate the CLI, the JavaScript engine, the host platform surface, and the build tooling. Understanding these layers helps in locating specific logic or determining where to implement new features.

    1. Process and Startup

    Handles the CLI entrypoint and runtime initialization.

    • src/main.c: CLI executable entrypoint.
    • src/ant.c & src/runtime.c: Runtime initialization and shared process setup.
    • src/cli/: Command-line specific behavior (e.g., version, package commands).

    2. JavaScript Engine

    The core language pipeline and memory management.

    • src/silver/: Lexer, parser, compiler, directives, VM glue, and bytecode operations.
    • src/gc/: Memory management primitives, object/string handling, and heap management.
    • Core engine support: src/errors.c, src/descriptors.c, and src/shapes.c.

    3. Host Platform Surface

    Provides the APIs and modules that JavaScript code interacts with.

    • src/modules/: Built-in modules and runtime-facing JS APIs.
    • src/builtins/: Bundled JavaScript shims and Node-compatible modules.
    • src/http/, src/net/, src/streams/: Protocol, networking, and streaming support.
    • src/esm/: Module loading, export wiring, and built-in bundle access.

    4. Tooling and Generated Inputs

    Manages the build graph and code generation.

    • src/tools/: Generates bundled sources (builtin bundle, JS snapshot).
    • src/core/: TypeScript sources and runtime metadata for generation.
    • src/pkg/: The Zig package manager.
    • meson/ & meson.build: Build graph, dependency setup, and code generation targets.

  12. Understand Dynamic Property Performance Optimization Strategies

    master

    Ant's dynamic property performance is driven by two primary architectural tracks:

    1. computed-property inline caches for obj[key] access.
    2. numeric-index storage for plain objects used as sparse arrays or heaps.

    Beyond these core tracks, Ant implements several supporting optimization buckets to improve performance for specific workloads:

    Key Conversion Fast Paths

    Reduces overhead when converting property keys. This includes specializing small non-negative integer keys, caching canonical string forms for hot numeric keys, and avoiding duplicate key string creation between GET_ELEM / PUT_ELEM and proxy dispatch.

    Proxy Dispatch Fast Paths

    Reduces the setup cost around Proxy trap calls. Improvements include caching handler get / set trap lookups when the handler shape is stable, reusing normalized property keys, and skipping expensive invariant checks when the target shape proves no relevant non-configurable property can exist.

    Megamorphic or Dictionary Mode

    For objects with high-cardinality add/delete patterns where shape-based slot layouts become inefficient, Ant can switch plain objects to a 'dictionary-mode' property storage. This helps workloads using many different string keys, not just integer-like keys.

    Trap-Aware Benchmarking

    To measure these optimizations, benchmarks should separate the following costs:

    • Plain numeric computed property access
    • Plain string computed property access
    • Pass-through proxy access
    • Demo-shaped proxy access (using Number(prop), isNaN, and Set.has)
    • High-cardinality add/delete workloads (for dictionary-mode)