Dependencies and snapshots

There are three different dependencies: a resource (@resource), an installed package (requirements: or Rust deps:), and a project script imported as a module (uses:). A resource is not a module, and a package declaration does not grant access to a resource.

Python and TypeScript modules

Create a Python script asset named common with this source (it needs no main):

def greet(name: str):
    return {"hello": name}

The calling asset hello is complete:

# uses: common
from common import greet

def main(name: str = "world"):
    return greet(name)

With {"name":"Ada"}, it returns {"hello":"Ada"}. TypeScript uses an exported module and a relative import:

// Source of asset common
export function greet(name: string) { return { hello: name }; }

// Source of asset hello
// uses: common
import { greet } from "./common";
export async function main(args: { name: string }): Promise<{ hello: string }> {
  return greet(args.name);
}

Use the asset reference, without .py/.ts, in uses:. Resolution is relative-first, then root, then unique bare name. The resolver walks transitive dependencies; missing modules, incompatible languages, cycles and ambiguous names are errors, not an arbitrary import choice. The runtime creates sibling files under the imported bare names; avoid two distinct dependency paths that need the same import name. Resources declared by dependencies are resolved relative to each dependency’s own folder.

Exactly what publication freezes

For a script endpoint, an ordinary uses: graph is frozen with the published source when no reference anywhere in the graph is (live). The warm pool can serve that snapshot. Editing the module does not change this endpoint until republish; rollback restores the frozen module graph too. This is not the old blanket rule that all modules are always live.

# uses: common, shared/rules (live)

Any explicit (live) reference makes the dependency graph resolve from current project scripts on every run and forces a fresh one-shot worker. Direct draft/test/schedule execution has no published frozen graph and resolves live. Legacy snapshots with no frozen dependency metadata also resolve live.

Workflow-step exception in 1.1.0: workflow publication bakes each step script’s main source and nested workflow definitions, but step uses: dependencies, including those in nested workflows, are populated from live scripts before each run. Do not rely on workflow rollback to restore these modules. A workflow with such dependencies can therefore change behavior without republishing even though its main step sources remain frozen.

Packages and environments

Python needs uv and a usable Python interpreter on the execution node; TypeScript needs Bun. Requirements are installed into a cached script environment. Publishing and explicit environment builds prepare it; missing dependencies, an inaccessible package index, native build tools or a failed install can still prevent a run. build-timeout: bounds preparation, not execution; timeout: bounds execution, not package installation. A cold environment reached during a run keeps the deployment’s install deadline rather than acquiring an arbitrarily long script-specific build window.

viat script env hello --json
viat script env hello --probe --json
viat script build hello --wait

The first reports recorded environment state; --probe consults the cache. Building changes deployment state and may download packages. Python/TypeScript dependency build failures can become publish warnings; acknowledging a warning is not proof that the runtime is ready. Check environment state and a safe draft run before switching traffic.

Rust uses Cargo dependencies and optionally a project crate, not uses:. Pin exact versions or carry a lockfile: artifact caching does not mean “check for a newer compatible dependency on every request.” Rust describes build and schema probes. Binary content is an artifact manifest, not an environment to install into.

Verification and cleanup

For a snapshot check, publish hello, edit only common, then compare a published call with viat script run hello --args '{"name":"Ada"}'; they intentionally differ until republish. Repeat with (live) only in an isolated project. No live verification is performed by this reference. Remove the test endpoint before deleting its scripts; deleting a shared dependency can break draft, live and legacy callers. Local offline imports do not prove publication or rollback semantics; see Testing.