Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Cache release-matrix builds with pinned nanocompile

justrach4f24adf8087d
diff --git a/.github/actions/setup-nanocompile/action.yml b/.github/actions/setup-nanocompile/action.yml
new file mode 100644
index 00000000..2f271435
--- /dev/null
+++ b/.github/actions/setup-nanocompile/action.yml
@@ -0,0 +1,29 @@
+name: Setup nanocompile release cache
+description: Build a pinned nanocompile and restore the target's declared-task cache
+inputs:
+ target:
+ description: Release-matrix target
+ required: true
+runs:
+ using: composite
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ repository: justrach/nanocompile
+ ref: dec24ac64b2c810cca247f850ed1784830362df5
+ path: .nanocompile-source
+ persist-credentials: false
+ - name: Build pinned nanocompile
+ shell: bash
+ working-directory: .nanocompile-source
+ run: |
+ zig build -Doptimize=ReleaseFast --prefix "$GITHUB_WORKSPACE/.nanocompile-tools"
+ echo "NANOCOMPILE_EXE=$GITHUB_WORKSPACE/.nanocompile-tools/bin/nanocompile" >> "$GITHUB_ENV"
+ echo "NANOCOMPILE_DIR=$GITHUB_WORKSPACE/.nanocompile-cache" >> "$GITHUB_ENV"
+ - name: Restore nanocompile task artifacts
+ uses: actions/cache@v6
+ with:
+ path: .nanocompile-cache
+ key: nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-dec24ac-${{ github.sha }}
+ restore-keys: |
+ nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-dec24ac-
diff --git a/.github/workflows/beta-release.yml b/.github/workflows/beta-release.yml
index 804d14c3..49462b9a 100644
--- a/.github/workflows/beta-release.yml
+++ b/.github/workflows/beta-release.yml
@@ -50,17 +50,20 @@ jobs:
steps:
- uses: actions/checkout@v7
- uses: ./.github/actions/setup-codegraff-zig
+ - uses: ./.github/actions/setup-nanocompile
+ with:
+ target: ${{ matrix.target }}
- name: Cross-compile beta CLI (${{ matrix.target }})
env:
BETA_VERSION: ${{ needs.plan.outputs.version }}
TARGET: ${{ matrix.target }}
run: |
set -euo pipefail
- zig build graff -Doptimize=ReleaseFast -Dtarget="$TARGET" -Dversion="$BETA_VERSION"
+ python3 scripts/build-release.py --target "$TARGET" --version "$BETA_VERSION" --verify-restore
name="graff-$TARGET"
mkdir "$name"
case "$TARGET" in *-windows) bin=graff.exe ;; *) bin=graff ;; esac
- cp "zig-out/bin/$bin" "$name/$bin"
+ cp "zig-out/$TARGET/bin/$bin" "$name/$bin"
cp README.md LICENSE "$name/"
tar -czf "$name.tar.gz" "$name"
- uses: actions/upload-artifact@v7
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7d494c53..fbc00713 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -46,6 +46,10 @@ jobs:
- name: Install Zig
uses: ./.github/actions/setup-codegraff-zig
+ - uses: ./.github/actions/setup-nanocompile
+ with:
+ target: ${{ matrix.target }}
+
- name: Cross-compile (${{ matrix.target }})
env:
TARGET: ${{ matrix.target }}
@@ -55,7 +59,7 @@ jobs:
# Release builds phone usage/evolution telemetry here by default
# (anonymous, opt out with --no-telemetry / GRAFF_NO_TELEMETRY).
TELEMETRY_ENDPOINT="https://harness-telemetry.rachpradhan.workers.dev"
- zig build graff -Doptimize=ReleaseFast -Dtarget="$TARGET" -Dversion="$VERSION" -Dtelemetry-endpoint="$TELEMETRY_ENDPOINT"
+ python3 scripts/build-release.py --target "$TARGET" --version "$VERSION" --telemetry-endpoint "$TELEMETRY_ENDPOINT" --verify-restore
name="graff-$TARGET"
mkdir "$name"
# Windows targets emit graff.exe; every other target emits graff.
@@ -63,7 +67,7 @@ jobs:
*-windows) bin=graff.exe ;;
*) bin=graff ;;
esac
- cp "zig-out/bin/$bin" "$name/$bin"
+ cp "zig-out/$TARGET/bin/$bin" "$name/$bin"
cp README.md LICENSE "$name/"
tar -czf "$name.tar.gz" "$name"
diff --git a/.gitignore b/.gitignore
index 7cc08993..209fbb1c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
# build output
.zig-cache/
+.zig-global-cache/
zig-out/
zig-pkg/
target/
@@ -16,6 +17,11 @@ harness.trajectory.jsonl
.simple-harness-keys.json
.simple-harness-codegraff.json
+# release task-cache checkout, tool and artifact stores
+.nanocompile-source/
+.nanocompile-tools/
+.nanocompile-cache/
+
# tooling artifacts
.zigrep_archive
codedb.snapshot
diff --git a/docs/adr/0291-release-builds-use-declared-task-caching.md b/docs/adr/0291-release-builds-use-declared-task-caching.md
new file mode 100644
index 00000000..0703128a
--- /dev/null
+++ b/docs/adr/0291-release-builds-use-declared-task-caching.md
@@ -0,0 +1,32 @@
+# 0291: Release builds use declared-task caching
+
+## Context
+
+The release and beta workflows build six CLI targets on Linux runners. A plain
+`nanocompile zig build` transparently delegates to Zig; it does not cache the
+nested compiler commands. Calling that a cached matrix would be misleading.
+Nanocompile already supports explicit, ordered whole-task contracts, including
+artifacts for targets its direct compiler cache conservatively bypasses.
+
+## Decision
+
+Pin the published nanocompile source revision and build it with the same pinned
+Zig as the CLI. Run each matrix build as one declared task. Include tracked
+repository files, the fetched dependency tree, the compiler/library resources,
+and the selected SDK when running locally on macOS. Pass the target, version,
+and telemetry choice explicitly. Give each target its own output prefix.
+
+Use a small fixed child environment instead of forwarding CI tokens, run IDs,
+and unrelated shell variables. Nanocompile still keys every retained value.
+Restore its artifact store with a target-specific Actions cache. Before
+packaging, remove the generated binary and require a byte-identical restoration
+and a recorded task hit. Signing and publishing remain outside the cache.
+
+## Consequences
+
+This is conservative whole-build reuse, not finer-grained compiler caching or a
+measured speed improvement. A new version or changed input may miss. Inputs
+are rehashed and artifact bytes are checked by nanocompile; the existing tests,
+six-target matrix, signing, and release freshness checks remain required.
+The source pin changes only after verification, not automatically with upstream
+`main`. New build-time resources must join the explicit contract.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index ba9be0f8..fdfc85ee 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -305,6 +305,7 @@ record only when you need the evidence or the edge cases.
| [0288](0288-anthropic-native-login-is-source-aware.md) | Native subscription PKCE login is shared across CLI, REPL and ACP; subscription wire compatibility stays credential-source-aware. |
| [0289](0289-mcp-results-preserve-typed-and-display-content.md) | Preserve typed MCP results independently of display content, show resource references without fetching them and answer pings during shared waits. |
| [0290](0290-mcp-task-replies-outlive-child-deadlines.md) | HTTP task calls wait for validated child and required preprocessing budgets plus reply cleanup; other requests keep their deadlines. |
+| [0291](0291-release-builds-use-declared-task-caching.md) | Pin nanocompile and cache complete release build tasks with explicit inputs, tool resources, and a verified byte-identical restore before packaging. |
## When to write one
diff --git a/scripts/build-release.py b/scripts/build-release.py
new file mode 100644
index 00000000..7ecb6ca7
--- /dev/null
+++ b/scripts/build-release.py
@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Build one release-matrix target through nanocompile's declared-task cache."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+
+TARGETS = ("aarch64-macos", "x86_64-macos", "x86_64-linux", "aarch64-linux",
+ "x86_64-windows", "aarch64-windows")
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def files(root):
+ return sorted({str(p.resolve()) for p in root.rglob("*") if p.is_file()})
+
+
+def contract(target, version, zig, telemetry=None):
+ # A fixed version avoids an undeclared dependency on git describe / .git.
+ output = ROOT / "zig-out" / target / "bin" / ("graff.exe" if target.endswith("windows") else "graff")
+ command = [str(zig), "build", "graff", "-Doptimize=ReleaseFast",
+ "-Dtarget=" + target, "-Dversion=" + version,
+ "--prefix", str(ROOT / "zig-out" / target)]
+ if telemetry is not None:
+ command.append("-Dtelemetry-endpoint=" + telemetry)
+ tracked = subprocess.check_output(["git", "ls-files", "-z"], cwd=ROOT).decode().split("\0")
+ inputs = {str(ROOT / p) for p in tracked if p and (ROOT / p).is_file()}
+ inputs.add(str(Path(__file__).resolve()))
+ # Zig 0.17 fetches its pinned package tree here. Include content, not just
+ # the dependency lock: local package edits must invalidate a task restore.
+ inputs.update(files(ROOT / "zig-pkg"))
+ description = subprocess.check_output([str(zig), "env"], text=True)
+ match = re.search(r'\.lib_dir = "([^"]+)"', description)
+ if not match:
+ raise RuntimeError("Cannot identify the selected Zig library tree")
+ resources = {str(zig)}
+ resources.update(files(Path(match.group(1))))
+ # On macOS the selected SDK is another installed tool resource. Linux
+ # matrix runners cross-link using Zig's bundled libraries instead.
+ if sys.platform == "darwin":
+ sdk = subprocess.check_output(["xcrun", "--show-sdk-path"], text=True).strip()
+ resources.update(files(Path(sdk)))
+ return {"schema": 1, "tasks": [{"name": "graff-" + target, "cwd": str(ROOT),
+ "command": command, "inputs": sorted(inputs), "outputs": [str(output)],
+ "tool_resources": sorted(resources)}]}, output
+
+
+def environment(cache):
+ # Run IDs, CI tokens and incidental shell variables must neither reach the
+ # compiler nor perturb its key. Every retained value is still keyed by Nano.
+ return {"PATH": os.defpath, "HOME": str(Path.home()), "LANG": "C", "LC_ALL": "C",
+ "TZ": "UTC", "NANOCOMPILE_DIR": str(cache),
+ "ZIG_GLOBAL_CACHE_DIR": str(ROOT / ".zig-global-cache"),
+ "ZIG_LOCAL_PKG_DIR": str(ROOT / "zig-pkg")}
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--target", required=True, choices=TARGETS)
+ parser.add_argument("--version", required=True)
+ parser.add_argument("--telemetry-endpoint")
+ parser.add_argument("--nanocompile", default=os.environ.get("NANOCOMPILE_EXE"))
+ parser.add_argument("--verify-restore", action="store_true",
+ help="remove the built output and prove a byte-identical cache hit")
+ args = parser.parse_args()
+ zig = Path(shutil.which("zig") or "zig").resolve()
+ cache = Path(os.environ.get("NANOCOMPILE_DIR", ROOT / ".nanocompile-cache")).resolve()
+ env = environment(cache)
+ subprocess.run([str(zig), "build", "--fetch=all"], cwd=ROOT, env=env, check=True)
+ spec, output = contract(args.target, args.version, zig, args.telemetry_endpoint)
+ if not args.nanocompile:
+ if args.verify_restore:
+ parser.error("--verify-restore requires --nanocompile or NANOCOMPILE_EXE")
+ return subprocess.call(spec["tasks"][0]["command"], cwd=ROOT, env=env)
+ binary = str(Path(args.nanocompile).resolve())
+ spec_path = ROOT / ".zig-cache" / ("nanocompile-" + args.target + ".json")
+ spec_path.parent.mkdir(parents=True, exist_ok=True)
+ spec_path.write_text(json.dumps(spec, sort_keys=True) + "\n")
+ command = [binary, "task", str(spec_path)]
+ subprocess.run(command, cwd=ROOT, env=env, check=True)
+ if args.verify_restore:
+ digest = hashlib.sha256(output.read_bytes()).hexdigest()
+ events = cache / "events"
+ offset = events.stat().st_size if events.exists() else 0
+ output.unlink()
+ subprocess.run(command, cwd=ROOT, env=env, check=True)
+ with events.open("rb") as source:
+ source.seek(offset)
+ if b"task_hit\n" not in source.read():
+ raise RuntimeError("nanocompile did not report a task cache hit")
+ if hashlib.sha256(output.read_bytes()).hexdigest() != digest:
+ raise RuntimeError("nanocompile restored different artifact bytes")
+ print("Verified byte-identical nanocompile restore:", args.target)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/src/main.zig b/src/main.zig
index 3494cabe..a4f4c0db 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -560,7 +560,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("beta_feed.zig"), @import("jev_tool.zig"), @import("jev_model_scope.zig"), @import("jev_provider_switch_tests.zig"), @import("jev_effort_state.zig"), @import("gemini_turns.zig"), @import("gemini_turns_tests.zig") };
_ = .{ @import("mcp_apps.zig"), @import("html_view.zig"), @import("usage_trace.zig"), @import("providers_confirmation_tests.zig"), @import("repl_model_confirmation_tests.zig"), @import("repl_model_pick_tests.zig"), @import("engine_sink_citation_tests.zig"), @import("cite_markup_stream_tests.zig"), @import("oneshot_citation_tests.zig"), @import("acp_permission.zig"), @import("acp_usage.zig") };
_ = .{ @import("mcp_server_tests.zig"), @import("main_test.zig"), @import("artifact_claim_command.zig"), @import("cli_path_hint.zig"), @import("run_budget.zig") };
- _ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };
+ _ = .{ @import("session_catalog.zig"), @import("session_size_tests.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };
_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig"), @import("oauth_chatgpt.zig"), @import("chatgpt_reauth.zig"), @import("oauth_anthropic.zig"), @import("anthropic_oauth_wire.zig"), @import("anthropic_login_tests.zig") };
_ = .{ @import("agent_empty_completion.zig"), @import("agent_length_cutoff.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig"), @import("headless_result.zig"), @import("oneshot.zig"), @import("agent_length.zig"), @import("agent_length_tests.zig") };
_ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("path_lookup.zig"), @import("agents_prepare.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };