Skip to content

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

Python

Make release task reuse explicitly host-portable

justrach34c85bc12dd0
diff --git a/.github/actions/setup-codegraff-zig/action.yml b/.github/actions/setup-codegraff-zig/action.yml
index 93e4980d..b58c4e4d 100644
--- a/.github/actions/setup-codegraff-zig/action.yml
+++ b/.github/actions/setup-codegraff-zig/action.yml
@@ -40,6 +40,7 @@ runs:
path: |
${{ github.workspace }}/.zig-cache
${{ github.workspace }}/.zig-global-cache
- key: codegraff-zig-build-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.version }}-${{ github.sha }}
+ ${{ github.workspace }}/zig-pkg
+ key: codegraff-zig-build-v2-${{ runner.os }}-${{ runner.arch }}-${{ inputs.version }}-${{ github.sha }}
restore-keys: |
- codegraff-zig-build-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.version }}-
+ codegraff-zig-build-v2-${{ runner.os }}-${{ runner.arch }}-${{ inputs.version }}-
diff --git a/.github/actions/setup-nanocompile-binary/action.yml b/.github/actions/setup-nanocompile-binary/action.yml
index 95c54bb7..9b1e8f84 100644
--- a/.github/actions/setup-nanocompile-binary/action.yml
+++ b/.github/actions/setup-nanocompile-binary/action.yml
@@ -23,7 +23,7 @@ runs:
uses: actions/checkout@v7
with:
repository: justrach/nanocompile
- ref: dec24ac64b2c810cca247f850ed1784830362df5
+ ref: 8b9a74763516919553b71282cdf1d645161e8459
path: .nanocompile-source
persist-credentials: false
diff --git a/.github/actions/setup-nanocompile/action.yml b/.github/actions/setup-nanocompile/action.yml
index 28ed6fba..e1885c1a 100644
--- a/.github/actions/setup-nanocompile/action.yml
+++ b/.github/actions/setup-nanocompile/action.yml
@@ -17,6 +17,6 @@ runs:
uses: actions/cache@v6
with:
path: .nanocompile-cache
- key: nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-dec24ac-${{ github.sha }}
+ key: nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-8b9a747-${{ github.sha }}
restore-keys: |
- nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-dec24ac-
+ nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-8b9a747-
diff --git a/.github/workflows/beta-release.yml b/.github/workflows/beta-release.yml
index 5a21ff3b..c6639456 100644
--- a/.github/workflows/beta-release.yml
+++ b/.github/workflows/beta-release.yml
@@ -60,7 +60,7 @@ jobs:
TARGET: ${{ matrix.target }}
run: |
set -euo pipefail
- python3 scripts/build-release.py --target "$TARGET" --version "$BETA_VERSION" --verify-restore
+ python3 scripts/build-release.py --target "$TARGET" --version "$BETA_VERSION" --verify-restore --portable-host
name="graff-$TARGET"
mkdir "$name"
case "$TARGET" in *-windows) bin=graff.exe ;; *) bin=graff ;; esac
diff --git a/.github/workflows/release-cache-benchmark.yml b/.github/workflows/release-cache-benchmark.yml
index 6fcea1aa..f99b1b91 100644
--- a/.github/workflows/release-cache-benchmark.yml
+++ b/.github/workflows/release-cache-benchmark.yml
@@ -39,7 +39,7 @@ jobs:
run: test "$RESTORED" = true
- name: Cold build
- run: python3 scripts/benchmark-release-cache.py --target '${{ matrix.target }}' --mode '${{ matrix.mode }}' --phase cold
+ run: python3 scripts/benchmark-release-cache.py --target '${{ matrix.target }}' --mode '${{ matrix.mode }}' --phase cold --portable-host
- name: Save measured build caches
uses: actions/cache/save@v6
@@ -47,6 +47,7 @@ jobs:
path: |
.zig-cache
.zig-global-cache
+ zig-pkg
.nanocompile-cache
.benchmark-state
key: release-benchmark-v1-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.mode }}-${{ matrix.target }}
@@ -95,13 +96,14 @@ jobs:
path: |
.zig-cache
.zig-global-cache
+ zig-pkg
.nanocompile-cache
.benchmark-state
key: release-benchmark-v1-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.mode }}-${{ matrix.target }}
fail-on-cache-miss: true
- name: Warm rebuild or declared-task restore
- run: python3 scripts/benchmark-release-cache.py --target '${{ matrix.target }}' --mode '${{ matrix.mode }}' --phase warm
+ run: python3 scripts/benchmark-release-cache.py --target '${{ matrix.target }}' --mode '${{ matrix.mode }}' --phase warm --portable-host
- name: Save timing results
uses: actions/upload-artifact@v7
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3f06bf71..3dd64968 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -60,7 +60,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"
- python3 scripts/build-release.py --target "$TARGET" --version "$VERSION" --telemetry-endpoint "$TELEMETRY_ENDPOINT" --verify-restore
+ python3 scripts/build-release.py --target "$TARGET" --version "$VERSION" --telemetry-endpoint "$TELEMETRY_ENDPOINT" --verify-restore --portable-host
name="graff-$TARGET"
mkdir "$name"
# Windows targets emit graff.exe; every other target emits graff.
diff --git a/docs/adr/0294-release-task-reuse-is-explicitly-host-portable.md b/docs/adr/0294-release-task-reuse-is-explicitly-host-portable.md
new file mode 100644
index 00000000..40656bc8
--- /dev/null
+++ b/docs/adr/0294-release-task-reuse-is-explicitly-host-portable.md
@@ -0,0 +1,46 @@
+# 0294: Release task reuse is explicitly host-portable
+
+## Context
+
+A declared task can miss after its artifacts are restored because compatible
+runners have different native CPUs or kernel versions. Separately, invoking
+`zig build --fetch=all` can compile the native build runner even when the
+complete dependency tree is already available. Neither cost is artifact
+restoration itself.
+
+## Decision
+
+Keep native host identity as nanocompile's default. The release workflows
+explicitly opt their audited Linux x86-64 host tasks into platform identity,
+which retains host OS, architecture and ABI partitions but not native CPU
+features or kernel versions. Commands specify the release target, version,
+optimization, and baseline target CPU. Source files, complete dependency
+contents, compiler/resources, paths, environment and outputs remain keyed.
+
+The release build and pinned dependency build scripts pass the selected target
+to every imported module; the CLI-only release step has no host-derived code
+generator or host-selected system library. A future build change introducing
+native CPU/kernel selection or other host-dependent outputs must remove this
+opt-in or declare and partition those influences before reusing tasks. A fixed
+compiler target alone is not proof of host independence.
+
+After a successful full dependency fetch, save a readiness snapshot containing
+the compiler binary digest, root manifest digest and complete dependency file
+membership/content digests. Reuse it only when the actual snapshot matches.
+Manifest/compiler changes and package edits, additions or removals trigger the
+normal full fetch. Do not use timestamps as proof, and do not fast-path hidden
+directory membership behind symlinks. Cache the package tree with the build
+caches so a fresh runner can validate that snapshot.
+
+The readiness record is only a preparation hint, not authority to reuse a
+binary: nanocompile still freshly hashes every declared source input and
+validates restored artifacts. Native builds and local invocations remain
+native-sensitive unless the caller explicitly opts in.
+
+## Consequences
+
+The release wrapper avoids redundant native preparation without weakening
+general-purpose task caching. Cross-runner reuse remains tied to stable paths,
+tools and environment; it is not relocatable or a claim of build hermeticity.
+Cold builds still pay preparation costs, and direct Zig cache hits can still
+be cheaper than whole-task validation.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 56652dd4..e660513b 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -310,6 +310,7 @@ record only when you need the evidence or the edge cases.
| [0292](0292-sol-subscription-context-is-500k.md) | GPT-6.1 Sol uses a 500k subscription window on Codex and ChatGPT sign-in; smaller catalog windows still win, other models retain their conservative caps, and API maxima do not widen subscription defaults. |
| [0293](0293-ci-reuses-checksum-pinned-tool-binaries.md) | Restore pinned CI executables from optional object storage only after checking a reviewed SHA-256; unavailable artifacts retain the pinned-source fallback. |
+| [0294](0294-release-task-reuse-is-explicitly-host-portable.md) | Only audited fixed-target/baseline-CPU release tasks opt into platform host identity; identical compiler/manifest/package snapshots avoid redundant native fetch preparation. |
## When to write one
diff --git a/scripts/benchmark-release-cache.py b/scripts/benchmark-release-cache.py
index 63797861..7cd3e32b 100644
--- a/scripts/benchmark-release-cache.py
+++ b/scripts/benchmark-release-cache.py
@@ -29,9 +29,11 @@ def main():
parser.add_argument("--target", required=True, choices=release.TARGETS)
parser.add_argument("--mode", required=True, choices=("plain", "nano"))
parser.add_argument("--phase", required=True, choices=("cold", "warm"))
+ parser.add_argument("--portable-host", action="store_true")
args = parser.parse_args()
start = time.perf_counter()
- metrics = {"target": args.target, "mode": args.mode, "phase": args.phase}
+ metrics = {"target": args.target, "mode": args.mode, "phase": args.phase,
+ "host_identity": "platform" if args.portable_host else "native"}
zig = Path(shutil.which("zig")).resolve()
cache = ROOT / ".nanocompile-cache"
env = release.environment(cache)
@@ -39,10 +41,11 @@ def main():
def run(command):
subprocess.run(command, cwd=ROOT, env=env, check=True)
- # Fetch is reported separately, but also included in total invocation time.
- timed(metrics, "fetch_seconds", lambda: run([str(zig), "build", "--fetch=all"]))
+ # Readiness validation is included, even when it avoids the native runner.
+ metrics["dependencies_reused"] = timed(metrics, "fetch_seconds",
+ lambda: release.fetch_dependencies(zig, env))
contract, output = timed(metrics, "contract_seconds", lambda: release.contract(
- args.target, "0.302.43", zig))
+ args.target, "0.302.43", zig, portable_host=args.portable_host))
state_path = ROOT / ".benchmark-state" / (args.mode + "-" + args.target + ".json")
expected = None
if args.phase == "warm":
diff --git a/scripts/build-release.py b/scripts/build-release.py
index 7ecb6ca7..71001bde 100644
--- a/scripts/build-release.py
+++ b/scripts/build-release.py
@@ -4,6 +4,7 @@ import argparse
import hashlib
import json
import os
+import platform
from pathlib import Path
import re
import shutil
@@ -19,12 +20,59 @@ def files(root):
return sorted({str(p.resolve()) for p in root.rglob("*") if p.is_file()})
-def contract(target, version, zig, telemetry=None):
+def file_digest(path):
+ digest = hashlib.sha256()
+ with path.open("rb") as source:
+ while chunk := source.read(1024 * 1024):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def dependency_state(zig):
+ packages = ROOT / "zig-pkg"
+ paths = list(packages.rglob("*"))
+ # Do not claim a complete snapshot when a directory link hides membership.
+ if any(p.is_symlink() and p.is_dir() for p in paths):
+ return None
+ inputs = [ROOT / "build.zig.zon"] + sorted(p for p in paths if p.is_file())
+ return {"schema": 1, "zig_sha256": file_digest(zig),
+ "inputs": {str(p.relative_to(ROOT)): file_digest(p) for p in inputs}}
+
+
+def fetch_dependencies(zig, env):
+ # --fetch=all also compiles Zig's native build runner. A successful fetch's
+ # exact manifest/package snapshot can be reused without launching it again.
+ # This is only a readiness hint: declared tasks still hash all actual inputs.
+ proof = Path(env["ZIG_GLOBAL_CACHE_DIR"]) / "graff-dependencies-v1.json"
+ state = dependency_state(zig)
+ try:
+ if state is not None and json.loads(proof.read_text()) == state:
+ return True
+ except (OSError, ValueError):
+ pass
+ subprocess.run([str(zig), "build", "--fetch=all"], cwd=ROOT, env=env, check=True)
+ state = dependency_state(zig)
+ if state is not None:
+ proof.parent.mkdir(parents=True, exist_ok=True)
+ pending = proof.with_name(proof.name + "." + str(os.getpid()) + ".tmp")
+ try:
+ pending.write_text(json.dumps(state, sort_keys=True) + "\n")
+ pending.replace(proof)
+ finally:
+ pending.unlink(missing_ok=True)
+ return False
+
+
+def contract(target, version, zig, telemetry=None, portable_host=False):
# 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 portable_host:
+ if sys.platform != "linux" or platform.machine().lower() not in ("x86_64", "amd64"):
+ raise ValueError("Portable release tasks require a Linux x86-64 host")
+ command.append("-Dcpu=baseline")
if telemetry is not None:
command.append("-Dtelemetry-endpoint=" + telemetry)
tracked = subprocess.check_output(["git", "ls-files", "-z"], cwd=ROOT).decode().split("\0")
@@ -44,9 +92,11 @@ def contract(target, version, zig, telemetry=None):
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
+ task = {"name": "graff-" + target, "cwd": str(ROOT), "command": command,
+ "inputs": sorted(inputs), "outputs": [str(output)], "tool_resources": sorted(resources)}
+ if portable_host:
+ task["host_identity"] = "platform"
+ return {"schema": 1, "tasks": [task]}, output
def environment(cache):
@@ -64,14 +114,16 @@ def main():
parser.add_argument("--version", required=True)
parser.add_argument("--telemetry-endpoint")
parser.add_argument("--nanocompile", default=os.environ.get("NANOCOMPILE_EXE"))
+ parser.add_argument("--portable-host", action="store_true",
+ help="audit opt-in for baseline-CPU cross-target tasks on Linux x86-64")
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)
+ fetch_dependencies(zig, env)
+ spec, output = contract(args.target, args.version, zig, args.telemetry_endpoint, args.portable_host)
if not args.nanocompile:
if args.verify_restore:
parser.error("--verify-restore requires --nanocompile or NANOCOMPILE_EXE")
diff --git a/scripts/install-nanocompile-ci.py b/scripts/install-nanocompile-ci.py
index d4b67efa..ef039906 100644
--- a/scripts/install-nanocompile-ci.py
+++ b/scripts/install-nanocompile-ci.py
@@ -11,10 +11,10 @@ import urllib.parse
import urllib.request
-REVISION = "dec24ac64b2c810cca247f850ed1784830362df5"
+REVISION = "8b9a74763516919553b71282cdf1d645161e8459"
ZIG_VERSION = "0.17.0"
TARGET = "x86_64-linux-musl"
-SHA256 = "8f7943e71444caf00a5c2563e69f360d6b32ad97f368e829cbb6f7c449e3bf45"
+SHA256 = "f1dd15b05dd4ad3365eee7a47a13c80407f2473693bd02ca13b981b7d20fab26"
ROOT = Path(__file__).resolve().parents[1]