prometeu-studio/discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md

id	ticket	title	status	created	completed	tags
PLN-0075	pbs-lsp-editor-assistance-wave-1	PBS Editorial Resolution Surface for Symbols, Members, and Signatures	open	2026-05-08		compiler compiler-pbs editor completion hover signature-help semantics

Objective

Introduce a compiler-backed editorial resolution surface in compiler/pbs that can answer symbol identity, kind, origin, signature/shape, callable details, and receiver members for use by LSP completion, hover, and signature help.

Background

DEC-0035 requires all three editor-assistance features to be built over one shared compiler-backed base. The current repository already has useful pieces:

• parser and AST for PBS;
• semantic validation and flow analysis;
• stdlib and import visibility rules;
• semantic token classification;
• builder-pipeline overlay analysis.

What is still missing is an explicit editorial surface designed for interactive symbol resolution instead of only diagnostics or coloring.

Scope

Included

• Define internal compiler-side models for editorial symbol resolution.
• Resolve local names, imported/public symbols, and recognized member surfaces.
• Resolve callable signatures for functions, methods, and constructors.
• Provide optional documentation slot(s) in the model without defining authored PBS documentation syntax.
• Add PBS-focused tests for symbol/member/signature resolution.

Excluded

• LSP protocol capability changes.
• VS Code client behavior.
• Authored documentation syntax such as Document(...).
• go to definition, references, rename, formatter, or code actions.

Non-Goals

• Rebuilding the full compiler around IDE concerns.
• Solving every ambiguous or partial parse state in wave 1.
• Designing a generic multi-language IDE framework before PBS proves the model.

Execution Steps

Step 1 - Define editorial resolution models in compiler-owned surfaces

What: Introduce explicit models for resolved symbols, member candidates, callable signatures, and optional documentation payload. How: Add compiler-owned DTO/model types that can express:

1. symbol identity and kind;
2. declared/imported origin;
3. callable label/signature shape;
4. receiver member entries;
5. optional documentation text field.

The model must be expressive enough for completion, hover, and signature help without forcing each consumer to reinterpret raw AST nodes. File(s): prometeu-compiler/prometeu-compiler-core/src/main/java/** and/or prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/** depending on final ownership split.

Step 2 - Build PBS symbol resolution for local and imported surfaces

What: Resolve names in editorial contexts. How: Reuse parser, name/linking, stdlib import knowledge, and any existing semantic tables to resolve:

1. local bindings in scope;
2. declared top-level PBS symbols;
3. imported/public symbols and aliases;
4. stdlib-owned surfaces currently recognized by the frontend.

The implementation must avoid duplicating semantic truth already present in compiler/linking logic. File(s): prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**.

Step 3 - Build member and callable resolution

What: Resolve members and callable signatures for recognized receiver and call surfaces. How: Support at minimum:

1. member lookup after . for services, hosts, builtin types, and structs;
2. direct callable lookup for functions and constructors;
3. active-call signature resolution for later signature help use.

This step must produce stable labels/details that can be reused unchanged by LSP features. File(s): prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**.

Step 4 - Add editorial conformance tests

What: Lock the compiler-backed editorial contract before LSP integration. How: Add tests for:

1. local variable and parameter resolution;
2. imported service/host/builtin-type resolution;
3. member lookup after . on recognized surfaces;
4. callable signature extraction for function/method/constructor cases;
5. optional documentation field stability when absent.

File(s): PBS/compiler test suites under prometeu-compiler/**/src/test/java/**.

Test Requirements

Unit Tests

• Model invariants for symbol/member/signature payloads.
• Resolver tests covering locals, imports, aliases, members, and constructors.

Integration Tests

• Compiler-backed overlay/editorial tests using representative PBS snippets and stdlib imports.

Manual Verification

• Inspect resolved payloads in tests or debug output and confirm they are sufficient to drive all three editor features without ad hoc reinterpretation.

Acceptance Criteria

• Compiler-side editorial models exist for symbols, members, signatures, and optional documentation.
• PBS can resolve local names, imported/public symbols, and recognized member surfaces.
• Function, method, and constructor signatures are available through the shared editorial surface.
• No consumer is required to reconstruct signature/member meaning from raw AST-only data.

Dependencies

• DEC-0035 accepted and normatively locked.
• Existing PBS semantic and import/linking infrastructure remains the truth source.

Risks

• Overfitting the first resolver to the current stdlib shape may hurt future fronts or future PBS growth.
• Mixing diagnostics-only semantics with editorial semantics carelessly may produce partial or contradictory answers.
• Incomplete member resolution can make completion appear flaky even if hover works.