prometeu-studio/discussion/workflow/plans/PLN-0072-frontend-semantic-host-projection-contract.md

id	ticket	title	status	created	completed	tags
PLN-0072	frontend-semantic-host-projection-flexibility	Frontend Semantic Host Projection Contract	done	2026-05-06	2026-05-06	compiler compiler-general frontend semantics host-projection vscode pbs

Objective

Introduce the canonical frontend-authored semantic host projection contract in compiler-general frontend metadata and migrate PBS to publish its first VS Code projection without weakening frontend-owned semantic vocabulary.

Background

DEC-0034 locks that semantic vocabularies remain frontend-owned and canonical, while hosts such as VS Code consume declarative projection metadata authored by the frontend. The current semantic presentation work already establishes frontend-owned themes through DEC-0033, but semantic adaptation still lacks a structured host projection contract.

PBS is the first concrete frontend and therefore the first migration target, but the contract MUST remain compiler-general rather than PBS-shaped.

Scope

Included

• Evolve compiler/frontend metadata to publish declarative semantic host projection descriptors.
• Define the contract shape for VS Code semantic token projection.
• Migrate PBS to author VS Code projection metadata for its canonical semantic keys.
• Add tests that lock the contract and prevent host-owned remapping logic from becoming the source of truth.

Excluded

• LSP transport changes.
• VS Code extension runtime consumption changes.
• Redesigning PBS canonical semantic keys to mimic VS Code categories.

Non-Goals

• Introducing a global rigid semantic taxonomy across frontends.
• Making VS Code semantic token types the canonical frontend semantic contract.
• Solving projection for every future host in the first wave.

Execution Steps

Step 1 - Define compiler-general host projection metadata

What: Extend the frontend semantic metadata surfaces to carry host projection descriptors alongside canonical semantic keys. How: Add or evolve compiler-general model types so a frontend can declare, for each host projection entry:

1. the canonical frontend semantic key being projected,
2. the target host identity,
3. the host token type or equivalent target category,
4. any host modifiers,
5. fallback projection semantics when the host cannot represent the key exactly.

The contract MUST preserve the frontend semantic key as canonical and MUST treat projection as derivative metadata. File(s): prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/models/**, related frontend definition surfaces.

Step 2 - Make projection rules operational and mechanically consumable

What: Turn the projection contract into an exact operational surface rather than an informal note. How: Define invariants, null/empty behavior, and lookup rules for projection descriptors, including:

1. host identifier semantics,
2. duplicate or conflicting projection handling,
3. missing projection behavior,
4. fallback behavior representation,
5. safe access patterns from FrontendSpec.

The result MUST allow host adapters to translate frontend-authored projection data mechanically without semantic reinterpretation. File(s): prometeu-compiler/prometeu-compiler-core/src/main/java/**, associated compiler-general tests.

Step 3 - Migrate PBS to author its first VS Code projection

What: Make PBS publish its VS Code semantic projection through the new contract. How: Update PBS frontend metadata so its canonical semantic keys remain unchanged while the frontend also declares how each key projects into VS Code semantic token types and modifiers. The authored projection MUST live in PBS frontend metadata and MUST NOT be reauthored inside the extension. File(s): prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**, related PBS semantic presentation tests.

Step 4 - Lock the contract with tests

What: Prevent future drift toward host-owned semantic policy. How: Add tests that assert:

1. frontends publish projection descriptors through compiler-general metadata,
2. PBS canonical keys remain frontend-owned,
3. PBS VS Code projection resolves mechanically from frontend metadata,
4. no global repository-wide rigid semantic taxonomy is introduced as the canonical contract.

File(s): compiler-general and PBS test suites.

Test Requirements

Unit Tests

• Validate projection model invariants, including required frontend key linkage and host target fields.
• Validate FrontendSpec safely exposes host projection metadata.
• Validate missing and duplicate projection handling.

Integration Tests

• Run targeted compiler and PBS tests proving host projection metadata compiles, resolves, and remains discoverable through frontend definitions.

Manual Verification

• Inspect PBS frontend metadata and confirm the VS Code projection is authored there rather than in host adapter code.
• Confirm canonical PBS semantic keys remain readable and unchanged in ownership terms.

Acceptance Criteria

• Compiler-general frontend metadata publishes declarative host projection descriptors.
• The contract preserves canonical frontend semantic keys as the source of truth.
• The contract supports a VS Code projection without forcing a global rigid taxonomy.
• PBS authors its VS Code semantic projection through the new contract.
• Tests lock the contract against host-owned semantic remapping drift.

Dependencies

• DEC-0034 accepted and normatively locked.
• DEC-0033 accepted where semantic presentation metadata already exists and may need coordinated evolution.

Risks

• Overfitting projection fields to PBS or to VS Code would weaken future frontend flexibility.
• Allowing ambiguous projection semantics would push semantic authorship back into adapters.
• Collapsing canonical keys into host-shaped aliases would violate DEC-0034.