feat(hooks): before-generate env reaches the assembler's generate

[apotema]

Part of labelle-web#24 (the threaded web build). Design: labelle-toolkit/labelle-web#24 (comment). The owner chose this option in the session.

Problem

A provider's env_file contribution (contract §2) reaches the fingerprint pass, the compile and every later hook, but not the labelle-assembler generate process. So a before generate hook can change how the generated tree compiles, but not what gets generated.

labelle-web needs exactly that: its config's "threads": true must turn on LABELLE_WASM_THREADS for the assembler (labelle-assembler#818), so users don't have to set an env var themselves. build_options (1.6) doesn't help, because they're -D flags on the compile, after generation.

Change

• assembler_proc.generate takes the build's accumulated hook environment and runs the assembler with it composed on top of ours. This covers normal builds (pipeline/generate.zig) and watched rebuilds (pipeline/rebuild.zig).
• With nothing contributed, the assembler inherits our environment exactly as before. Every project without a contributing hook is unaffected.
• Docs: provider-contract-v1.md §2 Scope and provider-hooks.md now list the core generation first among the environment's consumers.
• Not a wire change: the context is unchanged, and the env_file format is unchanged.

Tests

zig build test: 13/13 steps, 1163 passed (2 skipped), including the agnosticism guard. New GenerateEnvSpec:

• a contributed variable reaches the assembler's environment, and the base is kept
• no contribution, or an empty one, means inherit unchanged (null)

The end-to-end check (labelle-web's hook switching on a threaded build) comes with the labelle-web PR.

https://claude.ai/code/session_01LpszrcSrLLijQcxxvgWyUQ

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-01T23:09:43.357217Z	4f18dc0	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 261fb2f1-9c9d-46a7-84b1-a25ef9b31eb7

📥 Commits

Reviewing files that changed from the base of the PR and between a3fa0be and 4f18dc0.

📒 Files selected for processing (6)

• docs/provider-contract-v1.md
• docs/provider-hooks.md
• src/cli/assembler_proc.zig
• src/cli/pipeline/generate.zig
• src/cli/pipeline/rebuild.zig
• src/cli/provider_hooks.zig

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

---

📝 Walkthrough

Walkthrough

Provider-hook environment contributions now reach core assembler generation in normal and watched rebuild pipelines. The assembler composes nonempty contributions over the CLI environment. Documentation describes the generation step and retains exclusions for provider-tool builds and the core-launched game.

Changes

Assembler generation environment

Layer / File(s)	Summary
Compose and pass the environment src/cli/assembler_proc.zig	Assembler execution accepts an optional environment map. Generation composes nonempty provider contributions over the CLI environment and passes the result to the child process. Tests cover contributed variables and absent or empty contributions.
Wire hook environments into generation src/cli/pipeline/generate.zig, src/cli/pipeline/rebuild.zig, src/cli/provider_hooks.zig, docs/provider-contract-v1.md, docs/provider-hooks.md	The normal and watched rebuild pipelines pass their hook environments to assembler generation. The provider-hook documentation includes assembler generation among the steps that receive contributions.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Hooks as before-generate hooks
  participant Pipeline as generate pipeline
  participant Generate as assembler_proc.generate
  participant Run as Assembler.runWithEnv
  participant Assembler as labelle-assembler
  Hooks->>Pipeline: contribute environment
  Pipeline->>Generate: pass hook_site.env
  Generate->>Run: pass composed environment
  Run->>Assembler: spawn with optional environment

Loading

Suggested reviewers: danielmurta

Merge Risk: ⚪ Minimal · up to 4f18d

The reviewed changes preserve the CLI environment while applying hook contributions to assembler generation in normal and watched builds. No material merge risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: environment contributions from before-generate hooks now reach the assembler generate process.
Description check	✅ Passed	The description directly explains the problem, implementation, affected build paths, compatibility behavior, documentation updates, and test coverage.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}