prometeu-studio/discussion/workflow/decisions/DEC-0036-canonical-parameter-names-in-the-pbs-callable-semantic-model.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0036	pbs-autocomplete-parameter-names	Canonical parameter names in the PBS callable semantic model	accepted	2026-05-08	AGD-0040	compiler-pbs studio lsp autocomplete signature-help stdlib

Context

PBS editor assistance is becoming compiler-backed through completion, hover, and signature help.

The current call assistance can expose callable parameters as generated names such as arg0, arg1, and arg2, especially for stdlib and host-backed APIs. That output is not useful at the call site because it hides the meaning of each argument at the moment autocomplete and signature help are supposed to reduce lookup cost.

This decision follows AGD-0040. The agenda resolved four blocking questions:

• canonical parameter names should be offered through the compiler semantic model;
• arg0 and similar fallback names should not reach user-facing editor/LSP surfaces;
• the contract should cover all callable symbols, not only stdlib;
• stdlib and host-backed parameter names should be treated as public API surface.

Related context:

• DSC-0035 established compiler-backed PBS editor assistance.
• DSC-0036 discusses authored symbol documentation and markdown hover, but documentation is not the owner of structural parameter identity.

Decision

PBS callable parameter names are normative semantic metadata.

Every callable symbol exposed by the PBS compiler semantic model MUST provide a structured parameter list containing, at minimum:

• parameter name;
• parameter type when known;
• parameter order;
• callable origin sufficient for implementation/debugging.

This applies to all callable symbols:

• user-authored PBS functions and methods;
• stdlib callables;
• builtins;
• host-backed APIs;
• compiler intrinsics that are visible as callables to users or editor tooling.

The compiler semantic callable model is the canonical source of parameter names. Editor adapters, LSP protocol surfaces, completion items, signature help, and hover MUST consume parameter names from that semantic callable model rather than inventing independent display names.

Generated fallback names such as arg0, arg1, arg2, or equivalent ordinal placeholders are internal implementation fallbacks only. They MUST NOT appear in user-facing editor or LSP surfaces, including:

• completion labels;
• completion details;
• completion snippets;
• signature help;
• hover signatures;
• parameter documentation surfaces.

If a callable lacks a real canonical parameter name, the compiler/editor boundary MUST represent that as missing or unresolved metadata rather than presenting a fabricated argN name to users. Plans may define the exact fallback UI, but the UI must not imply that argN is the public API name.

For stdlib and host-backed APIs, parameter names are part of the normative public API contract. Renaming a public parameter MUST be treated as an API compatibility concern and should be reviewed with the same discipline as other public API shape changes.

Rationale

The editor should not need to know whether a callable came from user PBS code, stdlib declarations, host descriptors, builtins, or compiler intrinsics in order to display a usable signature. A single semantic callable model gives completion, hover, signature help, diagnostics, documentation, and future refactoring tools the same source of truth.

Keeping parameter names in LSP-only metadata would make the UI look better quickly, but it would split callable truth between compiler semantics and editor presentation. That split is fragile because later surfaces would need to decide which source is authoritative.

Binding parameter names to authored documentation is also the wrong ownership boundary. Documentation can describe what a parameter means, but the parameter name itself is structural callable identity.

Treating argN as user-facing output makes the product worse exactly where assistance should be strongest: stdlib discovery and call construction. It also risks normalizing generated placeholders as if they were API names.

Implications

Compiler implications:

• PBS semantic analysis must preserve or produce real parameter names for every user-visible callable.
• Stdlib, builtin, host-backed, and intrinsic callable definitions must be projected into the same parameter shape.
• Any internal descriptor that currently lacks real names must be enriched, adapted, or treated as incomplete metadata.

LSP/editor implications:

• Completion, signature help, and hover must use semantic callable parameter names.
• LSP adapters must not patch over missing semantic names with guessed UI names.
• Completion snippets may use canonical parameter names as placeholders, but snippet formatting is a plan/spec detail.

API governance implications:

• Public stdlib and host-backed parameter names become compatibility-sensitive.
• Renames require explicit review because they affect editor help, documentation, and user-facing API shape.

Scope implications:

• The normative contract covers all callable symbols.
• Implementation may be staged, but staging must not narrow the final contract to stdlib only.
• Optional/default/rest parameter representation is out of scope unless an existing callable shape already requires it.

Documentation implications:

• DSC-0036 may attach prose descriptions to parameters later.
• Documentation must not become the canonical owner of parameter identity.

Propagation Targets

• specs: update PBS/compiler semantic model specs to define callable parameter identity and fallback constraints; update LSP/editor assistance specs if present.
• plans: create an execution plan that discovers current stdlib/host/intrinsic callable representation, updates semantic callable projection, and propagates names to LSP surfaces.
• code: compiler semantic model, stdlib/builtin/host-backed callable descriptors, PBS LSP completion/signature/hover providers, VS Code consumer if it formats snippets locally.
• tests: semantic model tests for callable parameter preservation; stdlib/host-backed conformance tests rejecting public argN; LSP completion/signature/hover tests proving argN does not leak.
• docs: future lesson after implementation; any affected README or API documentation for stdlib parameter naming discipline.

References

• Agenda: AGD-0040
• Related: DSC-0035
• Related: DSC-0036

Constraints

• Do not implement an editor-only rename map as the canonical solution.
• Do not use authored documentation as the canonical source of parameter names.
• Do not expose generated ordinal placeholders to users as if they were API names.
• Do not limit the normative model to stdlib only; plans may stage implementation but must preserve the all-callables target.

Revision Log

• 2026-05-08: Initial decision drafted from accepted agenda AGD-0040.