---
id: LSN-0052
ticket: pbs-autocomplete-parameter-names
title: Canonical callable parameter names through PBS editor assistance
created: 2026-05-14
tags: [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`.