---
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