Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/plans/PLN-0078-specify-pbs-callable-parameter-identity-in-the-semantic-model.md

5.1 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0078 pbs-autocomplete-parameter-names Specify PBS callable parameter identity in the semantic model open 2026-05-08
DEC-0036
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