prometeu-studio/discussion/lessons/DSC-0037-pbs-autocomplete-parameter-names/LSN-0052-canonical-callable-parameter-names-through-pbs-editor-assistance.md

id	ticket	title	created	tags
LSN-0052	pbs-autocomplete-parameter-names	Canonical callable parameter names through PBS editor assistance	2026-05-14	compiler-pbs studio lsp autocomplete signature-help stdlib

Context

PBS editor assistance is compiler-backed. Completion, hover, and signature help should therefore expose the same callable shape that the compiler understands, not a parallel UI-only interpretation.

Before this discussion, some callable surfaces could reach editor assistance with synthesized labels such as arg0 and arg1. Those labels made stdlib and method calls harder to use because they erased the public meaning of each argument exactly where the editor is meant to help.

DEC-0036 made callable parameter names normative semantic metadata. PLN-0078, PLN-0079, and PLN-0080 implemented that rule in specs, compiler semantics, and LSP regression coverage.

Key Decisions

Compiler semantics own parameter identity

What: Every user-visible PBS callable must expose a semantic parameter list with canonical name, zero-based order, type when known, and origin/source metadata.

Why: Completion, hover, signature help, diagnostics, and later documentation surfaces need one source of truth for callable shape. If each editor adapter invents labels independently, stdlib and host-backed API names drift from compiler truth.

Trade-offs: This makes stdlib and host-backed parameter names part of public API shape. Renaming them becomes compatibility-sensitive, but that cost is appropriate because these names are visible to users and tooling.

Generated ordinal names stay internal

What: arg0, arg1, and equivalent ordinal placeholders must not appear in user-facing editor or LSP output.

Why: A generated ordinal name is not a public API name. Publishing it trains users and tests to rely on a placeholder that carries no semantic meaning.

Trade-offs: If a callable genuinely lacks a canonical parameter name, the boundary should represent the metadata as incomplete instead of fabricating a plausible-looking name. That can make missing metadata more visible, but it prevents false API contracts.

Patterns and Algorithms

The compiler-side pattern is to keep parameter identity attached to callable symbols, not only to AST declarations used by direct hover paths.

The PBS semantic support model now carries CallableParameter records beside callable input types. This preserves:

• authored parameter name;
• parameter order;
• resolved type view;
• source span as origin metadata.

Editor-facing formatting should then render signatures from those semantic parameters. Direct AST formatting and model-backed callable formatting should produce the same names for user-authored methods, stdlib services, host-backed declarations, and visible builtin/intrinsic method surfaces.

The LSP bridge should stay thin. It should map compiler editorial signatures into baseline completion, hover, and signature-help payloads without inventing names. The LSP4J mapper should preserve labels and parameter lists exactly as received from the baseline protocol model.

Pitfalls

• Do not fix missing parameter names with an editor-side rename table. That creates a second source of callable truth.
• Do not treat stdlib parameter names as incidental implementation details. They are public API surface once completion and signature help expose them.
• Do not use argN as a harmless fallback in tests. A passing test that expects arg0 is a regression against the semantic contract.
• Be careful when testing stdlib signatures that reference imported types. A test for parameter identity should not accidentally become a test for transitive type rendering unless that is the intended scope.

Final Result

The implemented slice updated:

• PBS and compiler specs to define callable parameter identity and argN leak prevention;
• PBS compiler semantic callable symbols to preserve structured parameter metadata;
• PBS editorial formatting to render semantic names instead of synthesized ordinals;
• LSP bridge and mapper tests to prove completion, hover, and signature help preserve semantic names.

The validating commits were:

• 4e00584 implements PLN-0078;
• eab763f implements PLN-0079;
• db8c514 implements PLN-0080.

Takeaways

• Parameter names are structural callable metadata, not documentation prose.
• Editor assistance should consume compiler semantics rather than patching over missing names locally.
• Public stdlib and host-backed parameter renames need compatibility review.
• Missing semantic metadata is better exposed as incomplete than disguised as arg0.