Modules

Once graph modules are Starlark files that export graph primitives. The primary exported primitive is a target kind: a schema, an optional resolver that expands locked dependency metadata into targets, and an optional implementation that turns one target into cacheable actions. Built-in and project target kinds use the same public contract, so a project can add a target kind without changing Once itself.

Built-in analysis loads the target-kind families needed by the graph together with their helper dependencies. Shared, ecosystem-neutral utilities remain available across families; toolchain-specific helpers do not need to be loaded for unrelated targets. This keeps analysis work proportional to the graph without changing the schemas available through discovery.

Built-in Apple target kinds use Xcode tool discovery on macOS and the registered xtool Darwin Swift SDK on Linux. The existing xcode_developer_dir attribute pins Xcode's Developer directory on macOS or a Darwin SDK bundle's Developer directory on Linux. Linux iOS device targets default to ARM64, independently of host architecture; archs still overrides library architectures. Compiler, SDK, resource-tool, and environment identities partition Linux action caches. Signing actions invoke rcodesign with ad-hoc signing and no timestamp service. Providers, action declarations, and resource budgeting are unchanged. The Linux starter is discoverable through once query example apple_application apple-application-linux, and the same example is available through MCP. See Build iOS Applications on Linux for setup and unsupported macOS runtime and resolver workflows.

Loading Project Modules#

Project modules are listed from the root manifest:

Each matched file exports one or more public target kind symbols. Public symbols are module globals that do not start with _. The exported symbol name becomes the target kind unless the target kind explicitly sets kind.

Target Kind Schema#

target_kind(...) declares the public contract exposed by once query schema and by Model Context Protocol target kind discovery.

• kind: optional override for the target kind used in once.toml. When omitted, Once uses the exported symbol name.
• docs: short human-readable target kind description.
• attrs: attr(...) declarations. Supported types include string, bool, int, float, list<string>, map<string, string>, target, and nested values used by select.
• deps: dep(...) declarations that name expected providers.
• providers: provider names this target kind can return.
• capabilities: command surfaces this target kind supports, such as build, lint, run, test, or metadata.
• tools: tool(...) declarations for workspace tools the implementation needs during analysis or execution.
• examples: example(...) declarations for starter workspaces exposed to agents.
• source_references: source_reference(...) declarations that connect this target kind to authoritative external rules, plugins, registry records, or build-system concepts.
• impl: optional function that declares actions and returns a provider record.
• resolver: optional function that reads declared text inputs and returns synthetic targets before graph validation and scheduling.

Attributes can be configurable unless their schema sets configurable = False. Non-configurable attributes reject select during validation before the implementation runs. Set implemented = False on compatibility attributes that should remain discoverable but are not available yet. Validation returns unimplemented_attr with an attribute-scoped repair before analysis starts. Values declared with the target type use the same package-relative target syntax as dependency references. Complete-workspace validation confirms that each referenced target exists and returns an attribute-scoped repair when it does not. Use allowed_values = ["first", "second"] on a string or target attribute when the schema accepts a fixed set. Validation reports an attribute-scoped repair before analysis when a manifest supplies another value. Use disallowed_values = ["", "reserved"] when the schema accepts arbitrary strings except for a small reserved set. Validation ignores surrounding whitespace when comparing these values and reports an attribute-scoped repair before analysis. Use min_count and max_count on dep(...) when a dependency role requires a bounded number of targets. For example, dep("deps", ["application"], min_count = 1, max_count = 1) requires exactly one default dependency and reports an attribute-scoped repair before analysis.

Native Project Discovery Contract#

native_project(...) lets a module recognize an ecosystem-native integration and map it to one ordinary seed target. The seed target's resolver emits the detailed graph through the same typed resolver contract as manifest-authored targets.

• target_kind names the target kind instantiated by the seed. Schema loading rejects a native integration that references an unknown target kind.
• markers lists files that must all exist in one directory. The first entry drives the bounded scan.
• inputs adds optional text globs to the seed's resolver inputs. Markers are always included.
• target_name names the ephemeral seed target.
• exclude lists directory names skipped during discovery.
• input_exclude lists directory names that cannot hold a resolver input, so gathering the seed's inputs does not descend into them. This is a different question from exclude: a vendored dependency directory is excluded from discovery, because it is not a project of its own, and yet its manifest is an input to the project that vendored it. A build output tree or a version control directory is neither, and walking one to look for inputs is the largest avoidable cost of loading a large workspace.
• on_match = "stop" keeps the shallowest matching root, which suits native workspaces that own nested package manifests. "descend" recognizes every nested file marker. "all" recognizes every matching directory, including directory-spanning markers such as *.xcodeproj/project.pbxproj.
• max_depth bounds discovery.
• requires_tools reports executables needed when the seed resolver runs.
• workspace_markers optionally lists literal paths, such as .git, that identify a containing workspace. For configuration-free build and test invocations in a matching native project, Once uses the nearest ancestor containing one of these paths as the filesystem boundary. Only that native project family beneath the invocation directory supplies seeds, so unrelated native integrations elsewhere in the repository do not block the command. Run, lint, and --all use the same boundary. Selection requires a marker directly in the selected project directory. A child project cannot change a repository-root invocation without an explicit target. Package-relative native targets select their owning project; sibling native seeds remain selectable. Marker files and directories both count. Without a containing marker, the invocation directory remains the boundary. Existing once.toml manifests take priority. The default is [], preserving ordinary workspace discovery.
• owns_descendants = true makes a matched workspace root take precedence over other native project seeds beside or below it. Use this for a native workspace whose checked tree intentionally contains another package format, examples, or third-party projects that belong to the outer build.

Detection reads file names only. It does not evaluate executable manifests or invoke native tools. Loading the graph runs the seed target's resolver through the normal trusted analysis boundary.

Discovery retains at most 16 mebibytes of match records. Once stops with an error if a workspace produces more, rather than allowing repository size to drive unbounded memory growth. Narrow the workspace include or exclude patterns, or use on_match = "stop" when nested projects belong to one workspace.

