59 lines
2.0 KiB
Markdown
59 lines
2.0 KiB
Markdown
---
|
|
id: PLN-0101
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Protect runtime artifacts from Doc metadata lowering
|
|
status: done
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Guard the decision that `[Doc]` is compile/editor metadata and must not be lowered into runtime artifacts by default.
|
|
|
|
## Objective
|
|
|
|
Ensure documentation metadata does not affect IR, bytecode, cartridge output, stack behavior, or runtime validation.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0097`.
|
|
- Should be validated before end-to-end conformance closure.
|
|
|
|
## Scope
|
|
|
|
- Confirm lowering ignores `Doc` metadata.
|
|
- Add regression tests comparing runtime-facing output with and without docs where practical.
|
|
- Protect constant pool and cartridge artifacts from documentation payload bloat.
|
|
|
|
## Non-Goals
|
|
|
|
- Define a future packaging format for documentation.
|
|
- Remove compiler/editor metadata before LSP consumption.
|
|
|
|
## Execution Method
|
|
|
|
1. Inspect PBS lowering paths under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering`.
|
|
2. Ensure documented declarations lower identically to undocumented declarations for runtime-facing IR/backend artifacts.
|
|
3. Add golden or structural tests comparing compiled output for equivalent documented and undocumented programs.
|
|
4. Ensure large documentation payloads do not appear in runtime constant pools unless a future decision explicitly changes that.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Runtime-facing artifacts are unchanged by adding `[Doc]`.
|
|
- Compiler/editor metadata remains available before lowering for LSP/editor consumers.
|
|
- Golden artifact tests or equivalent regression tests cover this boundary.
|
|
|
|
## Tests
|
|
|
|
- `PbsGoldenArtifactsTest`
|
|
- Backend/lowering tests relevant to PBS IR output.
|
|
- Any artifact comparison test already used by the compiler frontend.
|
|
|
|
## Affected Artifacts
|
|
|
|
- PBS lowering package
|
|
- Golden artifact test resources if needed
|
|
- Compiler backend artifact tests
|