---
id: PLN-0031
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Structural anchor semantic surface specification for Studio semantic read
status: done
created: 2026-04-03
completed: 2026-04-03
tags:
  - 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

- [x] The semantic-read spec defines a dedicated structural-anchor surface separate from `documentSymbols`.
- [x] The Code Editor spec reflects the two-indicator gutter model and frontend-owned presentation.
- [x] The contract is language-agnostic and does not assume braces as the only structural delimiter.
- [x] 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.