Native discovery provides ephemeral seeds in workspace roots that have no explicit Once targets. Explicit targets take precedence only in their own package, so an unrelated root target does not hide native roots elsewhere in a monorepo. The configured workspace include and exclude patterns still define the boundary.

Inspect the automatically derived graph through the ordinary query surface:

Discovery never writes once.toml. Resolver-emitted dependency and product targets remain derived from the native manifest and lockfile. Model Context Protocol callers use once_query_workspace and once_query_targets.

Dependency Resolver Contract#

A target kind resolver imports an authoritative locked dependency graph. It is not a replacement for the ecosystem package manager. Cargo, Mix and Hex, Swift Package Manager, Zig, or another native tool continues to own manifest semantics, registry behavior, version selection, and lockfile updates.

Compiled package outputs must retain compiler-generated resources alongside static package resources. Restoring a cached package must restore both, without requiring generated files to remain in the dependency's source checkout. Static resource staging must not replace directories containing compiler outputs.

The resolver receives a restricted context:

• ctx["label"]: package, name, and stable target identifier.
• ctx["attr"]: typed owner attributes. ctx["attrs"] is an equivalent spelling for resolver compatibility.
• ctx["configuration"]: normalized target operating system, architecture, and ordered selection tokens.
• ctx["srcs"]: declared build source patterns.
• ctx["files"]: resolver input files decoded as text, keyed by path relative to the owner package. Non-empty resolver_inputs patterns define this map. When the list is empty or omitted, srcs is used for compatibility.

Resolver files are limited to 16 mebibytes per file and 64 mebibytes in total for one target. Use resolver_inputs to keep binary, generated, or large build sources out of this text-only context while retaining them in srcs for build actions. A resolver should consume bounded text such as a manifest, lock file, or checked-in graph snapshot.

It may use generic host discovery primitives, including host_command, to ask the native package manager for locked metadata. It cannot declare actions or outputs. Resolution happens while the graph loads, so the returned value must be deterministic for the declared files, target attributes, module source, and resolver toolchain.

The compact return form is a list of target records. The detailed form also chooses owner roots and adds resolver-owned attributes to the owner:

Each target record accepts only name, kind, deps, dependencies, srcs, visibility, and attrs. Dependency references and exact visibility entries use the same syntax as a manifest, including ./name for a target in the owner package. A bare root name that matches an emitted target is also package-local. When roots is omitted, every emitted target becomes an owner dependency. Resolver-owned and synthetic attributes must be declared in their target kind schemas, including internal bookkeeping attributes. A resolver attribute cannot replace a value declared by the owner target. Expansion stops at 100,000 workspace targets so a recursive resolver cannot grow the graph without bound.

Built-in native workspace resolvers record first-party test target names in the non-configurable _default_test_roots attribute. Targetless once test and native command compatibility adapters use that metadata to avoid running test suites that belong only to resolved dependencies. A custom resolver can use the same convention by declaring the attribute as list<string> on its seed target kind and returning the generated test names through attrs.

A resolver can also return a non-configurable _display_name string for the owner. Generic run reporting uses it as the user-facing label without knowing which target kind produced it. When absent, reporting uses the target label.

Resolvers should preserve the ecosystem's authoritative lockfile and source selection. They may invoke the native package manager when a missing lockfile must be created or pinned sources must be materialized, and should surface its failure without inventing a parallel resolution. Modules may use the PubGrub version-solving algorithm for an ecosystem that has no authoritative resolver, but it is not the primary integration boundary.

See Ecosystems: Import Locked Third-Party Graphs for the shared update, source-materialization, query, and first-party consumer workflow.

Tool Requirements#

tool(name, executables = []) adds a tool requirement to the target kind schema and to every loaded graph target of that kind. name matches a key in the workspace mise.toml. executables lists the commands the target kind may invoke and defaults to the tool name.

The requirements are returned by once query schema and once query targets, so scheduling can collect the complete tool set as soon as the graph is loaded. Script targets derive the same requirement from their declared runtime.

Once carries a fixed mise version with each release. On first use it downloads the matching mise release binary, verifies its published checksum, and stores it in Once's data directory. A developer-installed mise is never required. When a graph build session starts, Once resolves declared executable names from the workspace tool environment and attempts installation when a tool is not ready. If workspace resolution fails, an available host executable can be used instead. Mise shims are not treated as concrete tool executables, so a shim cannot silently route an action back through a developer's global configuration. Command actions and scripts then run through mise exec with implicit installation disabled. Once authorizes the selected workspace configuration for these managed invocations while keeping user-global mise configuration isolated.

Starter Examples#

examples points at runnable starter bundles for a target kind. Each declaration provides the example slug, title, selection hint, and package-relative path. The bundle itself is a real workspace directory with manifests and sources. Use examples when a caller should be able to discover the target kind, choose a starter by intent, and materialize a working target without reading prose docs.

example(slug, name, use_when, path = None) defaults path to examples/<slug>. Paths are resolved relative to the module package, validated during schema loading, and loaded only when a caller requests that specific example.

once query target-kinds lists the available target kinds with their starter example slugs. Use once query schema <kind> --format json for the full target kind contract and lightweight example descriptors:

Agents should use use_when to pick the closest starter, then materialize it without copying file payloads through model context:

Fetch the file bundle only when the caller needs to inspect or adapt it:

Text files use contents. Binary files use contents_base64 so direct materialization preserves their exact bytes.

Model Context Protocol callers use once_list_target_kinds and once_query_schema for discovery, then once_materialize_example for direct setup or once_query_example to inspect the file bundle. Repository contributors can run mise run examples:verify-portable to materialize and execute the portable starter set.

External Rule Assimilation#

A project module can reproduce the useful portion of a rule or plugin that Once has never seen before. The coding harness owns the translation and keeps it with the project. Once supplies the typed schema, validation, generic action primitives, execution, cache, and evidence surfaces.

Start by fetching the authoritative source:

The fetch accepts public HTTPS text, does not follow redirects, and returns at most the requested byte limit. Its digest lets the harness remember which upstream content it interpreted. Use a final raw source, registry, or documentation address instead of an unbounded repository page.

Query the authoring contract instead of assuming that a remembered primitive signature is still current:

