Add user-defined iterator protocol

[itsfuad]

Goal

Add simple structural custom iteration while preserving built-in range, array, and slice loops.

Contract

• Accessible Next() method with exactly receiver and no extra/defaulted parameters.
• Return ?Item; outer none ends loop and a present result binds one Item.
• One custom item binding: for item in source. Built-in index, value behavior stays unchanged.
• Concrete static dispatch only. No Iterator interface, generic constraint, boxing, automatic erasure, iterator vtable, free-function fallback, or tuple prerequisite.
• Source evaluates once. continue attempts one next call; break and return do not advance again.
• Canonical call, optional-flow, CFG/effects, ownership, provenance, and cleanup guards remain authoritative.

Implementation status

For-side implementation complete, approved, committed, and pushed on feature/structural-iterators. Awaiting PR/merge lifecycle.

Commits:

• d614336 Add static iteration over local struct cursors
• e088415 Support temporary struct iterator sources
• 6c4e39d Generalize structural iterator sources and items

Final behavior:

• Removed concrete-struct, source-syntax, and scalar-item whitelists.
• Existing places retain storage identity; produced values use loop-scoped ordinary bindings.
• Dynamic indexed places capture one shared or mutable reference according to receiver shape, so index expressions evaluate once and body mutation cannot retarget traversal.
• Aggregate, owned-pointer, nested-optional, and legal reference items use ordinary binding, move, provenance, and cleanup machinery.
• Exact semantic payload-depth evidence removes one outer optional layer without flattening optional Item.
• Checked expansion remains visible before CFG, flow, effects, definite-init, ownership, HIR, and MIR. Lowering performs no method rediscovery or hidden iterator operation.
• Obsolete staged-limit diagnostics removed; protocol errors remain source-facing and actionable.
• Language specification and LSP item hover coverage added.

Coverage

• Differential implicit/explicit checks for field, dynamic-index, reference-parameter sources and aggregate, owner, nested-optional, and reference items.
• Existing differential ownership checks cover receiver borrowing, consumption, moves, body access, and conflicting borrows.
• Runtime fixture covers source evaluation/identity and generalized item behavior.
• Existing factory lifecycle tests cover empty loops, continue, break, return, nested exits, temporary cleanup, and local resume.
• Negative fixtures retain signature, binding-shape, mutability, interface-erasure, move, and ordinary-guard failures.

Validation

• Focused typechecker, ownership, effect, definite-init, CFG, HIR, MIR, and LSP tests passed.
• go test ./... passed.
• go run ./scripts/bundle.go passed.
• Full bundled fixture suite passed: PEEPER_BIN=/home/itsfuad/Dev/Peeper/compiler/build/bin/peeper go test -count=1 ./x_test.
• gofmt and git diff --check passed.

Separate central-language boundaries

Cross-module method discovery and broader reference-storage/provenance capabilities belong to ordinary method lookup and ownership systems. Future improvements there flow through this checked expansion; no iterator-specific workaround is planned.

[itsfuad]

Architecture planning update (no implementation): traced canonical method calls, optional extraction, CFG/effects, ownership and HIR/MIR. Proposed topology is once-only source initialization -> header checked advancement/result binding -> optional presence branch -> payload binding/body -> latch back to header. Generated operations must have indexed nodes/scopes and real CFG analysis sites before ownership; current loop segments lack those sites. HIR/MIR must consume the same operations without double execution. Reuse existing call adaptation, payload proofs, return origins and cleanup. Include nested optional items in coverage.

Item-only custom binding is working default pending final review; builtin index,value unchanged.

New design question: lowercase next is private under current uppercase export convention, and declared method lookup searches current module method table. Cross-module method visibility must be resolved centrally. Exported Next is a recommendation for review, not yet an approved spelling change. No private-method visibility bypass for iteration.

[itsfuad]

Implementation started on feature/structural-iterators. First slice: local concrete cursors, scalar items, one binding, exported Next() -> ?Item, static calls through central guards. No runtime interface iteration. Generated checked operations will enter CFG/flow/effects/ownership before lowering. Temporary sources, resource-bearing payloads and cross-module method availability remain follow-up scope; no implementation validation claimed yet.

[itsfuad]

Review refinement: user-facing iterator errors now describe source-level problems and actionable remedies instead of structural/concrete-cursor/scalar terminology. Added Next declaration/return-type labels, optional item/none guidance, argument/default explanations, index advice, local-variable workaround, explicit-loop alternative for unsupported item types, and interface-specific guidance. Recognition and ownership behavior unchanged. Diagnostic tests and negative fixture assert hints and exclude internal wording/hidden names. Validation passed: full Go suite, refreshed bundle, full bundled x_test suite, gofmt and git diff --check. Still uncommitted; first slice remains under user review.