dev/pbs-autocomplete-parameter-names #9

Merged
bquarkz merged 5 commits from dev/pbs-autocomplete-parameter-names into master 2026-05-14 06:55:29 +00:00
7 changed files with 79 additions and 626 deletions
Showing only changes of commit 0342df1d4e - Show all commits

View File

@ -1,5 +1,5 @@
{"type":"meta","next_id":{"DSC":38,"AGD":41,"DEC":37,"PLN":81,"LSN":52,"CLSN":1}}
{"type":"discussion","id":"DSC-0037","status":"in_progress","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[{"id":"AGD-0040","file":"AGD-0040-pbs-autocomplete-parameter-names-for-stdlib-and-method-calls.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[{"id":"DEC-0036","file":"DEC-0036-canonical-parameter-names-in-the-pbs-callable-semantic-model.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08","ref_agenda":"AGD-0040"}],"plans":[{"id":"PLN-0078","file":"PLN-0078-specify-pbs-callable-parameter-identity-in-the-semantic-model.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0036"]},{"id":"PLN-0079","file":"PLN-0079-project-canonical-parameter-names-through-pbs-compiler-callables.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0036"]},{"id":"PLN-0080","file":"PLN-0080-propagate-semantic-parameter-names-to-pbs-lsp-editor-assistance.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0036"]}],"lessons":[]}
{"type":"meta","next_id":{"DSC":38,"AGD":41,"DEC":37,"PLN":81,"LSN":53,"CLSN":1}}
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-14","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0037-pbs-autocomplete-parameter-names/LSN-0052-canonical-callable-parameter-names-through-pbs-editor-assistance.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]}
{"type":"discussion","id":"DSC-0036","status":"open","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0035","status":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
{"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}

View File

@ -0,0 +1,77 @@
---
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`.

View File

@ -1,172 +0,0 @@
---
id: AGD-0040
ticket: pbs-autocomplete-parameter-names
title: PBS autocomplete parameter names for stdlib and method calls
status: accepted
created: 2026-05-08
resolved:
decision:
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
---
## Pain
Domain owner: `compiler/pbs`
Autocomplete and signature help currently show method/function parameters as arg0, arg1, etc., especially for stdlib APIs, making calls hard to understand at the point of use.
The immediate user-facing problem is not just cosmetic. When a completion inserts or previews something like:
- `draw(arg0, arg1, arg2)`
- `setTile(arg0, arg1, arg2)`
- `loadSprite(arg0)`
the editor fails at the exact moment it should reduce lookup cost. The user has to leave the call site, inspect docs/source, or guess what each argument means.
For PBS, this is especially damaging because stdlib and host-backed APIs are likely to be the most frequently discovered through autocomplete.
## Context
The compiler-backed LSP wave can surface completions, hover, and signature help, but the parameter identity exposed to editor consumers is not yet reliable or authored enough for ergonomic API use.
Subdomains touched:
- `compiler/general`
- `studio/lsp`
- `tools/vscode-extension`
Related discussions:
- `DSC-0035` established the compiler-backed editor assistance wave.
- `DSC-0036` is discussing authored symbol documentation and markdown hover.
This agenda is narrower than `DSC-0036`.
`DSC-0036` asks how symbol documentation should be authored and transported. This agenda asks where canonical parameter names come from and how completion/signature surfaces should consume them. Parameter names may later connect to documentation, but they need their own canonical identity even without full prose documentation.
## Open Questions
- [x] Should canonical parameter names be owned by the compiler semantic callable model, or is stdlib/API metadata allowed to remain a separate source of truth?
- Answer: canonical parameter names should be offered through the compiler semantic model.
- [x] Is `arg0`/`arg1` allowed to reach any user-facing LSP/editor surface, or must it be treated as an internal fallback only?
- Answer: `arg0`/`arg1` should not reach user-facing editor or LSP surfaces.
- [x] For the first implementation slice, should the decision cover all callable symbols or explicitly target stdlib/host-backed APIs first?
- Answer: the decision should cover all callable symbols.
- [x] Are parameter names part of the normative public API contract for stdlib and host-backed surfaces?
- Answer: parameter names should be treated as part of the normative public API contract.
Non-blocking implementation investigations:
- Determine how stdlib APIs are represented today: PBS declarations, Java/Kotlin host descriptors, compiler intrinsics, generated metadata, or a mix.
- Verify whether user-authored PBS functions already preserve source parameter names through the compiler-backed LSP path.
- Decide exact snippet formatting after the canonical parameter source is settled.
- Defer optional/default/rest parameter representation until PBS has that callable shape.
## Options
### Option A - Canonical parameter names live in the compiler semantic callable model
- **Approach:** every callable symbol resolved by the compiler has an explicit parameter list with stable names, types, order, and origin. LSP completion, signature help, and hover all read from that same semantic shape.
- **Pro:** one authoritative contract; works for user code, stdlib, builtins, and host-backed APIs if they are projected into the semantic model.
- **Con:** requires stdlib/builtin surfaces to provide or be lowered into real parameter metadata instead of ad hoc editor-only labels.
- **Maintainability:** strong. It makes `arg0` a compiler/model quality issue rather than a UI formatting problem.
### Option B - Parameter names live in stdlib/API metadata consumed by the LSP adapter
- **Approach:** stdlib and host-backed APIs carry external metadata for names and docs; LSP consumes that metadata when building completion items and signatures.
- **Pro:** fast path for the worst current pain if the main offender is stdlib; avoids forcing every host descriptor into a richer compiler model immediately.
- **Con:** risks splitting callable truth between compiler semantics and editor metadata. User-authored and stdlib callables may drift.
- **Maintainability:** medium. Acceptable as a migration step, but weak as the final owner if the compiler and editor can disagree.
### Option C - Derive display names in the editor/LSP when semantic names are missing
- **Approach:** keep existing compiler output and have LSP/VS Code replace `arg0`, `arg1` with guessed names from docs, method names, types, or curated maps.
- **Pro:** minimal compiler change; can improve a handful of visible APIs quickly.
- **Con:** guessing parameter names is fragile and can mislead users. It treats presentation as truth.
- **Maintainability:** weak. This should be reserved only as a temporary compatibility shim with clear diagnostics.
### Option D - Bind parameter names to the documentation model from `DSC-0036`
- **Approach:** parameter names and descriptions are authored together in the symbol documentation surface, then completion/signature help extract display names from docs.
- **Pro:** ties names and descriptions together; can produce rich signature help.
- **Con:** parameter identity becomes dependent on documentation authoring. A callable without docs could still degrade to `arg0`.
- **Maintainability:** medium-to-weak as a canonical source. Good for prose descriptions, poor for structural identity.
### Option E - Allow `arg0`/`arg1` internally but ban them from user-facing LSP output
- **Approach:** define a conformance rule: generated fallback parameter names may exist internally, but completion/signature/hover must either show canonical names or omit placeholder names instead of exposing `argN`.
- **Pro:** creates a clear UX quality gate and prevents the worst editor output.
- **Con:** does not by itself solve where real names come from.
- **Maintainability:** strong as a guardrail, incomplete as the main design.
## Tradeoffs
The central tradeoff is speed versus ownership.
An editor-only fix can make the UI look better quickly, but it creates a second source of truth for API shape. That is exactly the kind of split that becomes expensive once hover, snippets, signature help, diagnostics, docs, and future refactors all need the same callable metadata.
Putting names into the compiler semantic model is heavier, but it matches the long-term direction implied by compiler-backed editor assistance. The editor should not need to know why a callable is user-authored, stdlib, host-backed, or intrinsic in order to display a usable signature.
There is still room for a staged path:
- immediately block or reduce `argN` in user-facing output;
- add canonical names for stdlib APIs through the nearest existing stdlib descriptor;
- converge those descriptors into the compiler's callable semantic model;
- let documentation add descriptions, examples, and prose later without owning structural names.
`DSC-0036` should remain complementary. Documentation can describe what a parameter means, but the parameter name itself should be structural metadata.
## Recommendation
Use **Option A** as the target design and **Option E** as a non-negotiable editor quality guardrail.
Recommended direction:
1. Treat canonical parameter names as part of the resolved callable symbol model.
2. Require stdlib, builtin, host-backed, and user-authored callables to expose the same parameter shape to editor assistance.
3. Define `arg0`, `arg1`, etc. as internal fallback names only; they should not appear in completion labels, snippets, signature help, or hover unless explicitly authored as real API names.
4. Let the documentation model from `DSC-0036` attach parameter descriptions later, but not replace structural parameter identity.
If implementation needs to be staged, the first slice should target the stdlib because that is where the current UX pain is most visible.
## Discussion
This agenda should avoid reducing the problem to "prettier snippets".
The real question is ownership:
- who owns a callable's parameter names?
- does the compiler know them?
- does the editor receive them as structured data?
- can tests assert that stdlib APIs do not leak fallback names?
Questions that do not need to block the decision:
- The current storage shape of stdlib declarations is implementation discovery; it affects the plan, but not the ownership decision.
- User-authored function behavior should be verified, but the target contract can still require every callable symbol to expose the same parameter shape eventually.
- Snippet placeholder details belong in plan/spec once the canonical parameter identity is decided.
- Optional/default/rest parameters are future callable-shape concerns unless current PBS or stdlib APIs already expose them.
The minimum acceptable outcome is that a user can discover a stdlib call from autocomplete and understand what each argument is supposed to represent without leaving the call site.
Potential acceptance examples for a later decision/plan:
- completion insert text uses named placeholders where snippets are enabled;
- signature help displays stable parameter names and types;
- hover can show a callable signature using the same names;
- conformance tests fail if public stdlib callables expose `argN` placeholders;
- fallback behavior is explicit when a callable genuinely lacks parameter names.
## Resolution
Proposed resolution:
- canonical parameter names are owned by the compiler semantic callable model;
- stdlib, host-backed, builtin, and user-authored callables should all expose parameter names through the same semantic callable shape;
- generated fallback names such as `arg0` and `arg1` are internal only and must not appear in completion, signature help, hover, or other user-facing editor/LSP surfaces;
- parameter names for stdlib and host-backed APIs are normative public API surface, so renaming them should be treated as an API compatibility concern;
- implementation may still be staged, but the normative decision should cover all callable symbols rather than defining a stdlib-only contract.
## Next Step
If this resolution matches the intended direction, the next step is to accept the agenda and create a decision artifact from it.

View File

@ -1,126 +0,0 @@
---
id: DEC-0036
ticket: pbs-autocomplete-parameter-names
title: Canonical parameter names in the PBS callable semantic model
status: accepted
created: 2026-05-08
ref_agenda: AGD-0040
tags: [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`.

View File

@ -1,100 +0,0 @@
---
id: PLN-0078
ticket: pbs-autocomplete-parameter-names
title: Specify PBS callable parameter identity in the semantic model
status: open
created: 2026-05-08
ref_decisions: [DEC-0036]
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
---
## Briefing
`DEC-0036` makes callable parameter names normative semantic metadata. Before implementation, the PBS and compiler specs need a clear contract for callable parameter identity so code changes do not invent a narrower interpretation.
This plan is the specification and conformance planning slice. It does not implement Java code. It defines the target semantic shape, public API compatibility rule, and test expectations that downstream plans must satisfy.
## Objective
Update normative documentation so every PBS user-visible callable has a canonical semantic parameter list with stable names, order, type when known, and origin. Define that generated ordinal placeholders such as `arg0` are internal only and must not appear in user-facing editor/LSP surfaces.
## Dependencies
- Depends on accepted decision `DEC-0036`.
- Must precede `PLN-0079` and `PLN-0080` because those plans implement and consume the contract defined here.
- Related but not blocked by `DSC-0036`; parameter documentation can attach prose later, but docs do not own structural names.
## Scope
- Update PBS static semantics and stdlib/SDK specs to define canonical callable parameter identity.
- Update compiler conformance/spec-to-test documentation to require `argN` leak prevention.
- Update LSP/editor assistance roadmap/spec text if a current spec surface exists for completion, hover, or signature help.
- Record that stdlib and host-backed parameter names are public API surface.
- Define the minimum semantic parameter record:
- name;
- order;
- type when known;
- origin/source sufficient for implementation and diagnostics.
## Non-Goals
- No Java/Kotlin implementation changes.
- No VS Code extension changes.
- No authored parameter prose documentation design.
- No optional/default/rest parameter design unless an existing PBS callable already exposes that shape.
- No editor-only rename map.
## Execution Method
1. Update PBS static semantic documentation:
- Target: `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`.
- Add a section for resolved callable parameter identity.
- State that every user-visible callable symbol MUST expose canonical parameter names through the compiler semantic model.
- State that generated ordinal placeholders MUST NOT be treated as public parameter names.
2. Update stdlib/SDK resolution documentation:
- Target: `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`.
- Add the requirement that stdlib and SDK/host-backed callable definitions carry stable public parameter names.
- State that parameter renames are API compatibility-sensitive.
3. Update host-backed and intrinsic documentation:
- Targets:
- `docs/specs/compiler-languages/pbs/6. VM-owned vs Host-backed.md`
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- Clarify that visible host-backed and intrinsic callables must be projected into the same semantic callable parameter shape.
4. Update compiler conformance documentation:
- Target: `docs/specs/compiler/13. Conformance Test Specification.md`.
- Add conformance expectations for semantic callable parameter preservation and LSP/editor `argN` leak prevention.
5. Update roadmap/spec references for LSP if still current:
- Targets:
- `docs/roadmaps/lsp/LSP - base PRs.md`
- `docs/roadmaps/lsp/LSP - roadmap remain.md`
- Add a short reference that editor assistance consumes compiler semantic parameter names.
## Acceptance Criteria
- Specs explicitly state the compiler semantic model is the canonical owner of parameter names.
- Specs explicitly cover user-authored PBS, stdlib, builtins, host-backed APIs, and visible intrinsics.
- Specs explicitly ban generated ordinal placeholders from user-facing editor/LSP output.
- Specs state stdlib and host-backed parameter names are public API compatibility surface.
- The plan leaves no permission for an editor-only rename map as the canonical solution.
## Tests
- Run `discussion validate`.
- If spec conformance tests exist for docs links or matrices, run the relevant Gradle test target.
- Manual review gate: confirm every MUST from `DEC-0036` is represented in the updated specs.
## Affected Artifacts
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `docs/specs/compiler-languages/pbs/6. VM-owned vs Host-backed.md`
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/specs/compiler/13. Conformance Test Specification.md`
- `docs/roadmaps/lsp/LSP - base PRs.md`
- `docs/roadmaps/lsp/LSP - roadmap remain.md`

View File

@ -1,114 +0,0 @@
---
id: PLN-0079
ticket: pbs-autocomplete-parameter-names
title: Project canonical parameter names through PBS compiler callables
status: open
created: 2026-05-08
ref_decisions: [DEC-0036]
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
---
## Briefing
`DEC-0036` requires all user-visible callables to expose canonical parameter names through the PBS compiler semantic callable model. This plan implements that compiler-side projection.
The immediate pain is visible in stdlib/editor assistance, but the implementation target is all callable symbols: user-authored PBS functions and methods, stdlib callables, builtins, host-backed APIs, and visible compiler intrinsics.
## Objective
Add or complete compiler semantic callable parameter metadata so every user-visible callable carries canonical parameter names, order, type when known, and origin. Ensure generated names such as `arg0` remain internal and are represented as missing/incomplete metadata rather than public names.
## Dependencies
- Depends on accepted decision `DEC-0036`.
- Should follow `PLN-0078` so implementation matches the updated spec wording.
- Must complete before `PLN-0080` can fully consume semantic parameter names in LSP/editor assistance.
## Scope
- Inspect and update PBS callable semantic types and resolution paths.
- Preserve source parameter names for user-authored PBS declarations.
- Project stdlib resource declarations into the same callable parameter model.
- Project host-backed, builtin, and visible intrinsic callables into the same model.
- Add semantic/conformance tests for parameter names and `argN` leak prevention at the compiler boundary.
## Non-Goals
- No LSP protocol formatting work; that belongs to `PLN-0080`.
- No VS Code extension behavior changes.
- No authored parameter descriptions.
- No generated editor-side alias table.
- No broad refactor of name resolution beyond callable parameter identity.
## Execution Method
1. Locate the current semantic callable model:
- Inspect:
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsCallableShape.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSignature.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialResolvedSymbol.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSupportService.java`
- Identify where parameter lists currently lose real names or synthesize ordinal placeholders.
2. Preserve user-authored parameter names:
- Inspect parser/AST sources:
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsDeclarationParser.java`
- Ensure declaration parameter identifiers survive into semantic callable shapes.
3. Project stdlib parameter names:
- Inspect stdlib resources:
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/**/main.pbs`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/**/mod.barrel`
- Inspect loaders:
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoader.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/stdlib/StdlibEnvironmentResolver.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java`
- Ensure stdlib declarations expose authored parameter names through the same semantic callable model.
4. Project builtin, host-backed, and intrinsic parameters:
- Inspect:
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsBuiltinLayoutResolver.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsHostAdmissionValidator.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsCallableShapeSurfaceService.java`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMIntrinsicRegistry.java`
- Enrich descriptors that currently lack stable names.
- If a descriptor genuinely lacks a real public name, represent that as incomplete metadata rather than `argN`.
5. Add compiler tests:
- Extend or add tests near:
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsEditorialSupportServiceTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsSemanticsDeclarationsTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoaderTest.java`
- Assert user-authored and stdlib callables expose real parameter names.
- Assert public semantic callable output does not contain `arg0`, `arg1`, or equivalent generated ordinal placeholders.
## Acceptance Criteria
- Every semantic callable exposed to editor assistance has a structured parameter list with names, order, type when known, and origin.
- User-authored PBS functions preserve declared parameter names.
- Stdlib declarations expose stable authored parameter names.
- Builtin, host-backed, and visible intrinsic callables either expose real names or report missing metadata without fabricating public `argN` names.
- Compiler tests fail if public semantic callable metadata leaks `argN`.
- No editor/LSP-only rename map is introduced.
## Tests
- `./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test` if the Gradle path is valid in the current build.
- If module targeting differs, run the nearest available PBS frontend test task from `./gradlew projects`.
- Run focused tests for:
- `PbsEditorialSupportServiceTest`
- `PbsSemanticsDeclarationsTest`
- `InterfaceModuleLoaderTest`
- Run `discussion validate`.
## Affected Artifacts
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsCallableShape.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSignature.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialResolvedSymbol.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSupportService.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoader.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/**`
- PBS frontend semantic and stdlib tests.

View File

@ -1,112 +0,0 @@
---
id: PLN-0080
ticket: pbs-autocomplete-parameter-names
title: Propagate semantic parameter names to PBS LSP editor assistance
status: open
created: 2026-05-08
ref_decisions: [DEC-0036]
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
---
## Briefing
`DEC-0036` requires completion, signature help, and hover to consume callable parameter names from the compiler semantic model and prevents generated ordinal placeholders from reaching user-facing editor/LSP output.
This plan implements the LSP/editor consumption slice after compiler semantic callable metadata exists.
## Objective
Propagate canonical semantic parameter names into PBS completion, signature help, hover, and VS Code-facing protocol mapping. Add tests proving `arg0`, `arg1`, and equivalent generated placeholders do not leak through user-facing LSP/editor surfaces.
## Dependencies
- Depends on accepted decision `DEC-0036`.
- Should follow `PLN-0078` for spec contract alignment.
- Requires `PLN-0079` or equivalent compiler semantic metadata before final acceptance.
## Scope
- Update PBS editorial support outputs consumed by the LSP bridge.
- Update LSP baseline messages/mappers if the protocol shape needs richer parameter metadata.
- Update completion item construction to use semantic parameter names in labels/details/snippets.
- Update signature help to display semantic parameter names and types.
- Update hover signatures to use the same parameter identity.
- Update VS Code extension only if it formats snippets or signatures locally.
- Add LSP/protocol tests that reject `argN` leakage.
## Non-Goals
- No compiler semantic model implementation; that belongs to `PLN-0079`.
- No authored parameter prose documentation.
- No final design for optional/default/rest parameter UI unless already surfaced by compiler metadata.
- No UI-only guesswork for missing names.
## Execution Method
1. Identify current LSP/editor assistance boundary:
- Inspect:
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/LanguageServiceBridge.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineCompletionItem.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignature.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignatureHelp.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineHover.java`
- Map which fields currently carry callable signatures and parameters.
2. Consume semantic parameter names from compiler outputs:
- Update bridge/mapping code so completion/signature/hover surfaces use parameter names from PBS semantic callable metadata.
- Do not generate display names from method names, types, docs, or local maps.
- Treat missing semantic names as incomplete metadata and apply a non-misleading fallback UI that does not show `argN`.
3. Update protocol mapping:
- Inspect:
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/Lsp4jProtocolMessageMapper.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/ProtocolMessageMapper.java`
- Ensure LSP4J completion/signature/hover conversion preserves semantic parameter names.
- Ensure snippet placeholders, if emitted, use canonical parameter names.
4. Update VS Code extension if required:
- Inspect:
- `tools/vscode-extension/src/extension.ts`
- If the extension formats call snippets or signatures locally, remove any generated ordinal placeholders and consume protocol-provided semantic names.
5. Add LSP/editor tests:
- Extend:
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridgeTest.java`
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/protocol/PrometeuTextDocumentServiceTest.java`
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/protocol/PrometeuLanguageServerTest.java`
- Assert completion labels/details/snippets do not contain `arg0` or `arg1`.
- Assert signature help parameter labels use semantic names.
- Assert hover callable signatures use the same semantic names.
## Acceptance Criteria
- Completion surfaces use canonical semantic parameter names and do not leak `argN`.
- Signature help surfaces use canonical semantic parameter names and do not leak `argN`.
- Hover callable signatures use canonical semantic parameter names and do not leak `argN`.
- The same callable uses the same parameter names across completion, signature help, and hover.
- Missing parameter metadata is represented without fabricating public ordinal names.
- VS Code extension behavior remains compatible with protocol outputs.
## Tests
- Run focused LSP tests:
- `CompilerLanguageServiceBridgeTest`
- `PrometeuTextDocumentServiceTest`
- `PrometeuLanguageServerTest`
- Run the LSP Gradle test task for `prometeu-lsp-v1` if available.
- Run VS Code extension tests/build if the extension code changes:
- `npm test` or `npm run compile` in `tools/vscode-extension`, depending on available scripts.
- Run `discussion validate`.
## Affected Artifacts
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/LanguageServiceBridge.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineCompletionItem.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignature.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignatureHelp.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineHover.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/Lsp4jProtocolMessageMapper.java`
- `tools/vscode-extension/src/extension.ts` if local formatting is present.
- LSP protocol and bridge tests.