The result contains the declaration helper source, schema invariants, implementation context, analysis primitives, action primitives, maintenance invariants, module registration, and runnable starters. For test modules it also returns a matching target table and an exact normalized result example. Attribute defaults in schemas are descriptive strings and do not insert runtime values. An implementation uses ctx["attr"].get(...) when an optional attribute needs a fallback. After writing the project module, validate it in isolation:

Attach the upstream relationship to the local target kind:

source_reference(...) is descriptive metadata, not executable trust. It is returned by target kind discovery so a future maintenance pass can refetch the source, compare its digest, and decide whether the local translation needs an update. Set content_digest only after a complete, untruncated fetch. Omit it for documentation-only references.

Translate only the dependency closure necessary for the user's requested capability. Keep everything else in the source build. Invoke tools directly with argument lists, declare inputs and outputs, and use portable setup primitives instead of hiding graph work in a shell command. Then validate the module, target tables, and complete workspace before executing the capability and checking fresh evidence.

Implementation Context#

An implementation receives ctx with generic graph data:

• ctx["label"]: package, name, and stable id.
• ctx["attr"]: typed attributes after manifest parsing.
• ctx["srcs"]: raw source patterns from the target.
• ctx["deps"]: provider records returned by analyzed dependencies.
• ctx["deps_by_role"]: provider records grouped by the dependency roles declared in the target kind schema. The deps entry contains the same providers as ctx["deps"].
• ctx["build_dir"]: workspace-relative output directory for the target.
• ctx["scratch_dir"]: workspace-relative scratch directory for action-private helper files that are materialized before an action runs but are not durable target outputs.
• ctx["capability"]: active capability being analyzed.
• ctx["run"]: run request options. ctx["run"]["visible"] is true when the caller requested a visible runtime interface. ctx["run"]["args"] contains caller arguments for the run capability and is empty for other capabilities. Their interpretation is target-kind-specific.
• ctx["test"]: test request options. ctx["test"]["filters"] contains stable semantic unit identifiers selected for this test execution. Target kinds that declare case filtering translate these identifiers into native runner arguments. ctx["test"]["batch_id"] is a stable batch identifier during automatically scheduled execution and is None for a normal whole-target execution.

The implementation returns a dictionary of provider fields. Downstream target kinds should read provider fields from ctx["deps"] or ctx["deps_by_role"] instead of inspecting target identities.

A resolver or implementation reports an actionable failure by calling fail with the text once.diagnostic.v1 followed by one JSON object holding code, message, and optionally attribute and repairs. The engine attaches the target and returns a structured diagnostic with those fields, so agents receive the same code, attribute, and repairs shape as schema validation. Any other failure text is reported as a generic analysis failure. Actionable resolver diagnostics stay attached to the resolver owner rather than preventing unrelated targets from loading. Selecting that owner or a dependent target still fails with the diagnostic and its repairs. Unexpected resolver evaluation failures remain fatal to graph loading.

When an artifact has different link-time and runtime dependency closures, publish those closures as separate provider fields. Do not flatten them into one transitive list. Runtime bundle records should retain the owning target, bundle path, module name, and complete file outputs so final packaging actions can de-duplicate, materialize, and sign the closure without rediscovering the graph.

Host Globals#

Target kind implementations can use these generic primitives:

Modules are trusted analysis code. host_command executes on the host while the graph is loading, so load modules only from trusted sources and reserve it for deterministic discovery. It must not mutate workspace sources or the build output tree, and resolver scratch state belongs only under .once/tmp. Prefer declared lock files and checked-in graph snapshots when a package manager can supply them. Build work and source fetching belong in explicit actions or a separate update workflow.

• host_arch() and host_os() return normalized host identifiers.
• host_env(name) returns one host environment variable, or an empty string when it is unset.
• workspace_root() returns the absolute workspace root.
• host_which(name) resolves an executable on PATH.
• host_command(argv, env = {}, cwd = None, merge_stderr = False, check = True, max_output_bytes = None) runs a discovery command and returns standard output. A non-zero exit status fails analysis unless check = False, which returns the captured output for idempotent setup that a later probe verifies. Arguments, environment values, the working directory, stream merging, check, and the output limit participate in the command-scoped cache key. When set, cwd must be an absolute path, normally derived from workspace_root(). Standard input is closed: discovery must not prompt or consume the caller's input. The captured output is limited to 16 mebibytes by default. Pass max_output_bytes to raise that bound for a command whose answer is inherently large, such as a build system's dependency-closure action graph; the bound applies while capturing each stream and to the merged result, and is recorded with the observation so later validation re-runs the command under the same limit.
• host_symlink_target(path) returns where a host symbolic link points, as written, or an empty string when the path is not a link. A planner uses it to declare the files a linked input depends on.
• host_file_size(path) returns the size in bytes of a host file, which a deferred planner uses to describe an artifact produced by an earlier action.
• host_file_exists(path) checks whether a host path is currently a file.
• host_path_exists(path) checks whether a host path currently exists, including directories and symbolic links. Use it when a resolver probes a source tree rather than reads a regular file.
• host_path_is_within(path, root) canonicalizes two existing host paths and reports whether the first is contained by the second. Symbolic links are resolved before the containment check.
• host_file_read(path) reads a host file as Unicode Transformation Format, 8-bit (UTF-8) text. Analysis rejects files larger than 16 mebibytes.
• host_file_sha256(path) returns a host file's Secure Hash Algorithm 256-bit digest as lowercase hexadecimal text.
• host_file_contains(path, needle) checks host file text content and applies the same 16 mebibyte file limit.
• glob(patterns, exclude = []) expands patterns under the active package, omits matches selected by package-relative exclude patterns, and returns sorted workspace-relative file paths.
• walk_files(root, excluded_paths = [], excluded_names = [], include_empty_directories = False) walks a package-relative directory and returns sorted workspace-relative file and symbolic-link paths. Exact root-relative exclusions and file names prune whole trees before traversal. With include_empty_directories = True, every directory with no remaining entries is returned as well, so a consumer that copies the tree keeps it.
• walk_symlinks(root, excluded_paths = [], excluded_names = []) walks a package-relative directory and returns one string per symbolic link, the link's workspace path and its target joined by a NUL character. It follows no link, so a planner learns every link and destination with one walk.
• walk_workspace_files(root, excluded_paths = [], excluded_names = []) walks a workspace-relative directory without following symbolic links. Use it when a resolver must inspect a path shared by targets in different packages or explicitly snapshot a symbolic link whose destination is host managed.
• declare_output(name) reserves an output under the target build directory.
• execution_path(path) returns a stable command value for a workspace-relative path. Once resolves it against the local, sandbox, or remote execution root immediately before launching the process. Use it for tools that require absolute paths without embedding a host workspace path in the action digest.
• cmd_args(args, use_arg_file = None) creates a structured command-line fragment. args is a list of strings. When use_arg_file is set, it is a dictionary with path plus optional format and arg_format. The supported format value is line-delimited, which writes one argument per line without shell escaping. The caller chooses path; use ctx["scratch_dir"] for action-private helper files and declare_output for durable target outputs. arg_format defaults to @{} and must contain exactly one {} placeholder.
• run_action(...) records a command action for Once to execute. Its optional keyword-only history reports a producer-owned logical identity for cross-run history, independently of execution and cache identity.
• action_history_key(namespace, components) creates a bounded opaque descriptor for run_action(history = ...). Use a versioned ASCII namespace (1–64 bytes) and 1–8 string components (2048 bytes total, no controls). Components are encoded as a canonical JSON array and SHA-256 hashed. Choose a stable owner, native operation and structural output variant; never use run IDs, action indices, cache digests, source revisions, display labels, absolute paths or credentials. Invalid optional metadata is omitted without failing analysis. Deferred children need their own explicit keys, while cached outcomes retain recorded keys. Older actions stay ungrouped.

