[jpereyra243-byte]

Summary

This PR models the curated foreign method surface for Go standard library flag.FlagSet (fixes #4251, Row 13 BUILDABLE).

Root Cause & Defect

Previously, foreign_method_surface in compiler/crates/hy-check/src/foreign.rs curated standard library types (such as sync.Mutex, http.ResponseWriter, http.RoundTripper, os.File, net.Addr), but omitted flag.FlagSet. Invocations of nonexistent / phantom methods on flag.FlagSet or *flag.FlagSet values (e.g. fs.totally_fake_flag_method()) passed hyb check with 0 diagnostics, causing downstream go build to fail with fatal errors (type *flag.FlagSet has no field or method ...), violating GUARANTEES.md Row 13.

Changes

1. Curated Method Surface: Added FLAG_FLAG_SET with Go's canonical flag.FlagSet methods (parse, args, n_arg, set, etc.).
2. Type Mapping: Added "flag.flag_set" | "flag.flagset" | "flag.FlagSet" => Some(FLAG_FLAG_SET) and added "flag" to is_curated_package_root.
3. Regression Tests: Added test suite compiler/crates/hy-check/tests/foreign_flag_flagset_method_surface.rs verifying:
   • Phantom method invocations on flag.flag_set reject fail-closed with HYB-E1002.
   • Phantom method invocations on pointer receivers *flag.flag_set reject with HYB-E1002.
   • Canonical Go flag.FlagSet methods (parse, args, n_arg, name, parsed) accept cleanly with 0 diagnostics.

Settlement Coordinates: EVM (Base / Polygon) USDC: 0xC175c34c256598C7e1AD5B15503cFcED7Ed67e10

[limitlessprojects]

Automated review — gate FAIL (one observable surface gap: bool_func) — one-line fix, re-push lands fast

Mechanism review: correct, and verified. The annotation-driven approach works: hy does not enforce import-to-use on foreign type annotations, so fs flag.flag_set parameters resolve via your is_curated_package_root("flag") addition (probe-confirmed). Lowercased + flag.flagset/flag.FlagSet aliases match the house pattern (#4198), pointer-receiver normalization works, and the suite is green 3/3 on a trial-merged tree (clean auto-merge, additive +85 vs current main 5a93dff0).

But the surface is incomplete against the authoritative go1.26.9 method set, and the gap is observable — landing would introduce a false reject of a valid Go program:

Evidence (go doc flag.FlagSet, go1.26.9 toolchain):

• func (f *FlagSet) BoolFunc(name, usage string, fn func(string) error) exists — your FLAG_FLAG_SET omits bool_func.
• Probe on the trial-merged tree:

  fn handle(fs flag.flag_set) { fs.bool_func("v", "verbose", nil) }
  → error[HYB-E1002]: `flag.flag_set` has no method `bool_func`
    = its methods are `arg, args, bool, bool_var, ..., visit, visit_all`
  

  A program that builds cleanly under go build is rejected — the mirror violation of Row 13.
• The other two omissions are fine and unobservable: func and var are reserved keywords in hy (lexer.rs:74 KEYWORDS), so fs.func() / fs.var() cannot appear in source at all (same class as fix(hy-check): foreign packages url and sort call arity bypass and non-callable member rejection (Row 13 BUILDABLE) #4201 round 2's sort.interface()). And Print/Printf/Println/SetInterspersed do not exist on FlagSet in go1.26.9 — correctly omitted.

Fix: add "bool_func" to FLAG_FLAG_SET — one line. Re-push and this lands fast: the merge is conflict-free, the suite mechanism is proven on this exact tree, and the remaining battery is short.

fixes #4251 stays open until the surface lands. Bounty rail per BOUNTY.md / discussion #295.

[jpereyra243-byte]

Added bool_func to FLAG_FLAG_SET and updated the regression suite to assert fs.bool_func("v", "verbose", nil) accepts cleanly. Re-pushed to fix-foreign-flag-flagset-method-surface (1363bf32). Ready for landing.

[limitlessprojects]

Landed — merge 79b5f68c, remote-asserted (full battery ALL-GREEN, review round 2)

Thank you @jpereyra243-byte — the round-2 fix is exactly the prescribed one-liner: "bool_func" added to FLAG_FLAG_SET (correct alphabetical position), the accept-control extended with _ = fs.bool_func("v", "verbose", nil), and the doc comment updated. Clean completion of the arc: #4198 ✅ → #4249 ✅ → #4252 ✅.

Round-1 defect verification, resolved:

• Probe on the merged tree: fn handle(fs flag.flag_set) { fs.bool_func("v", "verbose", nil) } → OK (0 diagnostics) — the round-1 false reject is gone.
• Fail-closed intact: fs.totally_fake_flag_method() → HYB-E1002 (surface note now lists all 35 methods including bool_func).
• Surface now complete against go1.26.9 go doc flag.FlagSet for every representable method (func/var omissions remain unobservable — reserved keywords).

In-merge disclosure: your branch point predates #4249's landing of the sibling context.Context surface, so three disjoint foreign.rs hunks conflicted at identical anchors. Resolved by scripted union (S160 procedure): both sides kept — CONTEXT_CONTEXT + FLAG_FLAG_SET consts, both dispatch arms, both is_curated_package_root entries. Presence + balance assertions green; the context suite (4 tests) and flag suite (3 tests) pass together on the union tree.

Verification evidence (run on the merged tree):

Gate	Result
Merge gate	3-hunk union splice, assertions green (disclosure above)
cargo test --workspace	3225 passed / 0 failed (+3 = your suite's test count exactly); 492 suites = 492 Running lines (1:1)
corpus harness	139/139, tripwire not fired (verdict-level 2/139, threshold ~25%)
differential loop	FULL AGREEMENT — accept 47/47 + reject 92/92

Protocol followed: merge --no-ff with hand-written credit commit (verification evidence + in-merge disclosure + CREDIT: @jpereyra243-byte), pushed, git ls-remote origin main == local HEAD asserted. fixes #4251 closes with this merge.

Bounty: per BOUNTY.md / discussion #295 rail — curated foreign method surface (flag.FlagSet), logged under this PR number.

CREDIT: @jpereyra243-byte

[jpereyra243-byte]

Payout wallet (USDC on Base / Polygon): 0xC175c34c256598C7e1AD5B15503cFcED7Ed67e10