Files
prometeu-studio/discussion/lessons/DSC-0109-pbs-logical-viewport-composition/LSN-0108-composition-reference-coverage-and-studio-boundaries.md
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
Add shared human/task asset batches with reviewed atomic publication, explicit
reference rebinds, ownership inspection and qualified glyph/scene budgets.
Expose the same authoring and capacity results through Assets and MCP.

Deliver isolated guest test targets, retained visual evidence and immutable
runtime lifecycle/control observations. Preserve provider qualification and
installed authoring examples alongside the completed discussion lessons.

Close AGD-106 coordination and the delivered discussion workflows through
housekeeping, updating lesson references and preserving qualification limits.
Sound remains outside the asset delivery wave.

Validation: 579 module tests and 31 additional desktop, process and installed
checks passed; native glyph/scene 16/17 boundaries qualified. Discussion
validation passed after housekeeping.
2026-11-11 01:21:25 +00:00

184 lines
10 KiB
Markdown

---
id: LSN-0108
ticket: pbs-logical-viewport-composition
title: Composition Reference Coverage and Studio Boundaries
created: 2026-11-10
tags: [studio, composer, documentation, diagnostics]
---
## Original problem and accepted outcome
**Owner:** `studio`, composition knowledge and authoring support independent of UI.
**Discussion:** DSC-0109, originating in AGD-0111.
A separate Zelda port exposed difficulty understanding the relationship between
terrain, camera, sprites, HUD, Gfx overlays and frame clearing. It also needed to
fit its original image into the Prometeu framebuffer. These observations prompted
an evaluation of useful support in Studio.
The user accepted the completed evaluation on 2026-11-10, requested coordination
with the umbrella and then explicitly requested housekeeping. The accepted
outcome is to retain the existing Studio product interfaces for this scope and
record the documentation/example gaps for the `compiler/pbs` content owner.
No Studio feature or service change was justified by the evaluated cases.
The evaluation and coordination are complete. No product implementation remains
in this discussion. The user requested direct housekeeping of this accepted
evaluation; no implementation plan or artificial code-change stage was created.
This lesson preserves the accepted conclusion after removal of the agenda.
## Responsibility boundaries
- The game project owns its presentation policy: viewport placement, borders,
offsets and rules needed to reproduce its original game. Existing HUD/layer
composition may implement borders, for example.
- Studio owns its integration of project knowledge and its existing automation
services. The language/SDK provider owns the content of its references.
- The runtime retains its existing execution and rendering contracts. This
discussion did not authorize runtime changes or commits.
- All UI improvements were excluded because a Studio UI replacement is planned.
That exclusion also prevents speculative services created only for a future UI.
- General authoring problems remain worth evaluating even if first observed in a
single game. Their origin does not make every local workaround a tool feature.
## What the audit established
Studio already exposes the project reference index through
`studio_project_context` and paginated text through `studio_reference_read`.
`CompilerProjectKnowledge` selects installed provider references for the current
project's SDK/target. The PBS build projects its canonical specifications, SDK
resources and example files into the installed reference index.
The installed Game/SDK 1 bundle contained **176 reference entries**:
| Kind | Entries |
| --- | ---: |
| SEMANTICS | 40 |
| SYNTAX | 1 |
| QUICKSTART | 1 |
| SDK | 28 |
| EXAMPLE | 106 |
EXAMPLE counts indexed files, not independent example projects. All 176 resources
matched their indexed SHA-256 hashes. The isolated installed probe paginated every
reference through the Studio knowledge service and reconstructed exactly the
provider's text. No reference-delivery defect was demonstrated in this scope.
The runtime's graphics specification is not an input of the PBS reference build.
Its absence from that catalog is not evidence that Studio dropped a page.
### Content coverage
| Topic | Existing coverage | Remaining content opportunity |
| --- | --- | --- |
| Composer/Gfx order | PBS chapter 5 calls Gfx primitive/overlay-oriented; bindings and signatures are available. | Explain final overlay order and why a clear can cover composed content. |
| Layers, priority and transparency | Parameter descriptions and the sprite-emission signature exist. | Explain operational composition with a small example, without assuming NES equivalence. |
| Camera, sprites and HUD | Camera bindings and sprite screen-coordinate descriptions exist. | Demonstrate the relationship between coordinate spaces and caller-owned transforms. |
| Empty background and clearing | Isolated Gfx examples exist. | Explain existing scene/no-scene behavior and demonstrate an appropriate empty-scene setup. |
| Visual query versus animation advance | PBS chapter 27 explicitly separates query/emission from playback advance. | No additional work justified by this question. |
| Fixed terrain and mutable objects | No complete general composition example was found in the audited example files. | Evaluate a neutral example independent of any port. |
`src/main.pbs` draws a moving Gfx rectangle. The production Gfx example uses
`fill_rect`. `src/animation.pbs` includes a helper calling `emit_sprite`, but the
audited PBS example files do not call `Composer.bind_scene` or
`Composer.set_camera`. These facts identify a content opportunity, rather than a
missing Studio operation.
The existing runtime contracts and sources were inspected read-only to check the
reported behavior. Future explanatory material must distinguish public contract
from implementation observations and preserve runtime ownership of execution.
## Recorded handoff to compiler/pbs
The owner of the distributed Composer/Gfx documentation and Game SDK 1 examples
can evaluate the following work in its own scope:
1. Improve explanations of composition order, coordinate spaces, priority,
transparency and clearing, using the existing execution contracts as authority.
2. Evaluate one complete neutral example with minimal owned resources, terrain,
actor, HUD, camera movement and mutable objects. Reuse the current reference
mechanism and SDK APIs; keep game-specific layout and occlusion policy local.
3. If an example is produced, qualify compilation, graphical execution and pixel
expectations separately through the existing headless path. A successful
compile alone does not establish correct visual output.
This handoff records a destination and concrete content gaps. It does not open a
new discussion, authorize implementation in another domain or promise a new SDK
API. Studio must not compensate with duplicated specifications or diagnostics
that classify valid game presentation choices as errors.
## Verification and evidence
The audit used Studio revision
`b351f2e5823039f82e3cd9666547578add13bebb`. The installed frontend JAR SHA-256 was
`780dc6f72755692731291d169d6f161eb47d0401579731753c5f59aa4a702f0e`.
**13 tests passed**, with no failures, errors or skips:
| Suite | Tests | What it verifies |
| --- | ---: | --- |
| ProjectReferencesTest | 6 | Studio reference integration, pagination, SDK selection and unavailable-reference handling. |
| PbsDocumentationTest | 5 | Provider/index consistency, exact SDK resources and supported selection. |
| InstalledKnowledgeTest | 2 | Isolated installed-JAR reads, complete paginated text and example compilation. |
The installed task was explicitly executed with `--rerun`; the result was not
merely reused from Gradle's up-to-date state.
```bash
./gradlew :prometeu-app:test --tests p.studio.app.compiler.ProjectReferencesTest :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests p.studio.compiler.pbs.documentation.PbsDocumentationTest --console=plain
./gradlew :prometeu-app:installedKnowledgeTest --rerun --console=plain
```
Preserved evidence:
- [Audit identity, integrity results and example occurrences](evidence/audit.json).
- [Installed reference-index snapshot](evidence/installed-reference-index.json).
- [Focused test log](evidence/knowledge-validation.log) and
[explicit installed-test execution log](evidence/installed-knowledge.log).
- [Studio reference test results](evidence/TEST-p.studio.app.compiler.ProjectReferencesTest.xml),
[provider test results](evidence/TEST-p.studio.compiler.pbs.documentation.PbsDocumentationTest.xml)
and [installed test results](evidence/TEST-p.studio.app.compiler.InstalledKnowledgeTest.xml).
The audit did not execute graphical rendering, compare pixels or exercise a
complete authenticated MCP HTTP session. Its evidence covers the neutral
knowledge integration, installed texts and compilation, not visual correctness.
No product code, specification, UI, SDK, runtime or port was changed.
## Coordination and remaining work
The [DSC-0104 / AGD-0106 umbrella](../DSC-0104-compiler-game-production-reliability/LSN-0113-coordinating-compiler-reliability-and-diagnostic-delivery.md)
preserves this accepted outcome as an external interface, preserving its existing
compiler reliability and diagnostics scope and its two agreed deliveries. This
content handoff does not become a new child, implementation gate or prerequisite
for closing that umbrella. The related assets discussion refers to this lesson
for the completed knowledge evaluation; it retains its own authoring/budget scope.
The prior [DSC-0108 installed examples lesson](../DSC-0108-pbs-production-contracts-executable-examples/LSN-0107-quoted-project-identities-and-installed-authoring-contracts.md)
remains valid. This later audit identifies composition coverage outside its
qualified corpus and does not reinterpret its acceptance or claim that graphics
were already tested there.
No further Studio implementation is pending for DSC-0109. Potential content work
remains a recorded handoff for its owner; UI improvements remain outside this
ticket and require their own future scope.
## Common mistakes
- Treating difficulty adapting a game's presentation as proof of a runtime gap.
- Adding a Studio endpoint before checking existing knowledge and headless APIs.
- Confusing incomplete source content with a broken Studio reference index.
- Duplicating language/SDK specifications in Studio to make text more accessible.
- Counting compilation or a reference hash match as proof of pixel correctness.
- Allowing a deferred UI feature to introduce speculative backend obligations.
- Reopening an umbrella's accepted deliverables through an external content handoff.
## Maintenance references
- [Studio 11, project knowledge and installed references](../../../docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
- [Studio 10, automation and canonical capture](../../../docs/specs/studio/10.%20DEV%20and%20Automation%20Specification.md).
- [CompilerProjectKnowledge](../../../prometeu-app/src/main/java/p/studio/app/compiler/CompilerProjectKnowledge.java).
- [PBS reference generation](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/build.gradle.kts).
- [PBS documentation provider](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/documentation/PbsDocumentation.java).
- [InstalledKnowledgeProbe](../../../prometeu-app/src/test/java/p/studio/app/compiler/InstalledKnowledgeProbe.java).
- [Runtime graphics authority, read-only reference](../../../../runtime/docs/specs/runtime/04-gfx-peripheral.md).