Built-in history currently covers Rust compilation/build scripts/test-runner compilation, Go compilation, Kotlin native/JVM/test compilation, Zig compilation and delegated CMake builds. Other actions still have occurrence details but do not claim cross-run equivalence. Rust registry/git dependencies use resolver-directory, resolver logical label and source identity without revision/requested-ref or userinfo, package and native target names, a Cargo-compatible version bucket, phase, output triple, host-tool role and mobile variant/consumer. Crates.io index protocols normalize to one origin. Stable 1.x versions share a bucket, 0.x versions use the minor range, and 0.0.x and prereleases stay exact. Workspace labels are version-independent; source-less generated dependency origins remain ungrouped. Target renames and incompatible versions start new histories. Producer derivation changes require a namespace version bump. The server omits ambiguous within-run keys from historical comparisons and qualifies first observations using retained reports.

• write_path(path, content) materializes generated text or byte-list files through normal actions.
• copy_path(source, destination, inputs = []) copies one workspace path by value. A directory symlink is materialized at the destination. Source paths are always action inputs; inputs adds any other paths read while deciding what to copy.
• copy_path(source, destination, kind = "tree", inputs = []) copies one or more directory contents while preserving their symlink layout. Each source tree is automatically hashed as an input.
• materialize_host_file(source, destination) snapshots one absolute host toolchain file into a workspace output. Analysis records its 256-bit Secure Hash Algorithm digest, and execution verifies the digest before the output enters the cache.
• materialize_host_tree(source, destination) snapshots one absolute host directory into a workspace directory output. Analysis and execution verify its content, file modes, and symbolic links before the output enters the cache.
• link_path(source, destination) declares an uncached, relative workspace link. The source must exist and is automatically declared as an input. Linked contents are not copied into the action cache, while downstream actions still hash them when they declare the link as an input. Windows hosts require permission to create symbolic links.
• prepare_path(path, kind = "remove") and prepare_path(path, kind = "directory") declare uncached cleanup and setup actions for workspace paths.
• write_tree_digest(root, output, include_suffixes = []) writes a deterministic digest listing for a workspace tree. The root is automatically declared as an input.
• write_archive(entries, output, sha256_output = None, format = "tar", uncompressed_sha256_output = None) writes a deterministic tar archive, uncompressed by default. Each entry declares a file, directory, recursive tree, or symlink (with a target), its archive path, fixed mode, numeric owner and group identifiers, and modification time. When requested, sha256_output records the Secure Hash Algorithm 256-bit digest. With format = "tar.gz" the archive is compressed with a gzip header that carries no timestamp, name, or operating system, so identical entries produce identical bytes on every machine; sha256_output then digests the compressed bytes and uncompressed_sha256_output digests the tar inside.
• download_and_extract(url, sha256, destination, authorization_env = None) streams a checksum-pinned ZIP archive into a declared directory output. An optional environment-variable name provides a web Authorization header only while the action executes, so its value is excluded from action declarations, cache keys, logs, and evidence. Runtime policy defaults to a 4 GiB downloaded archive and one million entries. Expanded regular-file data is capped at 4 GiB, or 64 times the declared download length when that is smaller. Symlinks and directories have separate metadata and entry-count limits; this is not a hard filesystem-space ceiling. Highly compressible archives exceeding this bound are refused. Archive bytes and the expansion bound are reserved together, so small known-length downloads can run concurrently without an extraction admission cycle. Unknown-length downloads reserve the full worst case and can serialize. Downloads share admitted staging, have a 30-second progress-stall bound, and must finish within 30 minutes, including staging waits and private archive writes. Checksum validation and extraction follow download completion; extraction retains admission until its physical filesystem work ends rather than being treated as cancellable. ZIP metadata is checked before decoder allocation. Multi-disk archives, prefixed data, trailing bytes, inconsistent ZIP64 records and excessive metadata are refused. Embedded end records with excessive entry counts may also be refused to prevent decoder fallback from bypassing the limits.
• toml_decode(src) and json_decode(src) decode data into Starlark values.

Portable file actions derive their cache keys from their operation and consumed inputs, not from unrelated actions declared earlier by the same target. Copy, link, tree-digest, and archive actions infer their direct source inputs. Use the inputs argument for additional paths that influence the operation. Portable actions still execute in declaration order, and Once hashes generated inputs directly. Blocking file operations and output capture own their scheduling reservations until the work stops, even when the caller is cancelled. A cancelled observer does not publish a completed action-cache entry for partial work.

