---
id: PLN-0075
ticket: pbs-lsp-editor-assistance-wave-1
title: PBS Editorial Resolution Surface for Symbols, Members, and Signatures
status: open
created: 2026-05-08
completed:
tags: [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.