Document the two-pass wired-graph codegen design (func! quotation) - #596
Merged
Conversation
Records the design decision for generating compiled-graph code by running the wiring and traversing the wired graph, with a second compilation pass: - why naive post-wiring traversal fails (erasure; closure types neither nameable nor inferable in generated code) and how the deleted classic wingfoil::codegen retrofit already proved those walls; - the func! quotation primitive that makes the route sound for a defined subset (closed / explicit-capture closures, EmitLiteral configs), with drift between the running value and the emitted text impossible by construction; - capture rules (fn-pointer coercion tier, serde_closure-style explicit captures, the freezing-vs-runtime-params fork); - regular closures stay first-class via an OpFn unification trait; graph! never needs func! and remains the single emission backend (the generator's artifact is a plain wiring fn wrapped in graph!); - what the design reuses from the Op-pattern rearchitecture, the three-condition gate for building the generator (dynamic topology, hot graph, config cadence <= deploy cadence), and the sequencing plan. Cross-links macro-extensibility-decision.md section 2, whose "No" now stands for the unassisted form only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SunAG7Q5ErqhaZBVtK5qv8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
next/docs/wired-graph-codegen-decision.md, recording the design decision for generating compiled-graph code by running the wiring and traversing the wired graph, with a second compilation pass — and cross-linksmacro-extensibility-decision.md§2, whose flat "No" to this question now stands for the unassisted form only.Docs-only; no code changes. Status recorded in the doc: accepted direction, not yet implemented — the build is gated on the sequencing plan (§8) and a named workload (§7).
The design in one paragraph
Naive post-wiring traversal fails on one precise point: closures are runtime values whose types are neither nameable nor inferable in generated code (the deleted classic
wingfoil::codegenretrofit proved the walls). Afunc!quotation macro at the closure call site fixes both blockers — it preserves the closure's tokens for splicing (so the emitted literal roots type inference exactly asgraph!does), and makes drift between the running value and the emitted text impossible by construction (same tokens play both roles). With capture rules (closed closures via fn-pointer coercion, or serde_closure-style explicit capture lists bounded byEmitLiteral), a generator can run dynamic wiring once and emit a plain wiring fn wrapped ingraph!— sograph!stays the single emission backend, regular closures stay first-class (anOpFnunification trait;graph!itself never needsfunc!), and the route buys the one thing the macro structurally cannot express: dynamic topology at compiled speed.Why write it down now
The reasoning chain (why traversal fails, why quotation fixes it, the capture-freezing fork, the graph!-as-backend decision, what the design reuses from the Op-pattern rearchitecture) is expensive to reconstruct later. The doc also fixes the gate for building anything: a workload where topology comes from data, the graph is hot, and config cadence ≤ deploy cadence.
🤖 Generated with Claude Code
https://claude.ai/code/session_01SunAG7Q5ErqhaZBVtK5qv8
Generated by Claude Code