Use these primitives to express resolver commands, source filtering, file formats, tool selection, compiler flags, provider conventions, and action layout.

Actions#

Native adapters can use the Apple kinds' prebuild_actions, prepackage_actions, and postbuild_actions attributes for ordered serialized script declarations. Preparation actions precede compilation or resource processing. Pre-package actions run after linking but before resource processing. Shell script records execute in the workspace so absolute native settings and in-place product edits agree with the declared output locations. Their caching still depends on complete input and output declarations; it does not imply filesystem isolation. They can generate resource files and declared resource-bundle trees. Post-build actions follow product assembly and precede final signing. Records carry a shell or argument list, environment, workspace-relative inputs and outputs, working directory, and an explicit cacheability decision. Native Xcode records also retain their phase identifier and original build directory so the target kind can map environment values and paths to the configured execution directory. Scripts without complete declarations must bypass the cache. After an untracked product script, the bundle tree is captured again so later actions consume modified and newly created files and respect deletions. A replaced output tree supersedes earlier records for its children. Stale top-level signatures are removed before these scripts; final signing and subsequent scripts consume the updated tree. Native records may carry unresolved_file_lists to retain bootstrap-dependent phases during import; executing such a record fails until those settings resolve.

run_action accepts:

• argv: command and arguments as strings or cmd_args fragments.
• inputs: workspace-relative files and directories hashed into the action digest.
• outputs: workspace-relative outputs the action must produce. Once creates their parent directories. If a previous action version left a file where a managed output now requires a directory, Once replaces the stale file. Later directory outputs supersede older child records. Later child outputs override earlier directory snapshots during restoration.
• clean_paths: workspace-relative paths to remove before a fresh command execution. Cache hits restore outputs without running the command.
• create_dirs: workspace-relative directories to create before a fresh command execution.
• cwd: workspace-relative directory to run the command in. Defaults to the workspace root when omitted or None.
• env: string environment variables.
• sandbox: local filesystem sandbox policy. off uses the current workspace view. inputs runs in an action-private workspace view populated from declared inputs and copies declared outputs back after a successful command. copied-inputs provides the same isolation but materializes private input copies for tools that cannot consume symbolic links. Both isolated modes create parent directories for declared outputs inside the private workspace. Use once query validate-actions to run an uncached contract investigation that checks created, modified, and deleted paths and returns structured repairs. Reads that leave no observable filesystem evidence remain a limitation of this investigation.
• success_exit_codes: integer list whose members mean the command completed and its declared outputs are valid. Defaults to [0]. Use this for tools that report valid findings with a nonzero process code. Accepted codes are normalized to success. If the list excludes 0, a process exiting with 0 fails instead of being cached as successful. After upgrading, actions whose list excludes 0 run once more instead of reusing earlier results. Policies including 0 keep their action-cache keys.
• cacheable: True by default. Set False for interactive or local side-effect actions. Uncacheable commands that run directly in the workspace (sandbox = "off", without network denial) record directory and symlink outputs as fingerprints, not restorable contents. Keep these outputs unchanged until their consumers finish. If an output needs restoration after cleanup or replacement, Once refuses rather than installing its fingerprint as file contents. Make the producer cacheable or use an input sandbox when consumers need restorable outputs. Consumers of these fingerprint-only outputs execute afresh, even when their own cacheable setting is True, because older cached results may contain fingerprint text instead of the original contents. This also applies to implicit same-target inputs through depends_on_prior_actions. Fresh results still use normal cache publication; ordinary file and restorable artifact inputs retain cache reuse. A raw file with bytes exactly equal to an earlier fingerprint at the same path cannot be restored during that invocation.
• inherit_parent_env: False by default. Set True only on an uncacheable, unsandboxed local run action that should behave like a command launched from the user's development shell. Explicit env values take precedence.
• depends_on_prior_actions: True by default. When true, each action key includes prior actions declared by the same target and acts as an ordering barrier. With False, declared input and output paths determine ordering; every consumed generated file must be listed in inputs. On a cache miss, unrelated cached outputs remain deferred until an ordered action or a requested output needs them. Declared filesystem changes that overlap cached outputs, including uncertain path aliases, retain conservative restoration before execution. This does not change action keys.
• intermediate: False by default. Set True on an action whose outputs only later actions of the same target read, such as a step that feeds the next one. When the action is a cache hit, its outputs stay in the cache instead of being written to disk at the end of the target, and are restored only when a later action that reads them has to run.
• toolchain_identity: optional string folded into the action digest.
• identifier: stable diagnostic label.
• display_name: optional human-readable name, such as Compile main.c or Link application. This keyword-only presentation field does not replace identifier or change the action's cache key. Do not include secrets, command arguments, or absolute host paths in names. Control characters are normalized to spaces to keep names on one line.
• source_files: optional keyword-only list of repository-relative file paths associated with the action. One file uses a one-element list; an action operating on several files can list each one. Omitted or None means no source links. Paths use forward slashes and cannot contain absolute paths, drive prefixes, backslashes, empty segments, . or .. segments, or control characters. These are links, not additional inputs or outputs.

All executable action primitives, including portable file actions, accept display_name, source_files, and presentation as optional keyword arguments. Portable file operations supply readable default names when no name is given. Bundled target kinds give compilation, linking, testing, packaging, and setup work descriptive names. Use source_files = _action_source_files(paths) to supply a descriptor of workspace source paths. Once resolves this presentation-only descriptor while collecting action metadata, memoizing file selection and repository mapping without adding execution observations or invalidating cached builds. It excludes directories, generated .once paths, absolute host files, and nonportable repository paths. Entries must be strings. It maps files relative to the nearest Git checkout, including worktrees, and honors an explicit GIT_WORK_TREE. Without a checkout, paths remain workspace-relative.

The optional presentation record describes ecosystem-native context without changing execution or cache identity:

