Skip to main content

Rust Code Tools

rust-code-tool is Holon's current compiled-code frozen-tool implementation kind. It lets a workspace persist a governed Rust CLI tool as managed source, build it under runtime control, validate it with tests and fixtures, and project it into the runtime tool catalog only after artifact readiness is proven.

Purpose​

This feature exists for cases where a reusable operation is stable enough that a generated or curated script is no longer the best implementation boundary, but Holon still needs to keep promotion, policy, evidence, and workspace scope under runtime authority.

In the current floor, Holon treats a rust-code-tool as a workspace-scoped frozen-tool proposal whose implementation is a compiled Rust binary rather than an inline script artifact.

Current Behavior​

A rust-code-tool proposal contains:

  • purpose, crate name, and binary name
  • relative source files, including a managed Cargo.toml
  • required input slots and optional secret refs
  • declared side effects and optional expected output schema
  • dependency requests against a curated Rust dependency catalog
  • at least one validation fixture
  • a validation command string used as part of promotion metadata

The runtime currently provides protocol and CLI support to:

  • validate a rust-code-tool proposal
  • create a frozen-tool proposal from that validated Rust tool definition
  • persist the managed source tree on disk under the runtime storage root
  • build the tool with cargo check and cargo build
  • test the tool with cargo test
  • run declared fixtures against the compiled binary using the Holon tool contract
  • read or list persisted Rust tool artifact records per workspace

Execution Contract​

The compiled binary must follow the same bounded contract Holon uses for deterministic tool execution:

  • read input JSON from HOLON_INPUT_JSON
  • write exactly one JSON object to stdout on success
  • write diagnostics to stderr
  • exit nonzero on failure

Holon now fails closed on invalid live output. Empty stdout, non-UTF8 stdout, non-JSON stdout, and JSON values that are not objects are rejected.

Storage And Artifact Model​

rust-code-tool is filesystem-backed by design. When a proposal is created, Holon writes the managed source tree under the runtime storage root and persists artifact metadata in the runtime database.

The current artifact record tracks:

  • workspace id and frozen-tool proposal id
  • tool name, crate name, and binary name
  • managed source root and manifest path
  • source hash and manifest hash
  • binary path when build succeeds
  • build, test, and fixture readiness status
  • last build, test, and fixture evidence JSON
  • provenance refs, validation evidence refs, and approved dependency refs

Because the feature writes managed source and build outputs to disk, Runtime::in_memory() is not a supported host for rust-code-tool workflows. A filesystem-backed runtime database is required.

Validation And Policy Floor​

The current v1 validation floor is intentionally narrow.

Holon rejects or blocks proposals that violate the bounded policy surface, including:

  • empty purpose, crate name, binary name, or missing files
  • rooted paths, parent-directory traversal, duplicate file paths, or empty file contents
  • unsafe in Rust source files
  • missing manifest file or malformed TOML
  • missing fixtures
  • missing required input schema, output schema, validation command, or side-effect declaration for promotion eligibility
  • build scripts, build-dependencies, [patch], or [replace]
  • uncataloged dependencies or dependency requests that do not match the approved catalog exactly
  • git dependencies, path dependencies, mismatched versions, or mismatched feature sets

The current approved dependency catalog is deliberately small. Runtime dependency projection for live execution is also intentionally narrow: the execution spec carries cargo as the required runtime dependency rather than exposing build-time crate approvals as runtime dependencies.

Readiness Model​

A validated proposal is not automatically executable.

rust-code-tool readiness is currently separate from generic frozen-tool validation and requires all of the following before the tool is projected as ready and live-executable:

  • build_status == "ready"
  • test_status == "ready"
  • fixture_status == "ready"
  • binary_path exists and is readable

Until those artifact checks pass, the proposal remains blocked for validated projection and live workflow execution.

Runtime Projection And Workflow Execution​

When a workspace-scoped rust-code-tool proposal is validated and artifact-ready, Holon projects it into the runtime tool catalog as a frozen tool.

The current projection behavior includes:

  • strict input schema derived from required_inputs
  • required output schema derived from expected_output_schema
  • side-effect and approval metadata derived from the Rust tool declaration
  • same-workspace gating and fail-closed behavior

Workflow execution reuses the existing FrozenToolLive posture rather than introducing a separate executor kind. For ready Rust tools, Holon executes the compiled binary directly and uses the manifest directory as the working directory.

This means workflow-driven live frozen-tool execution is no longer limited to script artifacts. The current live floor includes:

  • validated workspace-scoped script-artifact proposals
  • validated workspace-scoped rust-code-tool proposals with ready artifacts

CLI Surface​

The holon CLI currently exposes:

  • rust-code-tool validate <json-file>
  • rust-code-tool create-frozen-tool-proposal <workspace-id> <json-file> --name <name> --version <version>
  • rust-code-tool build <workspace-id> <frozen-tool-proposal-id>
  • rust-code-tool test <workspace-id> <frozen-tool-proposal-id>
  • rust-code-tool read <workspace-id> <frozen-tool-proposal-id>
  • rust-code-tool list <workspace-id>

CLI-created proposals currently seed provenance and validation refs with bounded defaults so the runtime can treat the generated artifact as governed workspace state.

Current Limitations​

The current implementation is intentionally bounded.

  • Only one compiled implementation kind exists today: rust-code-tool.
  • The dependency catalog is curated and minimal, not general-purpose Cargo support.
  • Build and test run through local cargo; if cargo is not ready in the workspace dependency posture, build readiness fails closed.
  • The runtime stores and executes binaries from Holon-managed local storage only; this is not a general plugin loader.
  • The current floor uses debug builds and local managed build directories.
  • Direct desktop execution is still not a separate command surface; live execution happens through workflow ready-run.
  • The current desktop review surface is still bounded to proposal/readiness/lifecycle inspection rather than a dedicated compiled-tool workbench.

Windows Notes​

Windows path length was the first concrete build issue during implementation. The current runtime mitigates that by using short managed target directories and an isolated CARGO_HOME under the managed tools root.

This is an implementation safeguard, not a portability guarantee for arbitrary Cargo project shapes.