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.ymlindex 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.ymlindex 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@v7with:repository: justrach/nanocompile- ref: dec24ac64b2c810cca247f850ed1784830362df5+ ref: 8b9a74763516919553b71282cdf1d645161e8459path: .nanocompile-sourcepersist-credentials: falsediff --git a/.github/actions/setup-nanocompile/action.yml b/.github/actions/setup-nanocompile/action.ymlindex 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@v6with: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.ymlindex 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-hostname="graff-$TARGET"mkdir "$name"case "$TARGET" in *-windows) bin=graff.exe ;; *) bin=graff ;; esacdiff --git a/.github/workflows/release-cache-benchmark.yml b/.github/workflows/release-cache-benchmark.ymlindex 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 cachesuses: actions/cache/save@v6@@ -47,6 +47,7 @@ jobs:path: |.zig-cache.zig-global-cache+ zig-pkg.nanocompile-cache.benchmark-statekey: 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-statekey: 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 resultsuses: actions/upload-artifact@v7diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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-hostname="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.mdnew file mode 100644index 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.mdindex 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 onediff --git a/scripts/benchmark-release-cache.py b/scripts/benchmark-release-cache.pyindex 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 = Noneif args.phase == "warm":diff --git a/scripts/build-release.py b/scripts/build-release.pyindex 7ecb6ca7..71001bde 100644--- a/scripts/build-release.py+++ b/scripts/build-release.py@@ -4,6 +4,7 @@ import argparseimport hashlibimport jsonimport os+import platformfrom pathlib import Pathimport reimport 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]}, outputdef 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.pyindex d4b67efa..ef039906 100644--- a/scripts/install-nanocompile-ci.py+++ b/scripts/install-nanocompile-ci.py@@ -11,10 +11,10 @@ import urllib.parseimport 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]