Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/plans/PLN-0079-project-canonical-parameter-names-through-pbs-compiler-callables.md

7.0 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0079 pbs-autocomplete-parameter-names Project canonical parameter names through PBS compiler callables open 2026-05-08
DEC-0036
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.