Design question: how should Hybrid hook into an existing go.mod project? (toolexec vs go:generate vs make-step)

[limitlessprojects]

The problem: Hybrid's pitch is add checked .hy files beside your .go files, keep everything else. Today hyb build assembles its own Go workspace (module hybrid.program, the runtime bindings copied in, the staticlib at lib/) — that's fine for a standalone program, but the bar for adoption is tighter, and Discussion #1 stated it well:

"A 10-minute sample repo that works with an existing go.mod, normal go test / go build via wrapper or -toolexec, and no separate project layout. The moment I need a separate module system, a new toolchain culture, or a parallel build process, the pitch dies."

The question: how should hyb integrate with an EXISTING Go module? Three candidate designs — critique them, or propose a fourth:

Design A — go build -toolexec wrapper. hyb becomes a toolchain wrapper: the developer runs ordinary go build ./..., and the tool registers hyb so .hy files are compiled (checked + transpiled to Go) as part of the standard build. Pros: zero new commands, go test/go vet keep working, the Go toolchain drives everything. Cons: -toolexec interposes on the compiler binary, not on arbitrary file types — so it likely requires a go:generate companion for the .hy → .go step anyway; version-fragility of the -toolexec contract is a known Go ecosystem pain.

Design B — go:generate step. //go:generate hyb generate ./... in one Go file; .hy files transpile to checked-in .go files, then the normal build proceeds untouched. Pros: simplest possible machinery, emitted Go is reviewable/diffable (the "delete the .hy file, get plain Go" property is literal), works with every CI system ever. Cons: generated files can go stale if someone edits .hy without regenerating (mitigable: hyb generate --check CI mode); two-step mental model.

Design C — make-step / taskfile convention. The repo root gets one conventional target (make hybrid / hyb sync) that checks .hy files are transpiled and up to date before go build. Pros: explicit, no Go-toolchain tricks, trivially scriptable. Cons: yet another build-system cultural artifact — exactly the "parallel build process" the bar says kills the pitch; Go developers who don't use make are out.

Constraints we hold ourselves to (from the same thread): no separate module system; deleting a .hy file yields plain Go; emitted Go must be plain, readable, and gofmt-clean; go test must cover Hybrid-checked code as ordinary Go tests; the checker must still run fail-closed (an untranspiled/stale .hy must FAIL the build, never silently skip).

Our current leaning: B as the MVP path (deterministic, diffable, boring), with --check mode making staleness a CI error, and A revisited when/if Go grows a first-party hook for non-.go sources. But this is exactly the kind of decision that should be argued about in public before it lands — so: what would make YOU trust the integration? What does your repo's build actually look like, and which of these three survives contact with it?

[limitlessprojects]

Closing the loop: design B landed (the go:generate recipe, chosen per the leaning stated in the opening post; no replies argued otherwise).

What shipped, in examples/gomod-integration/: an ordinary module with a two-line go.mod wiring, one hand-written app.go, a calc.hy that becomes a checked-in gofmt-canonical calc.hy.go, and calc_test.go. Plain go build / go vet / go test / go run all work; ordinary go test covers Hybrid-checked code; hyb generate --check catches drift in CI (semantic edits fail, comment-only edits do not).

The tools: hyb generate [--check] (fail-closed: a rejected .hy never emits; package inferred from sibling .go files) and hyb vendor-runtime <dir> (binding packages + module + the fresh arch-matched staticlib in one command).

If you try the 10-minute recipe against a real module and anything fights you, that is exactly the feedback this thread wants. The README has the section: "existing go.mod project (10 minutes)".