A package may contain ecosystem, name, version, revision, digest, and origin. A platform has a stable scheme and id, an optional display label, and optional usage (product or build-tool). A context entry has a stable namespaced key and value, and an optional display label. All fields default to empty; omit irrelevant concepts. Declared output platforms are not execution worker placement. Versions, VCS revisions, content digests, SDK levels, and compiler versions are separate concepts. Never copy raw environment maps, credentials, authenticated URLs, or host paths into presentation.

Once retains at most eight platforms and eight context entries, with at most 2048 bytes of string data in total. Names are bounded to 128 bytes, namespace keys to 64 bytes, identifiers and values to 256 bytes, and display labels to 128 bytes. Invalid or oversized identifiers are omitted rather than truncated; malformed optional records are ignored rather than failing execution. Labels normalize control characters to spaces and oversized labels are omitted. expand_actions(..., presentation = ...) passes platforms and context to children that do not declare their own metadata, but never inherits package ownership into unrelated generated actions.

Bundled producers select only owned facts: Cargo package versions and compiler triples, Apple output triples, Go OS/architecture and effective cgo settings, Kotlin JVM levels, Android API levels and native ABIs, Zig's effective optimize mode, OCI platform sets and immutable digests, Mix environment and dependency identity, and known test/task/build context. Mix registry dependencies use the hex ecosystem and a package version; Git/local dependencies use mix, with a Git revision or no version respectively. Opaque CMake/Bazel/React Native steps never claim invisible internal package graphs or worker platforms. Shell/file operations, runtime test runners, and other actions may correctly omit package or platform information. Cargo's ambiguous workspace 0.0.0 default is omitted unless an explicit package version is available. Cargo resolvers annotate host-tool outputs with the schema-declared _cargo_host_tool boolean. This marker controls presentation and logical-history role, not scheduling or execution placement. The optional, nonconfigurable _cargo_resolver string records the resolver's logical label so separate resolver declarations in one package keep distinct histories, including host tools. It does not enter execution or cache identity.

Once includes this metadata in per-action completion events and preserves it when replaying cached target outcomes. An event server can show the name and link each file at the run's Git revision using its own repository integration. Older servers ignore the additional optional fields; no protocol upgrade or new required feature is necessary. If optional presentation fields exceed the server's event-size limit, Once retains the source links that fit and may omit an oversized display name or structured context. The action's identity, timing, and result are preserved.

Consumers must include staged output paths in their declared inputs. Mentioning a path only in arguments or environment variables does not guarantee that a cached staging action materializes it. Prefer disjoint staged output trees rather than a parent directory followed by overlapping child copies. If a native consumer requires a complete build tree followed by application overlays, each child copy must declare the staged parent as an input so it is restored first.

Optional toolchain and action identities are encoded separately in the input hash, including presence and embedded separators. Equal concatenated text in different fields cannot share a cache key. This identity encoding invalidates older declared-action cache entries once without changing artifact formats.

The declared action is its executable cache contract. Once hashes its operation, arguments, argument files, environment, working directory, path setup, toolchain identity, declared input contents, and dependency action digests. Changing target-kind module source without changing that declaration does not invalidate the action. A rule edit that changes any declared behavior or input still produces a new digest.

Consecutive actions with depends_on_prior_actions = False may run concurrently when their declared reads, writes, argument files, and cleanup paths do not conflict. Uncacheable actions and ordering barriers remain sequential. Both target and action concurrency respect the command's memory budget. Independent graph targets become ready after their dependencies complete. Command preparation, portable filesystem operations, output capture, producer repairs, and cached output restoration use shared invocation admission. Inputs are restored before admitting their consumer, and each restore attempt releases its admission before repairing a missing producer. Cancellation does not release a reservation or action lock while its blocking filesystem work still runs. These execution guards do not change cache identity or authorize remote graph placement.

Deferred Action Planning#

expand_actions(implementation, inputs, outputs, args) declares a planning barrier. After preceding actions finish, Once restores its inputs and calls the named exported Starlark function from the same module environment. This lets a compiler's dependency scan describe further cacheable actions without running the compiler during initial analysis.

The callback receives ctx.args, ctx.inputs, ctx.outputs, ctx.build_dir, and ctx.label (id and package). It declares ordinary actions and returns None on success, or one structured diagnostic with code, message, target, attribute, and repairs. Every promised output must be produced by a declared action. Recursive expansion is rejected. The callback runs under the resource budget, and its child actions use normal caching and scheduling.

Initial action queries show the scan and planning barrier, not the expanded commands. Isolated contract validation reports this limitation rather than running prerequisite builds. Execution evidence contains the expanded actions. Targets with deferred actions currently replay planning on warm builds instead of using the whole-target shortcut; their individual actions still reuse cache entries.

content_sha256(text) hashes text without filesystem access. host_tree_sha256(path) hashes an absolute host directory's contents and structure, using metadata-validated cached digests on later invocations. It records the tree as an analysis observation and rejects symbolic links that escape the tree. Entry paths and symlink targets must be valid UTF-8; invalid text is rejected rather than assigned an ambiguous digest. Literal backslashes in Unix names remain literal characters, while Windows directory separators use the portable forward-slash spelling. Together with host_file_sha256(path), these primitives let target kinds include host tools and development kits in action identity. They identify host inputs; they do not make those inputs remotely available.

Executable And Container Providers#

Native binary target kinds can publish the shared once_executable provider. It carries the executable path, runtime files, operating system, architecture, architecture variant, and linkage. Consumers depend on that provider instead of branching on the language that produced the program.

The built-in oci_layer and oci_image target kinds use oci as the abbreviation for Open Container Initiative. An oci_layer packages native executable providers and source files into a deterministic filesystem layer, optionally gzip-compressed with compress and extended with symlinks. It can also pass through an existing uncompressed layer archive during incremental adoption. An oci_image assembles ordered layers, runtime configuration, a content-addressed image layout, and an archive accepted by Docker. Neither needs Docker or any interpreter: the layout is written by ordinary declared actions after the layers exist. Both native images and Dockerfile-backed images publish the shared container_image provider.

