prometeu-studio/discussion/workflow/plans/PLN-0031-studio-structural-anchor-semantic-surface-specification.md

id	ticket	title	status	created	completed	tags
PLN-0031	studio-editor-scope-guides-and-brace-anchoring	Structural anchor semantic surface specification for Studio semantic read	done	2026-04-03	2026-04-03	studio specs semantic-read structural-anchors frontend-contract

Objective

Specify the dedicated semantic surface required by DEC-0014 for structural anchors and guide-specific structural metadata, without overloading documentSymbols.

Background

DEC-0014 requires exact guide anchoring to come from frontend-owned structural metadata expressed as generic structural anchors. The decision explicitly forbids treating local text scanning as the final contract and explicitly keeps documentSymbols as the outline/navigation surface.

This plan covers the normative documentation and contract-shaping work needed before frontend payloads and Studio consumers can converge on a stable schema.

Scope

Included

• Define the semantic-read contract boundary for structural anchors in Studio specs.
• Specify a dedicated surface for structural guide metadata separate from documentSymbols.
• Define the normative semantics of structural ranges, parentage, and anchors in language-agnostic terms.
• Define how the Studio editor consumes that surface for exact guide start/end anchoring.

Excluded

• Frontend implementation of the new payload.
• Studio code changes that consume the new payload.
• Theme or visual styling decisions.

Execution Steps

Step 1 - Update the semantic-read specification with a dedicated structural-anchor surface

What: Add a normative section to the Studio semantic-read specification defining a new dedicated semantic surface for guide-oriented structural metadata.

How: Update the semantic-read spec to state that:

• documentSymbols remains the outline/navigation surface;
• structural guide metadata is delivered through a separate payload or surface;
• the surface must support structural ranges, parent/child relations when required, and exact anchors for guide rendering;
• the contract is language-agnostic and must not encode brace-only assumptions.

File(s):

• docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md

Step 2 - Update the Code Editor workspace specification for active indicators and anchor consumption

What: Propagate DEC-0014 into the Code Editor workspace specification.

How: Update the editor spec so it normatively states:

• the gutter remains the primary scope-indicator surface for the initial wave;
• the editor renders at most two active indicators: activeContainer and activeScope;
• exact start/end anchoring depends on the structural-anchor semantic surface;
• concrete visual treatment remains frontend-owned.

File(s):

• docs/specs/studio/5. Code Editor Workspace Specification.md

Step 3 - Define the schema and semantic invariants of structural anchors

What: Describe the minimum schema and invariants needed for frontend and Studio implementations to interoperate safely.

How: Specify, at minimum:

• what a structural range represents;
• how parentage is expressed or inferred;
• what anchor positions represent;
• how the model behaves for languages with braces, keywords, indentation, or mixed delimiters;
• which invariants tests and future implementations must honor.

If a separate schema subsection or appendix is needed, add it within the relevant spec surface rather than inventing an ad hoc note.

File(s):

• docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md
• docs/specs/studio/5. Code Editor Workspace Specification.md if editor-facing invariants need reiteration

Test Requirements

Unit Tests

• Not applicable at this spec-only stage.

Integration Tests

• Not applicable at this spec-only stage.

Manual Verification

• Review the spec text against DEC-0014 and confirm every normative requirement is represented.
• Confirm the spec does not overload documentSymbols.
• Confirm the spec speaks in generic structural anchors rather than brace-specific terms.

Acceptance Criteria

• The semantic-read spec defines a dedicated structural-anchor surface separate from documentSymbols.
• The Code Editor spec reflects the two-indicator gutter model and frontend-owned presentation.
• The contract is language-agnostic and does not assume braces as the only structural delimiter.
• The spec text is sufficient for a frontend and Studio implementation plan without reopening DEC-0014.

Dependencies

• Accepted decision DEC-0014-studio-editor-active-scope-and-structural-anchors.md
• Existing Studio specs in docs/specs/studio

Risks

• Over-specifying serialization too early may constrain future frontends unnecessarily.
• Under-specifying parentage and anchor semantics may leave ambiguous implementation choices and force a decision revisit.