An oci_image can extend a base dependency, any container_image provider that exports a layout. The new layers, runtime configuration, and history are appended to the base image's. entrypoint resets an inherited cmd unless cmd is also set, and env, labels, exposed_ports, and volumes merge with the base. tag and tags name the image, one layout entry per name. An oci_index combines single-platform images into one multi-platform index, rejecting two images for the same platform. An oci_pull fetches one image by content digest into a layout, keeping platform (or all), so the result is immutable and cacheable. An oci_import extracts an existing image layout archive (.tar, .tar.gz, .tgz) with tar and exposes it as an image. An oci_load target loads an image archive into a local engine when run, and an oci_push target publishes an image or index when run, keeping its manifest digest. Setting sign on an oci_push signs the pushed digest with cosign. Pull and push use crane and the Docker configuration for credentials; load uses docker or podman.

When a layer contains exactly one executable, the image uses that executable as its default entry point. Explicit entrypoint, cmd, env, user, working_dir, stop_signal, labels, annotations, and exposed ports override or extend the runtime configuration. Layer metadata defaults to zero for the numeric owner, group, and modification time so identical inputs produce identical bytes.

The dockerfile_image target kind defaults to execution_mode = "auto", which translates instructions into separate actions and runs one whole-file BuildKit action when the Dockerfile uses syntax that cannot be translated or an option that needs whole-file execution. The provider records the resolved execution_mode and any fallback_reason, and the lint capability reports a whole_file_execution note naming the reason. Native project discovery creates an image target for each Dockerfile. The Dockerfile's directory supplies its build context. Once uses the selected Buildx builder when it supports image-layout exports. When Docker's built-in builder is the implicit default, Once provisions and reuses a dedicated container builder for the current Docker endpoint without changing the selection. Set BUILDX_BUILDER to select a remote builder, or declare a target to configure a different Dockerfile, context, and caching policy. Starlark translates instruction boundaries and stage references into separate actions. Each action consumes declared context files and prior image snapshots, then produces an Open Container Initiative image layout. BuildKit executes the individual instruction. RUN commands keep their image filesystem, environment, user, working directory, and shell. Stage-scoped arguments and environment values are resolved during analysis, following Docker's scope and inheritance rules, and written into each instruction's definition; an ARG default that depends on the base image's own environment is not translatable. Cross-stage COPY and bind mounts declare their source snapshots as action inputs. Only stages reachable from the selected stage execute, and archive export is a separate action. Intermediate layouts preserve filesystem timestamps between instructions; source_date_epoch fixes the image creation time. BuildKit does not rewrite layers imported from a snapshot, so file timestamps inside the archive reflect when each instruction ran unless reproducible_layers = true, which rewrites each instruction's layer to source_date_epoch as it is exported. Whole-file mode normalizes the final layers.

Instruction mode requires a running Docker engine with Buildx and nothing else. Once provisions a container builder when the selected builder cannot export image layouts. That builder cannot see base images stored only in the local Docker image store. Use whole-file buildkit mode with Docker's built-in builder and pull = false for those images, or publish the base image to a registry and pin its digest.

The images dependency role passes container_image targets to the Dockerfile as named build contexts, so FROM name and COPY --from=name resolve to a content-addressed layout instead of a registry. The programs role passes native executables the same way, as a directory holding the executable under its file name. A context is named after its target; context_names maps a target to another name, including a registry reference such as alpine:3.23, which then replaces that reference wherever the Dockerfile uses it and counts as pinned for cacheable. tag and tags name the archive entries. Builds with a container or remote builder also export a layout that other targets can use.

Instruction execution exposes layout and plan output groups in addition to archive and metadata. The plan records source lines, instruction identities, snapshots, and advisory diagnostics. Metadata queries expose the parsed instructions and diagnostics without contacting Docker. Literal copy sources are tracked individually, together with the destinations of any symbolic links they reach. Wildcards, variable sources, and context bind mounts retain the full context input set conservatively. Empty directories in the context are inputs, so a copied tree keeps them. Generated definitions always exclude Once runtime state from the context.

The lint capability uses the shared lint provider and emits warnings with code, target, attribute, source line, and suggested repairs. Checks cover mutable base references and syntax frontends, copy sources missing from the context, package repositories, downloaded pipelines, and authentication mounts. Findings are advisory, can have false positives, and never change the explicit cacheable decision. Clean results do not prove reproducibility.

Set execution_mode = "buildkit" to delegate the complete recipe to BuildKit as one action. This mode supports heredocs, ONBUILD, # syntax= frontends, a backtick escape directive, multiple declarations in one ARG, and extended argument expressions. It also owns the export_cache, cache_to, and caches dependency contracts described below. With execution_mode = "instructions", unsupported syntax fails with the source line and this setting; auto switches to it instead, and lint and metadata queries never fail on such syntax. Docker and its selected Docker Buildx builder must be reachable when Once analyzes a build so the toolchain identity can include the builder driver and BuildKit version. Metadata and affected-file queries infer context inputs without contacting Docker.

When srcs is empty, Once infers every local file and symbolic link that the build context can expose, including hidden paths. It also adds the Dockerfile and the effective Docker ignore file automatically. Dockerfile-specific ignore files take precedence over the context's ignore file, matching Docker behavior.

Inference recognizes simple literal ignore paths plus **/<name> exclusions and prunes their trees before walking the context. Wildcards, exceptions, and other complex ignore rules remain declared as inputs, then BuildKit applies their complete semantics during the build. This conservative direction can cause extra rebuilds, but it cannot hide a file that the Dockerfile may read. Workspace runtime directories named .once are always excluded so outputs never become their own inputs.

Empty directories do not participate in the inferred input set yet. Declare a placeholder file when a Dockerfile must copy an otherwise empty directory.

Set srcs only when a smaller, manually maintained input set is worth the precision. Once still adds the Dockerfile and effective ignore file. Dockerfile actions use an input-only workspace view, so an explicit set must cover every local context file the build may read.

The rule rejects multiple values in platform; one target describes one exported platform. Selecting network = "host" also grants BuildKit's matching host-network entitlement.

Dockerfile actions are not stored in the Once action cache by default because image tags, package registries, and network instructions may change without a source edit. BuildKit still reuses its own layer cache. Set cacheable = true, pull = false, and an explicit platform with a container or remote builder only when every remote input is immutable, such as base images pinned by digest and network access disabled. Every base image of a built stage must be pinned by digest; analysis fails otherwise. Open Container Initiative export requires a Docker Buildx builder that supports archive export.

When the selected builder supports direct export, both archive formats are written without loading the image into the Docker engine. The built-in Docker driver cannot write an archive directly, so Docker output falls back to loading and saving the requested tag. That compatibility path uses shared engine state, leaves the loaded image behind, and always bypasses the Once action cache. Use a container or remote builder when builds sharing the same tag may run concurrently.

Set export_cache = true to export all intermediate BuildKit layers as a declared layer_cache directory alongside the archive. Once stores and restores that directory with the other outputs when action caching is enabled. Another image target can import it through a caches dependency:

The dependency must enable export_cache. Its cache directory is an explicit input to the consuming action, so it is available in the isolated execution workspace. Once stages the build definition with the effective ignore rules and a final exclusion for runtime directories, so COPY . cannot include imported caches. BuildKit decides which layers match the consuming Dockerfile. Layer exports include intermediate stages, but do not include the mutable contents of Dockerfile RUN --mount=type=cache mounts.

Use cache_from and cache_to lists of registry image references to share layers between independent builders, for example cache_from = ["registry.example.com/service:build-cache"]. Exports use mode=max to retain intermediate stages. Registry publication requires the builder's registry credentials. cache_to cannot be combined with cacheable = true because a Once cache hit would skip publication.

Select an existing remote BuildKit builder with builder to execute Dockerfile instructions remotely. The Buildx client transfers declared context inputs to that worker and returns the archive, metadata, and optional layer cache to Once. Remote builder provisioning, authentication, and worker resource limits are managed outside the target. Once budgets the local client process; it does not control the remote worker's memory budget.

Lint Target Kinds#

A lint target declares the reserved once_lint_info provider and generic lint capability:

Its lint_info record names the analyzer, requested source scope, command, portable report path, normalized result path, native artifacts, logs, and execution policy. The report uses Static Analysis Results Interchange Format. Tool-specific invocation and native configuration remain in the target kind. The Rust execution and result layers stay ecosystem-neutral.

once query module-contract --format json returns a complete lint_starter, matching target and adapter starters, and a normalized result example. See Custom lint target kinds for a complete direct reporter, native report conversion, validation, execution, and cache verification workflow.

Script-backed Test Target Kinds#

once query module-contract --format json returns a complete test_starter for a project-local script-backed test kind, a matching test_target_starter, and a normalized_test_result_example. The starter resolves its host tool, invokes a package-relative adapter directly, declares all inputs and outputs, and passes exact unit filters from ctx["test"]["filters"].

A test target declares the once_test_info provider and the generic test capability:

Its implementation returns test_info with this shape:

The provider may also return test_discovery_inputs, a list of workspace-relative files whose contents can change discovered unit identifiers. Once fingerprints those files before reusing a manifest. When the field is absent, Once conservatively fingerprints the provider's complete affected_inputs list.

The adapter writes JavaScript Object Notation results below the target test directory. When ctx["test"]["batch_id"] is present, the adapter must add batches/<batch_id> to that directory before declaring its result, log, and native-result paths. This prevents concurrent batches of one target from overwriting each other. Once merges the batch records into the target's canonical result after the schedule completes.

Case identifiers are stable target-qualified semantic names. Declare case_filtering = "runner_args" only when every requested identifier is translated exactly into the native runner invocation. For a nonempty exact request, normalized cases must contain exactly the requested IDs, each once, and summary.total must equal the observed case count. Reporting additional cases is not accepted as successful exact filtering. Parameterized cases need distinct discovered IDs; setup diagnostics belong in runner metadata or artifacts, not additional case identities. Otherwise declare unsupported.

Set sharding.supported only when exact filtering and batch-isolated outputs are both implemented. granularity = "file" groups all discovered cases with the same file value into one batch. granularity = "case" creates one batch per stable unit. granularity = "target", an absent manifest, or a stale manifest keeps the whole target as one batch. Batch identity depends on the target and semantic unit identifiers, not the worker count.

A failed or incomplete runner exits unsuccessfully and writes a matching failed result when possible. A successful host process status must never turn a runner crash or missing successful terminal record into a pass. Once validates this complete record before it derives discovery data or marks a scheduled batch as successful. A malformed runner, summary, attempt, or artifact record fails an exact batch instead of being accepted as partial evidence. A successful exact batch also requires a completed execution record, a passing result status, no reported failing cases, and a batch-owned result path. For exact requests, use the shared _test_output_dir(ctx) helper for results and their companion artifacts. It selects <build_dir>/test/batches/<batch_id> when ctx["test"]["batch_id"] is set and <build_dir>/test otherwise. Explicit unit requests require this isolation even when automatic sharding is disabled. A nonzero process exit always fails regardless of existing result files. Whole-target runners may omit normalized results, but they cannot advertise exact execution without them.

A complete-target plan must cover every unit in the current manifest with non-overlapping batches. Explicit unit and batch requests intentionally cover only their requested scope and never replace complete discovery. The adapter owns inventory completeness: declared discovery inputs must include every input that changes test registration, and failed or incomplete collection must not be reported as a successful complete run.

Authoring Target Kinds#

Keep ecosystem behavior within its target kind. A target kind can understand a compiler, package manager, binary format, or platform naming convention while still exposing the same target schema, action, and provider contracts as every other kind.

Provider records are the cross-target kind contract. Prefer small, typed, documented fields such as output paths, transitive inputs, flags, and metadata. Avoid making consumers branch on a dependency target kind.

Use toolchain_identity for tool versions, resolved compiler paths, platform tool selection, generated file contents, and other non-source inputs that should invalidate cached actions. Do not log secrets or place secrets in arguments, provider records, or action metadata.

When adding a public target kind, make it discoverable through once query target-kinds and once query schema, provide at least one starter example, and keep the schema, docs, and examples in sync.