Compare commits
57
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
632ba6d0d6
|
||
|
|
77aada6259
|
||
|
|
c410e35001
|
||
|
|
76a8b074e8
|
||
|
|
240216170c
|
||
|
|
b62db87245
|
||
|
|
d1e9259085
|
||
|
|
2a418085d2
|
||
|
|
39df63581c
|
||
|
|
c4e1b9055d
|
||
|
|
a04214a705
|
||
|
|
91eb86f317
|
||
|
|
13c0ababbb
|
||
|
|
603ed01227
|
||
|
|
bd5694dbdf
|
||
|
|
a9ede541af | ||
|
|
d71e46ade8
|
||
|
|
8dff6d8d5f
|
||
|
|
967b9ec598
|
||
|
|
d0737df0ac
|
||
|
|
97cf5e1919
|
||
|
|
3f675ca0c9
|
||
|
|
73aaeb0832
|
||
|
|
546c6d1ee5
|
||
|
|
4c3597a2fb
|
||
|
|
e6a83c94e0
|
||
|
|
4f148a50de
|
||
|
|
379420e7a9
|
||
|
|
bc76f08bbd
|
||
|
|
9592c9b274
|
||
|
|
20bbbd26bd
|
||
|
|
c1834bad1f
|
||
|
|
feb57c5298
|
||
|
|
58f11a8123
|
||
|
|
9f61f9c07d
|
||
|
|
e3c3b2cbb7
|
||
|
|
0ddf3ef70d | ||
|
|
a0a5050d5e
|
||
|
|
10f1b3f87c
|
||
|
|
7011209675 | ||
|
|
274ce28e8d
|
||
|
|
1fcecdb04d
|
||
|
|
e456bb8d7a
|
||
|
|
202c785f94
|
||
|
|
7629a73e0a
|
||
|
|
ce2e3e4cd3
|
||
|
|
3320f222bb
|
||
|
|
099857b636
|
||
|
|
20adc196d9 | ||
|
|
ae891262e1
|
||
|
|
6f45f4f205 | ||
|
|
65d2d40310
|
||
|
|
fa21a029ae | ||
|
|
12e2a4edcc
|
||
|
|
78d10cf03c | ||
|
|
5d3d48e802
|
||
|
|
331ad752d1 |
@@ -24,3 +24,8 @@ build
|
||||
**/.studio/**
|
||||
|
||||
.DS_Store
|
||||
|
||||
# Discussion workflow state is local; only consolidated lessons are versioned.
|
||||
discussion/*
|
||||
!discussion/lessons/
|
||||
!discussion/lessons/**
|
||||
|
||||
@@ -8,8 +8,10 @@ This repository packages the Studio shell together with the embedded services it
|
||||
|
||||
The root project is a monorepo with these main areas:
|
||||
|
||||
- `prometeu-app`: JavaFX application entry point (`p.studio.App`).
|
||||
- `prometeu-studio`: Studio UI, workspaces, project session lifecycle, play/stop flow, and debugger-facing surfaces.
|
||||
- `prometeu-app`: Spring Boot non-web composition, concrete adapters, packaging, and JavaFX entry point (`p.studio.app.StudioLauncher`).
|
||||
- `prometeu-studio-api`: toolkit-neutral Studio contracts and operation surfaces.
|
||||
- `prometeu-studio-core`: JavaFX-free project, session, assets, shipper, runtime, and execution services.
|
||||
- `prometeu-studio-ui-javafx`: the current human-facing JavaFX adapter.
|
||||
- `prometeu-packer`: embedded packer APIs and implementation used by Studio.
|
||||
- `prometeu-compiler`: compiler core, build pipeline, frontend APIs, and the PBS frontend.
|
||||
- `prometeu-infra`: shared infrastructure used across modules.
|
||||
@@ -19,14 +21,198 @@ The root project is a monorepo with these main areas:
|
||||
|
||||
## Current Product Shape
|
||||
|
||||
The Studio shell currently organizes the product around three workspaces:
|
||||
The Studio shell currently organizes the product around four workspaces:
|
||||
|
||||
- Assets
|
||||
- Debug
|
||||
- DEV (external-agent authorization and observation)
|
||||
- Shipper
|
||||
|
||||
At runtime, the app boots an embedded packer, restores project-local Studio state, and opens the Studio launcher window. Project creation currently scaffolds a Prometeu workspace with `prometeu.json`, `src/`, `assets/`, `build/`, `cartridge/`, `.workspace/`, and local Studio metadata.
|
||||
|
||||
## External Coding Agents (MCP)
|
||||
|
||||
Studio includes its own `mcp --project <absolute-root>` mode. Configure the native
|
||||
client once; project grants and desktop restarts no longer require copying ports
|
||||
or tokens. The initial integration targets Codex on macOS.
|
||||
|
||||
1. Install/stage Studio with its bundled Java runtime (see below). New projects
|
||||
prepare the local client entry during scaffolding. Opening an existing project
|
||||
also prepares its enabled integration automatically; Studio starts the shared
|
||||
MCP server itself. **DEV → Prepare assistant** retries preparation after resolving
|
||||
a reported setup conflict. Opening a project does not grant agent control.
|
||||
2. Open the coding client in the project directory. Trust the project and reload
|
||||
MCP once if the client requests it. Studio does not alter client approval policy.
|
||||
Tools can initialize/list even before the desktop is open or access is granted.
|
||||
3. Open the project in Studio and grant control in DEV (save first if prompted).
|
||||
Active Debug prevents granting. The connector discovers access automatically.
|
||||
4. The agent acquires a task, consults project/language/SDK references, edits saved
|
||||
project files with its native tools and validates through LSP/build. SDK and
|
||||
external libraries remain read-only.
|
||||
5. Recover uncertain operations by operationId/clientRequestId lookup within the
|
||||
same task; never replay build/advance blindly. Explicitly release control when
|
||||
done. Human reclaim also revokes access; stop direct external file edits separately.
|
||||
|
||||
The client invokes the same Studio artifact over stdio. It forwards to Studio's
|
||||
project-scoped loopback service using protected, transient
|
||||
`.studio/mcp/connection.json`. The permanent `.codex/config.toml` entry contains
|
||||
installed Java/classpath/root arguments, not credentials. Both local outputs are
|
||||
ignored by Git. Unrelated client settings are preserved; tracked or conflicting
|
||||
Studio entries require deliberate resolution. `.studio/setup.json` preserves
|
||||
neutral integration intent and existing runtime/editor settings.
|
||||
|
||||
After desktop restart, grant again in DEV. Keep the same client session and
|
||||
configuration; old task identities and operation receipts are not restored.
|
||||
DEV displays connection separately from project authority. No project-local
|
||||
launcher, Python transport script or embedded chat is required.
|
||||
|
||||
### Reading external source code
|
||||
|
||||
VS Code F12 opens SDK/core and admitted libraries as read-only documents, with
|
||||
hover, continued F12 and syntax highlighting. SDK/core stay bundled; no editorial
|
||||
copies are created. After a source revision changes or a session ends, navigate
|
||||
again instead of reusing old positions.
|
||||
|
||||
For MCP, use `studio_language_query` with `operation: "definition"`, then pass a
|
||||
returned `prometeu-source:` URI to `operation: "readExternalSource"`. The response
|
||||
contains `descriptor` and `text`; hover and definition accept the same URI within
|
||||
the owning task. Another task cannot reuse it. MCP does not require VS Code open.
|
||||
External or mixed edit proposals are refused in full. Library installation/cache
|
||||
management is outside this feature. See the [extension guide](tools/vscode-extension/README.md).
|
||||
|
||||
### Installation and IntelliJ development
|
||||
|
||||
Build and stage the complete distribution, including its Java runtime:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:stageStudioInstallation
|
||||
```
|
||||
|
||||
The macOS default is `~/Library/Application Support/Prometeu/Studio/current`.
|
||||
Staging validates a new version before atomically changing `current`, retaining
|
||||
older versions for rollback and running processes. Native client registration
|
||||
uses absolute paths and argument arrays, independent of shell PATH:
|
||||
|
||||
```text
|
||||
command: <installation>/current/runtime/bin/java
|
||||
args: ["-cp", "<installation>/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", "<absolute-project-root>"]
|
||||
```
|
||||
|
||||
For development, use an isolated installation:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:stageStudioInstallation -PstudioInstallationRoot=/absolute/dev-installation
|
||||
```
|
||||
|
||||
In IntelliJ, run/debug `p.studio.app.StudioLauncher` with the `prometeu-app`
|
||||
runtime classpath and VM option `-Dstudio.installationRoot=/absolute/dev-installation`.
|
||||
The desktop and client-owned connector are separate JVMs. To debug the latter,
|
||||
add the development-only VM argument
|
||||
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005`
|
||||
before `-cp` in the local MCP entry, restart that MCP process, then use IntelliJ's
|
||||
**Remote JVM Debug** on localhost:5005. Do not commit this local configuration.
|
||||
Because manual edits to the managed entry are protected, restore its original
|
||||
content before using preparation again. Regular registration never enables JDWP.
|
||||
|
||||
The packaged automated gate checks bundled Java, upgrade/rollback, project paths
|
||||
with spaces, minimal environment, scaffold/preparation and JavaFX startup:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:installedConnectorTest
|
||||
```
|
||||
|
||||
The current production tools cover context, references, task control, LSP,
|
||||
build/pack, operation lookup/cancellation and headless execution (17 tools).
|
||||
Headless requires a runtime installation configured for the project; missing or
|
||||
incompatible installations fail explicitly. DEV is an
|
||||
observation panel, not manual Play/input for the agent's session; **Debug** retains
|
||||
the human testing workflow. Edits are preserved on cancellation; Git/review/recovery
|
||||
remain the developer's responsibility.
|
||||
|
||||
See the [MCP contract](docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md)
|
||||
for schemas, authorization, limits and delivery boundaries.
|
||||
|
||||
### Troubleshooting automation
|
||||
|
||||
| Symptom | Action |
|
||||
| --- | --- |
|
||||
| Waiting for access / desktop restarted | Open the project and grant again in DEV. Keep the existing client configuration. |
|
||||
| Stale connection / incompatible catalog | Grant fresh access, or update the installed Studio when versions differ. Do not edit transient credentials. |
|
||||
| Preparation conflict | Preserve the existing client settings; resolve a tracked/user-owned/edited Studio table explicitly, then prepare again. |
|
||||
| Acquisition rejected or project busy | Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls. |
|
||||
| `RUNTIME_UNAVAILABLE` or handshake incompatibility | Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute. |
|
||||
| `NO_FRAME_AVAILABLE` | Advance at least one frame before requesting a capture. |
|
||||
| Advance/page limit rejected | Respect advertised limits and use reference pagination. Runtime's default maximum is 600 frames per advance; requests are not silently clamped. |
|
||||
| Unknown language or missing reference | Inspect project context and the declared manifest language; use only advertised capabilities/reference IDs. PBS is a creation default, not an unknown-language fallback. |
|
||||
| Returning control reports cleanup failure | Stop the external client's direct editing separately, then retry DEV reclaim after owned-process cleanup. Do not bypass the lock or restore stale editor buffers. |
|
||||
|
||||
Language and SDK references are bundled locally; reading them does not require a
|
||||
compiler checkout or network download. SDK/external-library changes remain outside
|
||||
the game-authoring task, even when a reference exposes a limitation.
|
||||
|
||||
The real headless process adapter and task-service composition can be verified
|
||||
using an extracted runtime distribution:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime
|
||||
```
|
||||
|
||||
This gate builds an installed PBS example, launches the actual runtime, checks
|
||||
canonical PNGs and explicit reset/reboot, cancels an advance and verifies process
|
||||
cleanup. It also runs the actual app composition through saved-file LSP queries,
|
||||
rebuilds and corrective loops after compile errors and guest faults. It does not
|
||||
download a runtime or substitute a protocol fixture.
|
||||
|
||||
To verify the complete HTTP-to-runtime-to-DEV image path, run this separate gate
|
||||
in a desktop environment:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2
|
||||
```
|
||||
|
||||
It opens the real DEV view, grants control, uses an HTTP MCP client to query LSP,
|
||||
edit/build the installed PBS example and execute a fixed input timeline. PNG bytes,
|
||||
frame identities, state and fault are compared with a separate direct-JSONL runtime
|
||||
process; every decoded ImageView pixel and its visible identity/stale label are
|
||||
checked. Reset, fresh-session repetition and rebuild are included. This automated
|
||||
client is not the external coding-agent acceptance gate.
|
||||
|
||||
The same suite also exercises cancellation, disconnect/reconnect, revocation,
|
||||
project/app closure, crash and forced shutdown, corrective builds, and return to
|
||||
the real manual Debug host. These scenarios require a POSIX desktop (validated
|
||||
on macOS ARM64) and free port 7777. Only processes created by the test are killed
|
||||
or suspended. After a forced-shutdown error, an explicit second reclaim can
|
||||
acknowledge completed cleanup; control stays locked until cleanup is confirmed.
|
||||
|
||||
### Follow-ups after the AI-first implementation
|
||||
|
||||
The following findings are recorded for investigation after implementation; they
|
||||
are not considered fixed by the passing integration tests:
|
||||
|
||||
- **PBS/LSP SDK navigation:** the historical probe of the former `Input.pad()`
|
||||
API returned no location; the current input API is `Pad`/`Button` and `Touch`. Project-source navigation and indexed SDK reference
|
||||
reads work. Investigate SDK symbol resolution separately; an empty definition
|
||||
result is not evidence of missing runtime support or permission to edit the SDK.
|
||||
- **Build tooling:** the validation environment's JDK 25 triggers Kotlin's target-24
|
||||
fallback and Java/Kotlin target compatibility warnings in `buildSrc`. The targeted
|
||||
regression passes, but the toolchain/target alignment needs separate review.
|
||||
|
||||
Cross-platform desktop coverage remains a validation boundary, not a confirmed
|
||||
product defect. Baseline HTTP desktop acceptance covers macOS ARM64 and Codex CLI only. The integrated stdio flow completed its separate acceptance gates through automated validation and user-confirmed native-client, graphical-launch and IntelliJ checks; see [LSN-0077](discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md) for evidence provenance.
|
||||
|
||||
The first real Codex CLI acceptance run exercised editing, LSP, build/pack, input,
|
||||
1,110 frames, native MCP images and explicit release. The developer confirmed the
|
||||
DEV result and successfully ran the edited game using manual Debug Play afterward.
|
||||
Additional follow-ups from that run: clearer errors for oversized
|
||||
reference pages, guidance for sequential headless queries after `BUSY`, and easier
|
||||
discovery of framebuffer dimensions. Capture before the first completed frame
|
||||
correctly returns `NO_FRAME_AVAILABLE`; it is not a runtime defect. Noninteractive
|
||||
clients must also provide an approval path for MCP work calls; the acceptance used
|
||||
Codex's approval review with a project-scoped workspace-write sandbox.
|
||||
|
||||
The completed baseline's architecture, acceptance evidence and post-implementation
|
||||
follow-ups are consolidated in [LSN-0076](discussion/lessons/DSC-0068-studio-headless-runtime-ai-first/LSN-0076-ai-first-studio-through-shared-authority-and-headless-evidence.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
- JDK 21 or newer recommended for local development
|
||||
@@ -64,9 +250,11 @@ Generate the aggregated coverage report:
|
||||
If you are new to the codebase, this order is usually the fastest path:
|
||||
|
||||
1. Start at `prometeu-app` to see application bootstrap.
|
||||
2. Read `prometeu-studio` for the shell, workspaces, and user-facing flows.
|
||||
3. Read `prometeu-packer` for asset and packaging boundaries.
|
||||
4. Read `prometeu-compiler` when you need compiler or PBS language behavior.
|
||||
2. Read `prometeu-studio-api` and `prometeu-studio-core` for Studio contracts and application services.
|
||||
3. Read `prometeu-studio-ui-javafx` for the current shell, workspaces, and human-facing flows.
|
||||
4. Read `prometeu-app` for Spring composition and provider gateways.
|
||||
5. Read `prometeu-packer` for asset and packaging boundaries.
|
||||
6. Read `prometeu-compiler` when you need compiler or PBS language behavior.
|
||||
|
||||
## Specs And Architecture
|
||||
|
||||
@@ -76,4 +264,4 @@ Important reference surfaces:
|
||||
- `docs/specs/packer/`: packer specifications
|
||||
- `docs/vm-arch/`: VM and ISA architecture references
|
||||
|
||||
These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.
|
||||
These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":14,"AGD":15,"DEC":10,"PLN":19,"LSN":28,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"open","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
@@ -1,14 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":14,"AGD":15,"DEC":12,"PLN":19,"LSN":28,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0010","file":"DEC-0010-studio-controlled-non-frontend-editor-write-wave.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0013"},{"id":"DEC-0011","file":"DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0014"}],"plans":[],"lessons":[]}
|
||||
@@ -1,15 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":14,"AGD":15,"DEC":13,"PLN":29,"LSN":28,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0010","file":"DEC-0010-studio-controlled-non-frontend-editor-write-wave.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0013"},{"id":"DEC-0011","file":"DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0014"}],"plans":[{"id":"PLN-0019","file":"PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0020","file":"PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0021","file":"PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0022","file":"PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0023","file":"PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0024","file":"PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0025","file":"PLN-0025-implement-fe-semantic-highlight-consumption.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[{"id":"AGD-0015","file":"AGD-0015-studio-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02","ref_agenda":"AGD-0015"}],"plans":[{"id":"PLN-0026","file":"PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0027","file":"PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0028","file":"PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]}],"lessons":[]}
|
||||
@@ -1,15 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":15,"AGD":16,"DEC":13,"PLN":29,"LSN":29,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[{"id":"AGD-0015","file":"AGD-0015-studio-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02","ref_agenda":"AGD-0015"}],"plans":[{"id":"PLN-0026","file":"PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0027","file":"PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0028","file":"PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]}],"lessons":[]}
|
||||
@@ -1,19 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":19,"AGD":20,"DEC":17,"PLN":38,"LSN":31,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
|
||||
{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0017","status":"open","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0015","file":"DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03","ref_agenda":"AGD-0018"}],"plans":[{"id":"PLN-0033","file":"PLN-0033-inline-hint-spec-and-contract-propagation.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0034","file":"PLN-0034-lsp-inline-hint-transport-contract.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0035","file":"PLN-0035-pbs-inline-type-hint-payload-production.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0036","file":"PLN-0036-studio-inline-hint-rendering-and-rollout.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0018","status":"open","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[{"id":"AGD-0019","file":"AGD-0019-studio-project-open-state-under-dot-studio.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04"}],"decisions":[{"id":"DEC-0016","file":"DEC-0016-project-local-studio-state-under-dot-studio.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04","ref_agenda":"AGD-0019"}],"plans":[{"id":"PLN-0037","file":"PLN-0037-project-local-studio-state-store-and-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04","ref_decisions":["DEC-0016"]}],"lessons":[]}
|
||||
@@ -1,20 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":20,"AGD":21,"DEC":18,"PLN":39,"LSN":32,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
|
||||
{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0017","status":"open","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0015","file":"DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03","ref_agenda":"AGD-0018"}],"plans":[{"id":"PLN-0033","file":"PLN-0033-inline-hint-spec-and-contract-propagation.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0034","file":"PLN-0034-lsp-inline-hint-transport-contract.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0035","file":"PLN-0035-pbs-inline-type-hint-payload-production.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0036","file":"PLN-0036-studio-inline-hint-rendering-and-rollout.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0019","status":"open","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[{"id":"AGD-0020","file":"AGD-0020-project-local-setup-separate-from-main-studio-state.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04"}],"decisions":[{"id":"DEC-0017","file":"DEC-0017-project-local-setup-separate-from-session-state.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04","ref_agenda":"AGD-0020"}],"plans":[{"id":"PLN-0038","file":"PLN-0038-separate-project-local-setup-from-session-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04","ref_decisions":["DEC-0017"]}],"lessons":[]}
|
||||
@@ -1,22 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":22,"AGD":23,"DEC":20,"PLN":41,"LSN":34,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
|
||||
{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0017","status":"open","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-studio-editor-inline-type-hints-for-let-bindings.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0015","file":"DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03","ref_agenda":"AGD-0018"}],"plans":[{"id":"PLN-0033","file":"PLN-0033-inline-hint-spec-and-contract-propagation.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0034","file":"PLN-0034-lsp-inline-hint-transport-contract.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0035","file":"PLN-0035-pbs-inline-type-hint-payload-production.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]},{"id":"PLN-0036","file":"PLN-0036-studio-inline-hint-rendering-and-rollout.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03","ref_decisions":["DEC-0015"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"open","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[{"id":"AGD-0022","file":"AGD-0022-studio-frontend-editor-write-and-save-wave.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04"}],"decisions":[{"id":"DEC-0019","file":"DEC-0019-studio-frontend-editor-write-and-save-wave.md","status":"accepted","created_at":"2026-04-04","updated_at":"2026-04-04","ref_agenda":"AGD-0022"}],"plans":[{"id":"PLN-0040","file":"PLN-0040-studio-frontend-editor-write-and-save-wave.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04","ref_decisions":["DEC-0019"]}],"lessons":[]}
|
||||
@@ -1,31 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":31,"AGD":34,"DEC":31,"PLN":62,"LSN":47,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0030","status":"done","ticket":"studio-scene-pack-runtime-binary-contract","title":"Studio scene pack contract for runtime SCENE binary payload","created_at":"2026-04-24","updated_at":"2026-05-01","tags":["studio","packer","runtime","scene","asset-pack","binary-format","tiled"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0030-studio-scene-pack-runtime-binary-contract/LSN-0046-canonical-scene-owns-editorial-truth-while-pack-stays-request-driven.md","status":"done","created_at":"2026-05-01","updated_at":"2026-05-01"}]}
|
||||
{"type":"discussion","id":"DSC-0029","status":"done","ticket":"studio-frame-composer-syscall-and-sprite-alignment","title":"Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["studio","compiler","pbs","stdlib","runtime-alignment","abi","syscall","frame-composer","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
|
||||
{"type":"discussion","id":"DSC-0028","status":"done","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-23","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0028-studio-tiled-parser-assets-scene-asset-type/LSN-0045-asset-owned-scene-bank-and-tiled-xml-workflow.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0027","status":"abandoned","ticket":"studio-scene-workspace","title":"Scene Workspace for SCENE Authoring","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["studio","workspace","scene","tilemap","asset","runtime-alignment"],"agendas":[{"id":"AGD-0029","file":"AGD-0029-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted agenda and its downstream work."}],"decisions":[{"id":"DEC-0026","file":"DEC-0026-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0029","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted decision and stop using it as normative guidance."}],"plans":[{"id":"PLN-0049","file":"PLN-0049-scene-workspace-spec-and-boundary-propagation.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0050","file":"PLN-0050-scene-workspace-shell-and-project-state-foundations.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0051","file":"PLN-0051-scene-artifact-and-assets-handoff-contract.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0052","file":"PLN-0052-scene-workspace-wave-1-tilemap-editor.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"packer-pipeline-metadata-ownership","title":"Pipeline Metadata Ownership and Runtime Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["packer","metadata","runtime-contract","tooling","studio"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0025-packer-pipeline-metadata-ownership/LSN-0039-runtime-header-boundary-and-tooling-owned-pipeline-metadata.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"jacoco-reports-consolidation","title":"JaCoCo Reports Consolidation in Gradle","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["infra","gradle","jacoco","coverage","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0038-jacoco-reports-consolidation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"},{"id":"LSN-0044","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0044-jenkins-jacoco-alignment.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-04-23","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0002-palette-management-in-studio/LSN-0042-schema-driven-palette-authoring-and-local-metadata-events.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"abandoned","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-04-24","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"abandoned","created_at":"2026-03-26","updated_at":"2026-04-24","_override_reason":"Explicit user request on 2026-04-24 to abandon AGD-0004 because the agenda is no longer valid."}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
|
||||
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0016-studio-editor-scope-guides-and-brace-anchoring/LSN-0034-active-scope-gutter-and-frontend-owned-structural-anchors.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0035","file":"discussion/lessons/DSC-0017-studio-editor-inline-type-hints-for-let-bindings/LSN-0035-frontend-owned-inline-hints-with-decorative-inline-rendering.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0043-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"gradle-version-catalog-migration","title":"Move dependency version management to Version Catalog (TOML)","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["gradle","buildSrc","dependency-management","version-catalog"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0023-gradle-version-catalog-migration/LSN-0037-gradle-version-catalog-adoption.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
@@ -1,35 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":35,"AGD":38,"DEC":35,"PLN":75,"LSN":47,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0034","status":"in_progress","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-06","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[{"id":"AGD-0037","file":"AGD-0037-frontend-semantic-host-projection-flexibility.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06"}],"decisions":[{"id":"DEC-0034","file":"DEC-0034-frontend-semantic-host-projection-flexibility.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06","ref_agenda":"AGD-0037"}],"plans":[{"id":"PLN-0072","file":"PLN-0072-frontend-semantic-host-projection-contract.md","status":"done","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0034"]},{"id":"PLN-0073","file":"PLN-0073-lsp-semantic-host-projection-transport.md","status":"done","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0034"]},{"id":"PLN-0074","file":"PLN-0074-vscode-semantic-host-projection-adapter.md","status":"done","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0034"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0033","status":"in_progress","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-06","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[{"id":"AGD-0036","file":"AGD-0036-frontend-visual-theme-spec-and-css-retirement.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06"}],"decisions":[{"id":"DEC-0033","file":"DEC-0033-frontend-visual-theme-spec-and-css-retirement.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06","ref_agenda":"AGD-0036"}],"plans":[{"id":"PLN-0068","file":"PLN-0068-frontend-visual-contract-and-pbs-migration.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0069","file":"PLN-0069-lsp-visual-theme-transport-and-selection.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0070","file":"PLN-0070-studio-visual-theme-adapter-and-css-retirement.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0071","file":"PLN-0071-vscode-dynamic-theme-translation-adapter.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0032","status":"in_progress","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-05","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[{"id":"AGD-0035","file":"AGD-0035-studio-new-lsp-api-and-v1-boundary.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05"}],"decisions":[{"id":"DEC-0032","file":"DEC-0032-studio-new-lsp-api-and-v1-boundary.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05","ref_agenda":"AGD-0035"}],"plans":[{"id":"PLN-0065","file":"PLN-0065-lsp-boundary-and-module-scaffolding.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]},{"id":"PLN-0066","file":"PLN-0066-project-scoped-lsp-server-lifecycle-in-studio.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]},{"id":"PLN-0067","file":"PLN-0067-compiler-backed-dumb-lsp-server-baseline.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0031","status":"in_progress","ticket":"studio-editor-workspace-cleanup","title":"Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados","created_at":"2026-05-05","updated_at":"2026-05-05","tags":["studio","editor","cleanup","vfs","lsp","migration"],"agendas":[{"id":"AGD-0034","file":"AGD-0034-vscode-editor-migration-feasibility.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-studio-editor-workspace-cleanup.md","status":"in_progress","created_at":"2026-05-05","updated_at":"2026-05-05","ref_agenda":"AGD-0034"}],"plans":[{"id":"PLN-0062","file":"PLN-0062-shell-session-and-state-cleanup-after-editor-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0063","file":"PLN-0063-legacy-lsp-and-vfs-module-removal-with-runtime-preservation.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0064","file":"PLN-0064-normative-test-and-lesson-cleanup-for-editor-stack-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0030","status":"done","ticket":"studio-scene-pack-runtime-binary-contract","title":"Studio scene pack contract for runtime SCENE binary payload","created_at":"2026-04-24","updated_at":"2026-05-01","tags":["studio","packer","runtime","scene","asset-pack","binary-format","tiled"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0030-studio-scene-pack-runtime-binary-contract/LSN-0046-canonical-scene-owns-editorial-truth-while-pack-stays-request-driven.md","status":"done","created_at":"2026-05-01","updated_at":"2026-05-01"}]}
|
||||
{"type":"discussion","id":"DSC-0029","status":"done","ticket":"studio-frame-composer-syscall-and-sprite-alignment","title":"Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["studio","compiler","pbs","stdlib","runtime-alignment","abi","syscall","frame-composer","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
|
||||
{"type":"discussion","id":"DSC-0028","status":"done","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-23","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0028-studio-tiled-parser-assets-scene-asset-type/LSN-0045-asset-owned-scene-bank-and-tiled-xml-workflow.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0027","status":"abandoned","ticket":"studio-scene-workspace","title":"Scene Workspace for SCENE Authoring","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["studio","workspace","scene","tilemap","asset","runtime-alignment"],"agendas":[{"id":"AGD-0029","file":"AGD-0029-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted agenda and its downstream work."}],"decisions":[{"id":"DEC-0026","file":"DEC-0026-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0029","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted decision and stop using it as normative guidance."}],"plans":[{"id":"PLN-0049","file":"PLN-0049-scene-workspace-spec-and-boundary-propagation.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0050","file":"PLN-0050-scene-workspace-shell-and-project-state-foundations.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0051","file":"PLN-0051-scene-artifact-and-assets-handoff-contract.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0052","file":"PLN-0052-scene-workspace-wave-1-tilemap-editor.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"packer-pipeline-metadata-ownership","title":"Pipeline Metadata Ownership and Runtime Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["packer","metadata","runtime-contract","tooling","studio"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0025-packer-pipeline-metadata-ownership/LSN-0039-runtime-header-boundary-and-tooling-owned-pipeline-metadata.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"jacoco-reports-consolidation","title":"JaCoCo Reports Consolidation in Gradle","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["infra","gradle","jacoco","coverage","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0038-jacoco-reports-consolidation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"},{"id":"LSN-0044","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0044-jenkins-jacoco-alignment.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-04-23","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0002-palette-management-in-studio/LSN-0042-schema-driven-palette-authoring-and-local-metadata-events.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"abandoned","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-04-24","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"abandoned","created_at":"2026-03-26","updated_at":"2026-04-24","_override_reason":"Explicit user request on 2026-04-24 to abandon AGD-0004 because the agenda is no longer valid."}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
|
||||
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0016-studio-editor-scope-guides-and-brace-anchoring/LSN-0034-active-scope-gutter-and-frontend-owned-structural-anchors.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0035","file":"discussion/lessons/DSC-0017-studio-editor-inline-type-hints-for-let-bindings/LSN-0035-frontend-owned-inline-hints-with-decorative-inline-rendering.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0043-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"gradle-version-catalog-migration","title":"Move dependency version management to Version Catalog (TOML)","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["gradle","buildSrc","dependency-management","version-catalog"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0023-gradle-version-catalog-migration/LSN-0037-gradle-version-catalog-adoption.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
@@ -1,35 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":35,"AGD":38,"DEC":35,"PLN":75,"LSN":49,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}
|
||||
{"type":"discussion","id":"DSC-0033","status":"in_progress","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-06","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[{"id":"AGD-0036","file":"AGD-0036-frontend-visual-theme-spec-and-css-retirement.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06"}],"decisions":[{"id":"DEC-0033","file":"DEC-0033-frontend-visual-theme-spec-and-css-retirement.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06","ref_agenda":"AGD-0036"}],"plans":[{"id":"PLN-0068","file":"PLN-0068-frontend-visual-contract-and-pbs-migration.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0069","file":"PLN-0069-lsp-visual-theme-transport-and-selection.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0070","file":"PLN-0070-studio-visual-theme-adapter-and-css-retirement.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0071","file":"PLN-0071-vscode-dynamic-theme-translation-adapter.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0032","status":"done","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-07","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0032-studio-new-lsp-api-and-v1-boundary/LSN-0047-project-scoped-lsp-boundary-and-protocol-containment.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}
|
||||
{"type":"discussion","id":"DSC-0031","status":"in_progress","ticket":"studio-editor-workspace-cleanup","title":"Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados","created_at":"2026-05-05","updated_at":"2026-05-05","tags":["studio","editor","cleanup","vfs","lsp","migration"],"agendas":[{"id":"AGD-0034","file":"AGD-0034-vscode-editor-migration-feasibility.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-studio-editor-workspace-cleanup.md","status":"in_progress","created_at":"2026-05-05","updated_at":"2026-05-05","ref_agenda":"AGD-0034"}],"plans":[{"id":"PLN-0062","file":"PLN-0062-shell-session-and-state-cleanup-after-editor-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0063","file":"PLN-0063-legacy-lsp-and-vfs-module-removal-with-runtime-preservation.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0064","file":"PLN-0064-normative-test-and-lesson-cleanup-for-editor-stack-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0030","status":"done","ticket":"studio-scene-pack-runtime-binary-contract","title":"Studio scene pack contract for runtime SCENE binary payload","created_at":"2026-04-24","updated_at":"2026-05-01","tags":["studio","packer","runtime","scene","asset-pack","binary-format","tiled"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0030-studio-scene-pack-runtime-binary-contract/LSN-0046-canonical-scene-owns-editorial-truth-while-pack-stays-request-driven.md","status":"done","created_at":"2026-05-01","updated_at":"2026-05-01"}]}
|
||||
{"type":"discussion","id":"DSC-0029","status":"done","ticket":"studio-frame-composer-syscall-and-sprite-alignment","title":"Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["studio","compiler","pbs","stdlib","runtime-alignment","abi","syscall","frame-composer","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
|
||||
{"type":"discussion","id":"DSC-0028","status":"done","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-23","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0028-studio-tiled-parser-assets-scene-asset-type/LSN-0045-asset-owned-scene-bank-and-tiled-xml-workflow.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0027","status":"abandoned","ticket":"studio-scene-workspace","title":"Scene Workspace for SCENE Authoring","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["studio","workspace","scene","tilemap","asset","runtime-alignment"],"agendas":[{"id":"AGD-0029","file":"AGD-0029-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted agenda and its downstream work."}],"decisions":[{"id":"DEC-0026","file":"DEC-0026-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0029","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted decision and stop using it as normative guidance."}],"plans":[{"id":"PLN-0049","file":"PLN-0049-scene-workspace-spec-and-boundary-propagation.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0050","file":"PLN-0050-scene-workspace-shell-and-project-state-foundations.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0051","file":"PLN-0051-scene-artifact-and-assets-handoff-contract.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0052","file":"PLN-0052-scene-workspace-wave-1-tilemap-editor.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"packer-pipeline-metadata-ownership","title":"Pipeline Metadata Ownership and Runtime Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["packer","metadata","runtime-contract","tooling","studio"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0025-packer-pipeline-metadata-ownership/LSN-0039-runtime-header-boundary-and-tooling-owned-pipeline-metadata.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"jacoco-reports-consolidation","title":"JaCoCo Reports Consolidation in Gradle","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["infra","gradle","jacoco","coverage","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0038-jacoco-reports-consolidation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"},{"id":"LSN-0044","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0044-jenkins-jacoco-alignment.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-04-23","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0002-palette-management-in-studio/LSN-0042-schema-driven-palette-authoring-and-local-metadata-events.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"abandoned","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-04-24","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"abandoned","created_at":"2026-03-26","updated_at":"2026-04-24","_override_reason":"Explicit user request on 2026-04-24 to abandon AGD-0004 because the agenda is no longer valid."}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
|
||||
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0016-studio-editor-scope-guides-and-brace-anchoring/LSN-0034-active-scope-gutter-and-frontend-owned-structural-anchors.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0035","file":"discussion/lessons/DSC-0017-studio-editor-inline-type-hints-for-let-bindings/LSN-0035-frontend-owned-inline-hints-with-decorative-inline-rendering.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0043-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"gradle-version-catalog-migration","title":"Move dependency version management to Version Catalog (TOML)","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["gradle","buildSrc","dependency-management","version-catalog"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0023-gradle-version-catalog-migration/LSN-0037-gradle-version-catalog-adoption.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
@@ -1,66 +0,0 @@
|
||||
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":54,"PLN":133,"LSN":70,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0065","status":"done","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0067","file":"discussion/lessons/DSC-0065-multi-frontend-avoid-premature-abstractions/LSN-0067-multi-frontend-phase-rejects-premature-infrastructure.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||
{"type":"discussion","id":"DSC-0064","status":"done","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0066","file":"discussion/lessons/DSC-0064-multi-frontend-architectural-tests/LSN-0066-archunit-guards-java-multi-frontend-boundaries.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||
{"type":"discussion","id":"DSC-0063","status":"done","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0065","file":"discussion/lessons/DSC-0063-multi-frontend-synthetic-test-frontend/LSN-0065-synthetic-test-frontend-proves-pipeline-neutrality.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||
{"type":"discussion","id":"DSC-0062","status":"done","ticket":"multi-frontend-pvm-neutrality","title":"Neutralidade da PVM e identificacao PBX independente de PBS","created_at":"2026-07-15","updated_at":"2026-09-18","tags":["vm-arch","runtime","pvm","pbx","compiler","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0061","file":"discussion/lessons/DSC-0062-multi-frontend-pvm-neutrality/LSN-0061-pbx-runtime-boundary.md","status":"done","created_at":"2026-09-18","updated_at":"2026-09-18"}]}
|
||||
{"type":"discussion","id":"DSC-0061","status":"done","ticket":"multi-frontend-sdk-canonical-definition","title":"Auditoria e centralizacao gradual da definicao canonica do SDK","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","sdk","stdlib","hostcalls","intrinsics","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0064","file":"discussion/lessons/DSC-0061-multi-frontend-sdk-canonical-definition/LSN-0064-runtime-owns-console-abi-pbs-is-delivery.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||
{"type":"discussion","id":"DSC-0060","status":"done","ticket":"multi-frontend-validation-boundaries","title":"Separar validacoes de linguagem e validacoes de plataforma","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","compiler-pbs","backend","validation","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0063","file":"discussion/lessons/DSC-0060-multi-frontend-validation-boundaries/LSN-0063-language-vs-platform-validation-ownership.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||
{"type":"discussion","id":"DSC-0059","status":"done","ticket":"multi-frontend-common-lifecycle","title":"Extrair lifecycle comum das responsabilidades do frontend PBS","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","compiler-pbs","lifecycle","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0062","file":"discussion/lessons/DSC-0059-multi-frontend-common-lifecycle/LSN-0062-common-lifecycle-assembly-stage.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||
{"type":"discussion","id":"DSC-0058","status":"done","ticket":"multi-frontend-serializable-ir","title":"Manter a IR comum serializavel por design","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","ir","backend","serialization","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0060","file":"discussion/lessons/DSC-0058-multi-frontend-serializable-ir/LSN-0060-data-contract-first-for-serializable-irbackend.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0057","status":"done","ticket":"multi-frontend-frontend-backend-contract","title":"Estabilizar contrato entre frontend e backend comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","ir","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0059","file":"discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0056","status":"done","ticket":"multi-frontend-remove-pbs-branches","title":"Generalizar o contrato LSP/editorial para frontends","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","studio","frontend","coupling","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0058","file":"discussion/lessons/DSC-0056-multi-frontend-remove-pbs-branches/LSN-0058-generic-frontend-editorial-contract-for-lsp.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0055","status":"done","ticket":"multi-frontend-compiler-vs-language-services","title":"Separar compilacao de servicos editoriais de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","lsp","editor","frontend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0056","file":"discussion/lessons/DSC-0055-multi-frontend-compiler-vs-language-services/LSN-0056-compile-first-frontends-with-optional-editorial-capabilities.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0054","status":"done","ticket":"multi-frontend-provider-contract","title":"Introduzir provider completo de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","registry","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0053","status":"open","ticket":"pbs-lsp-call-and-type-hierarchy","title":"PBS LSP Call and Type Hierarchy","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","call-hierarchy","type-hierarchy"],"agendas":[{"id":"AGD-0056","file":"AGD-0056-pbs-lsp-call-and-type-hierarchy.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0052","status":"open","ticket":"pbs-lsp-document-links","title":"PBS LSP Document Links","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","document-links","imports"],"agendas":[{"id":"AGD-0055","file":"AGD-0055-pbs-lsp-document-links.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0051","status":"open","ticket":"pbs-lsp-diagnostics-ux","title":"PBS LSP Diagnostics UX","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","diagnostics","ux"],"agendas":[{"id":"AGD-0054","file":"AGD-0054-pbs-lsp-diagnostics-ux.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0050","status":"open","ticket":"pbs-lsp-folding-and-selection-ranges","title":"PBS LSP Folding and Selection Ranges","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","folding","selection-range"],"agendas":[{"id":"AGD-0053","file":"AGD-0053-pbs-lsp-folding-and-selection-ranges.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0049","status":"open","ticket":"pbs-lsp-completion-depth","title":"PBS LSP Completion Depth","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","completion"],"agendas":[{"id":"AGD-0052","file":"AGD-0052-pbs-lsp-completion-depth.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0048","status":"open","ticket":"pbs-lsp-performance-cache-and-snapshots","title":"PBS LSP Performance Cache and Snapshots","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","performance","caching"],"agendas":[{"id":"AGD-0051","file":"AGD-0051-pbs-lsp-performance-cache-and-snapshots.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0047","status":"open","ticket":"pbs-lsp-semantic-tokens-semantic-classification","title":"PBS LSP Semantic Token Classification","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","semantic-tokens"],"agendas":[{"id":"AGD-0050","file":"AGD-0050-pbs-lsp-semantic-token-classification.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0046","status":"open","ticket":"pbs-lsp-import-assistance","title":"PBS LSP Import Assistance","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","imports","completion"],"agendas":[{"id":"AGD-0049","file":"AGD-0049-pbs-lsp-import-assistance.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0045","status":"open","ticket":"pbs-lsp-formatting","title":"PBS LSP Formatting","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","formatting"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-pbs-lsp-formatting.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0044","status":"open","ticket":"pbs-lsp-code-actions","title":"PBS LSP Code Actions and Quick Fixes","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","code-actions","quick-fix"],"agendas":[{"id":"AGD-0047","file":"AGD-0047-pbs-lsp-code-actions-and-quick-fixes.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0043","status":"open","ticket":"pbs-lsp-rename-symbol","title":"PBS LSP Rename Symbol","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","rename"],"agendas":[{"id":"AGD-0046","file":"AGD-0046-pbs-lsp-rename-symbol.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0042","status":"open","ticket":"pbs-lsp-workspace-symbols","title":"PBS LSP Workspace Symbols","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","workspace-symbols"],"agendas":[{"id":"AGD-0045","file":"AGD-0045-pbs-lsp-workspace-symbols.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0041","status":"open","ticket":"pbs-lsp-document-symbols-outline","title":"PBS LSP Document Symbols and Outline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["studio","lsp","vscode","compiler-pbs","editor","outline","document-symbols"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-pbs-lsp-document-symbols-and-outline.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0040","status":"done","ticket":"pbs-lsp-find-references","title":"PBS LSP Find References","created_at":"2026-07-15","updated_at":"2026-09-21","tags":["studio","lsp","vscode","compiler-pbs","editor","references"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0069","file":"discussion/lessons/DSC-0040-pbs-lsp-find-references/LSN-0069-pbs-find-references-is-the-physical-inverse-of-definition.md","status":"done","created_at":"2026-09-21","updated_at":"2026-09-21"}]}
|
||||
{"type":"discussion","id":"DSC-0039","status":"done","ticket":"pbs-lsp-go-to-definition","title":"PBS LSP Go to Definition","created_at":"2026-07-15","updated_at":"2026-09-21","tags":["studio","lsp","vscode","compiler-pbs","editor","definition"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0068","file":"discussion/lessons/DSC-0039-pbs-lsp-go-to-definition/LSN-0068-pbs-go-to-definition-uses-editorial-lookup-and-physical-files.md","status":"done","created_at":"2026-09-21","updated_at":"2026-09-21"}]}
|
||||
{"type":"discussion","id":"DSC-0038","status":"done","ticket":"studio-packer-rgba8888-asset-pipeline","title":"Studio and Packer RGBA8888 Asset Pipeline Alignment","created_at":"2026-05-23","updated_at":"2026-07-14","tags":["studio","packer","assets","glyph-bank","palette","rgba8888","runtime-alignment"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0038-studio-packer-rgba8888-asset-pipeline/LSN-0053-rgba8888-is-the-canonical-studio-packer-palette-contract.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
|
||||
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-14","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0037-pbs-autocomplete-parameter-names/LSN-0052-canonical-callable-parameter-names-through-pbs-editor-assistance.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]}
|
||||
{"type":"discussion","id":"DSC-0036","status":"done","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-07-15","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0057","file":"discussion/lessons/DSC-0036-pbs-symbol-documentation-and-hover-markdown/LSN-0057-compiler-owned-pbs-doc-markdown-for-editor-assistance.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0035","status":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
|
||||
{"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}
|
||||
{"type":"discussion","id":"DSC-0033","status":"done","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-08","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0033-frontend-visual-theme-spec-and-css-retirement/LSN-0050-frontend-owned-visual-themes-with-structured-contract-and-host-adapters.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
|
||||
{"type":"discussion","id":"DSC-0032","status":"done","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-07","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0032-studio-new-lsp-api-and-v1-boundary/LSN-0047-project-scoped-lsp-boundary-and-protocol-containment.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}
|
||||
{"type":"discussion","id":"DSC-0031","status":"done","ticket":"studio-editor-workspace-cleanup","title":"Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados","created_at":"2026-05-05","updated_at":"2026-05-08","tags":["studio","editor","cleanup","vfs","lsp","migration"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0031-studio-editor-workspace-cleanup/LSN-0049-remove-the-embedded-editor-stack-before-rebuilding-code-workflows.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
|
||||
{"type":"discussion","id":"DSC-0030","status":"done","ticket":"studio-scene-pack-runtime-binary-contract","title":"Studio scene pack contract for runtime SCENE binary payload","created_at":"2026-04-24","updated_at":"2026-05-01","tags":["studio","packer","runtime","scene","asset-pack","binary-format","tiled"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0030-studio-scene-pack-runtime-binary-contract/LSN-0046-canonical-scene-owns-editorial-truth-while-pack-stays-request-driven.md","status":"done","created_at":"2026-05-01","updated_at":"2026-05-01"}]}
|
||||
{"type":"discussion","id":"DSC-0029","status":"done","ticket":"studio-frame-composer-syscall-and-sprite-alignment","title":"Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["studio","compiler","pbs","stdlib","runtime-alignment","abi","syscall","frame-composer","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
|
||||
{"type":"discussion","id":"DSC-0028","status":"done","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-23","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0028-studio-tiled-parser-assets-scene-asset-type/LSN-0045-asset-owned-scene-bank-and-tiled-xml-workflow.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0027","status":"abandoned","ticket":"studio-scene-workspace","title":"Scene Workspace for SCENE Authoring","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["studio","workspace","scene","tilemap","asset","runtime-alignment"],"agendas":[{"id":"AGD-0029","file":"AGD-0029-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted agenda and its downstream work."}],"decisions":[{"id":"DEC-0026","file":"DEC-0026-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0029","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted decision and stop using it as normative guidance."}],"plans":[{"id":"PLN-0049","file":"PLN-0049-scene-workspace-spec-and-boundary-propagation.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0050","file":"PLN-0050-scene-workspace-shell-and-project-state-foundations.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0051","file":"PLN-0051-scene-artifact-and-assets-handoff-contract.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0052","file":"PLN-0052-scene-workspace-wave-1-tilemap-editor.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"packer-pipeline-metadata-ownership","title":"Pipeline Metadata Ownership and Runtime Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["packer","metadata","runtime-contract","tooling","studio"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0025-packer-pipeline-metadata-ownership/LSN-0039-runtime-header-boundary-and-tooling-owned-pipeline-metadata.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"jacoco-reports-consolidation","title":"JaCoCo Reports Consolidation in Gradle","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["infra","gradle","jacoco","coverage","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0038-jacoco-reports-consolidation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"},{"id":"LSN-0044","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0044-jenkins-jacoco-alignment.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-04-23","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0002-palette-management-in-studio/LSN-0042-schema-driven-palette-authoring-and-local-metadata-events.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"abandoned","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-04-24","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"abandoned","created_at":"2026-03-26","updated_at":"2026-04-24","_override_reason":"Explicit user request on 2026-04-24 to abandon AGD-0004 because the agenda is no longer valid."}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"done","ticket":"variable-tile-bank-palette-serialization","title":"Variable Glyph Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-07-14","tags":["packer","legacy-import","glyph-bank","palette-serialization","rgba8888","runtime-alignment"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0054","file":"discussion/lessons/DSC-0005-variable-glyph-bank-palette-serialization/LSN-0054-runtime-owned-variable-glyph-palette-counts.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
|
||||
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
|
||||
{"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
|
||||
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0016-studio-editor-scope-guides-and-brace-anchoring/LSN-0034-active-scope-gutter-and-frontend-owned-structural-anchors.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"studio-editor-inline-type-hints-for-let-bindings","title":"Inline Type Hints for Let Bindings in the Studio Editor","created_at":"2026-04-03","updated_at":"2026-04-06","tags":["studio","editor","inline-hints","inlay-hints","lsp","pbs","type-inference"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0035","file":"discussion/lessons/DSC-0017-studio-editor-inline-type-hints-for-let-bindings/LSN-0035-frontend-owned-inline-hints-with-decorative-inline-rendering.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"studio-project-local-studio-state-under-dot-studio","title":"Persist project-local Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","shell","layout","setup"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0018-studio-project-local-studio-state-under-dot-studio/LSN-0031-project-local-studio-state-and-lifecycle-safe-layout-restoration.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
|
||||
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0043-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"gradle-version-catalog-migration","title":"Move dependency version management to Version Catalog (TOML)","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["gradle","buildSrc","dependency-management","version-catalog"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0023-gradle-version-catalog-migration/LSN-0037-gradle-version-catalog-adoption.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
+8
@@ -8,6 +8,14 @@ tags: [studio, lsp, vscode, compiler-pbs, editor, definition]
|
||||
|
||||
# PBS go-to-definition uses editorial lookup and physical files
|
||||
|
||||
> Historical policy: DEC-0062 / PLN-0141 explicitly superseded the physical-only
|
||||
> definition restriction in October 2026. SDK/core and dependencies now use
|
||||
> revision-bound read-only external documents for supporting clients. Compiler
|
||||
> Spec 23 and Studio Spec 11 define the current contract. The original lesson below
|
||||
> preserves the earlier decision; it must not be read as prohibiting today's
|
||||
> external navigation. References, symbols, links and hierarchies retain their
|
||||
> separately scoped contracts. See LSN-0078 for the implementation and pitfalls.
|
||||
|
||||
## Original Problem
|
||||
|
||||
PBS editor assistance already had compiler-backed completion, hover, and signature help (`LSN-0051`). Users still could not jump from a use to a declaration. Wave 1 explicitly deferred `go to definition`.
|
||||
|
||||
+141
@@ -0,0 +1,141 @@
|
||||
---
|
||||
id: LSN-0070
|
||||
ticket: pbs-lsp-document-symbols-outline
|
||||
title: PBS outline is an AST-backed document-symbol tree
|
||||
created: 2026-09-21
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, outline, document-symbols]
|
||||
---
|
||||
|
||||
# PBS outline is an AST-backed document-symbol tree
|
||||
|
||||
## Original Problem
|
||||
|
||||
PBS already had compiler-backed completion, hover, signature help, go-to-definition (`LSN-0068`), and find-references (`LSN-0069`). VS Code Outline stayed empty. Long `.pbs` files had to be scanned by hand.
|
||||
|
||||
The risk was building outline from semantic success (so the tree vanishes while typing), flattening to `SymbolInformation`, inventing a Document Symbol SPI, or stuffing workspace search and folding into the same payload.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
PBS Document Symbols is the LSP projection of the **named declaration tree of the open `.pbs` file**, with the **recovered AST as backbone**.
|
||||
|
||||
Durable locks from `DEC-0054` (AGD-0044 Q1 A, Q2 AST tree, Q3 A, Q4 A, Q5 A, Q6 `.pbs`-only, Q7 existing kinds):
|
||||
|
||||
1. Presence, hierarchy, and ranges come from the document AST. Kind and `detail` may use cheap semantic enrichment. Semantics must not drop a named declaration still in the syntax tree, and must not require full analysis.
|
||||
2. Named `TopDecl` plus syntactic members:
|
||||
- `fn` → Function, no children;
|
||||
- `declare struct` → Struct, children: fields, `ctor`s, methods;
|
||||
- `declare service` → Service, children: methods;
|
||||
- `declare contract` → Contract, children: signatures as methods;
|
||||
- `declare host` → Host, children: signatures;
|
||||
- `declare builtin type` → Builtin type, children: projection fields and signatures;
|
||||
- `declare enum` → Enum, children: cases;
|
||||
- `declare error` → Error, children: labels;
|
||||
- `declare callback` → Callback, no children;
|
||||
- `declare global` / `const` → Global / Const, no children;
|
||||
- `implements Contract for Owner` → top-level Contract named `contractName`, `detail` = owner name, children: methods.
|
||||
Locals, parameters, `this`, imports, and comments stay out. Private fields stay in. Overloads stay siblings. Host and builtin type appear only if the open file declares them.
|
||||
3. Recovered AST is enough. Unnamed `InvalidDecl` is omitted. Named decls survive later semantic errors. No `PbsAst.File` → empty list. Do not invent nodes from text or token pairs.
|
||||
4. Keep the capability on aggregated `FrontendLanguageService.documentSymbols` (default empty) plus a hierarchical DTO (`name`, `kind`, optional `detail`, range offsets, selection offsets, `children`). No file path on the DTO. PBS builds the tree in `prometeu-frontend-pbs`. Common LSP must not import `p.studio.compiler.pbs.*`. No Document Symbol SPI.
|
||||
5. Advertise `documentSymbolProvider`. Payload is hierarchical `DocumentSymbol`, not flat `SymbolInformation`. `range` is the declaration span. `selectionRange` is the name span only if the AST already has one; this wave reuses the declaration span. Do not scan tokens for identifier spans. VS Code stays a thin client.
|
||||
6. First wave is the current `.pbs` only. Out: imported supplementals, `mod.barrel`, locals, parameters, imports, comments, virtual documents, workspace symbols, folding, rename, snapshot cache. Server order is AST declaration order, not alphabetical.
|
||||
7. Reuse `FrontendSymbolKind` / `PbsEditorialSymbolKind`. LSP projects to the closest host `SymbolKind`. Name is the identifier. `detail` may carry the AST signature (`(a: int) -> int`). Attributes such as `[Init]` do not enter the name.
|
||||
|
||||
Outline does not jump to another file. The physical-file destination policy of definition/references is not the outline policy.
|
||||
|
||||
Spec 23 §8.3 now also states: document symbols are the named declaration tree of the requested document; recovered syntax is enough; a missing syntax tree is empty; this is not a workspace index, folding ranges, or a foreign-file navigation list.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
| Layer | What landed |
|
||||
|---|---|
|
||||
| PBS editorial | `PbsAstDocumentSymbols` walks `PbsAst.File.topDecls` in source order. `PbsEditorialSupportService.documentSymbols` delegates to that walk. |
|
||||
| Generic contract | `FrontendLanguageService.documentSymbols` defaults to `List.of()`. `FrontendDocumentSymbol` is hierarchical and pathless. |
|
||||
| PBS mapping | `PBSFrontendLanguageService` requires `editorialContext.syntaxTree()` to be `PbsAst.File`. Barrels and unknown trees stay empty. Kinds map with `valueOf(kind.name())`. |
|
||||
| LSP | `documentSymbolProvider`, `textDocument/documentSymbol`, hierarchical `DocumentSymbol`. Nested enum/error children project to `EnumMember`. Compile-only frontends stay empty. |
|
||||
| VS Code | Unchanged thin client. |
|
||||
|
||||
`mod.barrel` is assembled as `BarrelFile`, not `PbsAst.File`, so `astByFile` has no barrel outline. Empty is the honest first-wave result.
|
||||
|
||||
Error case labels have no per-label span in the AST. Children reuse the parent `ErrorDecl` span rather than scanning tokens.
|
||||
|
||||
## Examples
|
||||
|
||||
Outline of a file is the declarations in that file, not imports or locals:
|
||||
|
||||
```pbs
|
||||
import { Log } from @sdk:log;
|
||||
|
||||
fn helper() -> int { return 42; }
|
||||
|
||||
fn frame() -> void {
|
||||
let local = 1;
|
||||
helper(local);
|
||||
}
|
||||
```
|
||||
|
||||
Outline: `helper`, `frame`. Not `Log`, not `local`.
|
||||
|
||||
Struct members and overloads as siblings:
|
||||
|
||||
```pbs
|
||||
declare struct Vec(x: int) {
|
||||
ctor make(x: int) { return; }
|
||||
fn blend(dx: int, dy: int) -> int { return dx; }
|
||||
}
|
||||
|
||||
fn helper() -> int { return 42; }
|
||||
fn helper(value: int) -> int { return value; }
|
||||
```
|
||||
|
||||
Outline: `Vec` (`x`, `make`, `blend`), then two `helper` siblings. Private field `x` is present. `detail` on `blend` is `(dx: int, dy: int) -> int`.
|
||||
|
||||
Recovered parse keeps the named decl:
|
||||
|
||||
```pbs
|
||||
declare ;
|
||||
fn ok() -> int { return 1; }
|
||||
```
|
||||
|
||||
Outline: `ok`. The unnamed `InvalidDecl` is omitted.
|
||||
|
||||
`[Init] fn init()` still names the symbol `init`.
|
||||
|
||||
`implements TickLike for Point` is a top-level node named `TickLike` with detail `Point`.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Do not wait for semantic analysis to succeed before showing outline. The tree must survive broken intermediate edits.
|
||||
|
||||
Do not omit private fields because they are not in `mod.barrel`. Outline is for the author of this file.
|
||||
|
||||
Do not collapse overloads. AST identity forbids merging declaration sets.
|
||||
|
||||
Do not walk `File.imports` or supplemental imported `TopDecl`s. Those symbols are not declared in this document.
|
||||
|
||||
Do not implement outline for `mod.barrel` in this contract. Barrel AST is a different root. Empty is correct until a later decision.
|
||||
|
||||
Do not scan tokens to invent a tighter `selectionRange`. This wave uses the declaration span.
|
||||
|
||||
Do not put a file path on `FrontendDocumentSymbol`. The host already has the document URI. Outline is not go-to-definition.
|
||||
|
||||
Do not reuse the physical-file jump rule of `LSN-0068` as an outline destination policy. Clicking outline stays inside the buffer.
|
||||
|
||||
Do not overload document symbols with folding or scope guides (`LSN-0034`, `AGD-0053`).
|
||||
|
||||
Do not split a Document Symbol SPI “for future languages”. PBS is a real consumer of `FrontendLanguageService` (`LSN-0067`).
|
||||
|
||||
Do not treat this lesson as closing workspace symbols, folding, rename, document links, or hierarchy.
|
||||
|
||||
## References
|
||||
|
||||
- Agenda: `AGD-0044` (Q1 A, Q2 AST tree, Q3 A, Q4 A, Q5 A, Q6 `.pbs`-only, Q7 existing kinds)
|
||||
- Decision: `DEC-0054`
|
||||
- Plan: `PLN-0133`
|
||||
- Spec 23 §8.3 — optional document symbols; recovered AST tree of the requested document
|
||||
- `LSN-0068` — definition is a jump; outline is not
|
||||
- `LSN-0069` — references invert definition identity
|
||||
- `LSN-0034` — do not overload document symbols with structural anchors
|
||||
- `LSN-0058` — generic `FrontendLanguageService` for LSP
|
||||
- `LSN-0047` — protocol stays in `lsp-v1`; compiler owns semantics
|
||||
- `LSN-0067` — no SPI without a real in-repo consumer
|
||||
- Still open: `AGD-0045` workspace symbols, `AGD-0046` rename, `AGD-0051` snapshots, `AGD-0053` folding, `AGD-0055` document links, `AGD-0056` hierarchy
|
||||
+149
@@ -0,0 +1,149 @@
|
||||
---
|
||||
id: LSN-0071
|
||||
ticket: pbs-lsp-workspace-symbols
|
||||
title: PBS workspace symbols are a physical named-declaration search
|
||||
created: 2026-09-21
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, workspace-symbols]
|
||||
---
|
||||
|
||||
# PBS workspace symbols are a physical named-declaration search
|
||||
|
||||
## Original Problem
|
||||
|
||||
PBS already had compiler-backed completion, hover, signature help, go-to-definition (`LSN-0068`), find-references (`LSN-0069`), and an AST-backed outline of the open `.pbs` file (`LSN-0070`). VS Code workspace search (`Ctrl+T` / `workspace/symbol`) stayed empty.
|
||||
|
||||
The risk was treating workspace symbols as a second outline, inventing a `SymbolId` index, waiting for snapshot cache (`AGD-0051`), or returning stdlib/SDK hits whose declarations are still virtual paths (`/virtual/stdlib`). Workspace symbols is a jump. Outline is not.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
PBS Workspace Symbols is the LSP projection of a **flat named-declaration search** over **regular filesystem files** of the current analysis, flattening the **same outline set** and using the **same physical-file destination policy** as definition.
|
||||
|
||||
Durable locks from `DEC-0055` (AGD-0045 Q1 A, Q2 A, Q3 A, Q4 A, Q5 A, Q6 first-wave exclusions):
|
||||
|
||||
1. Emit only declarations whose `fileTable` handle is a regular filesystem file. Virtual stdlib/SDK, including `/virtual/stdlib`, is omitted. Do not invent virtual documents, `untitled:` buffers, or synthetic URIs.
|
||||
2. `workspace/symbol` does not require an open text document. The server obtains the project analysis surface (`astByFile` / `projectSurface`) from `analyze()`. Missing surface → empty list.
|
||||
3. The set is the flatten, file by file, of the named-declaration tree locked by outline (`LSN-0070`):
|
||||
- `fn` → Function;
|
||||
- `declare struct` → Struct plus fields, `ctor`s, methods;
|
||||
- `declare service` → Service plus methods;
|
||||
- `declare contract` → Contract plus signatures;
|
||||
- `declare host` → Host plus signatures;
|
||||
- `declare builtin type` → Builtin type plus projection fields and signatures;
|
||||
- `declare enum` → Enum plus cases;
|
||||
- `declare error` → Error plus labels;
|
||||
- `declare callback` → Callback;
|
||||
- `declare global` / `const` → Global / Const;
|
||||
- `implements Contract for Owner` → `contractName`, kind CONTRACT, `detail` = owner, plus methods.
|
||||
Locals, parameters, `this`, imports, and comments stay out. Private fields stay in. Overloads stay sibling hits. Unnamed `InvalidDecl` is omitted. Named decls survive later semantic errors.
|
||||
4. First wave is `.pbs` whose recovered root is `PbsAst.File`. `mod.barrel` (`BarrelFile`) stays empty. Presence, name, kind, `detail`, and spans come from recovered AST. Do not invent nodes from text search.
|
||||
5. Query is a case-insensitive substring of `name` only. Blank query returns the full first-wave corpus. Do not match `detail`, path, `containerName`, or qualified `Vec.blend`. No fuzzy ranking, no `top N`. After the filter, order is stable by name, then path, then start offset.
|
||||
6. `containerName` is the parent name for members and empty for top-level declarations. `detail` may repeat the outline AST signature. Attributes such as `[Init]` do not enter the name.
|
||||
7. Keep the capability on aggregated `FrontendLanguageService`. Add `workspaceSymbols` (default empty) plus a flat DTO with `name`, `kind`, optional `detail`, `containerName`, absolute path, and offsets. Do not reuse pathless `FrontendDocumentSymbol`. PBS flattens in `prometeu-frontend-pbs`. Common LSP must not import `p.studio.compiler.pbs.*`. No Workspace Symbol SPI, `SymbolId`, `RefIndex`, or snapshot cache.
|
||||
8. Advertise `workspaceSymbolProvider` when the frontend exposes a language service. Payload is flat `SymbolInformation`. Do not emit hierarchical `DocumentSymbol` on this request. Compile-only frontends stay empty. VS Code stays a thin client.
|
||||
|
||||
Spec 23 §8.3 now also states: workspace symbols are a flat search of named declarations in compiler-known physical source files of the current analysis; recovered syntax is enough; a missing analysis surface is empty; the request must not require an open document; a declaration without a physical file is omitted; this is not outline, folding, a persistent index, or navigation to virtual locations.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
| Layer | What landed |
|
||||
|---|---|
|
||||
| PBS editorial | `PbsAstWorkspaceSymbols` flattens `PbsAstDocumentSymbols` and filters by name. `PbsEditorialSupportService.workspaceSymbols(ast, query)` delegates to that flatten. |
|
||||
| Generic contract | `FrontendWorkspaceRequest` (`projectRoot`, `query`). `FrontendWorkspaceSymbol` carries path. `FrontendLanguageService.workspaceSymbols` defaults to `List.of()`. `prepareEditorialContext(FrontendPhaseContext)` defaults to empty so a workspace request can obtain project surface without a `FileId`. |
|
||||
| PBS mapping | Project-level `prepareEditorialContext` attaches `fileTable` + `astByFile`. Regular `PbsAst.File` entries are flattened; non-regular handles are skipped. Results sort by name, path, offset. |
|
||||
| LSP | `workspaceSymbolProvider`, `workspace/symbol` on `PrometeuWorkspaceService` (no document URI). `CompilerLanguageServiceBridge` analyzes the project with an empty overlay map. Mapper emits flat `SymbolInformation`. Nested enum/error hits with a container project to `EnumMember`. Compile-only frontends stay empty. |
|
||||
| VS Code | Unchanged thin client. |
|
||||
|
||||
`workspace/symbol` in this wave reads the project on disk. Unsaved editor overlays are not shared into the search. Empty is honest until a later overlay/snapshot decision.
|
||||
|
||||
`mod.barrel` is still `BarrelFile`, not `PbsAst.File`. Empty barrel hits are the honest first-wave result.
|
||||
|
||||
Error case labels still have no per-label span. Flattened children reuse the parent `ErrorDecl` span, same as outline.
|
||||
|
||||
## Examples
|
||||
|
||||
Workspace search of a project file is the flatten of that file's outline, not imports or locals:
|
||||
|
||||
```pbs
|
||||
import { Log } from @sdk:log;
|
||||
|
||||
fn helper() -> int { return 42; }
|
||||
|
||||
fn frame() -> void {
|
||||
let local = 1;
|
||||
helper(local);
|
||||
}
|
||||
```
|
||||
|
||||
Query `frame` → `frame`. Query `helper` → `helper`. Query empty → `helper`, `frame` (plus other physical decls), sorted. Not `Log`, not `local`.
|
||||
|
||||
Members keep a container; overloads stay siblings:
|
||||
|
||||
```pbs
|
||||
declare struct Vec(x: int) {
|
||||
ctor make(x: int) { return; }
|
||||
fn blend(dx: int, dy: int) -> int { return dx; }
|
||||
}
|
||||
|
||||
fn helper() -> int { return 42; }
|
||||
fn helper(value: int) -> int { return value; }
|
||||
```
|
||||
|
||||
Query `blend` → method `blend` with `containerName` `Vec`. Query `helper` → two hits. Query `Vec.blend` → empty (this wave matches `name` only).
|
||||
|
||||
Stdlib remains hover-only while the handle is virtual:
|
||||
|
||||
```pbs
|
||||
import { Gfx } from @sdk:gfx;
|
||||
Gfx.clear(0);
|
||||
```
|
||||
|
||||
Query `Gfx` is empty. F12 on `Gfx.clear` is already empty (`LSN-0068`). Workspace search does not reopen that jump.
|
||||
|
||||
Recovered parse keeps the named decl:
|
||||
|
||||
```pbs
|
||||
declare ;
|
||||
fn ok() -> int { return 1; }
|
||||
```
|
||||
|
||||
Query empty → `ok`. The unnamed `InvalidDecl` is omitted.
|
||||
|
||||
`[Init] fn init()` still names the symbol `init`.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Do not implement workspace symbols as workspace text search in `lsp-v1` or in the VS Code extension. It will lie about overloads, members, and imports.
|
||||
|
||||
Do not reuse `FrontendDocumentSymbol`. Outline is pathless because the host already has the document URI. Workspace symbols is a jump and must carry a path.
|
||||
|
||||
Do not require an open editor buffer to answer `workspace/symbol`. Analyze the project and walk `astByFile`.
|
||||
|
||||
Do not include `/virtual/stdlib` so Ctrl+T on `Gfx` “does something”. Empty is the honest result until those sources are regular files.
|
||||
|
||||
Do not wait for snapshot cache. References already walks the current analysis request-locally. Snapshots (`AGD-0051`) can make the walk cheaper without changing this contract.
|
||||
|
||||
Do not add a `SymbolId` index “for rename later”. Outline already named the declarations; definition already named the destination.
|
||||
|
||||
Do not match `containerName`, path, or `Vec.blend` in this wave. The query is a substring of `name`.
|
||||
|
||||
Do not emit hierarchical `DocumentSymbol` on `workspace/symbol`. That payload is outline.
|
||||
|
||||
Do not treat unsaved overlay absence as a missing feature of this contract. First-wave analysis is the project on disk.
|
||||
|
||||
Do not split a Workspace Symbol SPI “for future languages”. PBS is a real consumer of `FrontendLanguageService` (`LSN-0067`).
|
||||
|
||||
Do not treat this lesson as closing rename, snapshots, folding, document links, or hierarchy.
|
||||
|
||||
## References
|
||||
|
||||
- Agenda: `AGD-0045` (Q1 A, Q2 A, Q3 A, Q4 A, Q5 A, Q6 first-wave exclusions)
|
||||
- Decision: `DEC-0055`
|
||||
- Plan: `PLN-0134`
|
||||
- Spec 23 §8.3 — optional workspace symbols; physical-file-or-omit; no open document required
|
||||
- `LSN-0070` — outline set this feature flattens
|
||||
- `LSN-0068` — physical-file destination this feature reuses
|
||||
- `LSN-0069` — project `astByFile` walk already exists for references
|
||||
- `LSN-0058` — generic `FrontendLanguageService` for LSP
|
||||
- `LSN-0047` — protocol stays in `lsp-v1`; compiler owns semantics
|
||||
- `LSN-0067` — no SPI without a real in-repo consumer
|
||||
- Still open: `AGD-0046` rename, `AGD-0051` snapshots, `AGD-0053` folding, `AGD-0055` document links, `AGD-0056` hierarchy
|
||||
+128
@@ -0,0 +1,128 @@
|
||||
---
|
||||
id: LSN-0072
|
||||
ticket: pbs-lsp-rename-symbol
|
||||
title: PBS rename is a validated physical workspace edit
|
||||
created: 2026-09-22
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, rename]
|
||||
---
|
||||
|
||||
# PBS rename is a validated physical workspace edit
|
||||
|
||||
## Original Problem
|
||||
|
||||
PBS already had compiler-backed completion, hover, signature help, go-to-definition (`LSN-0068`), find-references (`LSN-0069`), outline (`LSN-0070`), and workspace symbols (`LSN-0071`). Users still could not rename a symbol through the editor. Manual text edits miss uses or rewrite unrelated overloads, comments, strings, and same-name declarations.
|
||||
|
||||
The risk was a file-local rename, a lexeme replace, a new `SymbolId` / `RefIndex`, snapshot cache (`AGD-0051`) as a prerequisite, virtual stdlib documents, or a successful empty `WorkspaceEdit` that pretends the symbol changed.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
PBS Rename Symbol is the LSP projection of a **validated `WorkspaceEdit`** over **physical identifier spans** of the **same identity definition already returns**.
|
||||
|
||||
Durable locks from `DEC-0056` (AGD-0046 Q1–Q6 = A):
|
||||
|
||||
1. Identity is the physical declaration-location set from definition. Do not text-search. Do not add `SymbolId` or a persistent `RefIndex`.
|
||||
2. Sites are identifier tokens whose definition intersects that identity, plus identifier-sized declaration name spans. Overloads of the same name in the same owner rewrite together. Members rewrite only that member. Comments, strings, and homonyms of another identity stay.
|
||||
3. Walk regular `fileTable` files of the current `analyze()` surface. Omit `/virtual/stdlib` and other non-regular handles. Every edit location must be a compiler-known physical source file.
|
||||
4. Refuse when physical identity is empty: builtins, virtual stdlib/SDK, unresolved names, keywords, comments, strings, `this`, `Self`. Refuse `mod.barrel`. Refuse `declare error` case labels that have no per-label span.
|
||||
5. Exception: a local or parameter name span is renameable even when definition at that offset is empty. Identity becomes that name span; uses are identifiers whose definition intersects it.
|
||||
6. Refuse when the cursor lexeme is an import alias (`item.alias()` distinct from `item.name()`), including uses of that alias. Do not follow alias definition and rewrite the export. Export rename happens only when the cursor writes the original name. Export rewrite must not change `as Alias` tokens or uses that spell a differing alias.
|
||||
7. `prepareRename` validates the cursor and returns the identifier range, or null. `rename` also validates the new name: PBS identifier, not a keyword, no collision in the same binding space (top-level `fn`/`service`/`global`/`const`, local/param in the same scope, field in the same struct, method in the same owner, case in the same enum), ignoring rewritten sites and the overload set. Failure is an LSP error. Never return a successful empty `WorkspaceEdit`. The server does not write files and does not rename paths.
|
||||
8. Keep the capability on aggregated `FrontendLanguageService`. `prepareRename` defaults empty; `rename` defaults unsupported. PBS maps in `prometeu-frontend-pbs`. Common LSP must not import `p.studio.compiler.pbs.*`. No Rename SPI. Advertise `renameProvider` with `prepareProvider`. Compile-only stays unsupported. VS Code stays a thin client.
|
||||
|
||||
Spec 23 §8.3 now also states: rename is a validated workspace edit of identifier spans in compiler-known physical source files; identity is definition; local/param name spans remain renameable; alias, virtual, and error-label cursors refuse; invalid names and collisions are protocol errors, not empty success; the server does not write files; `prepareProvider` is advertised when rename is exposed.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
| Layer | What landed |
|
||||
|---|---|
|
||||
| PBS editorial | `PbsEditorialSupportService.planRename` builds identity from definition or local/param name span, refuses aliases and error labels, walks `IDENTIFIER` tokens whose definition intersects identity and whose lexeme is the original name, then validates identifier/keyword/collision. |
|
||||
| Generic contract | `FrontendLanguageService.prepareRename` defaults empty. `rename` defaults `FrontendRenameResult.unsupported()`. `FrontendRenameEdit` is path + offsets + `newText`. Applied results reject an empty edit list. |
|
||||
| PBS mapping | `PBSFrontendLanguageService` reuses `projectDocuments` and `toFrontendLocation`. Empty physical identity is refuse, even if editorial sites exist on virtual handles. |
|
||||
| LSP | `renameSupported`, `prepareRename`, `rename`. Mapper advertises `RenameOptions.prepareProvider`. Refused rename is `ResponseErrorException`, not an empty `WorkspaceEdit`. Compile-only does not advertise. |
|
||||
| VS Code | Unchanged thin client. |
|
||||
|
||||
Stdlib and SDK modules remain virtual (`/virtual/stdlib/...`). F2 on `Gfx.clear` is refused, matching empty F12 / Shift+F12. Hover is unchanged.
|
||||
|
||||
`let total` at the binding itself still has empty definition. Rename uses the name span as identity so F2 on the binding works.
|
||||
|
||||
## Examples
|
||||
|
||||
Same-file function, including overloads and the declaring identifier. Comment and string stay:
|
||||
|
||||
```pbs
|
||||
fn helper() -> int { return 1; }
|
||||
fn helper(value: int) -> int { return value; }
|
||||
|
||||
fn frame() -> void {
|
||||
helper();
|
||||
helper(2);
|
||||
// helper
|
||||
let text = "helper";
|
||||
}
|
||||
```
|
||||
|
||||
F2 on `helper` → `aid` rewrites both declarations and both calls.
|
||||
|
||||
Local name span:
|
||||
|
||||
```pbs
|
||||
fn frame() -> void {
|
||||
let total = 1;
|
||||
return total;
|
||||
}
|
||||
```
|
||||
|
||||
F2 on `let total` or on the use rewrites both identifier sites.
|
||||
|
||||
Alias is refused. Export rename keeps the local alias:
|
||||
|
||||
```pbs
|
||||
import { Log as Logger } from @sdk:log;
|
||||
Logger.info("a");
|
||||
```
|
||||
|
||||
F2 on `Logger` or `Logger.info` is refused. F2 on a physical `Log` declaration rewrites the original name and `import { Log as Logger }`, and leaves `Logger` / `Logger.info`.
|
||||
|
||||
Builtins and virtual stdlib stay hover-only:
|
||||
|
||||
```pbs
|
||||
let n: int = 1;
|
||||
Gfx.clear(5);
|
||||
```
|
||||
|
||||
Invalid new names (`fn`, `1ab`) and collisions (`helper` → existing `frame`) fail with an LSP error.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Do not implement rename as workspace text search in `lsp-v1` or in the VS Code extension. It will rewrite comments, strings, overloads of another identity, and import aliases.
|
||||
|
||||
Do not follow definition through an import alias. `Logger` currently resolves to `Log`'s span; a blind inverse-of-definition rename would rewrite the export.
|
||||
|
||||
Do not return a successful empty `WorkspaceEdit` for a refused cursor. The editor will treat that as “renamed”.
|
||||
|
||||
Do not skip the local/param name-span exception. F2 on `let total` is the common case, and definition there is empty.
|
||||
|
||||
Do not rewrite `declare error` case labels by using the parent `ErrorDecl` span. Those labels have no per-label span.
|
||||
|
||||
Do not wait for snapshot cache. Rename reuses the request-local walk already used by references.
|
||||
|
||||
Do not treat empty/refused stdlib rename as a missing feature. Virtual paths are not regular files.
|
||||
|
||||
Do not split a Rename SPI “for future languages”. PBS is a real consumer of `FrontendLanguageService` (`LSN-0067`).
|
||||
|
||||
Do not treat this lesson as closing snapshots, folding, document links, hierarchy, code actions, formatting, file rename, or local-alias rename.
|
||||
|
||||
## References
|
||||
|
||||
- Agenda: `AGD-0046` (Q1–Q6 = A)
|
||||
- Decision: `DEC-0056`
|
||||
- Plan: `PLN-0135`
|
||||
- Spec 23 §8.3 — optional rename; physical-file-or-empty; alias refuse; error instead of empty success; `prepareProvider`
|
||||
- Spec: `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md` §4.3–4.4
|
||||
- `LSN-0068` — definition identity this feature writes
|
||||
- `LSN-0069` — physical inverse that supplies usage sites
|
||||
- `LSN-0051` — wave 1 deferred rename
|
||||
- `LSN-0058` — generic `FrontendLanguageService` for LSP
|
||||
- `LSN-0047` — protocol stays in `lsp-v1`; compiler owns semantics
|
||||
- `LSN-0067` — no SPI without a real in-repo consumer
|
||||
- Still open: `AGD-0051` snapshots, `AGD-0053` folding, `AGD-0055` document links, `AGD-0056` hierarchy
|
||||
+130
@@ -0,0 +1,130 @@
|
||||
---
|
||||
id: LSN-0073
|
||||
ticket: pbs-lsp-code-actions
|
||||
title: PBS quick fixes are frontend repairs transported by the LSP
|
||||
created: 2026-09-22
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, code-actions, quick-fix]
|
||||
---
|
||||
|
||||
# PBS quick fixes are frontend repairs transported by the LSP
|
||||
|
||||
## Original Problem
|
||||
|
||||
PBS diagnostics already reach the editor, but the server did not advertise `codeActionProvider`. A user could see a duplicate attribute or a bad `InitAllowed` and still had to repair it by hand.
|
||||
|
||||
The tempting shortcut was a code-to-edit table in the LSP. That shortcut does not work. Compiler `Diagnostic` values carry a stable code, phase, template, placeholders, span, and related locations, but the reserved-attribute reports use the short constructor: empty placeholders, and the English sentence is the only fine discriminator. `E_SEM_MALFORMED_RESERVED_ATTRIBUTE` covers Doc without `markdown`, a wrong payload, empty markdown, an unknown argument, `InitAllowed` with arguments, an out-of-range `AssetLowering`, and a bad `Host` shape. A switch on the code cannot pick a safe edit without reading the message. Diagnostic wording is rendering, not identity. Code actions are an optional editorial capability: the frontend owns the meaning, and the LSP transports it.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
PBS quick fix is one `WorkspaceEdit` tied to one diagnostic of the requested physical document. The frontend produces the repair from the syntax tree. The LSP does not invent it.
|
||||
|
||||
Durable locks from `DEC-0057` (AGD-0047: scope A, producer B, residence B, first wave C):
|
||||
|
||||
1. This wave is quick fix only. No organize-imports, source action, refactor, function or struct stub, code lens, or server command.
|
||||
2. The server does not write files. The client applies the edit.
|
||||
3. Each repair names the stable diagnostic code, the primary span of that diagnostic, and exactly one local text edit. The LSP must not keep a code-to-edit table and must not read the diagnostic message to build the edit.
|
||||
4. The repair is computed on `textDocument/codeAction` from the current document analysis. It is not a required field of compiler `Diagnostic`, and it is not published inside `publishDiagnostics`, including `data`.
|
||||
5. `publishDiagnostics` carries the stable compiler code on `Diagnostic.code` so the client can echo it. Source, severity, message, and related information stay as they were. Those presentation questions remain with `AGD-0054`.
|
||||
6. A repair is returned only when the request context contains a diagnostic with the same code and the same primary range. An empty diagnostic list returns an empty action list. An `only` filter that does not include quick fix returns an empty action list.
|
||||
7. Each item is a QuickFix `CodeAction`, not a `Command`. The edit touches one file, the requested physical document, and contains one `TextEdit`. There is no lazy resolve.
|
||||
8. A path that is not a compiler-known regular file, including `/virtual/stdlib`, gets no edit.
|
||||
9. If the frontend does not expose the capability, the server does not advertise `codeActionProvider`. A request that arrives anyway returns an empty list, not a protocol error. Absence of a fix is not a refused cursor.
|
||||
10. PBS exposes the capability. Another frontend does not gain it merely by having a language service.
|
||||
11. The first wave is two shapes, not three diagnostic codes.
|
||||
- For every extra reserved attribute the declaration validator already reports as `E_SEM_DUPLICATE_RESERVED_ATTRIBUTE`, delete exactly that occurrence's span. Do not delete the first occurrence, the declaration, or neighboring whitespace.
|
||||
- For an `InitAllowed` attribute with a non-empty argument list on a host signature, the shape the validator reports as `E_SEM_MALFORMED_RESERVED_ATTRIBUTE` when the file is an interface module, replace that attribute span with `[InitAllowed]`. Do not emit that repair for any other attribute that shares the code. `[InitAllowed()]` is not diagnosed today and gets no repair.
|
||||
12. Nothing else gets a quick fix in this wave. In particular: inserting `[Doc(markdown = """""")]` or any other Doc rewrite, inserting an empty or incomplete `[Host]` or `[BuiltinType]`, `W_SEM_IGNORED_VALUE`, unresolved imports, an invalid reserved-attribute target, parse errors, unresolved overloads, and method stubs.
|
||||
|
||||
`AGD-0048` still owns formatting. `AGD-0049` still owns import assistance and organize-imports. `AGD-0054` still owns range, related locations, and diagnostic presentation. The PBS diagnostics spec does not gain a mandatory remediation field.
|
||||
|
||||
Spec 23 §8.3 now states the shared contract: code actions are quick fixes only; the frontend produces each repair from the document syntax; tooling transports it and does not parse the message or switch on codes; the published diagnostic carries the stable code; a repair is returned only for a matching context diagnostic; the edit is one physical file; the server does not write files, return a command, or require resolve; a missing capability is an empty list, not an error; virtual documents get no edit.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
| Layer | What landed |
|
||||
|---|---|
|
||||
| PBS repairs | `PbsQuickFixCollector` walks the same attribute surfaces as `PbsDeclarationSemanticsValidator`, including the interface-module gate. Duplicate reserved attributes become an empty replacement of the extra span. The first `InitAllowed` with arguments on an interface host signature becomes `[InitAllowed]`. |
|
||||
| Source kind | `PbsSemanticReadSurface.sourceKindByFile` records the kind used to parse each file. A missing kind means project rules, so a project `declare host` does not pretend the validator emitted the interface-only `InitAllowed` diagnostic. |
|
||||
| Generic contract | `FrontendLanguageService.codeActionsSupported` defaults false. `codeActions` defaults empty. `FrontendCodeAction` is title, diagnostic code, path, offsets, and `newText`. Empty `newText` is a deletion and is allowed. |
|
||||
| PBS mapping | `PBSFrontendLanguageService` exposes the capability and returns repairs only for the requested regular file. `/virtual/stdlib` fails `Files.isRegularFile` and produces nothing. |
|
||||
| LSP | `BaselineDocumentIssue.code` is copied onto `Diagnostic.code`. `data` stays unset. The bridge drops repairs whose code and range do not match a context diagnostic. `PrometeuTextDocumentService.codeAction` honors the quick-fix `only` filter and never fails the request for “no fix”. |
|
||||
| Protocol | `codeActionProvider` is `CodeActionOptions` with kind `quickfix` and `resolveProvider` false, and only when the frontend reports support. Mapped actions are `CodeAction` values with a `WorkspaceEdit`. They are not `Command`s. |
|
||||
|
||||
Titles are `Remove duplicate reserved attribute` and `Remove InitAllowed arguments`.
|
||||
|
||||
## Examples
|
||||
|
||||
Duplicate `Doc` on a project file. The first copy stays. Each later copy is deleted at its own span:
|
||||
|
||||
```pbs
|
||||
[Doc(markdown = """
|
||||
First.
|
||||
""")]
|
||||
[Doc(markdown = """
|
||||
Second.
|
||||
""")]
|
||||
fn duplicated() -> void { return; }
|
||||
```
|
||||
|
||||
The quick fix removes the second attribute and leaves `First.`. A context diagnostic with the same range but code `E_SEM_MALFORMED_RESERVED_ATTRIBUTE` produces no action. An empty diagnostic list produces no action.
|
||||
|
||||
Malformed or empty Doc is visible and not repairable here:
|
||||
|
||||
```pbs
|
||||
[Doc(text = """
|
||||
Wrong argument.
|
||||
""")]
|
||||
fn malformed() -> void { return; }
|
||||
```
|
||||
|
||||
`InitAllowed` with arguments is repaired only on an interface-module host signature:
|
||||
|
||||
```pbs
|
||||
declare host Gfx {
|
||||
[Host(module = "gfx2d", name = "clear", version = 1)]
|
||||
[InitAllowed(flag = 1)]
|
||||
fn clear() -> void;
|
||||
|
||||
[Host(module = "gfx2d", name = "fill", version = 1)]
|
||||
[InitAllowed()]
|
||||
fn fill() -> void;
|
||||
}
|
||||
```
|
||||
|
||||
`clear` becomes `[InitAllowed]`. `fill` is already valid to the validator, so `[InitAllowed()]` is left alone. The same `InitAllowed(flag = 1)` inside a project file does not get that repair, because the validator does not emit the malformed-attribute diagnostic there.
|
||||
|
||||
The same collector deletes the extra copy of `BuiltinType`, `IntrinsicCall`, `BuiltinConst`, `Host`, and `AssetLowering` when the validator reports `E_SEM_DUPLICATE_RESERVED_ATTRIBUTE` for that surface. A malformed `Host` that merely shares the malformed-attribute code gets no edit.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Do not choose the edit in `prometeu-lsp` by switching on `E_SEM_MALFORMED_RESERVED_ATTRIBUTE` or by parsing the English message. The code is too coarse, and the message is not the identity.
|
||||
|
||||
Do not store the repair on compiler `Diagnostic` or in `Diagnostic.data`. Compilation and quick fix stay different surfaces. The published code exists so the client can echo it back.
|
||||
|
||||
Do not match on `Diagnostic.source` as if it were the long-term identity field. Today the bridge still copies the code into `source` for the existing presentation. The code-action match uses `Diagnostic.code`. `AGD-0054` may change `source` later.
|
||||
|
||||
Do not delete the first duplicate, and do not trim the whitespace around the deleted span. That cleanup is formatting and belongs to `AGD-0048`.
|
||||
|
||||
Do not insert `[Doc(markdown = """""")]`, an empty `[Host]`, or an empty `[BuiltinType]`. Those edits trade one diagnostic for another, or invent a declaration.
|
||||
|
||||
Do not treat `W_SEM_IGNORED_VALUE` as a source edit. Discard exists in lowering, not as PBS syntax.
|
||||
|
||||
Do not offer the `InitAllowed` rewrite for `[InitAllowed()]` or for a project file. The validator does not diagnose those shapes as “arguments not allowed”, so there is no diagnostic to attach.
|
||||
|
||||
Do not return a protocol error when there is no fix. Rename refuses a bad cursor with an error. Quick fix answers “nothing to do” with an empty list.
|
||||
|
||||
Do not advertise `codeActionProvider` for every frontend that has a language service. The default capability is unsupported.
|
||||
|
||||
Do not treat this lesson as closing formatting, import assistance, diagnostic presentation, snapshots, folding, document links, or hierarchy.
|
||||
|
||||
## References
|
||||
|
||||
- Agenda: `AGD-0047` (scope A, producer B, residence B, first wave C)
|
||||
- Decision: `DEC-0057`
|
||||
- Plan: `PLN-0136`
|
||||
- Spec 23 §8.3 — optional code actions; frontend-owned repair; match by code and range; empty list when unsupported
|
||||
- Spec: `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` — wording is not identity; remediation stays outside the v1 diagnostic minimum
|
||||
- `LSN-0056` — code actions are an optional editorial capability
|
||||
- `LSN-0058` — generic `FrontendLanguageService` for the LSP
|
||||
- `LSN-0067` — no new editorial SPI without a real consumer; PBS implements the existing language service
|
||||
- Still open: `AGD-0048` formatting, `AGD-0049` import assistance, `AGD-0054` diagnostics UX, `AGD-0051` snapshots, `AGD-0056` hierarchy
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
---
|
||||
id: LSN-0074
|
||||
ticket: pbs-lsp-remaining-editor-surface
|
||||
title: PBS remaining editor surface is frontend-owned and transported by the LSP
|
||||
created: 2026-09-22
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor]
|
||||
---
|
||||
|
||||
# PBS remaining editor surface is frontend-owned and transported by the LSP
|
||||
|
||||
## Original Problem
|
||||
|
||||
Nine open LSP agendas still described formatting, imports, semantic tokens, snapshots, completion, folding, diagnostics, document links, and call hierarchy as if none of that surface existed. By the time those agendas were still open, the server already advertised hover, completion, signature help, definition, references, outline, workspace symbols, rename, quick fix, and full semantic tokens. Each request still rebuilt analysis. References and rename had already shipped without a snapshot cache. There was no diagnostic whose meaning was "this name is not imported."
|
||||
|
||||
Treating the nine agendas as nine decisions would have reimplemented finished work and locked stale premises.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
`DEC-0058` retired that split. One plan, `PLN-0137`, landed seven steps. The frontend produces the editorial result. The LSP transports it and does not invent a second policy. A missing capability is not advertised and returns an empty list, not a protocol error.
|
||||
|
||||
The wave explicitly does not add a project snapshot cache, type hierarchy, `completionItem/resolve`, snippets, a ranking score, range or on-type formatting, organize imports, a missing-import quick fix, `relatedInformation`, or a new semantic-token key.
|
||||
|
||||
1. Published editor diagnostic `source` is the bound frontend `languageId`. For PBS that is `pbs`. `code` stays the stable compiler code. The code is not copied into `source`.
|
||||
2. A document link covers only the span of a `ModuleRef` whose module assembly already resolved to a regular file. Virtual stdlib and unresolved modules produce no link.
|
||||
3. Folding comes from recovered spans of the listed declarations, their bodies, parameter lists, and `Doc` text blocks. A brace, parenthesis, or text block the tree does not cover still folds, including an unmatched opener through the end of the text. Selection grows outward from identifier, to argument or parameter list, to block or `Doc` text block, to declaration.
|
||||
4. Formatting is full-document only. It reprints the token stream, indents by four spaces where brace or parenthesis nesting changes, leaves `Doc` text-block interiors untouched, and does not reorder declarations or move comments off their line.
|
||||
5. Semantic tokens keep `PBSSemanticTokenProvider` as the baseline. Hover resolution may replace an identifier token only when an existing `PbsSemanticKind` matches the symbol. Failure, a broken file, or a symbol with no existing key keeps the baseline token.
|
||||
6. Completion inside a `ModuleRef` lists project and stdlib modules the current resolver can already name. Every other offset keeps the existing member or general completion. Items stay eager and `resolveProvider` stays false.
|
||||
7. Call hierarchy walks `CallExpr` nodes for functions and methods. It does not use the references index. A cursor that is not on a callable is empty. Type hierarchy is not advertised.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
`CompilerLanguageServiceBridge` reads `LspProjectContext.languageId` into `BaselineDocumentIssue.source`. Document links read the physical module map that module assembly already built; stdlib files under `/virtual/stdlib` are not regular files, so they are not links. Folding, selection, and formatting reparse the open buffer with the existing lexer and parser. They do not require a successful project analysis. The semantic-token overlay runs only when editorial context is available and otherwise returns the provider tokens, including when project discovery fails. Module completion labels are the project modules from that same physical map plus the modules `ResourceStdlibEnvironmentResolver` can already resolve. Call hierarchy collects function, method, and constructor declarations from the recovered AST and matches `CallExpr` callees by name and call shape.
|
||||
|
||||
Spec 23 §8.3 states each of these rules. The nine earlier agendas, `AGD-0048` through `AGD-0056`, were abandoned and are not normative.
|
||||
|
||||
## Examples
|
||||
|
||||
A project import `@app:a` that resolves to `src/a/source.pbs` is one document link on that module-reference span. `@sdk:log` is not, because the stdlib file is virtual.
|
||||
|
||||
```pbs
|
||||
fn helper() -> int { return 1; }
|
||||
fn main() -> int { return helper; }
|
||||
```
|
||||
|
||||
The use of `helper` without a call is an identifier in the lexical pass. Hover resolves it as a function, so the overlay key is `pbs-function`. A local such as `value` has no existing key, so it stays `pbs-identifier`.
|
||||
|
||||
```pbs
|
||||
fn helper() -> int { return 1; }
|
||||
fn main() -> int { return helper(); }
|
||||
```
|
||||
|
||||
Prepare on `main` returns that function. Outgoing calls include `helper`. Incoming calls of `helper` include `main`. A cursor on a struct name returns no item.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Do not copy the diagnostic code into `source`. The editor then shows the code twice and loses the language id.
|
||||
- Do not build document links to `/virtual/stdlib`. Definition already refuses that destination.
|
||||
- Do not treat document symbols as folding ranges. Outline and folding are different payloads.
|
||||
- Do not pretty-print from the AST. Comments and `Doc` text-block interiors are not fully modeled as trivia on the tree.
|
||||
- Do not add `pbs-local`, `pbs-parameter`, or `pbs-field` in the overlay. Those symbols stay on the baseline token until a later decision adds the key.
|
||||
- Do not implement call hierarchy by inverting the references index. A reference is a use of a name, not a call.
|
||||
- Do not start a snapshot cache because a later feature feels slow. This wave deliberately kept request-local analysis.
|
||||
|
||||
## References
|
||||
|
||||
- `DEC-0058` and `PLN-0137`, removed by housekeeping after this lesson
|
||||
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md` §8.3
|
||||
- Earlier surface: `LSN-0068`, `LSN-0069`, `LSN-0070`, `LSN-0071`, `LSN-0072`, `LSN-0073`
|
||||
- Abandoned agendas: `AGD-0048` through `AGD-0056`
|
||||
+103
@@ -0,0 +1,103 @@
|
||||
---
|
||||
id: LSN-0075
|
||||
ticket: studio-core-javafx-decoupling
|
||||
title: Studio Services Must Outlive the Current UI
|
||||
created: 2026-09-25
|
||||
tags: [studio, architecture, spring, spring-modulith, javafx, adapters]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Prometeu Studio began as a desktop application in which JavaFX controls, application workflows, provider integrations, background execution, and lifecycle management shared one Gradle module. A static `p.studio.Container` made these dependencies easy to reach, but it also made the visual adapter the practical center of the product. That shape could not support another consumer, such as a future agent adapter, without either driving the UI or duplicating Studio behavior.
|
||||
|
||||
The migration needed to preserve the existing Java product and its behavior while making JavaFX replaceable. It also needed to preserve the autonomy of compiler, LSP, runtime, and especially `p.packer`; separating Studio did not authorize absorbing those domains.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Human and non-visual adapters consume the same Studio services
|
||||
|
||||
**What:** The Studio is physically divided into `prometeu-studio-api`, `prometeu-studio-core`, `prometeu-studio-ui-javafx`, and `prometeu-app`. JavaFX depends on the neutral API, Core implements application use cases, and the application module composes concrete adapters.
|
||||
|
||||
**Why:** The stable boundary is UI versus application services, not JavaFX versus a future web framework. A future agent can depend on the same API without moving application rules out of Core.
|
||||
|
||||
**Trade-offs:** More constructor parameters and explicit contracts are required. That cost is intentional: dependencies are visible, testable, and constrained by Gradle instead of hidden behind a global container.
|
||||
|
||||
### Spring is a composition mechanism, not a domain dependency
|
||||
|
||||
**What:** Spring Boot runs in non-web mode only in `prometeu-app`. Core objects remain constructor-injected POJOs. Spring Modulith verifies the six functional Core modules: project, session, assets, shipper, runtime, and execution.
|
||||
|
||||
**Why:** Spring provides deterministic construction and lifecycle without contaminating the public API or Core. Modulith supplies executable documentation and dependency checks while Gradle remains the physical classpath boundary.
|
||||
|
||||
**Trade-offs:** The application configuration is deliberately explicit. Broad component scanning and turning JavaFX controls into Spring singletons would recreate hidden ownership and lifecycle problems.
|
||||
|
||||
### Provider boundaries follow stability, not uniformity
|
||||
|
||||
**What:** Core uses a provider's public API directly when it is stable and neutral. It owns a narrow port when the available integration is static, concrete, lifecycle-oriented, or otherwise unsuitable for Core. Packer's stable API is consumed directly; compiler static access, LSP lifecycle, and runtime process integration are isolated behind consumer-owned gateways implemented in `prometeu-app`.
|
||||
|
||||
**Why:** Wrapping every dependency creates redundant abstractions, while importing concrete implementations leaks infrastructure into Core. The useful boundary depends on the provider contract.
|
||||
|
||||
**Trade-offs:** The integration matrix must be reviewed case by case. There is no universal rule that every provider receives a gateway.
|
||||
|
||||
### Long-running work is a neutral application contract
|
||||
|
||||
**What:** Build, pack, and execution expose `OperationHandle<R>` with identity, snapshots, completion, cancellation, updates, and typed results. The application owns the executor implementation; JavaFX only projects operation state and switches to the FX thread.
|
||||
|
||||
**Why:** Background work must be equally consumable by JavaFX and future adapters. An executor or JavaFX `Task` is an implementation detail, not an application contract.
|
||||
|
||||
**Trade-offs:** Cancellation races and terminal state transitions require explicit tests. In particular, stopping execution must cancel the outer execution handle before its nested preparation handle can complete it successfully.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
The dependency pattern is:
|
||||
|
||||
```text
|
||||
JavaFX adapter ---> Studio API <--- future adapters
|
||||
^
|
||||
|
|
||||
Studio Core
|
||||
^
|
||||
|
|
||||
Spring non-web composition
|
||||
```
|
||||
|
||||
External providers remain outside the Core module graph. Stable public provider APIs may be direct Core dependencies; concrete adapters remain in the application module.
|
||||
|
||||
Operational failures that a caller can recover from are returned as typed results or diagnostics. For example, metadata writes convert I/O failures into `AssetMetadataWriteResult`. JavaFX renders that result and does not treat an unexpected exception message or stack trace as a functional contract.
|
||||
|
||||
The removal sequence for a service locator is also reusable:
|
||||
|
||||
1. establish architecture tests and final modules;
|
||||
2. introduce neutral contracts and explicit factories;
|
||||
3. move behavior slice by slice into constructor-injected services;
|
||||
4. reduce static call sites to zero;
|
||||
5. delete the static container and manual composition together;
|
||||
6. remove the mixed legacy module;
|
||||
7. run the full build, packaging, desktop smoke, and shutdown gate as one indivisible acceptance step.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Renaming packages without changing Gradle dependencies does not create a replaceable frontend.
|
||||
- Replacing `Container` with `ApplicationContext.getBean()` throughout the code is still a service locator. Context lookup belongs only at the explicit application bootstrap boundary.
|
||||
- Registering every control or dialog as a Spring singleton gives Spring ownership of visual lifecycle and makes multiple windows or future adapters harder.
|
||||
- A gateway that merely mirrors a stable provider API adds indirection without protection. Conversely, direct use of static or concrete provider entry points leaks infrastructure into Core.
|
||||
- Moving Packer behavior into `p.studio.core.assets` would reverse domain ownership. Studio coordinates Packer; `p.packer` remains independently consumable.
|
||||
- Returning raw exception messages to JavaFX turns implementation accidents into an unstable user-facing protocol. Expected failures need neutral results or diagnostics.
|
||||
- Marking the migration complete after compilation alone misses packaging, restoration, real JavaFX interaction, cancellation, and shutdown leaks.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The durable product boundary is the Studio service surface, not the current frontend technology.
|
||||
- Spring belongs in composition; Spring Modulith belongs in verification and documentation; neither belongs in the neutral API.
|
||||
- Gradle modules enforce physical isolation, while functional Core modules express ownership and allowed dependencies.
|
||||
- JavaFX is an equivalent adapter, not the owner of project, asset, build, runtime, or execution rules.
|
||||
- `Container` removal is a completion criterion, not an optional cleanup step.
|
||||
- A future agent module can now be added as another API consumer without revisiting this migration or coupling AI concerns to JavaFX.
|
||||
|
||||
## References
|
||||
|
||||
- Decision: `DEC-0059` — Separate Studio Core from JavaFX with Spring Boot non-web and Spring Modulith.
|
||||
- Plan: `PLN-0138` — Complete Studio Core and JavaFX Boundary Migration.
|
||||
- Studio architecture: `docs/specs/studio/9. Studio Core and Adapter Architecture Specification.md`.
|
||||
- Studio specifications: `docs/specs/studio/README.md`.
|
||||
- Packer boundary: `docs/specs/packer/1. Domain and Artifact Boundary Specification.md`.
|
||||
- Packer integration: `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`.
|
||||
+303
@@ -0,0 +1,303 @@
|
||||
---
|
||||
id: LSN-0076
|
||||
ticket: studio-headless-runtime-ai-first
|
||||
title: AI-first Studio Through Shared Authority and Headless Evidence
|
||||
created: 2026-09-29
|
||||
tags: [studio, runtime, headless, ai, mcp, automation]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Owner: **studio**, with runtime preparation in `../runtime` and language-owned PBS
|
||||
documentation/LSP integration. DSC-0068, accepted DEC-0060 and PLN-0139 delivered
|
||||
28 ordered steps: runtime (01–07), DEV/shared services (08–14), MCP (15–21), and
|
||||
real integration/acceptance (22–28). Those workflow identifiers are historical
|
||||
references; maintained contracts live in the specs linked below.
|
||||
|
||||
The original headless host was an in-process runtime API. Studio's human Debug
|
||||
was useful, but neither a public automation protocol nor a safe authority boundary
|
||||
for another editor. The goal was an external coding agent able to learn PBS,
|
||||
edit a game, build/run it, see its pixels and iterate while the developer watches.
|
||||
A complete gameplay library or embedded AI chat was not a prerequisite.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Separate ownership, not parallel implementations
|
||||
|
||||
The external coding client owns conversation, model/provider, native file edits
|
||||
and budget. Studio owns project authority, build orchestration, process supervision
|
||||
and the shared observation model. Runtime owns execution and framebuffer semantics.
|
||||
The language frontend/SDK owns its references; the existing project LSP owns semantic
|
||||
queries. DEV and MCP consume the same neutral services.
|
||||
|
||||
```text
|
||||
External coding agent -- local MCP HTTP --> Studio API/Core <-- DEV (JavaFX)
|
||||
|
|
||||
compiler/packer + existing LSP
|
||||
|
|
||||
supervised runtime JSONL/stdio
|
||||
|
|
||||
canonical PNG + frame identity
|
||||
```
|
||||
|
||||
The configured installation provides `prometeu headless --stdio`. UTF-8 JSONL is
|
||||
versioned, bounded and protocol-only on stdout; logs belong on stderr. A process
|
||||
contains one session, with no implicit conflicting-work queue. Handshake establishes
|
||||
runtime/protocol versions, capabilities and effective limits. Human Debug keeps its
|
||||
own host/protocol. API/Core do not depend on JavaFX, Spring, HTTP/MCP or wire DTOs.
|
||||
|
||||
This avoids a provider adapter inside Studio and avoids automating the human debugger
|
||||
as the execution API. The deliberate cost is an explicit process boundary and
|
||||
reconfiguration of the external client after Studio restarts.
|
||||
|
||||
### Connection, authority and operation receipts are different identities
|
||||
|
||||
Authentication to loopback `/mcp` permits discovery/context/reference reads, not
|
||||
editing authority. A human grants a specific project in DEV; acquisition then
|
||||
returns a task identity. Manual Debug and agent work exclude each other in services,
|
||||
not only through disabled UI buttons. Waiting for acquisition already blocks
|
||||
conflicting manual work. A disconnected client does not release the project.
|
||||
|
||||
An operation's `clientRequestId` deduplicates a build or advance within the task.
|
||||
The same ID and parameters return the same operation; changing parameters fails.
|
||||
Lookup recovers a lost receipt without replaying frames. These records are in-memory,
|
||||
not a source journal or restart-recovery mechanism. Runtime wire correlation has
|
||||
its own `requestId`; neither identity is a substitute for valid task authority.
|
||||
|
||||
### Return is a cleanup barrier
|
||||
|
||||
The sequence is: invalidate task authority → stop managed work/processes → refresh
|
||||
open documents from saved files → enable manual control. A late result cannot publish
|
||||
a new capture or restore authority. Closing only DEV does not end the task; closing
|
||||
the project/app does. Reopening starts manual, never with recovered agent authority.
|
||||
|
||||
Compile errors, guest faults and runtime loss remain distinct outcomes. The first
|
||||
two permit correction within the same task. Runtime loss requires explicit session
|
||||
replacement, not replay. Forced cleanup reports infrastructure failure first; a
|
||||
later explicit reclaim may acknowledge success only after the process tree is dead.
|
||||
|
||||
The adversarial gate exposed a real app-teardown gap: UI closure alone did not own
|
||||
every project session. The project-session factory now tracks and closes sessions
|
||||
before dependent executors/LSP are destroyed, attempts other sessions after a failure,
|
||||
and rejects new opens once closure begins. Cancellation also tolerates a concurrent
|
||||
writer/timer shutdown so that it cannot bypass cleanup waiting.
|
||||
|
||||
### Direct edits require truthful boundaries
|
||||
|
||||
The agent edits actual project files. No worktree, merge/apply stage, code rollback,
|
||||
Git cleanliness gate or automatic commit is imposed. Studio offers save-all-and-grant
|
||||
for its dirty buffers and refreshes from disk on return. External unsaved buffers,
|
||||
concurrent native writes and Git discipline remain the developer's responsibility.
|
||||
Revocation cannot stop an external process from writing files directly; the developer
|
||||
must also stop that client. SDK/external libraries are readable, not editable by
|
||||
the game task. Read-only semantic refactoring scopes are enforced by the adapter.
|
||||
|
||||
### Pixels are evidence; metadata explains which evidence
|
||||
|
||||
MCP returns the lossless canonical PNG as native image content, plus session/build,
|
||||
logical frame, render FrameId, dimensions, stride and pixel format. DEV projects
|
||||
the same capture, with an explicit stale label after edits/rebuild/session changes.
|
||||
Logical frames and render frames are independent counters. Neither a hash nor a
|
||||
desktop screenshot replaces framebuffer pixels. Captures do not travel through
|
||||
temporary image files, and there is no continuous video requirement.
|
||||
|
||||
Default bounds are 600 frames/advance, 64 KiB/command, 32 MiB/response including
|
||||
image/envelope, 5 s handshake, 60 s call, and 5 s cancel/shutdown grace. Oversized
|
||||
requests fail rather than clamp. Deadlines supervise processes, not simulated time.
|
||||
|
||||
## Final Result and Acceptance Evidence
|
||||
|
||||
All 28 plan steps completed on the tested platform. Production exposes 17 MCP
|
||||
tools, live DEV configuration-copy, shared task authority, existing LSP/build,
|
||||
indexed offline language references and the supervised real Rust headless host.
|
||||
There is no production fake, embedded agent/chat, generic MCP editor/shell or
|
||||
provider-specific runtime behavior.
|
||||
|
||||
### Requirement-to-evidence map
|
||||
|
||||
| Requirement and steps | Evidence retained in code or acceptance record |
|
||||
| --- | --- |
|
||||
| Runtime contract, commands, limits, determinism; 01–07 | Runtime `automation_process.rs`, headless tests, published request/response schemas and packaged-installation smoke |
|
||||
| Neutral architecture; 08, 14, 15, 27 | Studio specs 9–11; architecture/Modulith tests, 17 passing cases in final full rerun |
|
||||
| Grant/revoke, symmetric locks, dirty-buffer handoff; 09–14 | `DefaultAutomationSessionTest`, Core execution/session tests, `DevDesktopTest`, `DevWorkspaceProjectionTest` |
|
||||
| HTTP authentication/Origin/restart and real config; 16, 21 | `LocalMcpServerTest`, `McpContractTest`, `McpConnectionGuideTest`; packaged restart rejects prior credential |
|
||||
| Manifest context, unknown languages/versions, indexed offline docs; 17–18 | `CompilerProjectKnowledgeTest`, `CompilerProjectLanguageCatalogTest`, `InstalledKnowledgeTest` |
|
||||
| Saved-source LSP and dependency navigation; 19 | `AutomationLspQueriesTest`, including `externalDependencyNavigationIsReadableButRefactoringIsReadOnly`; SDK limitation remains explicit below |
|
||||
| Task operations, lost receipts, deduplication; 20–21 | `McpTaskToolsTest`, Core operation tests; reconnect/duplicate advance in real desktop HTTP gate |
|
||||
| Real supervision/build/corrective iterations; 22–23 | `HeadlessProcessSessionTest`, `HeadlessInstalledRuntimeTest`, `HeadlessTaskIntegrationTest` |
|
||||
| Runtime/MCP/DEV pixel and identity parity; 24 | `HeadlessMcpDesktopTest` + independent `DirectHeadlessOracle`; compare every ImageView pixel, PNG bytes, metadata, reset/fresh-session/rebuild |
|
||||
| Interruption/cleanup/Debug regression; 25 | Nine real HTTP/runtime/DEV tests, including crash, forced shutdown, app close, stale-result rejection and real manual Debug; controlled document participant makes refresh barrier observable |
|
||||
| Real coding client and human confirmation; 26 | Codex CLI 0.158.0 run described below; developer confirmed DEV and manual Debug Play |
|
||||
| Full regression and distribution; 27 | Commands/counts below; installed references and two extracted-ZIP application lifecycle cycles |
|
||||
| Final propagation and handoff; 28 | This lesson, updated spec 11 delivery boundary, README troubleshooting, CLI validation and housekeeping |
|
||||
|
||||
### Real external-client example
|
||||
|
||||
The developer granted control in `../ai-first-smoke` and copied the descriptor.
|
||||
Codex CLI 0.158.0 used a fresh ephemeral session, only the configured Studio MCP,
|
||||
project-root workspace-write isolation and its approval-review mechanism. Default
|
||||
noninteractive approval policy initially blocked acquisition before any edit; the
|
||||
retry retained sandboxing and did not bypass the human grant. The configured default
|
||||
model was used; this record does not assert an independently verified model identity.
|
||||
Credentials stayed out of versioned files and reports.
|
||||
|
||||
The agent consulted language/SDK references, edited only `src/main.pbs`, queried
|
||||
LSP, built/packed and consumed native MCP image blocks. It changed the bundled
|
||||
16x16 orange rectangle to one-pixel/frame directional movement in a 480x270 frame,
|
||||
with no idle movement, opposing directions canceled before clamping, and unchanged
|
||||
colors. Both builds succeeded; diagnostics were empty; final guest fault was null.
|
||||
The 77 MCP calls included rejected/recovered calls and 13 native image blocks.
|
||||
|
||||
| Scenario | Logical frame / FrameId | Client-reported observed position |
|
||||
| --- | --- | --- |
|
||||
| Idle for 10 frames | 10 / 9 | (0,32) |
|
||||
| Right 20; down 20 | 30 / 29; 50 / 49 | (20,32); (20,52) |
|
||||
| Left 10; up 10 | 60 / 59; 70 / 69 | (10,52); (10,42) |
|
||||
| Horizontal then vertical opposites, 10 each | 80 / 79; 90 / 89 | (10,42), unchanged |
|
||||
| Right + down, 500 | 590 / 589 | (464,254), intact at bottom-right |
|
||||
| All directions, 10 | 600 / 599 | (464,254), unchanged at edge |
|
||||
| Left + up, 500; idle 10 | 1100 / 1099; 1110 / 1109 | (0,0), intact at top-left |
|
||||
|
||||
Build ID: `da441f65-479b-4099-8b86-fe48c7750e76`; runtime session:
|
||||
`aa089209ec22c9a07286e5b01e967a57`. Frame identities/statuses were checked in tool
|
||||
evidence; positions are the coding client's visual observations, not an invented
|
||||
independent pixel measurement. Step 24 separately supplies exhaustive pixel parity.
|
||||
Release returned MANUAL, no headless host remained, and game edits were preserved.
|
||||
The developer confirmed the DEV result and successfully played the game through
|
||||
normal Debug afterward. No game commit was made automatically.
|
||||
|
||||
### Builds, commands and scope
|
||||
|
||||
Studio executable code was `e6a83c94`; acceptance/troubleshooting documentation
|
||||
was committed as `4c3597a2`. Runtime is merged at `01fab56`, distribution 0.1.0,
|
||||
protocol 1.0. Native acceptance was **macOS ARM64 only**; no other coding client,
|
||||
operating system or native-installer matrix is claimed.
|
||||
|
||||
Studio final commands:
|
||||
|
||||
```sh
|
||||
./gradlew test build :prometeu-app:installDist --max-workers=2 --console=plain
|
||||
./gradlew test :prometeu-app:installedKnowledgeTest :prometeu-app:headlessProcessTest --rerun-tasks -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2 --console=plain
|
||||
```
|
||||
|
||||
The forced rerun executed all 91 tasks: normal suite **803 passed, 15 pre-existing
|
||||
disabled tests, zero failures/errors**; installed knowledge **1 passed**; real
|
||||
headless integration **4 passed**. The disabled compiler classes were
|
||||
`IRVMIntrinsicRegistryParityTest`, `BackendGateIIntegrationTest` and
|
||||
`MainProjectPipelineIntegrationTest`; none was disabled for this delivery.
|
||||
The earlier step 25 targeted run had **254 passing tests**, including 9 real
|
||||
HTTP/runtime/DEV and 4 DEV/Debug desktop tests. These overlap the full suite and
|
||||
must not be added together as unique tests.
|
||||
|
||||
The Studio ZIP was extracted outside the checkout. A test-only JavaFX probe loaded
|
||||
only its distribution JARs, delegated to the real App init/start/stop, used isolated
|
||||
preferences, and passed two shown-launcher/closed-listener cycles, credential
|
||||
renewal and old-token rejection. It did not operate the developer's open window.
|
||||
ZIP SHA-256: `256f80b25416c284dca58e5519fdde0be36e9a6a2a450cb58f9c453862188c8d`.
|
||||
|
||||
Runtime final commands (cwd `../runtime`, separate temporary Cargo target):
|
||||
|
||||
```sh
|
||||
cargo test --workspace --offline --quiet
|
||||
PROMETEU_PROTOCOL_TEST_INSTALL=/absolute/path/to/runtime cargo test -p prometeu-cli --offline --test automation_process -- --include-ignored
|
||||
cargo test -p prometeu-host-desktop-winit --offline --lib -- --ignored
|
||||
```
|
||||
|
||||
Workspace **678 passed**, with six opt-in tests ignored there; separate runs passed
|
||||
all **13** process/protocol cases including the installed package, and all **5**
|
||||
localhost Debug cases. Twelve process cases overlap the workspace result. The
|
||||
runtime package was built during preparatory delivery; the final gate reused and
|
||||
validated it rather than claiming a fresh distribution build. Installed headless
|
||||
SHA-256: `24b74712397545ddd7f745daded859c12d19102f81c5b51bf46c202fb8d6b65d`.
|
||||
|
||||
## Deferred Findings — Return Here After Implementation
|
||||
|
||||
The user requested deferred investigation, not silent removal of these findings.
|
||||
|
||||
| Finding | Owner and next investigation |
|
||||
| --- | --- |
|
||||
| `Input.pad()` SDK definition returns no location | Investigated on 2026-09-29: editorial lookup succeeds, but the physical-file policy filters the virtual SDK source. A separate chained-call editorial limitation was reproduced; see below. No runtime defect or fix is claimed. |
|
||||
| Oversized reference page produces generic `-32602` | Studio MCP: improve parameter-limit discoverability/error specificity; default pagination already works. |
|
||||
| Concurrent capture/fault/state may return BUSY | Studio MCP/Core: review concurrency guidance and clarity. Sequential calls work; do not weaken accepted exclusivity implicitly. |
|
||||
| Framebuffer dimensions were discovered from capture | Language/runtime documentation: improve discovery; this does not prove dimensions are absent from every reference. |
|
||||
| JDK 25/Kotlin target-24 fallback, JavaFX module/native-access/Unsafe warnings | Build/desktop tooling: review supported toolchain alignment and startup options separately. Passing tests do not erase warnings. |
|
||||
| UI automation helper required newer Node than 22.13.1 | Environment tooling, not Studio: upgrade only as separate authorized work; human DEV confirmation supplied acceptance. |
|
||||
| macOS ARM64 + Codex is the validated matrix | Future interoperability/platform testing; no uniform Grok/Windows/Linux promise. |
|
||||
|
||||
`NO_FRAME_AVAILABLE` before the first completed frame and client permission prompts
|
||||
are expected boundaries, not guest defects. The shutdown ownership/reclaim bugs
|
||||
found during step 25 are fixed and tested, not outstanding issues.
|
||||
|
||||
### Follow-up Investigation: SDK Navigation and Chained Calls
|
||||
|
||||
Owner: `compiler/pbs`, with propagation to compiler tooling contracts and Studio/LSP
|
||||
consumers. This diagnosis does not reopen the completed AI-first delivery or change
|
||||
its accepted requirements.
|
||||
|
||||
On 2026-09-29, a temporary Java probe exercised `CompilerLanguageServiceBridge`
|
||||
with a request-local PBS overlay on `test-projects/main/src/main.pbs`, using the
|
||||
application runtime classpath. It compared raw PBS editorial locations, exported
|
||||
frontend locations, final LSP definitions, and hover. No production source was
|
||||
changed. The comparison included imports from `@sdk:input` and `@sdk:gfx`, a local
|
||||
`helper()`, an explicitly typed `pad: InputPad`, and `button: InputButton`.
|
||||
|
||||
| Cursor target | Raw PBS locations | Frontend / LSP locations | Hover |
|
||||
| --- | --- | --- | --- |
|
||||
| Local `helper()` | 1 | 1 / 1 | Resolved |
|
||||
| `pad` in `Input.pad()` | 1 | 0 / 0 | `pad() -> InputPad` |
|
||||
| `left` in `pad.left()` | 1 | 0 / 0 | `left() -> InputButton` |
|
||||
| `down` in `button.down()` | 1 | 0 / 0 | `down() -> bool` |
|
||||
| `down` in `pad.left().down()` | 0 | 0 / 0 | No symbol information |
|
||||
| `left` and `down` in `Input.pad().left().down()` | 0 each | 0 / 0 each | No symbol information |
|
||||
| `clear` in `Gfx.clear(0)` | 1 | 0 / 0 | Resolved |
|
||||
|
||||
There are two separate causes:
|
||||
|
||||
1. **SDK destination policy, not failed lookup.** `InterfaceModuleLoader` registers
|
||||
SDK declarations under `/virtual/stdlib/sdk/input/main.pbs` (and the corresponding
|
||||
`gfx` path). The source handle can read the declaration text, but the path is not
|
||||
a physical file. `PBSFrontendLanguageService.toFrontendLocation` explicitly
|
||||
rejects it via `Files.isRegularFile`. The LSP bridge also reads destination text
|
||||
from disk; removing the frontend check alone would not deliver a usable target.
|
||||
This behavior follows Compiler Spec 23 §8.3 and the physical-file rule preserved
|
||||
in `LSN-0068`, and already has an explicit `Gfx.clear()` regression assertion in
|
||||
`CompilerLanguageServiceBridgeTest.definitionUsesEditorialLookupAndPhysicalStdlibFiles`.
|
||||
2. **Chained-call editorial receiver resolution.**
|
||||
`PbsEditorialSupportService.resolveReceiverTypeBeforeDot` uses
|
||||
`resolveChainSegmentsEndingAt`, which walks identifier/dot chains, not a call
|
||||
expression ending in `)`. Thus the receiver of `down` in `pad.left().down()` is
|
||||
unknown before destination mapping even begins. An explicitly typed intermediate
|
||||
`button` restores raw lookup and hover, while the virtual-source policy still
|
||||
prevents navigation. This is an editorial limitation, not evidence that executing
|
||||
the same expression fails.
|
||||
|
||||
Recommended follow-up, not an accepted implementation decision: address chained
|
||||
receiver resolution in the PBS editorial layer, and separately decide how to expose
|
||||
the exact SDK sources as navigable read-only files. A version-scoped physical source
|
||||
cache is compatible with the existing destination policy; virtual-document support
|
||||
would require an explicit contract revision. Neither approach should duplicate SDK
|
||||
semantics in MCP, permit SDK edits, or point to an unrelated developer checkout.
|
||||
|
||||
## Pitfalls and Takeaways
|
||||
|
||||
- A successful HTTP fixture is not an external-agent acceptance test. Prove both.
|
||||
- Tab disposal is not task disposal; application teardown must own hidden sessions.
|
||||
- Never unlock before process termination and document refresh acknowledge completion.
|
||||
- Do not replay an advance because a connection or receipt was lost.
|
||||
- A matching hash/blank canvas is weak visual evidence. Compare actual pixels,
|
||||
metadata and an input timeline that changes a known object.
|
||||
- An empty SDK definition is a language limitation, not permission to edit SDK code.
|
||||
- Packaging language knowledge is part of making an unfamiliar language usable by
|
||||
agents; adding another hidden language configuration is not.
|
||||
- Keep provider permissions separate from Studio authority. Neither bypasses the other.
|
||||
- Preserve explicit platform/client/test exclusions and deferred findings at closure.
|
||||
|
||||
## References
|
||||
|
||||
- Historical accepted decision DEC-0060 and completed plan PLN-0139, DSC-0068.
|
||||
- [Studio architecture](../../../docs/specs/studio/9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md).
|
||||
- [DEV and authority contract](../../../docs/specs/studio/10.%20DEV%20and%20Automation%20Specification.md).
|
||||
- [MCP tools and knowledge contract](../../../docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
|
||||
- [Usage and troubleshooting](../../../README.md#external-coding-agents-mcp).
|
||||
- Runtime-owned contract: `../runtime/docs/specs/runtime/11a-headless-automation-protocol.md`.
|
||||
- Previous foundation: [Services must outlive UI](../DSC-0067-studio-core-javafx-decoupling/LSN-0075-studio-services-must-outlive-the-current-ui.md).
|
||||
+190
@@ -0,0 +1,190 @@
|
||||
---
|
||||
id: LSN-0078
|
||||
ticket: pbs-editorial-chains-sdk-navigation
|
||||
title: PBS chains and revision-bound external sources
|
||||
created: 2026-10-07
|
||||
tags: [compiler, compiler-pbs, lsp, studio, sdk, navigation]
|
||||
---
|
||||
|
||||
# PBS chains and revision-bound external sources
|
||||
|
||||
Domain owner: `compiler/pbs`. Propagation: `compiler/general` and `studio`.
|
||||
DEC-0062 and PLN-0141 were implemented together. This lesson preserves the outcome
|
||||
and validation after their workflow artifacts are removed.
|
||||
|
||||
## Original problem
|
||||
|
||||
Compilation supported expressions such as `Input.pad().left().down()`, but the
|
||||
editorial receiver scanner only understood identifier/dot sequences. Hover,
|
||||
definition, completion and signature help therefore lost the receiver after a call.
|
||||
Separately, definition discarded SDK/core handles because their bundled resources
|
||||
had virtual paths rather than regular files. SDK hover could succeed while F12
|
||||
returned nothing. These were independent defects requiring integrated acceptance.
|
||||
|
||||
A third regression fixture confirmed that source discovery skipped a dependency
|
||||
explicitly admitted under `.workspace`: the crawler tested every ancestor of the
|
||||
absolute path against ignored directory names.
|
||||
|
||||
## Consolidated decision
|
||||
|
||||
Keep language resolution in the frontend. Share receiver typing across the four
|
||||
project queries, using PBS parsing and flow semantics. Support known-return call
|
||||
chains, nested arguments, typed/inferred variables, parentheses and recoverable
|
||||
partial code. Unknown or ambiguous receivers stay unresolved. This changes no
|
||||
language rule, compiler/linker pipeline, ABI or runtime behavior.
|
||||
|
||||
Expose SDK/core and admitted dependency sources as read-only in-memory documents.
|
||||
SDK/core remain bundled, without editorial extraction. Libraries remain their
|
||||
existing physical sources; a library inside the project directory is still an
|
||||
external owner. Dependency installation, download, cache management and its future
|
||||
Studio UI remain DSC-0072 / AGD-0074.
|
||||
|
||||
Each external document binds content, byte ranges and frontend semantic context to
|
||||
the same analyzed revision. The host emits an opaque project-session URI; the
|
||||
content digest is not an SDK version. VS Code and MCP share that source and
|
||||
semantic authority. They do not implement another PBS resolver.
|
||||
|
||||
All proposals touching external sources are refused as a whole. Normal project
|
||||
editing remains available. References, workspace symbols, links and hierarchies
|
||||
retain their earlier physical scopes. External definition does not expand them.
|
||||
|
||||
## Final implementation
|
||||
|
||||
1. `PbsParser.parseExpression` exposes the existing expression grammar for complete
|
||||
receiver fragments. `PbsEditorialSupportService` locates a fragment boundary and
|
||||
delegates its type to `PbsFlowExpressionAnalyzer`. The same path serves all four
|
||||
project queries, including trailing dots and unfinished arguments.
|
||||
2. `SourceCrawler` tests ignored descendants relative to the explicitly admitted
|
||||
traversal root. It does not admit incidental `.workspace` trees as project code.
|
||||
3. `FrontendSourceDocument` carries exact text, origin, presentation metadata,
|
||||
read-only ownership and opaque frontend context. Definition locations optionally
|
||||
carry that source; invalid path/range combinations are rejected. PBS preserves
|
||||
source ownership separately from `SourceKind.PROJECT`; external ownership wins
|
||||
when paths overlap. Existing default-empty frontend capabilities remain valid.
|
||||
4. `ExternalSourceRegistry` belongs to `TcpLspServerHost`, not the shared compiler
|
||||
bridge. It retains source/context together, with separate consumer grants,
|
||||
acknowledged uses and reconnect validation. Repeated uses in one semantic
|
||||
snapshot coalesce. Another reader's release cannot invalidate a retained source.
|
||||
5. LSP negotiates external support and emits `prometeu-source:` destinations only
|
||||
to supporting clients. External read, retain, release and revalidate requests
|
||||
share server-issued consumer identity. The bridge uses retained content for
|
||||
positions, hover, definition and highlighting. Unsupported consumers keep local
|
||||
physical navigation without receiving unusable external targets.
|
||||
6. VS Code registers a `TextDocumentContentProvider`, assigns PBS language, routes
|
||||
hover/F12/highlighting and prevents external edit commands. Disconnect preserves
|
||||
displayed text but disables queries until validation; the status bar explains
|
||||
unavailable external documents. Changed revisions require fresh navigation.
|
||||
7. MCP adds `readExternalSource` to `studio_language_query`. Task-owned consumers
|
||||
survive short-lived sockets, acknowledge returned definitions, revalidate before
|
||||
reuse, and release on task return/cancellation. Cross-task/project replay is
|
||||
refused. Failed navigation releases unacknowledged results; failed responses
|
||||
roll back newly retained sources. No human editor is needed.
|
||||
|
||||
### Example
|
||||
|
||||
A project definition on `Gfx.clear` opens the bundled SDK source. Hover/F12 on its
|
||||
`LowGfx.clear` call reaches the host declaration. F12 on `Color` reaches the core
|
||||
resource. The same operations work through MCP by reading the returned external
|
||||
URI and querying positions in that text. A dependency under `.workspace/repos/lib`
|
||||
uses the same presentation and write protection.
|
||||
|
||||
If that library changes on disk while a document is open, the retained document's
|
||||
hover/F12 still use its old AST and old text. After disconnect, revalidation against
|
||||
the changed source fails; clients must navigate again for new content and ranges.
|
||||
|
||||
## Validation evidence
|
||||
|
||||
Failures were reproduced before production changes: all four chain assertions
|
||||
failed, both crawler/admitted-FileTable fixtures failed, and the old bridge test
|
||||
confirmed SDK hover with empty bundled definition alongside working local F12.
|
||||
|
||||
Final module results (2026-10-07):
|
||||
|
||||
| Suite | Executed successfully | Skipped |
|
||||
| --- | ---: | ---: |
|
||||
| PBS frontend | 245 | 0 |
|
||||
| Frontend API | 27 | 0 |
|
||||
| Build pipeline | 141 | 15 existing disabled cases |
|
||||
| LSP | 38 | 1 opt-in development-host case in the ordinary run |
|
||||
| App: AutomationLspQueries, McpContract, CompilerProjectKnowledge | 24 | 0 |
|
||||
| Core: TaskLanguageQueries | 1 | 0 |
|
||||
| Actual VS Code Development Host, run separately | 1 | 0 |
|
||||
|
||||
All 477 executed JUnit cases passed across these scoped runs. TypeScript compilation,
|
||||
`discussion validate` and `git diff --check` also passed. The disabled main-project
|
||||
pipeline integration test was not treated as evidence.
|
||||
|
||||
The actual VS Code host exercised typing refusal, declaration selection, semantic
|
||||
highlighting, hover, continued F12, a physical `.workspace` library with Unicode/CRLF,
|
||||
reconnection and normal project edits. Provider tests exercised cached disconnected
|
||||
text, matching/changed revisions, close and canceled reads. MCP tests used the actual
|
||||
TCP server independently of VS Code, including task return, aliases, mixed rename
|
||||
refusal and changed revisions. Registry tests covered multiple readers, distinct
|
||||
projects, last release, task/session lifetime and canceled/unopened navigation.
|
||||
|
||||
The source-snapshot regression changed a dependency on disk after navigation and
|
||||
verified that old hover/F12 still used the original declaration and semantic context.
|
||||
Dedicated write-boundary checks refuse external didChange/didSave, formatting,
|
||||
rename, prepareRename and code actions, including unnegotiated identities.
|
||||
|
||||
Commands are preserved in the plan-derived development instructions and test owners:
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-compiler:prometeu-frontend-api:test :prometeu-compiler:prometeu-build-pipeline:test :prometeu-lsp:prometeu-lsp-v1:test --console=plain
|
||||
./gradlew :prometeu-app:test --tests '*AutomationLspQueriesTest' --tests '*McpContractTest' --tests '*CompilerProjectKnowledgeTest' :prometeu-studio-core:test --tests '*TaskLanguageQueriesTest' --console=plain
|
||||
npm --prefix tools/vscode-extension run compile
|
||||
PROMETEU_VSCODE_DEV_TEST=1 ./gradlew :prometeu-lsp:prometeu-lsp-v1:test --tests '*ExternalSourceDevelopmentHostTest' --console=plain
|
||||
```
|
||||
|
||||
Packaged Studio was excluded from the initial acceptance above. On 2026-10-07,
|
||||
the user explicitly requested this additional validation. The existing
|
||||
`InstalledKnowledgeTest` now launches its isolated probe with the Java runtime
|
||||
from `installDist`, using distribution JARs plus test probe classes, with its working
|
||||
directory and projects outside the checkout. It asserts that the frontend and LSP
|
||||
bridge load from JARs and that SDK/core resources have `jar:` URLs.
|
||||
|
||||
The packaged gate passed:
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-app:installedKnowledgeTest --console=plain
|
||||
```
|
||||
|
||||
Besides reading the installed documentation and compiling its example, it verifies
|
||||
project-to-SDK, SDK-to-host and SDK-to-core definitions, matching declaration lines,
|
||||
exact SDK/core text against JAR bytes, read-only bundled descriptors, SDK hover and
|
||||
semantic tokens, and source revalidation after reconnect. The project contains only
|
||||
its original manifest and sources after navigation: no bundled source extraction.
|
||||
The first run caught an incorrect cursor position in the test fixture; calculating
|
||||
the position from the source fragment fixed the fixture. No production fix was needed.
|
||||
This is a packaged resource/backend gate; it does not launch the Studio desktop or
|
||||
repeat the VS Code UI checks against the installed process.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Compiler success does not prove editorial resolution. Query the four surfaces.
|
||||
- A physical path under the project root is not proof of editable ownership.
|
||||
- Retaining text alone is insufficient: fresh analysis can attach different meaning
|
||||
to old positions. Keep the corresponding semantic context.
|
||||
- MCP socket closure is not task completion. Retain consumer state independently.
|
||||
- VS Code normalizes escaped URI components. The first actual-host run exposed
|
||||
mismatched identities from escaped slashes; emitted URIs now use unreserved
|
||||
characters and keep names separately in metadata.
|
||||
- `TextEditor.edit` is an extension programming API, not user typing. The real UI
|
||||
gate uses the `type` command; backend edit proposals are checked independently.
|
||||
If another extension changes a virtual buffer, the provider refuses queries whose
|
||||
text differs from the retained revision.
|
||||
- VS Code MarkdownString properties need direct inspection; JSON serialization can
|
||||
show `{}` even when hover contains valid content.
|
||||
- Enriching a shared definition DTO can accidentally expand references. Keep each
|
||||
surface's admission policy explicit; the compatibility suite caught this coupling.
|
||||
- Do not silently drop external edits from a mixed proposal. Refuse the operation.
|
||||
|
||||
## References
|
||||
|
||||
- [Compiler Spec 23](../../../docs/specs/compiler/23.%20Compiler%20Pipeline%20Entry%20Points%20Specification.md).
|
||||
- [PBS Spec 5](../../../docs/specs/compiler-languages/pbs/5.%20Manifest,%20Stdlib,%20and%20SDK%20Resolution%20Specification.md).
|
||||
- [PBS Spec 8](../../../docs/specs/compiler-languages/pbs/8.%20Stdlib%20Environment%20Packaging%20and%20Loading%20Specification.md).
|
||||
- [Studio Spec 11](../../../docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
|
||||
- [Extension guide](../../../tools/vscode-extension/README.md).
|
||||
- [Historical physical-only policy, LSN-0068](../DSC-0039-pbs-lsp-go-to-definition/LSN-0068-pbs-go-to-definition-uses-editorial-lookup-and-physical-files.md).
|
||||
- DEC-0031 / LSN-0049 still govern removal of the old embedded editor/VFS; none was restored.
|
||||
+178
@@ -0,0 +1,178 @@
|
||||
---
|
||||
id: LSN-0077
|
||||
ticket: studio-persistent-mcp-connector
|
||||
title: Integrated Studio MCP Through Stable Setup and Ephemeral Access
|
||||
created: 2026-09-29
|
||||
tags: [studio, mcp, connection, lifecycle, installation]
|
||||
---
|
||||
|
||||
# Integrated Studio MCP: Stable Setup, Ephemeral Access
|
||||
|
||||
Owner: **studio**, MCP integration, project lifecycle and local installation.
|
||||
DSC-0070 / DEC-0061 / PLN-0140 delivered this integration, including the user's
|
||||
accepted revision for automatic preparation on project open. These identifiers
|
||||
are historical references; maintained contracts are linked below. Automated
|
||||
validation and the user's confirmation of final manual acceptance are recorded
|
||||
separately.
|
||||
|
||||
## Original Problem
|
||||
|
||||
The original integration exposed a new HTTP port and bearer token on each Studio
|
||||
restart. Developers had to configure their coding client repeatedly. Ad hoc
|
||||
transport scripts then duplicated initialization, authentication and result
|
||||
handling, obscuring native MCP tools and images.
|
||||
|
||||
The durable solution separates three lifetimes: installation, connection and
|
||||
project authority. A stable client registration must not imply durable permission
|
||||
to edit, and a transport interruption must not replay work.
|
||||
|
||||
## Consolidated Design
|
||||
|
||||
The distributed Studio artifact supports two modes. Normal invocation opens the
|
||||
desktop. `StudioLauncher mcp --project <absolute-root>` runs a stdio connector
|
||||
without JavaFX, Spring desktop composition, LSP or a second HTTP server. The coding
|
||||
client owns that process; developers do not launch it manually for each project.
|
||||
|
||||
The desktop starts one shared loopback HTTP server. Opening a project prepares its
|
||||
enabled integration automatically through the same neutral port used by scaffold
|
||||
and the explicit DEV retry. An explicitly disabled integration remains disabled.
|
||||
Preparation failure is visible in DEV and does not make the project unusable.
|
||||
Opening a project does not publish credentials or grant control.
|
||||
|
||||
The macOS installation has a stable `current` reference pointing to a validated,
|
||||
versioned distribution containing dependency JARs and Java. The native client
|
||||
invokes the absolute installed Java path with a classpath/main/project argument
|
||||
array. Updating the installation changes the reference, not every project's client
|
||||
entry. Old versions remain available for rollback and existing processes.
|
||||
|
||||
The tradeoff is an additional lightweight JVM for stdio transport, plus managed
|
||||
installation lifecycle. In return, there are no per-project launchers or copied
|
||||
connector binaries, and execution does not depend on an interactive shell PATH.
|
||||
|
||||
## Configuration and Authority Have Different Owners
|
||||
|
||||
| Surface | Lifetime and responsibility |
|
||||
| --- | --- |
|
||||
| `.studio/setup.json` | Neutral integration intent; preserves runtime/editor settings |
|
||||
| `.codex/config.toml` | Local installed command, arguments and canonical project binding; no transient credentials |
|
||||
| `.studio/mcp/connection.json` | Protected, temporary discovery data published by human grant |
|
||||
| Core grant/task/operation records | In-memory authority and receipts; never restored from configuration |
|
||||
|
||||
Preparation edits only a managed client entry, validates the result with a TOML
|
||||
parser and preserves unrelated settings/comments. User-owned, edited or tracked
|
||||
entries cause explicit conflicts. Initial client trust or reload may still be
|
||||
required; Studio does not change approval policy.
|
||||
|
||||
Human grant publishes a fresh credential scoped to one canonical project root.
|
||||
HTTP sessions are bound to that credential, and the server enforces scope even
|
||||
for knowledge reads. Restricting only the connector would leave a direct HTTP
|
||||
bypass. Acquisition still creates a separate task identity through shared Core
|
||||
services.
|
||||
|
||||
## Publication Is Part of the Grant Transaction
|
||||
|
||||
Publication cannot be a best-effort snapshot listener. The neutral lifecycle port
|
||||
coordinates preparation, publication, activation, invalidation and cleanup:
|
||||
|
||||
1. Save and verify documents under the existing handoff rules.
|
||||
2. Acquire the OS publication lock and write a private temporary descriptor outside
|
||||
the authority monitor.
|
||||
3. Atomically publish, then activate under the grant generation fence. Acquisition
|
||||
remains unavailable until the transition completes.
|
||||
4. Abort failed or superseded grants and remove their provisional access.
|
||||
5. Revoke credentials before asynchronous work cleanup; remove only the owned
|
||||
publication and release its lock.
|
||||
|
||||
The lock file's inode is retained. Deleting it could let another process lock a
|
||||
new inode while the first owner still holds the old one. The OS releases the lock
|
||||
after a crash, allowing safe replacement of stale discovery data. Directories are
|
||||
0700 and secret-bearing files 0600; Git exclusion alone is not access control.
|
||||
Cleanup checks publication ownership so an old callback cannot delete newer data.
|
||||
File cleanup failure must not prevent runtime cancellation.
|
||||
|
||||
## Reconnect Without Replaying Intent
|
||||
|
||||
The stdio connector initializes and lists its packaged catalog before Studio or a
|
||||
grant is available. It verifies live instance, root and catalog identity before
|
||||
forwarding. Calls preserve structured results and native image blocks; response
|
||||
limits are separate from the smaller request limit.
|
||||
|
||||
Discovery and ping may be retried. Build and frame advancement must not be
|
||||
resubmitted automatically after a lost response. Within the same authorized task,
|
||||
recover by operationId/clientRequestId lookup. After restart, old in-memory
|
||||
receipts are unavailable: report an unknown outcome and require a fresh grant/task
|
||||
and an explicit next intent. Connection liveness and working/manual authority are
|
||||
separate DEV states.
|
||||
|
||||
## Implementation Findings
|
||||
|
||||
- JSON-RPC numeric IDs must be compared by numeric value. Jackson can represent
|
||||
the same wire number with different integer node types.
|
||||
- Grant publication is asynchronous. Tests must await the transition without
|
||||
blocking the JavaFX thread or assuming a button callback completes filesystem IO.
|
||||
- `jlink` can generate read-only license files. Normalize staged runtime write
|
||||
permissions so subsequent Gradle installation updates can replace them.
|
||||
- An IntelliJ desktop can run from classes without a managed installation. A
|
||||
generic “preparation incomplete” message hid this prerequisite. The specific
|
||||
diagnostic now points to `:prometeu-app:stageStudioInstallation` and the optional
|
||||
`studio.installationRoot` VM setting.
|
||||
- Preparation belongs to project opening, not only creation or a manual DEV
|
||||
button. Otherwise existing projects retain unnecessary onboarding friction.
|
||||
- Capture data larger than 1 MiB must not inherit the request-body cap. The
|
||||
connector bounds response size and body-read time separately.
|
||||
|
||||
## Verified Results and Acceptance
|
||||
|
||||
The full implementation gate recorded 839 passing tests, 15 existing skips and no
|
||||
failures, including installation, desktop and real runtime gates. The later
|
||||
missing-installation diagnostic and automatic-open revision passed their targeted
|
||||
preparation, Core, app, architecture and runtime suites. Installation staging,
|
||||
`git diff --check` and `discussion validate` also passed.
|
||||
|
||||
Process tests cover cold initialization, later grant and restart in one connector;
|
||||
large images; root/session scope; stale identity/catalog rejection; lost build
|
||||
response with execution count remaining one; unknown old-task receipts; concurrent
|
||||
publisher JVMs and crash recovery; protected files; grant/close races; TOML
|
||||
preservation; and stable installed Java across updates.
|
||||
|
||||
On 2026-09-29, after being asked specifically about the outstanding manual gates,
|
||||
the user confirmed that all were finished. This closes the native Codex
|
||||
acquire/build/image/release and reconnect-after-restart cycle, installation update
|
||||
and graphical-client launch, and IntelliJ debugger attachment. The provenance of
|
||||
this final evidence is **user-reported acceptance**, not an additional automated
|
||||
run or an independently observed transcript. The implementation's automated
|
||||
environment was macOS ARM64 with bundled Corretto 21.0.4 and Codex CLI 0.158.0
|
||||
installed; that version inspection alone was not treated as native-client proof.
|
||||
|
||||
The prior HTTP-only acceptance from DSC-0068 was not substituted for these gates.
|
||||
The first accepted integration remains Codex on macOS; other clients/platforms
|
||||
and the embedded terminal are outside this delivery.
|
||||
|
||||
## Operational Example
|
||||
|
||||
Open the project in Studio. Its enabled client integration is prepared without a
|
||||
separate per-project Run. Start the coding client in that project and satisfy its
|
||||
initial trust/reload requirements. Grant access in DEV, acquire the task through
|
||||
native tools, edit/validate, then release. After Studio restarts, grant again;
|
||||
keep the client configuration unchanged. An old task is never restored.
|
||||
|
||||
For an IntelliJ desktop, run `p.studio.app.StudioLauncher` with the
|
||||
`prometeu-app` classpath and Java 21. If a managed installation is missing, stage
|
||||
it once with `./gradlew :prometeu-app:stageStudioInstallation`. An isolated
|
||||
installation uses the `studio.installationRoot` desktop VM property. The MCP
|
||||
stdio process remains client-owned; attach Remote JVM Debug to that process using
|
||||
an explicit development-only loopback JDWP option. Do not configure the desktop
|
||||
Run itself with `mcp --project` arguments.
|
||||
|
||||
## References
|
||||
|
||||
- DEC-0061 and PLN-0140: historical source decision and completed implementation
|
||||
plan for DSC-0070; removed from active workflow during housekeeping.
|
||||
- [Studio shell and project creation](../../../docs/specs/studio/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md).
|
||||
- [Project-local state and discovery](../../../docs/specs/studio/8.%20Project-Local%20Studio%20State%20Specification.md).
|
||||
- [Core and adapter architecture](../../../docs/specs/studio/9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md).
|
||||
- [DEV and authority](../../../docs/specs/studio/10.%20DEV%20and%20Automation%20Specification.md).
|
||||
- [MCP contract and acceptance boundary](../../../docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
|
||||
- [Setup and IntelliJ debugging](../../../README.md).
|
||||
- [DSC-0068 baseline lesson](../DSC-0068-studio-headless-runtime-ai-first/LSN-0076-ai-first-studio-through-shared-authority-and-headless-evidence.md).
|
||||
- DSC-0071: the separate embedded-terminal discussion; unchanged by this work.
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
---
|
||||
id: LSN-0079
|
||||
ticket: compiler-pbx-registry-conformance
|
||||
title: Typed common IR through production PBX admission
|
||||
created: 2026-10-14
|
||||
tags: [runtime-integration]
|
||||
---
|
||||
|
||||
## Original problem and ownership
|
||||
|
||||
Owner: compiler/general; interfaces: compiler/pbs and studio.
|
||||
|
||||
The old producer carried parameter/result slot counts without complete semantic
|
||||
types and emitted a retired PBX function layout. A writer-only repair could not
|
||||
recover signatures, distinguish nominal identities or describe closures and
|
||||
trait implementations. The fix had to cross the entire common producer chain.
|
||||
|
||||
This lesson consolidates AGD-0076, accepted DEC-0063 and completed PLN-0142
|
||||
(DSC-0074). Those workflow artifacts were removed by housekeeping after their
|
||||
normative content and evidence were propagated. The active integration umbrella
|
||||
is [AGD75](../../workflow/agendas/AGD-0075-studio-runtime-readiness.md).
|
||||
|
||||
## Consolidated decisions
|
||||
|
||||
Use stable declaration references before assigning deterministic dense image
|
||||
IDs. Preserve Struct/Trait nominal identity; canonicalize Builtin imports,
|
||||
Array elements and Fn signatures. Names are descriptive, not nominal keys.
|
||||
Parameters, results, captures, implementations and lifecycle roles are explicit
|
||||
common values, preserved through IRVM, optimization and emission.
|
||||
|
||||
The common IR remains serializable by design, but a concrete codec was
|
||||
explicitly deferred. Complete representation does not require selecting a
|
||||
transport format. References avoid recursive Java object graphs and the public
|
||||
contract audit rejects mutable or frontend-specific shapes.
|
||||
|
||||
PBS is one frontend. Optional and Result already belong to PBS's normative
|
||||
language contract and have parser/semantic implementations. Defects in their
|
||||
executable lowering do not justify new backend categories or rejection rules.
|
||||
Their implementation and carrier choices remain frontend-owned. The user
|
||||
explicitly scoped consumer migration to subsequent tickets and a single AGD75
|
||||
integrated delivery. No PBS semantics were added to this backend change.
|
||||
|
||||
## Final implementation
|
||||
|
||||
- IRRegistry and FunctionMetadata represent all five type categories, ordered
|
||||
signatures/captures, roles and implementations. Aggregation remaps callable
|
||||
references while preserving stable type identity.
|
||||
- LinkedRegistry canonicalizes imports/structural declarations deterministically
|
||||
with an iterative dependency traversal. Nominal anchors permit recursion;
|
||||
purely structural cycles reject.
|
||||
- Lowering derives widths from semantic signatures, links typed operands and
|
||||
remaps implementation targets. IRVM coherence and optimization preserve the
|
||||
Registry and function metadata.
|
||||
- The PBX writer emits the 32-byte header and all eight mandatory sections,
|
||||
optional debug, strict UTF-8, exact function records and explicit empty capture
|
||||
environments. Width caches are not serialized. Constant deduplication now
|
||||
relocates PUSH_CONST indices rather than silently changing their meanings.
|
||||
- Local verification decodes all function ranges, validates references and
|
||||
operand categories, forbids retired/raw opcodes and analyzes reachable stack
|
||||
and type facts to convergence. Conflicts become Unknown; exact semantic groups
|
||||
retain provenance when available. Unknown remains subject to runtime checks.
|
||||
- Production loading remains authoritative for native identity/capability/ABI,
|
||||
runtime budgets and executable admission.
|
||||
- Studio previously discarded error.details when a headless response rejected
|
||||
boot. AutomationFailure now preserves the entire runtime error envelope,
|
||||
including initialization, binding and resource details, through MCP output.
|
||||
|
||||
## Examples and pitfalls
|
||||
|
||||
A `vec2 -> vec2` function has logical arity one/one and derived slot widths two/two.
|
||||
The function record writes the two TypeId lists, not the numbers two/two. A test
|
||||
compares that record with independent fixed bytes from the runtime contract.
|
||||
|
||||
A capturing body is not a direct-call target. MAKE_CLOSURE names the body and
|
||||
expected Fn type, consumes its explicit capture groups and produces a callable.
|
||||
CALL_CLOSURE consumes that callable after the explicit arguments. The synthetic
|
||||
frontend test proves this path without PBS source, SDK or language ASTs.
|
||||
|
||||
Jumps contain absolute offsets from the current function start. They are not
|
||||
relative to the next PC. A taken jump to function end is a return boundary;
|
||||
ordinary fallthrough is invalid. These details were checked against the actual
|
||||
runtime verifier, not inferred from older emitter behavior.
|
||||
|
||||
Do not derive type identity from slot width, spelling or display names. Do not
|
||||
claim a self-round-trip proves external conformance. Do not treat parser tests
|
||||
as execution evidence or a load-only argument-taking entry as a boot test.
|
||||
|
||||
Initialization diagnostics have null outer executed PC. A verifier PC remains
|
||||
nested in initError.load.pc; file offsets remain offsets. Preserve the original
|
||||
JSON structure rather than flattening it into human-readable messages.
|
||||
|
||||
## Qualification evidence
|
||||
|
||||
Runtime: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`.
|
||||
Platform: macOS 27.0.1 arm64. Rust harness uses the runtime Cargo.lock, default
|
||||
load limits and NONE capabilities except the positive native case (SYSTEM).
|
||||
Resource-negative cases explicitly lower Types, TemporaryBytes or Work.
|
||||
Runtime checkout remained unchanged.
|
||||
|
||||
| Gate | Result |
|
||||
| --- | --- |
|
||||
| Build-pipeline suite | 178 tests: 163 passed, 15 skipped, no failures |
|
||||
| Frontend-api suite | 28 passed |
|
||||
| PBS suite | 245 passed; not a claim of complete executable migration |
|
||||
| Headless process suite | 9 passed, including six observed runtime fault payloads |
|
||||
| Architecture suite | 17 passed |
|
||||
| Independent binary oracle | Exact 194-byte minimal image and fixed vec2 function bytes |
|
||||
| Production loader positives | 12 admitted images, including native binding |
|
||||
| Genuine execution | 11 programs: direct/common path, closures/captures, trait, Array/Dynamic, joins, roles, intrinsic and native; vec2 signature is load-only |
|
||||
| Production negative corpus | 32 rejected malformed/binding/code/resource fixtures |
|
||||
| Workflow and patch integrity | discussion validate and git diff --check passed |
|
||||
|
||||
The 15 skipped tests are older conditional integration adapters. The dedicated
|
||||
production harness above ran explicitly; their skip state is not substituted
|
||||
for runtime evidence. The intrinsic/native catalogue goldens are serialization
|
||||
fixtures and do not claim current PBS catalogue compatibility.
|
||||
|
||||
Reproduce with the commands in
|
||||
[the harness README](../../../tools/pbx-conformance/README.md). The harness
|
||||
creates its Cargo build outside the runtime checkout and saves generated PBX and
|
||||
observed JSON under the build-pipeline build directory.
|
||||
|
||||
## Remaining integration work
|
||||
|
||||
The runtime LoadReason enum has four values missing from the published headless
|
||||
schema: LifecycleRole, LifecycleSignature, DuplicateLifecycleRole and
|
||||
NonFiniteValue. The corpus observes the first and last. Both payloads fail the
|
||||
original schema solely because of the missing enum value. The harness explicitly
|
||||
reports this upstream gap, validates the original payload with that single enum
|
||||
addition, and leaves the payload unchanged. It does not claim those two cases
|
||||
conform to the unmodified schema. Runtime must correct the schema under AGD75.
|
||||
|
||||
PBS typed producer migration, Optional/Result executable lowering, catalogue
|
||||
alignment, installed runtime delivery, hook selection, memcard gating and
|
||||
persistence remain with their consumer tickets. The common schema and synthetic
|
||||
producer work without those features. There is no legacy PBX fallback and no
|
||||
slot-to-type inference to conceal an incomplete handoff.
|
||||
|
||||
## References
|
||||
|
||||
- [Typed common Registry/PBX specification](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md)
|
||||
- [Backend conformance matrix](../../../docs/specs/compiler/22.%20Backend%20Spec-to-Test%20Conformance%20Matrix.md)
|
||||
- [Runtime qualification harness](../../../tools/pbx-conformance/README.md)
|
||||
- Runtime sources: registry_v0.rs, program_image.rs, registry_verifier, and
|
||||
devtools/headless-protocol/response.schema.json at the revision above.
|
||||
+182
@@ -0,0 +1,182 @@
|
||||
---
|
||||
id: LSN-0080
|
||||
ticket: compiler-runtime-catalog-parity
|
||||
title: Manual runtime catalog port and independent conformance
|
||||
created: 2026-10-15
|
||||
tags: [runtime-integration]
|
||||
---
|
||||
|
||||
## Original problem and ownership
|
||||
|
||||
Owner: `compiler/general`; consumers: `compiler/pbs`, `vm-arch` and `studio`.
|
||||
This lesson consolidates AGD-0077, accepted DEC-0064 and completed PLN-0143
|
||||
(DSC-0075), including the user's explicit acceptance revision on 2026-10-15.
|
||||
Their workflow files were removed after propagation and CLI housekeeping.
|
||||
|
||||
The runtime published 105 intrinsics with 18 fields and 15 builtin constants
|
||||
occupying 16 slots. Studio had 42 intrinsic records with 12 fields, no constant
|
||||
mirror and a disabled parity test. Copying the CSV could not update the compiler's
|
||||
manual ABI representation, reject retired endpoints or preserve new effects.
|
||||
Against the previous Studio catalog, the port added 82 identities, removed 19
|
||||
and updated 23 retained identities.
|
||||
|
||||
## Consolidated decision
|
||||
|
||||
The runtime owns identities, layouts, constant values, effects and costs.
|
||||
Studio imports both CSVs unchanged at an explicit target revision, inventories
|
||||
the differences, then manually ports the compiler representation and consumers.
|
||||
`IRVMIntrinsicDefinition` represents the runtime supported by this compiler
|
||||
version. Normal compilation uses local versioned code/resources; it neither
|
||||
queries the latest runtime nor depends on a sibling checkout.
|
||||
|
||||
Manual maintenance keeps compiler adaptations explicit and reviewable, at the
|
||||
cost of maintaining a port. Active comparisons against independently exported
|
||||
CSV data detect drift. Enum generation, a shared implementation library and
|
||||
moving the backend were not required. An explicit provider check uses runtime
|
||||
source/tests to establish behavior and export provenance. A different runtime
|
||||
commit is not itself proof of incompatibility; revision and hashes identify
|
||||
the evidence target without introducing version negotiation.
|
||||
|
||||
Read dispatch, verifier and execution tests as well as CSVs. CSV fields describe
|
||||
the published shape but cannot explain all null handling, native-reference
|
||||
validation, traps or charging behavior.
|
||||
|
||||
## Final implementation
|
||||
|
||||
- `IRVMIntrinsicDefinition` and `IRVMIntrinsicRegistry` cover all 105 entries and
|
||||
18 published fields. Exact name/version resolution and ID lookup reject
|
||||
retired identities; old IDs are not compatibility aliases.
|
||||
- `IRVMBuiltinConstantDefinition` independently groups all 15 constants by
|
||||
target/name/version, preserving ordered slots and exact values/bits. Its
|
||||
materialization supplies common bytecode constant values.
|
||||
- Lowering checks caller counts against the selected definition. IRVM validation,
|
||||
emission and bytecode precheck reject unknown IDs and inconsistent signature
|
||||
caches, including unknown IDs in unreachable code. Module-only IRVM emission
|
||||
derives intrinsic signatures from the same target definitions.
|
||||
- Explicit carrier mappings distinguish Int32, Int64, Float, Bool, String,
|
||||
color and Random. Unsupported tokens fail. Static facts do not claim to prove
|
||||
native handle identity or session validity; the runtime remains authoritative.
|
||||
- Compiler and PBS SDK JARs package both CSVs and provenance from checked-in
|
||||
mirrors at `runtime-catalog/compiler/` and `runtime-catalog/pbs-sdk/`.
|
||||
Installed-resource tests validate actual JAR bytes/hashes outside the checkout.
|
||||
- Active parity tests, synthetic common-IR behavior and the production runtime
|
||||
harness provide separate evidence. No new PBS facade or numeric/random
|
||||
algorithm was implemented in this common backend work.
|
||||
|
||||
## Examples and pitfalls
|
||||
|
||||
**A retained name can have a different ABI.** `input.touch.x/y` moved to
|
||||
`0x2134/0x2135`, lost their receivers and return Int64. Resolving the name alone
|
||||
is insufficient; stale caller counts must fail. Input metadata coverage does
|
||||
not mean the existing PBS input syntax already lowers to these direct queries.
|
||||
|
||||
**Constants are not generic zero-argument intrinsics.** `mathf.pi` and
|
||||
`mathf.tau` materialize Float bits `0x400921FB54442D18` and
|
||||
`0x401921FB54442D18`. `vec2.zero` materializes two Float slots and has no
|
||||
intrinsic ID. Some color names independently have both mechanisms, which does
|
||||
not establish a rule for other constants. Pool deduplication may share the
|
||||
zero value but must preserve both emitted vec2 components.
|
||||
|
||||
**Determinism is not purity.** All four Random intrinsics mutate guest state;
|
||||
only `random.new` allocates. The tested common program aliases one generator,
|
||||
discards a `next` result, then mixes `nextf`, `range` and `next`. Removing the
|
||||
discarded call changes the sequence. Optimized and unoptimized executions
|
||||
matched the independent seed-42 vector and each used 100 cycles/20 steps.
|
||||
`random.range` preserves base cost 4, cost 8 per attempt and limit 64. The VM
|
||||
performs charging; storing metadata does not create a second Java scheduler.
|
||||
|
||||
**Static and dispatch rules can differ.** Runtime `abi_mask` permits String
|
||||
only for intrinsic String arguments, while `value_matches_abi_type` accepts
|
||||
String or null in dispatch. The Studio precheck therefore rejects a proven
|
||||
null at load time. The production loader confirmed that rejection with
|
||||
`LOAD_INVALID_CODE/TypeMismatch`; a String `#AABBCCDD` executed to color
|
||||
`0xAABBCCDD`. Random's static reference mask includes null, leaving native
|
||||
handle validity to runtime checks.
|
||||
|
||||
Do not use a serializer of the Java enum as its own expected catalog, infer
|
||||
carrier identity from slot width, disable stale fixtures to hide regressions,
|
||||
or equate JAR resource parity with successful PBS or installed-host execution.
|
||||
|
||||
## Qualification evidence
|
||||
|
||||
Selected runtime: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, clean checkout.
|
||||
Host: macOS 27.0.1 arm64; JDK 25 for Studio build and JDK 21 for the installed
|
||||
launcher. Provider exporter used Cargo test profile/default features; the
|
||||
production VM harness used dev profile/default features and default load
|
||||
limits. New catalog fixtures used NONE capabilities. Runtime was not modified.
|
||||
|
||||
| Artifact | SHA-256 |
|
||||
| --- | --- |
|
||||
| INTRINSICS.csv | `0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa` |
|
||||
| BUILTIN_CONSTANTS.csv | `e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039` |
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| Build-pipeline suite | 187 tests: 175 passed, 12 existing skips, zero failures |
|
||||
| PBS suite | 245 passed, zero failures; no claim of executable PBS migration |
|
||||
| Normal catalog parity | All fields, identities, constant bits/groups and packaged hashes passed |
|
||||
| Explicit provider check | Committed-source/mirror/hash comparison and real runtime exporter test passed; missing provider failed as required |
|
||||
| Catalog execution corpus | Random with alias/discarded mutation, exact constants, vec2.zero and String conversion passed on the actual VM |
|
||||
| Admission/availability negatives | Removed unreachable ID and proven-null String rejected; known input loaded then trapped UNAVAILABLE without hardware |
|
||||
| Installed catalog gate | Passed using actual compiler/SDK JAR resources and bundled launcher outside the checkout |
|
||||
| Full installed example gate | Failed before and after the port: missing typed metadata for Gfx.clear; explicit consumer handoff and acceptance revision below |
|
||||
| Workflow/patch integrity | `discussion validate` and `git diff --check` passed |
|
||||
|
||||
The complete existing PBX harness corpus also passed with its already documented
|
||||
runtime schema exceptions: LifecycleRole and NonFiniteValue remain absent from
|
||||
the published fault-schema enum. The harness reports these gaps and preserves
|
||||
payloads; this port does not claim the upstream schema was corrected.
|
||||
|
||||
Reproduce the catalog and consumer checks from the repository root:
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-compiler:prometeu-build-pipeline:test :prometeu-compiler:frontends:prometeu-frontend-pbs:test --console=plain
|
||||
./gradlew :prometeu-app:installedKnowledgeTest --tests '*installedCompilerAndSdkCarryTheSameVerifiedCatalog' --console=plain
|
||||
python3 tools/runtime-catalog/verify.py --runtime ../runtime
|
||||
python3 tools/pbx-conformance/run.py --runtime ../runtime
|
||||
```
|
||||
|
||||
## Accepted boundary and remaining consumer work
|
||||
|
||||
The full `:prometeu-app:installedKnowledgeTest` failed with
|
||||
`LOWER_IRVM_INVALID_TYPED_REGISTRY: typed function metadata required: Gfx.clear`.
|
||||
The same failure was reproduced on an independent archive of previous Studio
|
||||
HEAD `bd5694dbdf5b214b4295fc8e01ddbe0ba5479599`; only diagnostic stdout was
|
||||
enabled in its test probe to reveal the exact existing error.
|
||||
|
||||
On 2026-10-15 the user explicitly approved concluding catalog acceptance and
|
||||
leaving that correction with AGD-0078. DEC-0064 and PLN-0143 recorded this precise
|
||||
revision before housekeeping: the installed catalog probe is this delivery's
|
||||
mandatory installed gate; the full example test remains active and failing.
|
||||
All catalog, common behavior, affected module and provider-execution checks
|
||||
remain required and passed. No general waiver for future failures was granted.
|
||||
|
||||
- AGD-0078 owns PBS typed metadata, existing input/types and vec2 source
|
||||
materialization. Correct the Gfx.clear producer path and rerun the full
|
||||
installed example gate; do not weaken the common typed Registry contract.
|
||||
- AGD-0083 owns math/mathf facades, overloads and source constant exposure.
|
||||
`PbsExecutableBodyLowerer.emitBuiltinConstFetch` still assumes an intrinsic
|
||||
with one return; pi/tau require the independent constant materialization path.
|
||||
- AGD-0084 owns PBS Random handles, storage, aliasing and source replay tests.
|
||||
Common-IR execution provides a base, not proof of the future PBS facade.
|
||||
- AGD-0080 owns actual installed-runtime Build/Play/headless qualification.
|
||||
Catalog resources identify the compiler target without proving that flow.
|
||||
|
||||
These handoffs and the explicit acceptance revision are recorded in the active
|
||||
agendas and [integration umbrella](../../workflow/agendas/AGD-0075-studio-runtime-readiness.md).
|
||||
Future catalog updates must review source, imports, manual consumers, provenance
|
||||
and behavior together. Roll back that set together if necessary.
|
||||
|
||||
## References
|
||||
|
||||
- [Normative catalog support](../../../docs/compiler/general/specs/runtime-catalog-support.md)
|
||||
- [Typed common Registry/PBX contract](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md)
|
||||
- [VM mirror and provider verification policy](../../../docs/vm-arch/README.md)
|
||||
- [Production runtime harness](../../../tools/pbx-conformance/README.md)
|
||||
- Runtime sources at the recorded revision: catalog.rs, builtins.rs,
|
||||
input_intrinsics.rs, math_intrinsics.rs, random_intrinsics.rs, random.rs,
|
||||
registry_verifier/{heights,types}.rs and tests/numeric_contract.rs.
|
||||
|
||||
Workflow tooling note: the installed CLI registers an existing lesson but has
|
||||
no lesson-allocation command. LSN-0080 was selected by reading the next counter;
|
||||
`discussion housekeep` performed all index mutations and counter advancement.
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
---
|
||||
id: LSN-0081
|
||||
ticket: pbs-existing-types-input-alignment
|
||||
title: PBS Typed Values and Direct Input Queries
|
||||
created: 2026-10-15
|
||||
tags: [compiler/pbs, runtime-integration]
|
||||
---
|
||||
|
||||
## Context and result
|
||||
|
||||
Owner: **compiler/pbs**, with shared compiler IR and installed Studio consumer propagation. DSC-0076 (AGD-0078, accepted DEC-0065, completed PLN-0144) aligned existing PBS values and input with the published runtime. The original object chain exposed intermediate input objects that had no useful runtime representation. PBS also omitted exact executable function metadata, causing the full installed example to fail at `Gfx.clear` under the shared typed registry validator.
|
||||
|
||||
The delivered implementation replaces those chains, produces typed function metadata, preserves complete value groups, and passes both actual-runtime execution and the full installed knowledge gate. The completed agenda, decision and plan were removed through framework housekeeping; this lesson preserves their implementation evidence.
|
||||
|
||||
## Public selectors and direct runtime endpoints
|
||||
|
||||
Use a nominal selector value and a public query:
|
||||
|
||||
```pbs
|
||||
let button = Button.A;
|
||||
let pressed = Pad.pressed(button);
|
||||
let frames: long = Pad.hold(button);
|
||||
let x: long = Touch.x();
|
||||
```
|
||||
|
||||
`Button` has twelve cases: Up, Down, Left, Right, A, B, X, Y, L, R, Start, Select. The four Pad operations are pressed, released, down and hold. Each public function dispatches through an exhaustive enum switch to one of the 48 zero-argument LowPad endpoints. For example, `Pad.pressed(Button.A)` reaches `LowPad.a_pressed()`, bound to `input.pad.a.pressed`. The selector is evaluated once and only the selected endpoint reads input. Obtaining or passing a Button has no input effect. Constant specialization is unnecessary for correctness.
|
||||
|
||||
Touch exposes pressed/released/down as Bool and hold/x/y as Int64. The implementation uses existing runtime endpoints, with no ABI or lifecycle redesign. `Input.pad().a()` and aliases of its intermediate object are removed; import diagnostics explain the replacement. Strings, integers and unrelated enums cannot substitute for Button. The source type remains nominal even though its executable carrier is Int32.
|
||||
|
||||
## Exact values must survive frontend lowering
|
||||
|
||||
The explicitly accepted integer mapping is `int` to Int32 and `long` to Int64. Integer literals default to int; an explicit long context admits Int64 literals. Conversions use existing `as` syntax. Variables of different numeric widths require explicit conversion. Pad.hold and Touch.hold/x/y therefore return long.
|
||||
|
||||
`PbsRuntimeTypes` connects source types and declarations to canonical registry types and exact parameter/result groups. Callable lookup includes arity so overloaded SDK functions do not overwrite each other's signatures. Existing unsupported source types retain their previous executable boundary; shared strict metadata validation was not relaxed to admit them.
|
||||
|
||||
Locals, parameters, calls and returns carry whole groups: vec2 uses two Float slots and pixel uses two Int64 coordinates plus color. Slot count alone never establishes type identity. Builtin constants are resolved through the shared constant catalog: vec2.zero materializes two Float zero values, without inventing a one-result intrinsic. The backend validates the declared group width against the catalog materialization.
|
||||
|
||||
Named application first evaluates expressions in source order, stores their complete groups, and then loads those values in parameter order. The runtime proof calls `combine apply (y: Probe.y(), x: Probe.x())`: effects record Y then X while combine receives x then y. Its final oracle is 211020.
|
||||
|
||||
## Qualification evidence
|
||||
|
||||
Qualification date: 2026-10-15; platform: Darwin arm64. Studio base revision: `603ed012272b137361ba618f6887f015f7317803` plus this delivery's working-tree changes. Runtime revision: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`. The runtime checkout was not modified. Default Gradle configuration; controlled input and no-platform configurations in the real runtime harness.
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-compiler:prometeu-build-pipeline:test :prometeu-compiler:prometeu-frontend-api:test :prometeu-lsp:prometeu-lsp-v1:test :prometeu-app:installedKnowledgeTest --console=plain
|
||||
CARGO_TARGET_DIR=/tmp/pln144-cargo-target python3 tools/pbx-conformance/run.py --runtime ../runtime
|
||||
git diff --check
|
||||
discussion validate
|
||||
```
|
||||
|
||||
| Suite | Passed | Existing skips | Failures/errors |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| PBS frontend | 246 | 0 | 0 |
|
||||
| Build pipeline | 179 | 12 | 0 |
|
||||
| Frontend API | 28 | 0 | 0 |
|
||||
| LSP | 38 | 1 | 0 |
|
||||
| Full installed knowledge | 2 | 0 | 0 |
|
||||
|
||||
`PbsRuntimeAlignmentTest` generates 114 PBX programs through the production compiler, lowerer, emitter and preload verifier. The actual runtime harness loads and executes all of them:
|
||||
|
||||
- 48 Pad combinations using a local Button passed through a typed function, plus 48 direct constant combinations; controlled input asserts the exact returned value and exactly one selected read.
|
||||
- All six Touch queries, including signed x/y values. All 102 input programs are also executed without a platform and must trap with TRAP_UNAVAILABLE.
|
||||
- Twelve value/fault programs cover Int32, Int64, Float, String, color, vec2, pixel, tuple returns, named evaluation order, Int32 wrapping, checked narrowing and division by zero. Bool is covered by input queries. Registry default layouts are checked for all eight existing canonical value types.
|
||||
|
||||
Frontend negatives cover invalid Button arguments, mixed int/long variables, literal overflow and migration diagnostics. Existing shared tests continue to cover wrong typed signatures, stale touch signatures, unreachable removed IDs, and lifecycle assembly. The original full installed failure at `Gfx.clear` is fixed. This does not claim completion of the separate Studio desktop integration agenda. Existing upstream fault-schema gaps (LifecycleRole/NonFiniteValue) remain explicitly reported by the shared harness, without suppressing this delivery's oracles.
|
||||
|
||||
## Pitfalls and reusable patterns
|
||||
|
||||
- A dotted builtin target is already a complete catalog name: use `input.pad.a.pressed`, not a partial `a.pressed` that silently loses its owner.
|
||||
- A numeric literal's context must reach calls, returns and constructors; parsing an integer into a wide host value is insufficient to give it an Int64 guest type.
|
||||
- Handle the signed minimum literal before rejecting its positive magnitude. A positive value above Int64 maximum must produce a diagnostic, not become zero.
|
||||
- Preserve catalog overflow behavior: Int32 addition wraps; out-of-range narrowing traps with TRAP_NUMERIC_RANGE. Do not assume all numeric operations trap on overflow.
|
||||
- A switch can omit its final comparison only when exhaustive coverage is proven. Non-exhaustive statement switches must not execute an unmatched final arm.
|
||||
- A catalog or structural test alone cannot prove a frontend consumer. Generate PBS programs, run the real VM, and keep the full installed example as an independent gate.
|
||||
- Publish the focused canonical spec in installed knowledge as well as in the checkout. SDK exports, diagnostics, language services and examples must migrate together.
|
||||
|
||||
## References
|
||||
|
||||
- [Normative PBS input and existing-value contract](../../../docs/compiler/pbs/specs/input-and-existing-type-runtime-alignment.md)
|
||||
- [Shared runtime catalog contract](../../../docs/compiler/general/specs/runtime-catalog-support.md)
|
||||
- [Typed registry and PBX contract](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md)
|
||||
- [PBS source-to-PBX qualification](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeAlignmentTest.java)
|
||||
- [Actual-runtime harness instructions](../../../tools/pbx-conformance/README.md)
|
||||
+85
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: LSN-0082
|
||||
ticket: packer-runtime-graphics-conformance
|
||||
title: Packer Contracts and CI Failure Evidence
|
||||
created: 2026-10-16
|
||||
tags: [packer, studio, testing, jenkins]
|
||||
---
|
||||
|
||||
# Packer Contracts and CI Failure Evidence
|
||||
|
||||
## Original problem and scope
|
||||
|
||||
A broad runtime-readiness audit suggested graphics integration qualification,
|
||||
but historical review did not establish a new asset format migration. Existing
|
||||
Studio work already covered RGBA8888, scene identity and variable palettes.
|
||||
The actual opportunity was to strengthen producer-boundary evidence and ensure
|
||||
CI preserved useful results when tests failed.
|
||||
|
||||
Owner: packer; transverse owner: Studio Gradle/Jenkins infrastructure. The user
|
||||
explicitly excluded runtime provisioning in Jenkins and all new automated
|
||||
runtime tests, including local ones. Existing games remain the manual integrated
|
||||
verification method. This lesson does not claim those games were run.
|
||||
|
||||
## Consolidated decision and implementation
|
||||
|
||||
The packer's ordinary Java/JUnit suite now checks complete serialized GLYPH
|
||||
payloads for tile sizes 8/16/32 and palette counts 1/3/64, using independently
|
||||
authored hex expectations. Alpha, ordinary index zero and high-first nibble
|
||||
order are compared as bytes. A complete four-layer SCENE fixture covers
|
||||
little-endian identity, parallax, flags/flips and decoded-size accounting.
|
||||
An out-of-range palette cannot publish a new artifact.
|
||||
|
||||
A mixed-asset test reads the embedded header of assets.pa, checks sidecar
|
||||
agreement and proves that all payload slices cover the file contiguously.
|
||||
Two GLYPH preloads use slots 0/1 while SCENE uses its own slot 0; a fourth
|
||||
asset is deliberately not preloaded. AssetId 16909060 remains the scene's
|
||||
cold dependency even though the glyph preload slot is 1. These identities
|
||||
must not be conflated.
|
||||
|
||||
Jenkins now uses the repository wrapper, headless JVMs and a separate clean
|
||||
stage. Verification uses --continue: independent tests and reports complete,
|
||||
but Gradle still fails on test failure. Unconditional post handling isolates
|
||||
JUnit, coverage, HTML and archive publishers. Missing evidence after a successful
|
||||
verification is an error; failed preparation does not publish old reports.
|
||||
Existing coverage thresholds and their UNSTABLE policy remain unchanged.
|
||||
No production writer change was necessary.
|
||||
|
||||
## Evidence and limits
|
||||
|
||||
Studio base: 13c0ababbb0ff8623eb4df671729a891788b1ab1. Contract reference:
|
||||
runtime f7d7c167531bb662a1af9d73fc326bb476bf8aa7. Validation on 2026-10-16:
|
||||
|
||||
- Packer suite: 119 tests passed, zero skips; five new contract cases included.
|
||||
- Ordinary headless repository run: 897 tests, two failures, 13 existing skips.
|
||||
Consolidated JaCoCo XML and HTML were generated despite test failure.
|
||||
- Failures in unchanged files: PbsGradleDependencyAllowlistTest rejects the
|
||||
existing build-pipeline testImplementation PBS dependency; McpContractTest
|
||||
rejects an existing tool exampleArguments contract. The complete repository
|
||||
test gate is not green; these failures were not suppressed by this change.
|
||||
- Groovy 4.0.29 parsed the Jenkinsfile. Seven local step-double scenarios passed:
|
||||
success, test failure, publisher failure, missing contract report, absent
|
||||
reports on success/failure and clean failure. This does not validate actual
|
||||
controller plugins or constitute a Jenkins job run.
|
||||
- git diff --check and discussion validate passed.
|
||||
|
||||
No runtime invocation, automated frame comparison or manual gameplay was
|
||||
performed. Producer bytes passing these assertions do not prove live loading
|
||||
or presentation. Report manual game/revision/actions/results only after play.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Deriving expected bytes through the production writer makes an oracle circular.
|
||||
- Checking only exported JSON misses corruption in the embedded artifact header.
|
||||
- Publishing reports only after a successful shell step hides failure diagnostics.
|
||||
- Allowing empty reports on successful verification can turn absent execution into
|
||||
apparent success. Allow absence only when the build already failed.
|
||||
- A broad contract corpus is not a reason to duplicate existing tests or port a
|
||||
runtime decoder into Java. Keep checks at the producer's actual output boundary.
|
||||
|
||||
## References
|
||||
|
||||
- [Fixture interpretation and commands](../../../prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md).
|
||||
- [CI commands and failure behavior](../../../files/config/README.md).
|
||||
- [Build artifact specification](../../../docs/specs/packer/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md).
|
||||
- Completed workflow provenance: AGD-0079, DEC-0066, PLN-0145 (housekept after implementation).
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
---
|
||||
id: LSN-0083
|
||||
ticket: pbs-typed-collections-and-dynamic
|
||||
title: PBS Arrays Optional and Contract Execution
|
||||
created: 2026-10-16
|
||||
tags: [compiler/pbs, runtime-integration]
|
||||
---
|
||||
|
||||
# PBS arrays, optional values and contract execution
|
||||
|
||||
Owner: compiler/pbs. This lesson consolidates accepted DEC-0067 and completed PLN-0146 (DSC-0079). The [typed arrays specification](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md) is the normative reference; the [implementation evidence](../../evidence/DSC-0079-implementation/README.md) records the tested tree and commands.
|
||||
|
||||
## The original problem
|
||||
|
||||
Games need to reserve enemy positions before constructing enemies. Filling storage with fabricated objects or treating numeric zero as absence gives the wrong semantics. The runtime already offered Array, Dynamic, Struct and Trait, but their existence did not make PBS source executable: optional lowering, struct construction/fields and contract dispatch were incomplete.
|
||||
|
||||
The solution separates static source types, optional presence and physical storage. It also completes the existing struct/contract execution path instead of deferring it to closure work.
|
||||
|
||||
## The resulting source contract
|
||||
|
||||
```pbs
|
||||
let enemies: array<Enemy> = new array(10);
|
||||
let groups: array<array<Enemy>> = new array(3);
|
||||
let scores: array<int> = [10, 20, 30];
|
||||
|
||||
if let enemy = enemies[1] {
|
||||
enemy.takeDamage(10);
|
||||
}
|
||||
enemies.clear(1);
|
||||
```
|
||||
|
||||
Arrays have fixed length, shared reference identity and invariant element/depth types. Allocation initializes only outer positions to empty; it does not create enemies or nested arrays. Following DSC-0088, explicit `new array<T>(n)` supplies its own type; `new array<>(n)`, `new array(n)` and every array literal require an expected array type. Nesting uses `array<array<T>>`; compiler structural limits prevent unbounded expansion. Length and indices accept int/long without loss, with the promotion confined to these operations.
|
||||
|
||||
Reads return optional T. A vacant position is none, zero is present, and an invalid index faults. `if let` evaluates once and binds only in the success block. Optional fallback is lazy. Optional values, tuples, fields, parameters and results preserve complete groups. Optional array elements are rejected; an optional array itself is valid. PBS gains neither public Dynamic nor public null.
|
||||
|
||||
## How the implementation works
|
||||
|
||||
Array positions use internal Array<Dynamic>. Single-slot values are packed directly, while native multi-slot values use the runtime's immutable Dynamic boxing. A null Dynamic tag marks vacancy. Checking DYN_CAN_UNPACK alone is incorrect because a null carrier can be compatible with nullable types such as strings or references.
|
||||
|
||||
Private nullable Struct carriers represent optional values. None is null; some owns a carrier holding the complete payload. Named tuples are flattened across callable boundaries and privately boxed for storage. Tuple labels remain editorial metadata rather than changing compatible storage identity. Nominal struct and contract identities include declaration provenance, preventing unrelated modules from sharing a type merely because their names match.
|
||||
|
||||
The compiler emits actual struct allocations, field loads/stores, constructors, typed receivers, contract adapters and CALL_TRAIT. It selects overloads using parameter and result shapes and substitutes Self consistently in semantics and executable metadata. Imported calls retain their module identity. Services have a private singleton accessor so imports share the provider's instance.
|
||||
|
||||
Global initializers run through the file-init path in dependency order. This matters for reserved arrays: a source declaration must create storage before subsequent code uses it. Grouped global values use private carriers rather than losing slots.
|
||||
|
||||
## Lessons from failures found during implementation
|
||||
|
||||
- **VM availability is not frontend support.** A parser accepting an expression, or an assembly probe passing, says nothing about complete source lowering.
|
||||
- **Presence and compatibility are different questions.** Test the Dynamic tag before unpacking; do not turn type or bounds faults into absence.
|
||||
- **Global defaults are not nullable defaults.** VM global slots initially contain Int32 zero. The service singleton guard must recognize that initial state before publishing a reference.
|
||||
- **A tuple is not just its first slot.** Optional extraction, field storage and callable transport must agree on full layouts. Tuples stored in private carriers must be flattened again when read.
|
||||
- **Arity is insufficient for overloads.** Preserve input/output shape, Self substitution and module identity. Choosing a method by name and arity silently changes program meaning.
|
||||
- **Lexical scope also exists during lowering.** Restore slot/type/owner/projection bindings after blocks and if-let branches; semantic scope checks alone do not preserve shadowed runtime locals.
|
||||
- **Generated tests must be mandatory.** A runtime harness that scans only available files can pass while a producer stopped generating required fixtures. The structured corpus names every required case.
|
||||
|
||||
## Verified result and boundaries
|
||||
|
||||
The final gates executed 500 tests without failures; 13 pre-existing disabled tests are listed in the evidence. All 27 new PBS-to-production-PBX cases and 18 resource-refusal runs passed the real loader/VM, alongside 114 existing PBS fixtures and the common backend/catalog corpus. The integer-array case succeeds with one handle total. The GC case reclaims at least 1,100 discarded objects while preserving referenced objects, tuples and strings.
|
||||
|
||||
The GC safepoint is provided by an explicit test-only driver hook; it does not claim PBS sync/closure delivery. Default runtime quotas and GC thresholds were not relaxed. Two pre-existing upstream JSON-schema enum gaps remain explicitly reported by the existing harness. No installed-game qualification or performance claim is inferred from these results.
|
||||
|
||||
The installed knowledge package includes the specification and an executable [array example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/arrays.pbs). SDK collections continue in AGD89, closures in AGD82, and installed reference-game qualification in AGD88.
|
||||
|
||||
## Implementation references
|
||||
|
||||
- [Source conformance tests](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsStructuredValuesTest.java)
|
||||
- [Runtime harness and reproduction instructions](../../../tools/pbx-conformance/README.md)
|
||||
- [Static semantics](../../../docs/specs/compiler-languages/pbs/4.%20Static%20Semantics%20Specification.md)
|
||||
- [Dynamic semantics](../../../docs/specs/compiler-languages/pbs/9.%20Dynamic%20Semantics%20Specification.md)
|
||||
- [Earlier typed common IR/PBX lesson](../DSC-0074-compiler-pbx-registry-conformance/LSN-0079-typed-common-ir-to-production-pbx.md)
|
||||
+113
@@ -0,0 +1,113 @@
|
||||
---
|
||||
id: LSN-0084
|
||||
ticket: pbs-closures-and-indirect-calls
|
||||
title: PBS Function Values and Explicit Captures
|
||||
created: 2026-10-17
|
||||
tags: [compiler, pbs, runtime-integration]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Owner: `compiler/pbs`. PBS needed functions usable as ordinary values for game
|
||||
logic and agent-authored programs. Its nominal callback declarations and bind
|
||||
model did not provide the chosen structural function surface. Runtime support
|
||||
for closures already existed; source typing, lowering, tooling and executable
|
||||
integration still had to be delivered together.
|
||||
|
||||
The accepted DEC-0068 was implemented through PLN-0147. Both are completed
|
||||
workflow artifacts; this lesson preserves their durable rationale and outcome.
|
||||
|
||||
## Consolidated decision
|
||||
|
||||
`Fn(int) -> int` identifies the ordered parameter/result types. Named functions
|
||||
and lambdas with that signature can be assigned, passed, returned and stored.
|
||||
Calls use ordinary parentheses. Overloaded function identifiers need an expected
|
||||
signature that selects exactly one target.
|
||||
|
||||
Lambdas use `fn [captures](name: Type) -> Return { ... }`. Captures, parameter
|
||||
annotations, result annotation and block are explicit, including empty `[]`.
|
||||
This makes dependencies visible to both programmers and code-generating agents.
|
||||
The cost is deliberate verbosity; implicit capture and expression-body shorthand
|
||||
are not alternative forms.
|
||||
|
||||
Captures snapshot values at creation. Captured bindings cannot be reassigned,
|
||||
even when their source bindings were mutable. Capturing an object reference
|
||||
preserves object identity and permitted field mutation. Shared state therefore
|
||||
uses explicit objects instead of hidden shared lexical cells.
|
||||
|
||||
```pbs
|
||||
declare struct Counter(pub mut value: int);
|
||||
fn createCounter() -> Fn() -> int {
|
||||
let counter = new Counter(0);
|
||||
return fn [counter]() -> int {
|
||||
counter.value += 1;
|
||||
return counter.value;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Each factory call creates independent state. Two closures capturing the same
|
||||
counter intentionally share state. Arrays use `array<(Fn() -> int)>` and existing
|
||||
optional-read rules. Methods become function values through explicit lambdas
|
||||
capturing their receiver. The old `declare callback`, callback barrel exports
|
||||
and `bind(context, function)` are rejected.
|
||||
|
||||
## Objects and frames
|
||||
|
||||
A closure is a managed object with the same reachability lifecycle as other
|
||||
objects. Returning from its creator does not destroy it. Globals, arrays, fields
|
||||
and other captures can retain it across frames. GC traces its environment and
|
||||
collects unreachable closures and objects.
|
||||
|
||||
An invocation completes within its frame. Keeping a closure alive across frames
|
||||
does not suspend an invocation. PBS has no coroutine or sync syntax. The frontend
|
||||
already publishes FRAME_ROOT; the existing lifecycle assembler supplies the
|
||||
guarded wrapper and its return. Reuse that integration rather than introducing
|
||||
a new loop or frame-ending operation for closures.
|
||||
|
||||
## Implementation
|
||||
|
||||
The AST and type parser represent structural Fn inputs/results and explicit
|
||||
lambda captures. Semantic analysis creates an isolated capture/parameter scope,
|
||||
checks returns and signatures, and rejects uncaptured outer locals. Editor
|
||||
traversal uses lambda scopes so references, rename and completion preserve
|
||||
binding identity.
|
||||
|
||||
Lowering registers deterministic generated functions and ordered typed capture
|
||||
metadata. MAKE_CLOSURE creates values, GET_CAPTURE reads environments, and
|
||||
CALL_CLOSURE invokes the expected signature. Named functions use empty capture
|
||||
lists. Captures do not become public parameters. Existing common IR/PBX registry
|
||||
and runtime contracts supply the execution machinery without production changes
|
||||
to frame assembly or runtime authority.
|
||||
|
||||
Complete logical groups must survive capture and return: a tuple or contract
|
||||
receiver cannot be treated as one slot simply because its containing closure
|
||||
occupies one slot. Imported functions retain provider callable identity.
|
||||
|
||||
## Validation and pitfalls
|
||||
|
||||
The production VM executes nine closure programs returning 42 and six allocation
|
||||
quota/ownership cases. A separate fixture uses the real lifecycle wrapper for
|
||||
three frames: a stored closure and captured object survive the first collection,
|
||||
execute in the next frame, then become collectible after their root is cleared.
|
||||
Each frame discards another 1,200 closures. This proves both retention and release.
|
||||
|
||||
The final Gradle gates execute 513 tests without failures; 13 existing disabled
|
||||
tests and two existing runtime JSON-schema enum gaps are recorded explicitly.
|
||||
Installed knowledge includes the owner specification and a compiled example.
|
||||
|
||||
Common mistakes to avoid:
|
||||
|
||||
- Treating frame completion as destruction of all closure objects.
|
||||
- Adding coroutine/sync machinery merely to retain a function value.
|
||||
- Capturing a mutable local as a hidden shared cell instead of a snapshot.
|
||||
- Deep-copying captured objects and losing intended shared identity.
|
||||
- Testing only opcode emission while missing runtime roots, imports or full groups.
|
||||
- Leaving editor visitors or installed examples on the retired callback model.
|
||||
|
||||
## References
|
||||
|
||||
- [Normative function and capture specification](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
- [Implementation evidence and reproducible commands](../../evidence/DSC-0080-implementation/README.md).
|
||||
- [Production VM conformance harness](../../../tools/pbx-conformance/README.md).
|
||||
- [Executable installed example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/closures.pbs).
|
||||
+160
@@ -0,0 +1,160 @@
|
||||
---
|
||||
id: LSN-0085
|
||||
ticket: pbs-runtime-math-integration
|
||||
title: Service constants and source-to-runtime math conformance
|
||||
created: 2026-10-17
|
||||
tags: [runtime-integration]
|
||||
---
|
||||
|
||||
## Original problem and ownership
|
||||
|
||||
Owner: compiler/pbs. Supporting contract: compiler/general; runtime numeric
|
||||
semantics remain owned by the VM. This lesson consolidates accepted DEC-0069
|
||||
and implemented PLN-0148 from AGD-0083 / DSC-0081.
|
||||
|
||||
The common compiler already represented all runtime math identities and canonical
|
||||
constants. That did not make them usable from PBS source. The remaining work was
|
||||
service syntax, exact overload resolution, SDK publication, constant reads and
|
||||
source-to-production execution evidence.
|
||||
|
||||
## Consolidated decision
|
||||
|
||||
The user explicitly chose services themselves as namespaces. Services export
|
||||
constants alongside methods; there is no separate namespace declaration or new
|
||||
numeric builtin type. The same capability applies to project and SDK services.
|
||||
|
||||
`math` exposes exact int/long overloads and `mathf` exposes Float functions.
|
||||
Conversions between numeric carriers are explicit. The compiler consumes its
|
||||
existing manually ported, independently checked common catalog. It does not query
|
||||
a runtime checkout during normal compilation or duplicate the VM's math backend.
|
||||
|
||||
Pi and tau use canonical builtin constant materialization, not zero-argument
|
||||
intrinsics. Mathematical calls retain their faults and costs even with literal
|
||||
arguments. Qualification must start with source and compare exact bits, faults
|
||||
and cycles on a named runtime build.
|
||||
|
||||
## Final implementation
|
||||
|
||||
The service AST retains constant declarations with their owner. Parser, declaration
|
||||
checks, dependency/cycle validation, type resolution, lowering and editor member
|
||||
surfaces carry them through. Constants are immutable, exported with their service,
|
||||
and available through qualified reads and import aliases. Within the owner, a
|
||||
constant reference takes precedence over a same-named global; locals retain their
|
||||
normal lexical precedence. Explicit long annotations contextually type integer
|
||||
constant literals, without converting references to already typed int constants.
|
||||
|
||||
SDK services at `@sdk:math` and `@sdk:mathf` bind their 26 exact signatures through
|
||||
reserved IntrinsicCall metadata. Each generated callable loads its declared
|
||||
arguments, calls the common catalog identity and returns. Consequently its normal
|
||||
CALL/GET_LOCAL/RET overhead is distinct from the intrinsic's own charge. Imports
|
||||
with aliases resolve to the original provider callable identity.
|
||||
|
||||
BuiltinConst metadata on service constants records the qualified source name.
|
||||
The existing BUILTIN_CONST instruction materializes `IRVMBuiltinConstantDefinition`.
|
||||
Pi and tau retain bits `0x400921FB54442D18` and `0x401921FB54442D18`. A qualified
|
||||
constant read does not construct a singleton or call a getter. Constant-only
|
||||
probes cost six cycles: an ordinary load plus the root return.
|
||||
|
||||
```pbs
|
||||
import { math } from @sdk:math;
|
||||
import { mathf as numbers } from @sdk:mathf;
|
||||
|
||||
fn example(counter: long, angle: float) -> float {
|
||||
let bounded = math.clamp(counter, 0 as long, 100 as long);
|
||||
return math.to_float(bounded) + numbers.sin(angle) + numbers.pi;
|
||||
}
|
||||
```
|
||||
|
||||
General service constants use ordinary source expressions:
|
||||
|
||||
```pbs
|
||||
declare service Settings {
|
||||
declare const base: int = 40;
|
||||
declare const answer: int = base + 2;
|
||||
fn read() -> int { return answer; }
|
||||
}
|
||||
```
|
||||
|
||||
## Qualification and reproducibility
|
||||
|
||||
Runtime revision: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, unchanged clean checkout.
|
||||
Platform: macOS 27.0.1 arm64. Production harness profiles: dev and release;
|
||||
VM feature: resource-diagnostics, default load limits, NONE capabilities for math.
|
||||
Java build uses JDK 25; installed launcher uses the existing distribution runtime.
|
||||
|
||||
The corpus contains 261 independent numeric cases, emitted both normally and with
|
||||
the PBS/common optimizer enabled: 522 mandatory cases in each runtime profile.
|
||||
It combines the first 240 scalar provider fixture rows with exact published
|
||||
contract examples, removing duplicates. It covers all 26 signatures, signed zeros,
|
||||
subnormals, finite extrema, checked conversions, ties-to-even, invalid clamp,
|
||||
negative sqrt, abs(MIN) and atan2 axes. Additional probes cover pi/tau, direct
|
||||
literal sin, ordinary int/long constants, dependencies and a real project with
|
||||
SDK imports, service aliases and exported project constants.
|
||||
|
||||
Every numeric case checks the selected intrinsic identity, exactly one retained
|
||||
call, exact result bits or fault code, and per-instruction charging. Numeric costs
|
||||
come from independent fixture rows; other instruction costs come from the provider
|
||||
ISA contract. A full-budget execution must charge the sum of those steps.
|
||||
Optimized and unoptimized versions must charge identical totals.
|
||||
|
||||
| Gate | Result |
|
||||
| --- | --- |
|
||||
| PBS frontend suite | 249 tests passed |
|
||||
| Common backend suite | 175 passed, 12 pre-existing skips |
|
||||
| Selected architecture/source suites | Math, existing values/input, structured values and closures passed |
|
||||
| Installed knowledge | Both gates passed; packaged example imports math and aliased mathf |
|
||||
| Complete production harness | Passed in dev and release, including 522 math vectors per profile |
|
||||
| Workflow and patch integrity | discussion validate and git diff --check passed |
|
||||
|
||||
| Evidence artifact | SHA-256 |
|
||||
| --- | --- |
|
||||
| Runtime Cargo.lock | cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795 |
|
||||
| INTRINSICS.csv | 0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa |
|
||||
| BUILTIN_CONSTANTS.csv | e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039 |
|
||||
| Provider numeric-conformance.tsv | 5536ee18cadaf32e3719b0e8d541dfcf1a84a49ea978a702101547c5ccdee3fe |
|
||||
| Consumer numeric-source.tsv | 95067131dbc7a4252352424ee52f4b9215c8d8ecd80124218a38819211ff7ccb |
|
||||
|
||||
Reproduce from the Studio root:
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-compiler:prometeu-build-pipeline:test
|
||||
./gradlew :prometeu-architecture-tests:test --tests '*PbsRuntimeMathTest' --tests '*PbsRuntimeAlignmentTest' --tests '*PbsStructuredValuesTest' --tests '*PbsClosuresTest'
|
||||
./gradlew :prometeu-app:installedKnowledgeTest
|
||||
python3 tools/pbx-conformance/run.py --runtime ../runtime
|
||||
python3 tools/pbx-conformance/run.py --runtime ../runtime --release
|
||||
```
|
||||
|
||||
Optional CARGO_TARGET_DIR can preserve harness compilation artifacts in a temporary
|
||||
directory. The script never writes to the runtime checkout. Use --math-only for
|
||||
the complete math subset; it still rejects missing mandatory math fixtures.
|
||||
|
||||
Qualification on macOS/x86_64 and Linux/x86_64 remains pending. This delivery does
|
||||
not qualify those hosts, installed-runtime deployment or a complete reference game.
|
||||
The existing provider schema gaps for LifecycleRole and NonFiniteValue remain
|
||||
explicitly reported by the full harness; original payloads are preserved.
|
||||
|
||||
## Pitfalls and maintenance
|
||||
|
||||
- Catalog parity is not source integration. Test the facade, imports, overloads,
|
||||
actual emission and production VM together.
|
||||
- Constants are not nullary intrinsics. Preserve their canonical bits and ordinary
|
||||
load costs independently of method binding.
|
||||
- A service alias changes source spelling, not the provider callable identity.
|
||||
- Preserve constant ownership during expansion. Caller locals/globals must not
|
||||
accidentally change the lexical meaning of a constant's initializer.
|
||||
- Float equality hides the sign of zero. Conformance must compare raw bits.
|
||||
- Intrinsic costs exclude wrapper and argument-producing instructions. Charge and
|
||||
compare the complete program without treating virtual cycles as CPU timings.
|
||||
- Extend the corpus and its mandatory count together. Never silently skip absent
|
||||
fixtures, accept host tolerances, or replace provider oracles with compiler output.
|
||||
|
||||
## References
|
||||
|
||||
- [Service constants and runtime math specification](../../../docs/compiler/pbs/specs/service-constants-and-runtime-math.md)
|
||||
- [Runtime catalog policy](../../../docs/compiler/general/specs/runtime-catalog-support.md)
|
||||
- [Production harness](../../../tools/pbx-conformance/README.md)
|
||||
- [Catalog-port lesson](../DSC-0075-compiler-runtime-catalog-parity/LSN-0080-manual-runtime-catalog-port-and-conformance.md)
|
||||
- Historical execution artifacts: DEC-0069 and PLN-0148, removed by CLI housekeeping after completion.
|
||||
|
||||
Tooling note: the CLI has no lesson-allocation command. LSN-0085 was selected from
|
||||
the next counter; CLI housekeeping registers the lesson and advances that counter.
|
||||
+161
@@ -0,0 +1,161 @@
|
||||
---
|
||||
id: LSN-0086
|
||||
ticket: pbs-runtime-random-integration
|
||||
title: Explicit Random handles and source-to-runtime conformance
|
||||
created: 2026-10-17
|
||||
tags: [runtime-integration]
|
||||
---
|
||||
|
||||
## Original problem and ownership
|
||||
|
||||
Owner: `compiler/pbs`; supporting integration: `compiler/general`. This lesson
|
||||
consolidates AGD-0084, accepted DEC-0070 and completed PLN-0149 of DSC-0082.
|
||||
The user accepted the direction and authorized plan generation and implementation.
|
||||
The workflow scaffolding is removed by housekeeping; the normative PBS contract
|
||||
is [Runtime Random Integration](../../../docs/compiler/pbs/specs/runtime-random-integration.md).
|
||||
|
||||
The common catalog already contained all four Random entries, with a synthetic
|
||||
IR test of mutation and aliasing. That did not establish a usable PBS SDK or
|
||||
prove source evaluation, typed storage, imports and captures. A deterministic
|
||||
operation can still mutate state: the same seed is not permission to fold or
|
||||
eliminate a call.
|
||||
|
||||
## Consolidated decision
|
||||
|
||||
Expose an explicit opaque `Random` handle and `random.new/next/nextf/range`.
|
||||
Use the runtime's exact signatures, single-slot BuiltinId 0x0016 and catalog
|
||||
metadata. All operations mutate guest state; only new allocates. Do not add an
|
||||
implicit global generator, duplicate algorithm or compiler-side billing engine.
|
||||
|
||||
Copies alias the same generator. Two allocations with the same seed begin with
|
||||
equal sequences and evolve independently. Source order, named-argument effects
|
||||
and discarded calls must survive lowering and optimization. Handle identity must
|
||||
survive locals, globals, fields, arrays, parameters, results, captures and private
|
||||
Dynamic storage. The runtime remains authoritative for faults, transactional
|
||||
mutation, resources and cycles. No game seed policy or replay serialization API
|
||||
is introduced.
|
||||
|
||||
## Final implementation
|
||||
|
||||
Game SDK 1 publishes `Random` and `random` from `@sdk:random`, with normal import
|
||||
aliases and reserved metadata bindings. PBS registers Random as the existing
|
||||
runtime builtin. The parser accepts `new` in callable/member positions so the
|
||||
published spelling is `random.new(seed)`. It still distinguishes source allocation
|
||||
expressions, and rejects `new Random()`.
|
||||
|
||||
Fieldless builtins are treated as opaque by the semantic model. Exact contextual
|
||||
types prevent returning a Random reference as an unrelated Struct or contract;
|
||||
explicit contract adaptation is rejected too. Existing member checks reject
|
||||
payload access. The discovered return-path gap is now a frontend diagnostic,
|
||||
not a later backend stack/Registry error.
|
||||
|
||||
Existing array, optional, struct and closure lowering already preserves reference
|
||||
identity, so no second storage representation or common backend algorithm was
|
||||
needed. Common catalog tests and runtime execution verify the inherited effects
|
||||
and costs. The reference model remains language-neutral.
|
||||
|
||||
```pbs
|
||||
import { Random, random } from @sdk:random;
|
||||
|
||||
fn sample() -> long {
|
||||
let generator: Random = random.new(42 as long);
|
||||
let alias = generator;
|
||||
random.next(generator); // discarded result still advances shared state
|
||||
return random.range(alias, 0 as long, 100 as long);
|
||||
}
|
||||
```
|
||||
|
||||
The four operations use long/Float carriers exactly. `nextf` returns `[0,1)`;
|
||||
`range` returns `[min,max)` and requires `min < max`. Intrinsic costs are 32, 8,
|
||||
12 and `4 + 8*N` respectively. Range accepts at most 64 attempted words: attempt
|
||||
64 can succeed, while rejecting all 64 faults and rolls state back without
|
||||
refunding 516 charged cycles. Explicit source conversions and ordinary bytecode
|
||||
instructions have separate costs.
|
||||
|
||||
## Source evidence and provider evidence
|
||||
|
||||
`PbsRuntimeRandomTest` compiles the packaged SDK and project declarations through
|
||||
production linking, common lowering, optimization and PBX emission. A dedicated
|
||||
fixture uses the real workspace builder, import aliases and lifecycle assembler.
|
||||
The focused callable driver explicitly calls file initialization before Probe.main;
|
||||
it does not replace or introduce a lifecycle feature.
|
||||
|
||||
The 48 provider oracle rows cover six seeds and eight draws. Projecting both
|
||||
integer and Float outputs, with optimization off/on, produces 192 fixtures.
|
||||
Another 30 source fixtures cover aliases, independent objects, mixed/discarded
|
||||
operations, named/positional effects, storage/captures, limits, faults and GC. Four
|
||||
controlled provider fixtures cover null and typed-null carriers. Together with real
|
||||
imports this is **223 source fixtures plus four controlled provider fixtures**.
|
||||
The DEC-0073 follow-up requalified this revised corpus in the dev profile; the
|
||||
original debug/release evidence below describes the earlier source corpus.
|
||||
Each of the 226 callable fixtures executes with single-step budgets and twice
|
||||
with full budgets to compare exact bits/faults, call charges and total cycles.
|
||||
The runner checks oracle byte equality against the selected runtime.
|
||||
|
||||
The GC fixture reuses the established test-only FRAME_SYNC marker mechanism.
|
||||
All allocations and accesses are PBS source. After at least 1,100 discarded
|
||||
Random objects are reclaimed, array, field and closure roots still draw the
|
||||
expected shared sequence. The source corpus also exercises a genuine rejected
|
||||
PCG word followed by acceptance, charging range 20 cycles.
|
||||
|
||||
PBS has no public null or Dynamic type. Following the explicit DEC-0073
|
||||
clarification, every completing constructor path initializes every field. Null
|
||||
coverage uses a controlled provider fixture: compile a fully initialized Random
|
||||
field, then suppress its unique field store in test bytecode to exercise the provider
|
||||
reference default.
|
||||
Storing it in a typed array preserves a present Dynamic tag and exact TypeId;
|
||||
extracting it then drawing traps NULL_REFERENCE. This must not be confused with
|
||||
an empty array slot. Existing global-initializer restrictions are unchanged.
|
||||
|
||||
Provider evidence is separate: 13 guest contract tests and 11 private Random
|
||||
engine/VM tests passed in both debug and release. Those prove synthetic
|
||||
64th-attempt success, capped rejection rollback, malformed carriers, fault
|
||||
precedence, resource refusal, exact Dynamic types, stale handles, reset and
|
||||
native provenance. They are not described as PBS-produced rare-path execution.
|
||||
|
||||
## Validation and limits
|
||||
|
||||
The [evidence record](evidence.json) pins source/catalog/oracle/lockfile hashes,
|
||||
commands, toolchains, profiles and suite counts. Executed on macOS arm64 with
|
||||
runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`.
|
||||
|
||||
- Java: frontend 249 passed; architecture 63 passed; common pipeline 175 passed
|
||||
with 12 existing skips; installed knowledge 2 passed. Total: 489 passed.
|
||||
- Full production-loader conformance harness passed in debug and release,
|
||||
including all 227 Random fixtures and existing math/input/Registry/collection
|
||||
and closure suites.
|
||||
- Runtime provider Random suites: 13 contract + 11 private tests per profile.
|
||||
- Catalog copies and provider exporter matched; workflow and diff validation passed.
|
||||
|
||||
Qualification covers the local target only. Other platforms and the reference
|
||||
game's corpus are not claimed. The full harness retains the pre-existing,
|
||||
explicitly reported runtime fault-schema gaps for LifecycleRole and NonFiniteValue;
|
||||
this work neither changes nor hides them. Installed knowledge validates packaged
|
||||
SDK/spec/example delivery, not execution through an installed runtime process.
|
||||
|
||||
## Pitfalls and maintenance
|
||||
|
||||
1. Do not confuse deterministic with pure. Eliminating a discarded draw changes
|
||||
every subsequent result; eliminating discarded new also changes allocation.
|
||||
2. Do not duplicate the RNG in Java to prove Java output. Keep independent provider
|
||||
vectors and execute generated PBX on the VM.
|
||||
3. Do not use interface-module validation for arbitrary project code. The tests
|
||||
compile SDK metadata separately and link trusted declarations into project source.
|
||||
4. Do not use a runtime carrier's physical HeapRef shape as permission for a
|
||||
Struct/contract adaptation. Exact source and Registry identities matter.
|
||||
5. Distinguish present typed null from absent Dynamic. Check the tag before unpacking.
|
||||
6. Keep new fixture families separate from older enumerated corpora; the old
|
||||
eight-type input suite must not accidentally count Random fixtures.
|
||||
7. Record fingerprints and distinguish provider rare-path proofs from source
|
||||
tests. A passing synthetic common-IR test is not a source integration claim.
|
||||
|
||||
## References
|
||||
|
||||
- [PBS Random specification](../../../docs/compiler/pbs/specs/runtime-random-integration.md).
|
||||
- [Typed arrays and optional execution](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
|
||||
- [Functions and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
- [Conformance commands and boundaries](../../../tools/pbx-conformance/README.md).
|
||||
- [Provider Random specification](../../../../runtime/docs/specs/runtime/02e-vm-owned-random-core.md).
|
||||
- [Provider qualification](../../../../runtime/docs/vm-arch/RANDOM_QUALIFICATION.md).
|
||||
- Historical accepted DEC-0070 and completed PLN-0149: obligations are preserved
|
||||
in the normative spec, this lesson and its evidence after workflow cleanup.
|
||||
@@ -0,0 +1,114 @@
|
||||
{
|
||||
"date": "2026-10-17",
|
||||
"discussion": "DSC-0082",
|
||||
"decision": "DEC-0070",
|
||||
"plan": "PLN-0149",
|
||||
"runtime_revision": "f7d7c167531bb662a1af9d73fc326bb476bf8aa7",
|
||||
"platform": "macOS-27.0.1-arm64-arm-64bit-Mach-O",
|
||||
"rustc": "rustc 1.98.1 (48a229cea 2026-09-01)\nbinary: rustc\ncommit-hash: 48a229ceaefd4985c50990b14116b6d856af0985\ncommit-date: 2026-09-01\nhost: aarch64-apple-darwin\nrelease: 1.98.1\nLLVM version: 22.1.8",
|
||||
"java": "openjdk version \"25.0.4\" 2026-07-21 LTS\nOpenJDK Runtime Environment Corretto-25.0.4.7.1 (build 25.0.4+7-LTS)\nOpenJDK 64-Bit Server VM Corretto-25.0.4.7.1 (build 25.0.4+7-LTS, mixed mode, sharing)",
|
||||
"runtime_profiles": [
|
||||
"dev",
|
||||
"release"
|
||||
],
|
||||
"harness_features": [
|
||||
"resource-diagnostics"
|
||||
],
|
||||
"provider_features": "default",
|
||||
"source_fingerprints": {
|
||||
"../runtime/Cargo.lock": "cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795",
|
||||
"../runtime/docs/vm-arch/INTRINSICS.csv": "0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa",
|
||||
"../runtime/docs/vm-arch/BUILTIN_CONSTANTS.csv": "e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039",
|
||||
"../runtime/crates/console/prometeu-vm/tests/fixtures/random-conformance.tsv": "0bee1cd0366f1716687aee8c7ac39dd495da5fe2908cce37b1443cb04fac542f",
|
||||
"../runtime/crates/console/prometeu-vm/tests/random_contract.rs": "de961a4c57c4ed7b1f01b002abd8a319c3fed90cb5bce07a5c023ef9239490b1",
|
||||
"../runtime/crates/console/prometeu-vm/src/random.rs": "48e46d50f0665c85bb899d7324783cb1b5121378cb21f06059f2c2617e6d9e16",
|
||||
"../runtime/crates/console/prometeu-vm/src/virtual_machine/random.rs": "136cdbe46a687a7b755d559a2842d44f494cf76e8a34427eeb48494820935a42",
|
||||
"tools/pbx-conformance/main.rs": "76d3d1b90b417c33737fb0ede6ea7af8ffe586bfb2bf4f710684a8d9f72c7466",
|
||||
"tools/pbx-conformance/run.py": "49b01cfc81d378871ca3cc32dec7b1f830fdb7c86545d5a32e2e3455c4f1588f",
|
||||
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeRandomTest.java": "2d474bd65b0ddcfa2b9ad8d7887c2f964cf73336a8747f4f34478e6a2137bf59",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/random/main.pbs": "c21c12d99c5a033a1e4026432bbab56393ad09c0fe2d36711504ccca01ce93b5",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/random/mod.barrel": "7924c022a140b9bc634f3699175c8775f24093d3aa82e650752232971b0380fb",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsRuntimeTypes.java": "c973cb5de13a3e1bddaecad140436ea54d4a78ac5f08310511a60b637630889a",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsDeclarationParser.java": "50d494f4e2b79d7147acc25e0ce4cad244ef2a04288ea823aecdd5347feb48c6",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsExprParserContext.java": "7b6de40de18fd676210bcfc6655b0dbbd10d589513d35f1cf0c4b01cbf30e7d5",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowExpressionAnalyzer.java": "4775395a00edba94ff55cd2d93959973fc8ad70cae260cc5e2631087827eee9d",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowSemanticSupport.java": "2c39d3fed360aeef0ac1c6c8f8c1d92989f84f60cbe23dd01ebce8a9d575d128",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowStructuralExpressionAnalyzer.java": "ba32cc9521ee4bc4840e0910566b4fad7d50a382dac8288c4f6e1ac3ab2fe4ab"
|
||||
},
|
||||
"java_tests": {
|
||||
"frontend": {
|
||||
"passed": 249
|
||||
},
|
||||
"architecture": {
|
||||
"passed": 63
|
||||
},
|
||||
"common_pipeline": {
|
||||
"passed": 175,
|
||||
"existing_skipped": 12
|
||||
},
|
||||
"installed_knowledge": {
|
||||
"passed": 2
|
||||
}
|
||||
},
|
||||
"random_fixtures_per_profile": 227,
|
||||
"callable_replays_per_fixture": 3,
|
||||
"provider_tests_per_profile": {
|
||||
"random_contract": 13,
|
||||
"private_random": 11
|
||||
},
|
||||
"commands": [
|
||||
"./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test :prometeu-compiler:prometeu-build-pipeline:test :prometeu-app:installedKnowledgeTest --console=plain",
|
||||
"CARGO_TARGET_DIR=/tmp/pln149-cargo-target python3 tools/pbx-conformance/run.py",
|
||||
"CARGO_TARGET_DIR=/tmp/pln149-cargo-target python3 tools/pbx-conformance/run.py --release",
|
||||
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm random --target-dir /tmp/pln149-provider-target",
|
||||
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm --lib random --release --target-dir /tmp/pln149-provider-target",
|
||||
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm --test random_contract --target-dir /tmp/pln149-provider-target",
|
||||
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm --test random_contract --release --target-dir /tmp/pln149-provider-target",
|
||||
"python3 tools/runtime-catalog/verify.py --runtime ../runtime"
|
||||
],
|
||||
"logs": {
|
||||
"regression": {
|
||||
"sha256": "1379beaf5dbb205c9ff5894775835467dd0772fad3b87f3241b94e03c6609bf8",
|
||||
"result": "passed"
|
||||
},
|
||||
"conformance-dev": {
|
||||
"sha256": "99e7c3a4b5c3f1a408d22eef8a736b9a6fd061eff5c13e405c1bd019f504ce4d",
|
||||
"result": "passed"
|
||||
},
|
||||
"conformance-release": {
|
||||
"sha256": "f1df27a348bb98976b4ee0b46a0e121b56d524aab5f43deecc0c705c08e1fd79",
|
||||
"result": "passed"
|
||||
},
|
||||
"provider-dev": {
|
||||
"sha256": "3b9b0b522d3c5ed305536aa5be621fc34f0b4cce0f6b5705626052a4fb252be2",
|
||||
"result": "passed"
|
||||
},
|
||||
"provider-release": {
|
||||
"sha256": "8555828137f4e747f079145892c7c11e18ac55f2e9720497affaf9fe828f48b9",
|
||||
"result": "passed"
|
||||
},
|
||||
"provider-contract-dev": {
|
||||
"sha256": "5c2a31b0f33e75dfe644993e0e79f8cf19bd01bc95db23b41190fc2069d16f8e",
|
||||
"result": "passed"
|
||||
},
|
||||
"provider-contract-release": {
|
||||
"sha256": "cbf430b84132edbdda2fe0b5ab34cf5fad6e78a048811695efe223eac37a3333",
|
||||
"result": "passed"
|
||||
},
|
||||
"catalog": {
|
||||
"sha256": "66b7003ff94115aece4b278522b0c080e806497e26ca17dd756163bc7974fa83",
|
||||
"result": "passed"
|
||||
}
|
||||
},
|
||||
"limitations": [
|
||||
"macOS arm64 only",
|
||||
"Reference-game and installed-runtime process qualification excluded",
|
||||
"Existing explicit provider schema gaps LifecycleRole and NonFiniteValue retained"
|
||||
],
|
||||
"follow_up_2026_10_22": {
|
||||
"discussion": "DSC-0094",
|
||||
"scope": "Explicitly authorized complete PBS constructor field initialization; revise null fixtures to controlled provider injection",
|
||||
"qualification": "227 Random fixtures passed on macOS arm64 dev; prior release evidence describes the original corpus",
|
||||
"evidence": "../DSC-0094-pbs-generic-structs/evidence.json"
|
||||
}
|
||||
}
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
---
|
||||
id: LSN-0087
|
||||
ticket: pbs-array-type-syntax
|
||||
title: Parametric arrays and contextual construction
|
||||
status: consolidated
|
||||
created: 2026-10-19
|
||||
tags: [compiler-pbs, arrays, type-inference, parsing]
|
||||
---
|
||||
|
||||
# Parametric arrays and contextual construction
|
||||
|
||||
Owner: `compiler/pbs`. Worker: Lesson Worker. Discussion: DSC-0088.
|
||||
|
||||
## Original problem and consolidated decision
|
||||
|
||||
Array already executed through PBS, PBX and the VM, but its `array T` and `array[N] T` syntax did not match the parametrized notation selected for future collections. DEC-0071, explicitly accepted by the user and implemented through PLN-0150, replaced that syntax without changing the storage contract. Those completed workflow artifacts were removed by housekeeping; this lesson and the specs retain their operational content.
|
||||
|
||||
Use `array<T>` and composition for nesting. Explicit construction supplies the type; both contextual sugars receive it:
|
||||
|
||||
```pbs
|
||||
let a = new array<Enemy>(10);
|
||||
let b: array<Enemy> = new array<>(10);
|
||||
let c: array<Enemy> = new array(10);
|
||||
let groups: array<array<Enemy>>=new array<>(3);
|
||||
```
|
||||
|
||||
The first binding infers `array<Enemy>`. The next two constructor forms are equivalent and require a sufficient expected array type. Length does not infer the element type. The last allocation creates three empty outer positions, without allocating inner arrays. Old Array spellings are rejected rather than supported in parallel.
|
||||
|
||||
All prior execution rules remain: fixed length, reference aliases, invariance, vacancy versus present zero, optional reads, faults for invalid indices, int/long lengths and indices, single evaluation, complete value groups, nominal identity, ownership, quotas and GC. Optional elements remain invalid; optional arrays remain valid. Literal arrays remain contextual. This work does not implement shifts, new collections, generic structs/functions or broader overload inference.
|
||||
|
||||
## Implementation and architectural boundaries
|
||||
|
||||
`PbsAst.TypeRef` already provides a recursive `inner` node and a span for each type. Reuse that representation for Array's single argument. `NewExpr` now also carries an explicit array TypeRef and a diamond marker; its original total span remains available. An explicit element argument therefore retains its source identity and diagnostics span.
|
||||
|
||||
`PbsTypeParser` recognizes angle delimiters and enforces the existing structural nesting limit, including the constructor's outer array node. Barrel types use the same parser. `PbsTokenCursor.consumeTypeClose` peels one closing `>` and preserves the remaining token and byte offsets. For example, a type close taken from `>=` leaves `=` for the binding parser. The mechanism can also peel combined `>>`/`>>=` tokens if tokenization later changes, without adding shifts now. Ordinary expression comparisons remain intact; result and Fn spellings do not change.
|
||||
|
||||
Flow analysis resolves explicit constructor types without an expected destination, validates element surfaces and names, and checks invariant compatibility when a destination exists. Contextual construction uses the existing expected-type path for local/global bindings, assignment, arguments with a single resolved signature and returns. Missing context is an error, including unresolved overload contexts; no new overload inference was introduced.
|
||||
|
||||
PBS lowering must independently know the explicit constructor type. Local inference already consumes the initializer type, but updating only semantic analysis would leave executable lowering without enough information. Common backend and VM representations remain unchanged. Source type renderers now emit `array<T>`; editorial tests cover constructor-only element references, rename, inferred receiver completion and formatter round trips.
|
||||
|
||||
## Pitfalls exposed by execution
|
||||
|
||||
- Do not assume that parser acceptance proves execution. New constructor AST fields must feed semantic analysis, lowering and editorial type displays.
|
||||
- Do not use the enclosing expression's expected return type to match a contextual constructor argument. The integrated test exposed this in lowering: constructor arguments need the selected parameter's type. Statically validated contextual constructors now follow the contextual argument path.
|
||||
- Do not globally split comparison tokens. Peel type closers only in type context and retain exact remainder spans.
|
||||
- Do not infer element type from length or silently coerce invariant arrays.
|
||||
- Do not leave a second type grammar in barrel parsing or obsolete examples in installed knowledge.
|
||||
- Do not count only the element subtree when checking explicit-constructor nesting limits; the outer array is a node too.
|
||||
|
||||
## Validation and final result
|
||||
|
||||
On 2026-10-19 the following gates passed without failures or errors:
|
||||
|
||||
| Gate | Result |
|
||||
| --- | --- |
|
||||
| PBS frontend | 255 tests, none skipped |
|
||||
| Architecture PBS tests | 64 tests, none skipped |
|
||||
| LSP v1 | 39 tests, one skipped |
|
||||
| Installed knowledge | 2 tests, none skipped |
|
||||
| Production loader/VM harness | Exit 0; new array-parametric fixture and existing structured, optional, alias, group, fault, resource, closure/GC, Random, math and catalog corpora |
|
||||
| Whitespace review | `git diff --check` passed |
|
||||
|
||||
The new runtime fixture checks explicit local inference, diamond/omitted call arguments, global initialization/assignment, return context, nested outer-only allocation, aliases, adjacent closers/assignment and ordinary `>=`; its expected result is 42. Frontend tests separately cover all three constructor forms across expected-type positions, invariant mismatches, unknown/optional/void element types, missing context, malformed/obsolete types, nesting bounds and compound token spans.
|
||||
|
||||
Reproduce the Java gates with:
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test --tests '*Pbs*' :prometeu-lsp:prometeu-lsp-v1:test :prometeu-app:installedKnowledgeTest --console=plain
|
||||
python3 tools/pbx-conformance/run.py --runtime ../runtime
|
||||
```
|
||||
|
||||
Local run logs were `/tmp/agd90-final-tests.log`, `/tmp/agd90-frontend-final.log` and `/tmp/agd90-vm2.log`; this summary preserves the evidence after temporary logs expire.
|
||||
|
||||
## References
|
||||
|
||||
- [Normative Array contract](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
|
||||
- [Function values and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
- [Array storage and optional execution](../DSC-0079-pbs-typed-collections-and-dynamic/LSN-0083-pbs-arrays-optional-and-contract-execution.md).
|
||||
- [Executable installed example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/arrays.pbs).
|
||||
- Completed workflow: AGD-0090 → DEC-0071 → PLN-0150 → this lesson. Future collection and contract discussions consume this completed syntax foundation independently.
|
||||
+204
@@ -0,0 +1,204 @@
|
||||
---
|
||||
id: LSN-0088
|
||||
ticket: pbs-generic-contracts
|
||||
title: Concrete Generic Contracts from PBS Source to the VM
|
||||
created: 2026-10-20
|
||||
tags: [compiler-pbs, generic-contracts, nominal-identity, runtime-conformance]
|
||||
---
|
||||
|
||||
## Original problem and final result
|
||||
|
||||
Owner: `compiler/pbs`; cross-domain propagation: `compiler/general` and Studio/LSP.
|
||||
DSC-0089 implemented accepted DEC-0072 through PLN-0151. Those control artifacts
|
||||
are removed by housekeeping; the linked specifications are the operational
|
||||
reference. All twelve decision requirements were implemented together.
|
||||
|
||||
PBS already supported nominal contracts and concrete implementation tables. The
|
||||
missing feature was a frontend path from `Identity<T>` to exact concrete types.
|
||||
Simple contract names appeared in the AST, imports, validation, lowering and
|
||||
editor projections. Extending only the parser would have left those consumers
|
||||
disagreeing about the same program.
|
||||
|
||||
The completed path is:
|
||||
|
||||
```text
|
||||
parameterized declaration + explicit application
|
||||
-> resolve defining declarations and logical arguments
|
||||
-> memoize nominal application and substitute signatures
|
||||
-> emit concrete Trait, implementation and function metadata
|
||||
-> existing PBX loader/verifier and CALL_TRAIT execution
|
||||
```
|
||||
|
||||
There is no runtime generic-instantiation engine or new PBX/ISA category. One
|
||||
distinct application has one nominal Trait identity per image. Equivalent
|
||||
applications share it. This delivers user-defined generic contracts; collection
|
||||
storage and algorithms remain separate work.
|
||||
|
||||
## Using a strategy
|
||||
|
||||
```pbs
|
||||
declare contract Identity<T> {
|
||||
fn hash(e: T) -> int;
|
||||
fn equals(a: T, b: T) -> bool;
|
||||
}
|
||||
|
||||
declare service IntIdentity {}
|
||||
|
||||
implements Identity<int> for IntIdentity using strategy {
|
||||
fn hash(e: int) -> int { return e; }
|
||||
fn equals(a: int, b: int) -> bool { return a == b; }
|
||||
}
|
||||
|
||||
fn equalSeven() -> bool {
|
||||
let identity: Identity<int> = IntIdentity;
|
||||
return identity.equals(7, 7);
|
||||
}
|
||||
```
|
||||
|
||||
`IntIdentity` is the receiver; `int` describes the elements. The service keeps
|
||||
its singleton identity. Structs can instead provide constructed strategy
|
||||
instances. Contextual assignments, arguments and returns, or explicit `as`,
|
||||
form a view without allocating an adapter wrapper.
|
||||
|
||||
A contract can have several ordered parameters, such as `Converter<A, B>`.
|
||||
Applications are explicit, exact-arity and invariant. A barrel exports the
|
||||
declaration (`pub contract Identity<T>;`), not one closed application. There are
|
||||
no raw types, contract diamond inference, default arguments, blanket generic
|
||||
implementations or injected direct owner methods.
|
||||
|
||||
## Identity is resolved before representation
|
||||
|
||||
`PbsContractTypes` is the PBS-owned resolution and substitution boundary. Its
|
||||
application key contains the defining declaration and ordered canonical logical
|
||||
argument keys. File/source declaration identity distinguishes unrelated nominal
|
||||
types; length-framed child keys avoid ambiguous nested encodings. Display names
|
||||
and image-local numeric TypeIds are not identity keys.
|
||||
|
||||
Imports carry a semantic `TypeBindingDecl`: the local spelling, original
|
||||
declaration and importing scope. The original signature keeps its lexical scope.
|
||||
Reexports propagate that binding rather than synthesizing a new declaration.
|
||||
Thus importing `Enemy as Opponent` makes `Identity<Opponent>` the same type as
|
||||
`Identity<Enemy>`. Two unrelated declarations both named `Enemy` remain distinct.
|
||||
The production multi-module fixture exercises both properties.
|
||||
|
||||
Physical storage must follow logical resolution. `array<int>` and `array<bool>`
|
||||
can share the internal Array storage carrier while still identifying different
|
||||
`Marker<array<...>>` applications. A parameter that never occurs in a method
|
||||
signature still participates in identity. One owner can implement both
|
||||
applications; implementation function names carry the full application key.
|
||||
|
||||
Substitution traverses arguments, arrays, Fn inputs/results, optional payloads,
|
||||
named tuples and nested contracts. Existing return normalization applies before
|
||||
signature comparison: for example, a one-field named return payload does not
|
||||
create a second Fn result identity. Labels and parameter names remain available
|
||||
for tooling. Existing restrictions still reject invalid substituted positions,
|
||||
including optional void, void Fn inputs and invalid Array elements. `Self`
|
||||
keeps its existing scope rules.
|
||||
|
||||
## Recursive graphs and bounded processing
|
||||
|
||||
Register an application anchor before scanning its substituted signatures. A
|
||||
reference to an existing key closes a finite nominal graph; self and mutual
|
||||
recursion therefore terminate. A work queue discovers further instances.
|
||||
|
||||
`Growing<T>` returning `Growing<array<T>>` continually creates new applications.
|
||||
It is diagnosed as `E_SEM_CONTRACT_EXPANSION`, rather than hanging or becoming an
|
||||
ordinary type mismatch. Analysis has explicit depth, work, instance and key
|
||||
storage ceilings (256, 1,048,576, 65,536 and 64 Mi characters respectively). These producer
|
||||
bounds do not increase runtime admission limits or replace loader accounting.
|
||||
|
||||
## Integration pitfalls exposed by real execution
|
||||
|
||||
**Trait call stack order differs from implementation parameter order.** The
|
||||
implementation function receives its concrete owner first. At the CALL_TRAIT
|
||||
instruction, explicit argument groups precede the two-slot view on the operand
|
||||
stack. Lowering evaluates and roots the receiver, evaluates arguments left to
|
||||
right, then reloads the complete view immediately before the call. No-argument
|
||||
contract tests alone did not expose the old ordering error.
|
||||
|
||||
**Globals have one image namespace.** Independently compiled files can each
|
||||
start allocating globals at slot zero. Common IR aggregation now relocates
|
||||
declarations and GET_GLOBAL/SET_GLOBAL operands together. Lifecycle assembly
|
||||
preserves those linked slots and places its initialization guard after all
|
||||
globals. Without this, an imported strategy singleton could collide with the
|
||||
guard. The fix belongs to the neutral compiler, with no PBS rule in the backend.
|
||||
|
||||
**Aliases must cover all consumers.** Imported function emission uses the true
|
||||
target callable while local resolution uses its alias. Aliased services also
|
||||
retain their constants. Generic hover uses original declaration names in both
|
||||
the application heading and substituted signatures; navigation still reaches
|
||||
the original declaration. A final alias-specific editorial test caught a
|
||||
heading/signature disagreement that plain `Echo<int>` tests did not reveal.
|
||||
|
||||
**Verifier Unknown is not proof of a type error.** A mutated wrong-Trait call
|
||||
can be rejected statically or admitted with unknown local facts. In the latter
|
||||
case, execution must trap with the runtime type check. The conformance harness
|
||||
accepts exactly these valid outcomes rather than weakening runtime checks or
|
||||
requiring the verifier to infer more than its contract promises.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
Verified on 2026-10-20 against runtime revision
|
||||
`f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS/arm64, Rust 1.98.1,
|
||||
development profile with `resource-diagnostics`. Defaults remain unchanged
|
||||
except in explicit refusal tests. The harness builds in a temporary directory
|
||||
and does not modify the provider checkout.
|
||||
|
||||
The fourteen mandatory generic fixtures compile actual PBS through the
|
||||
production frontend, typed IR, PBX emitter, loader, verifier and VM:
|
||||
|
||||
| Fixture | Evidence | Types / implementations | PBX bytes |
|
||||
| --- | --- | --- | --- |
|
||||
| identity | Contextual/explicit adaptation and dispatch | 5 / 1 | 1,921 |
|
||||
| manual | Handwritten concrete behavioral reference | 5 / 1 | 1,859 |
|
||||
| multiple | Same owner, several applications | 6 / 2 | 1,991 |
|
||||
| tuple | Two parameters, Array input, complete tuple result | 9 / 1 | 2,762 |
|
||||
| optional | Absence/presence and optional groups | 6 / 1 | 2,267 |
|
||||
| function | Fn argument and call | 5 / 1 | 1,705 |
|
||||
| contract | Nested contract argument | 5 / 2 | 2,014 |
|
||||
| native | Native vec2 payload groups | 5 / 1 | 1,607 |
|
||||
| recursive | Finite recursive application and chained calls | 4 / 1 | 1,791 |
|
||||
| phantom | Distinct logical Array arguments, identical signatures | 5 / 2 | 2,036 |
|
||||
| receiver | Constructed struct receiver state | 4 / 1 | 1,534 |
|
||||
| gc | Closure retains view/receiver through collection | 7 / 1 | 2,153 |
|
||||
| installed | Packaged runnable contracts example | 5 / 1 | 2,105 |
|
||||
| imports | Aliases/reexports, distinct origins, lifecycle globals | 5 / 3 | 2,540 |
|
||||
|
||||
The generic and handwritten references both succeed with one heap handle and
|
||||
equal guest allocation footprint. Typed absence and ImplementationId zero are
|
||||
checked separately. The GC fixture reclaims at least 1,100 discarded objects
|
||||
while the captured receiver remains callable. Reduced GuestBytes/HandleSlots
|
||||
and zero implementation admission test resource refusal, bounded publication
|
||||
and complete ownership release. These observations do not imply identical PBX
|
||||
bytes or a performance improvement.
|
||||
|
||||
The complete provider harness also passed the existing source/input, structured
|
||||
value, closure, math, Random, lifecycle, malformed-image and resource corpora.
|
||||
Its two previously documented upstream schema enum gaps remain explicitly
|
||||
reported; they are not hidden or counted as schema conformance.
|
||||
|
||||
Compiler API (29 tests), PBS frontend (274 tests) and build-pipeline suites
|
||||
passed, together with 68
|
||||
affected architecture tests, 22 LSP bridge/protocol tests and both installed
|
||||
knowledge tests. The build-pipeline suite retains twelve pre-existing disabled
|
||||
legacy integration cases; production fixtures exercise the required paths.
|
||||
Additional focused cases cover mutual recursion and imported alias navigation.
|
||||
Workflow validation and whitespace checks passed before completion.
|
||||
|
||||
Reproduce with the gates in the [conformance harness documentation](../../../tools/pbx-conformance/README.md).
|
||||
The new specification and `contracts.pbs` example are discoverable in installed
|
||||
knowledge, not only in the source checkout.
|
||||
|
||||
## Handoffs and references
|
||||
|
||||
AGD92/List is next in the umbrella sequence. SDK data/algorithm specialization
|
||||
and stable object-identity hashing still require their consumer decisions.
|
||||
Generic functions/structs, constraints, variance, inheritance/default methods,
|
||||
associated strategy members and runtime specialization were not introduced.
|
||||
|
||||
- [PBS generic contracts specification](../../../docs/compiler/pbs/specs/generic-contracts.md).
|
||||
- [Typed Registry/PBX and global relocation](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
- [Arrays, optional and contract execution](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
|
||||
- [Functions and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
- [Installed source example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/contracts.pbs).
|
||||
- Historical workflow: AGD-0091, accepted DEC-0072, completed PLN-0151; DSC-0089.
|
||||
+234
@@ -0,0 +1,234 @@
|
||||
---
|
||||
id: LSN-0090
|
||||
ticket: pbs-sdk-list
|
||||
title: Mutable Lists and Stable Snapshot Cursors
|
||||
created: 2026-10-22
|
||||
tags: [compiler-pbs, collections, snapshot-cursor, atomic-publication, runtime-conformance]
|
||||
---
|
||||
|
||||
## Original problem and final result
|
||||
|
||||
Owner: `compiler/pbs`. Transversal owners: `compiler/general` for neutral IR/PBX
|
||||
and the runtime provider for storage, faults, ownership and resource accounting.
|
||||
DSC-0090 implemented accepted DEC-0075 through PLN-0153, covering R1–R14.
|
||||
The workflow control artifacts are disposable; the
|
||||
[List/Cursor specification](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md)
|
||||
is the durable normative reference.
|
||||
|
||||
PBS needed a resizable collection whose existing references remain valid, together
|
||||
with a traversal that survives later collection edits. Both now live in the
|
||||
executable SDK: ordinary generic `list<T>`, the shared `Cursor<T>` contract and
|
||||
private snapshot nodes. The compiler provides trusted private bindings and source
|
||||
projections; generic storage instructions support complete publication in the VM.
|
||||
Linked, Set and Map remain separate discussions.
|
||||
|
||||
## Separate collection identity, logical positions and physical storage
|
||||
|
||||
A List is a shared object containing a private fixed-length array and logical size.
|
||||
Growth replaces the backing reference inside that same object. Existing aliases
|
||||
therefore continue to observe the collection after growth, reserve or trim.
|
||||
|
||||
Size includes holes. Capacity alone does not create valid positions. For example,
|
||||
`new list<int>(16)` has size zero; `resize(3)` creates three valid empty positions.
|
||||
Writing position zero then stores a present value without changing size. Zero and
|
||||
false remain present values. `clearAt` leaves a hole, while `removeAt` removes a
|
||||
position and shifts the complete suffix, including its holes.
|
||||
|
||||
The complete API includes constructors, size/capacity, bracket access, add, insert,
|
||||
clearAt, removeAt, clear, resize, reserve, trim and cursor. The
|
||||
[specification](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md) defines
|
||||
their exact results, geometric growth, structural limits and fault classifications.
|
||||
Clear, shrink and removal erase discarded references; later growth cannot resurrect
|
||||
old values. Directly optional elements are rejected, including through grouping;
|
||||
an optional List remains valid. Applications are invariant, and argument values
|
||||
do not infer the element type.
|
||||
|
||||
## A snapshot freezes the sequence of references
|
||||
|
||||
List capture scans its logical positions backwards and prepends one node per
|
||||
present occurrence. The resulting chain visits increasing source indices, skips
|
||||
holes and preserves duplicates. Nodes are private, immutable, singly linked and
|
||||
non-circular. Capture finishes before the Cursor is returned. There is no second
|
||||
array, source-slot alias or source collection reference needed for traversal.
|
||||
|
||||
Replacing, inserting, removing, clearing or resizing the List cannot change this
|
||||
captured sequence. A captured object reference still identifies the same object,
|
||||
so later mutations of its fields remain visible. This distinction lets gameplay
|
||||
change its collections while a consumer walks a stable sequence.
|
||||
|
||||
The private cursor object stores its current-node reference. It can replace that
|
||||
root as it advances without changing any node link. Once other owners and call
|
||||
frames release consumed nodes, the prefix becomes collectible. The current node
|
||||
retains the remaining suffix.
|
||||
|
||||
### Successor-based hasNext and a retained last element
|
||||
|
||||
`current()` initially reports the first element. `hasNext()` asks whether that
|
||||
element has a successor. `next()` follows an existing successor and otherwise
|
||||
does nothing.
|
||||
|
||||
| Snapshot/state | hasNext() | current() |
|
||||
| --- | --- | --- |
|
||||
| Empty, initially or after repeated next | false | none |
|
||||
| [A], initially or after repeated next | false | some(A) |
|
||||
| [A, B], initially | true | some(A) |
|
||||
| [A, B], after one or any further next | false | some(B) |
|
||||
|
||||
Process current, then either advance or stop. A hasNext-only loop omits the last
|
||||
element. A loop waiting for current to become none never finishes a nonempty
|
||||
snapshot. The
|
||||
[distributed example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/collections.pbs)
|
||||
captures 20 and 22 around a hole, clears the List, visits both captured values and
|
||||
returns 42. Current still contains 22 afterwards.
|
||||
|
||||
The outer optional describes whether a node exists. A producer with optional T
|
||||
must preserve `some(none)` as a present node whose payload is none. A synthetic
|
||||
non-List producer qualifies that distinction independently of List's element rule.
|
||||
Future Linked/Set producers use Cursor<T>; Map entries use Cursor<keyval<K,V>>.
|
||||
Their construction rules and ordering guarantees belong to their own discussions.
|
||||
|
||||
## Prepare the whole mutation before publishing
|
||||
|
||||
An insert without growth can shift many slots and update size. A remove also
|
||||
prepares an optional result and clears its old tail. Each operation needs a single
|
||||
failure boundary for all observable changes.
|
||||
|
||||
The generic provider adds four operations, carried through common IR and PBX:
|
||||
|
||||
| Operation | Purpose |
|
||||
| --- | --- |
|
||||
| INDEX_GUARD | Check a signed-long logical index against an exclusive limit |
|
||||
| ARRAY_CHECK_LENGTH | Validate a structural length without allocating |
|
||||
| ARRAY_COPY | Transfer complete stored groups with overlap-safe prestate semantics |
|
||||
| STORAGE_PUBLISH | Prepare and commit source-selected copy/fill ranges and two typed fields |
|
||||
|
||||
The SDK chooses its indices, ranges, fill value, target backing and resulting size.
|
||||
The generic layer validates those operands and resource charges. It snapshots
|
||||
complete source groups into charged scratch before any write, then commits the
|
||||
selected copy, fill and field updates without allocation, callbacks, scheduler or
|
||||
GC interleaving. Its four immediate operands identify the Array/Struct types and
|
||||
two distinct fields. There is no exported preparation token or general transaction
|
||||
syntax.
|
||||
|
||||
For growth, a private candidate array is allocated and populated first. For a
|
||||
no-growth edit, scratch and all argument/result carriers are prepared first.
|
||||
`removeAt` obtains its previous optional value before publication. Raw transfer
|
||||
keeps presence tags, full value groups and existing reference/carrier identity.
|
||||
Per-element public optional unpack/repack would add failure points and allocation
|
||||
costs while shifting.
|
||||
|
||||
Refusal leaves backing identity, capacity, size and complete stored groups
|
||||
unchanged. Argument effects evaluated before the call remain ordinary source
|
||||
effects. Unpublished candidates and scratch follow normal ownership and budgets.
|
||||
The provider has no List/Cursor opcode, category or syscall; collection algorithms
|
||||
remain in
|
||||
[SDK source](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs).
|
||||
|
||||
## Compiler and tooling integration
|
||||
|
||||
Reserved SDK attributes carry trusted definition origin. Copying their names into
|
||||
a project cannot grant private primitive access, and a user struct named list does
|
||||
not acquire SDK indexing or constructor rules. The public barrel exports List and
|
||||
Cursor; backing fields, storage bindings, nodes and bracket adapters stay private.
|
||||
|
||||
SDK executable functions and implementations use the ordinary generic pipeline.
|
||||
Supporting them exposed reusable shape requirements: optional recursive payload
|
||||
members, concrete contract methods, applicable implementations and native group
|
||||
field maps must survive specialization. Complete values include vec2, pixel,
|
||||
tuples, nested arrays, contracts and function references.
|
||||
|
||||
List index/length arguments accept localized lossless int-to-long promotion.
|
||||
Receiver and arguments execute once in source order, including named arguments.
|
||||
General numeric conversion rules stay unchanged. Common aggregation, optimization,
|
||||
emission and preload verification retain all four publication operands; malformed
|
||||
types or fields are rejected even in unreachable instructions.
|
||||
|
||||
Editor projections show concrete public List/Cursor methods, optional results,
|
||||
constructor overloads and SDK definitions. Hover/completion hide private adapters
|
||||
and backing fields. Installed JAR tests load the actual packaged SDK, normative
|
||||
spec and example outside the checkout, generate PBX and execute it in the provider.
|
||||
|
||||
## Evidence and practical limits
|
||||
|
||||
The selected provider is clean commit
|
||||
`d9b9eeb171d2861ec660d4cf5703b0795eac49a9`. Studio changes were tested over base
|
||||
`76a8b074e89e17c7425220888eeec38427261d46`. Qualification used macOS 27.0.1 arm64,
|
||||
Rust 1.98.1/LLVM 22.1.8, the dev runtime profile with resource-diagnostics,
|
||||
capabilities NONE, Gradle 9.3.1 and the repository's Java 21 toolchain
|
||||
(Corretto 21.0.4). Ordinary and optimized producer paths were exercised.
|
||||
|
||||
| Gate | Observed result |
|
||||
| --- | --- |
|
||||
| Provider bytecode and VM libraries | 6 + 302 passed; 2 existing measurement tests ignored |
|
||||
| Full Studio regression and installed knowledge | Passed; existing skipped tests retained |
|
||||
| Final frontend/editor, LSP, source generation and installed checks | Passed; both installed tests passed |
|
||||
| PBS List/Cursor through production verifier/VM | 27 cases in each producer mode: 54 passed |
|
||||
| Non-PBS common IR | 2 storage fixtures executed through production VM |
|
||||
| Whole-operation quota refusals | 71 attempts; independently observed prior List state preserved |
|
||||
| Cursor GC | Nodes/items: 1200/1200 → 1/1 → 1/1 → 0/0 |
|
||||
| Reexports and installed example execution | Both passed; final captured value 22 retained |
|
||||
| Provider catalogs and canonical mirrors | Clean pinned provider; catalog parity and all four mirrors match |
|
||||
|
||||
The refusal matrix lowers GuestBytes, HandleSlots, AuxiliaryBytes and TemporaryBytes
|
||||
around candidate allocation, no-growth publication scratch, optional return
|
||||
preparation, node creation and frame/operand preparation. It compares the typed
|
||||
List fields and every backing group before and after each refusal, and verifies
|
||||
resource accounting returns to zero after VM drop. Generic provider tests also
|
||||
cover overlapping multi-slot transfers, late invalid fields/ranges, immutable
|
||||
Dynamic-box identity and malformed encodings.
|
||||
|
||||
Controlled normal GC safepoints prove consumed-prefix reclamation, retention of
|
||||
the final value 1199 despite repeated next calls, and release after dropping the
|
||||
Cursor. No source or snapshot Array remains live for that payload type at those
|
||||
safepoints. Optional carriers and other legitimate owners still have their normal
|
||||
allocation and retention costs. Capturing n positions with k present values takes
|
||||
O(n) time and O(k) additional nodes; next follows one link in O(1).
|
||||
|
||||
[Machine-readable evidence](runtime-conformance-evidence.json) records commands,
|
||||
source and PBX hashes, default ceilings, every lowered refusal quota, GC observations
|
||||
and tested provenance. New cases are mandatory; missing fixtures fail the harness.
|
||||
The full harness also reports two pre-existing response-schema gaps, LifecycleRole
|
||||
and NonFiniteValue, with original payloads preserved. These were not changed by
|
||||
this delivery. Qualification makes no release-profile or cross-platform claim.
|
||||
|
||||
R1–R5 are covered by type/construction/bounds/mutation/capacity fixtures; R6–R9 by
|
||||
snapshot states, identity, non-List optional production and GC; R10–R11 by direct
|
||||
provider tests, common IR and the refusal matrix; R12 by editor/import/distribution
|
||||
gates; R13 by resource accounting and retention observations; R14 by the mandatory
|
||||
production corpus, full regressions and pinned provenance.
|
||||
|
||||
## Pitfalls to preserve in future work
|
||||
|
||||
- Treat logical size and capacity separately. An index inside physical capacity
|
||||
can still require TRAP_OOB; a hole is an optional result only at a valid index.
|
||||
- Keep faults distinct from absence. Long overflow, invalid bounds and resource
|
||||
refusal cannot become none or a truncated index.
|
||||
- Prepare optional returns and temporary groups before publication. Individual
|
||||
Array instruction atomicity alone cannot prove whole-mutator atomicity.
|
||||
- Preserve complete stored groups while shifting. Public optional reboxing can
|
||||
change identity, roots, costs and refusal boundaries.
|
||||
- Follow the Cursor state table. Never advance a nonempty cursor past its last
|
||||
node or retain an initial-head root just to support an unrequested reset.
|
||||
- Account for node and optional-carrier allocation. A linked snapshot has no
|
||||
promise of lower memory use than an array or immediate quota recovery.
|
||||
- Carry all publication operands through linking and optimization. A lost second
|
||||
field identity can invalidate otherwise well-typed SDK calls after imports.
|
||||
- Keep privileged bindings origin-based and private. Names and copied attributes
|
||||
are insufficient authority.
|
||||
|
||||
## References and reproduction
|
||||
|
||||
- [List/Cursor specification](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md)
|
||||
and [Array/optional foundation](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
|
||||
- [Common Registry/PBX specification](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md)
|
||||
and [canonical provider publication code](../../../../runtime/crates/console/prometeu-vm/src/virtual_machine/storage_publication.rs).
|
||||
- [Source fixture generator](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsListCursorTest.java),
|
||||
[neutral IR fixtures](../../../prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/registry/StoragePublicationPipelineTest.java)
|
||||
and [production harness instructions](../../../tools/pbx-conformance/README.md).
|
||||
- [Generic structs lesson](../DSC-0094-pbs-generic-structs/LSN-0089-concrete-generic-state-and-bodies.md)
|
||||
and [generic contracts lesson](../DSC-0089-pbs-generic-contracts/LSN-0088-concrete-generic-contracts-from-source-to-vm.md).
|
||||
|
||||
Run `./gradlew test :prometeu-app:installedKnowledgeTest --console=plain` before
|
||||
`python3 tools/pbx-conformance/run.py --runtime ../runtime` so the complete fixture
|
||||
corpus, including the installed example, exists. Provider and catalog commands,
|
||||
their working directories and the tested configuration are in the evidence file.
|
||||
@@ -0,0 +1,699 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"discussion": "DSC-0090",
|
||||
"historical_decision": "DEC-0075",
|
||||
"historical_plan": "PLN-0153",
|
||||
"owner": "compiler/pbs",
|
||||
"date": "2026-10-22",
|
||||
"provenance": {
|
||||
"studio_base": "76a8b074e89e17c7425220888eeec38427261d46",
|
||||
"studio_changes": "uncommitted implementation",
|
||||
"runtime": "d9b9eeb171d2861ec660d4cf5703b0795eac49a9",
|
||||
"runtime_working_tree": "clean",
|
||||
"platform": "macOS-27.0.1-arm64-arm-64bit-Mach-O",
|
||||
"java": "Corretto 21.0.4+7-LTS; repository Java toolchain 21",
|
||||
"gradle": "9.3.1",
|
||||
"rustc": "1.98.1 (48a229cea 2026-09-01)",
|
||||
"rust_host": "aarch64-apple-darwin",
|
||||
"llvm": "22.1.8",
|
||||
"runtime_profile": "dev",
|
||||
"features": [
|
||||
"resource-diagnostics"
|
||||
],
|
||||
"capabilities": "NONE",
|
||||
"producer_modes": [
|
||||
"ordinary",
|
||||
"optimized"
|
||||
]
|
||||
},
|
||||
"default_vm_limits": {
|
||||
"GuestBytes": 268435456,
|
||||
"HandleSlots": 1048576,
|
||||
"AuxiliaryBytes": 67108864,
|
||||
"TemporaryBytes": 67108864,
|
||||
"StringBytes": 67108864,
|
||||
"StringAllocations": 262144,
|
||||
"IndividualStringBytes": 4194304,
|
||||
"CallDepth": 1024
|
||||
},
|
||||
"source_sha256": {
|
||||
"tools/pbx-conformance/run.py": "9acf64b74241f65fa09ab33fcb7d0daf57b56142d2874d87812d7b9948fe94ef",
|
||||
"tools/pbx-conformance/main.rs": "c24ade424adfe9edd7168814aabdfc869272c7bcfb816f5e4945b771cca96efd",
|
||||
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeRandomTest.java": "ba0b3de2e0aa7177fa71b5a837a56bc262a080717df3276c3a73b67b33dcb384",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/random/main.pbs": "c21c12d99c5a033a1e4026432bbab56393ad09c0fe2d36711504ccca01ce93b5",
|
||||
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsListCursorTest.java": "e9a7b24ca82a00339c0b0c96a53660ef4dcf69a52587a7c9e56f5f28b5c0b94a",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs": "fd3fb817a55e25553d4f7bbe8cbad5f306f22fd0a8e0bb6f8bf05bc43bc0794b",
|
||||
"../runtime/crates/console/prometeu-vm/src/virtual_machine/storage_publication.rs": "6d63bb474d7659a1e256e242fb2f3c9655d80173d51a263bad56b30cae3088b6",
|
||||
"../runtime/Cargo.lock": "cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795",
|
||||
"../runtime/docs/vm-arch/INTRINSICS.csv": "0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa",
|
||||
"../runtime/docs/vm-arch/BUILTIN_CONSTANTS.csv": "e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039",
|
||||
"../runtime/crates/console/prometeu-vm/tests/fixtures/numeric-conformance.tsv": "5536ee18cadaf32e3719b0e8d541dfcf1a84a49ea978a702101547c5ccdee3fe",
|
||||
"../runtime/crates/console/prometeu-vm/tests/fixtures/random-conformance.tsv": "0bee1cd0366f1716687aee8c7ac39dd495da5fe2908cce37b1443cb04fac542f"
|
||||
},
|
||||
"pbx_sha256": {
|
||||
"common-storage-optimized.pbx": "2820aa4ab46544e719e73dfce7e2c03b36377399e5f12e44f32d1f3020bbd087",
|
||||
"common-storage.pbx": "2820aa4ab46544e719e73dfce7e2c03b36377399e5f12e44f32d1f3020bbd087",
|
||||
"pbs-list-basic-optimized.pbx": "700dd48e3ceb84ad5f3e3f793fc0d2c6057ce1e87e0fdbadf408f82cf637f5fd",
|
||||
"pbs-list-basic.pbx": "0669143076d8b4e4610c9699b371de539ccd3aedf0a6f2d5dc46cc78f23dd148",
|
||||
"pbs-list-capacity-optimized.pbx": "a75c1ff31ef7527e1097e5da3e33747834ca0bc278f843edde32193aeb489fcc",
|
||||
"pbs-list-capacity.pbx": "35d68be7ffefc4dd930351efd083e78f34af1603e16c85eab96f4611fc8e2415",
|
||||
"pbs-list-construction-optimized.pbx": "21ab588682a00856461f2758cd3135f444fb9477d5dd70f6e48c001f7d54fe36",
|
||||
"pbs-list-construction.pbx": "b10de1f77f47758ca5a1eb7167e0c5241683a660073ae1241063a40b35098100",
|
||||
"pbs-list-contract-optimized.pbx": "5c5737ad4d3db9306415d2e9d389ceff8bef752b9beef2d57b15ee368c029eb9",
|
||||
"pbs-list-contract.pbx": "3c3250138ecaa1235f2bf1351e90a988e440dd34118cc22b1d26ab58c91189b7",
|
||||
"pbs-list-cursor-empty-optimized.pbx": "8741c4ec6a1736a2521fa414def12684af881561c829f88a96dcf1f24b961451",
|
||||
"pbs-list-cursor-empty.pbx": "c65d444082b8ceebfc9ec266811833c4dc40260ed47bc85cd0d9851d5be31cd1",
|
||||
"pbs-list-cursor-many-optimized.pbx": "7f5fa28ad380321f459df27606bc59d7e6d8b0bda7be4acc4305c859ca2af740",
|
||||
"pbs-list-cursor-many.pbx": "3ef35e99df5800fb5368f198a91350ffbb561d46af465db5a19ba986452693e3",
|
||||
"pbs-list-cursor-single-optimized.pbx": "8a19dd496746df5aea0208e983bc50bbdbd4596cea1cc79fed2f94b12e62c939",
|
||||
"pbs-list-cursor-single.pbx": "8ff5fe78d78915e51ad7dce6c1af354b4efc5c4729c9655da2172f0595fbd66a",
|
||||
"pbs-list-evaluation-optimized.pbx": "6e5e5a7e3085ea2eefa5f7e0ff296444eb633072fa8b301224737390d55965d3",
|
||||
"pbs-list-evaluation.pbx": "06f2de5f371973b93ee07577224670a2c02d15899b7dbd791be9733a67a5fb2b",
|
||||
"pbs-list-false-present-optimized.pbx": "48460d05c9dc22c8c3cd7ac87d429ff0e5ecffc17b2ca254196598e965248816",
|
||||
"pbs-list-false-present.pbx": "be70e9a6e741541f68c0180760bfd73ef81c54175c359f2208b512c4f3656816",
|
||||
"pbs-list-fault-constructor-optimized.pbx": "676d4c73965dbf4976de01655c4e0f97601dc1cdc01d312957e5be9d4d5135fd",
|
||||
"pbs-list-fault-constructor.pbx": "89cfeced7967ea96280874591e640eb88c255f88016f16cd69a9b2ed1330e02f",
|
||||
"pbs-list-fault-insert-optimized.pbx": "1c3ade1229ec4ed3095feaf961ad9a1dcedf9d6e2bca2f217187ca1a06be1668",
|
||||
"pbs-list-fault-insert.pbx": "fc92df90d591665f12dafa4ae937b44adb62dd7b308dd38d30b4ea30459f4f5f",
|
||||
"pbs-list-fault-length-optimized.pbx": "c114f0f0bae45d1cc6625319af8c79b158f8e4680448a7343f8899f1ae9e1153",
|
||||
"pbs-list-fault-length.pbx": "fc06adc9a6b67f25644042147f1f7475d9ac9d25b856b1f0ed3d40e3b9e46482",
|
||||
"pbs-list-fault-long-index-optimized.pbx": "b098baa781990fa70baf0d6d4671eb5e24978b4491f6317c9f2466f7535447eb",
|
||||
"pbs-list-fault-long-index.pbx": "10ac9074183cf09ef3e2bff8396bd6451b976a80f3b05458804c20169e353a15",
|
||||
"pbs-list-fault-negative-optimized.pbx": "1f42b229ed6d8118d61767494bc0e132d2a6e63485642ef6f4d218638c676964",
|
||||
"pbs-list-fault-negative.pbx": "0614c7b5dc4d5b4d799c179974e9e614dbc1fbdefba688c0acc0c43984090112",
|
||||
"pbs-list-fault-overflow-optimized.pbx": "c8f9f03f0d4c2d67acff1f094dcce96c129ce9e1abd3b9be04240f780ebe6e46",
|
||||
"pbs-list-fault-overflow.pbx": "3b66b7da63516af9981e3722997aa477bd0736a882eb0fce1c189bf040cf8554",
|
||||
"pbs-list-fault-read-optimized.pbx": "208f256e6c97753611edd7d222923a2b1a855c7ff1a7c872d1bc3bb9c1dfe72b",
|
||||
"pbs-list-fault-read.pbx": "acf039804bc732dc642fea696429bee398c2e6b6b6975e03dc2b2b24e1048c19",
|
||||
"pbs-list-fault-write-optimized.pbx": "35051291b52de2109e5f7f7d4bd0a8a218fefc31cb167fdda173871cd531be2f",
|
||||
"pbs-list-fault-write.pbx": "bcd721c64efe44f073ee660daebff72dca8ac9c2f8619be04d018ead799795ca",
|
||||
"pbs-list-function-optimized.pbx": "1002a115aebb3a7433f3978cbaa300fcadf26ad837da6272fd34260e2a9b7dad",
|
||||
"pbs-list-function.pbx": "1a047759799eff2982e8212a86d7d5237e8584e74cacff8301c29c4ff2c16b7c",
|
||||
"pbs-list-gc.pbx": "265bf39e53bd3e521166dc1ac14c99920d83726ebac8a0e0a3a339d49d19bb29",
|
||||
"pbs-list-holes-optimized.pbx": "ad331fd7f9298eadea06dbc55587d48a964f8b746406b316c108819186633d30",
|
||||
"pbs-list-holes.pbx": "c8263fb24fa8df2b98d7cb405733329281f386946c9c6ad186b01051fa25752c",
|
||||
"pbs-list-identity-optimized.pbx": "f8c572e91351cc8ff4901cc6e972bc05ea0e2e696a550526dc8c511919b438a9",
|
||||
"pbs-list-identity.pbx": "0e20e6c0a1c9d754a3cd9421155debb231b0dbd93d0935cc3e59b1f70dc21eca",
|
||||
"pbs-list-imports.pbx": "2364fde21bb3db0a86717f904103d5df657248e2b7979d0e17d2fe9c27ea7e1e",
|
||||
"pbs-list-installed.pbx": "83748e5203837069363e4d01b0c26e6423d7978f18ee5f6438dcf6336faeef0f",
|
||||
"pbs-list-nested-array-optimized.pbx": "c6d5d630c620589cf72bdad3f4226748c60a64f14d0965d5ee1aa22e89d79e17",
|
||||
"pbs-list-nested-array.pbx": "7e3b07300b6f03eeba738dec95001b6d9ab583f58c268dddfdf0b876605999db",
|
||||
"pbs-list-pixel-optimized.pbx": "ba46dd0ed8efacbbae0015cdfdc0cfa1567684df6681ed836f3ef15a5f828e82",
|
||||
"pbs-list-pixel.pbx": "36ceaa3115e9439ff21550637f62631dbae39ff06c553f459d58fd91e69cea24",
|
||||
"pbs-list-refusal-cursor.pbx": "0734d3608ff52a2cd9754b319c6d8a471429571e4336b9f2ae0cff729177042b",
|
||||
"pbs-list-refusal-growth.pbx": "2c453f52469127cc71818c69d7e3b3dd1add99f524f791ed46fb0c507da2f392",
|
||||
"pbs-list-refusal-insert.pbx": "6786c290f3ed924c6cfc1666afb3624385ca75cf44b397a05071388f951ccb80",
|
||||
"pbs-list-refusal-remove.pbx": "d7f0460f35a716bd0ef6dca47816d5f76bf8b1a9b32d9e3620479d5e2ace0888",
|
||||
"pbs-list-shared-optional-optimized.pbx": "bb71e6ffcae4da82bada01aeda5a8941361417c2eb97186b416715b8087d5ab2",
|
||||
"pbs-list-shared-optional.pbx": "98d12e6ab4eaefdab0c825fc063300feaf74839ad3d695b97187d4b6a510a557",
|
||||
"pbs-list-snapshot-optimized.pbx": "d673a2bbbcbc1de9c343f295fa15cf0a7e68aa2f694474842116fda3f1ec1787",
|
||||
"pbs-list-snapshot.pbx": "11c9dbbdc3ad403c55875e28054343b5275a1467a721ccf8fe1265204858d39e",
|
||||
"pbs-list-structural-growth-optimized.pbx": "d7ef11a773ac5ff179297b5ea89d1e4e7c7abfb9e5ab16d5bdb6860e28550ef9",
|
||||
"pbs-list-structural-growth.pbx": "a35fa7776ce571ceb8c6e77cbc3bcdac98851396eeb581e2445b4a774591d8a3",
|
||||
"pbs-list-tuple-optimized.pbx": "84f12aeb2e7686b91cbcbf4f64e584857184fe0f98bcddb72b6637c8f3cfe8bc",
|
||||
"pbs-list-tuple.pbx": "43d948da3e128f4eaeda52e64cf04c1e3f90df6205c17f847f55365729da1997",
|
||||
"pbs-list-vec2-optimized.pbx": "a2850a8204adaafc9f2bd0d84e01b53ed0898d7d0a5044f5ea716aa2d4429383",
|
||||
"pbs-list-vec2.pbx": "5d31b5f46c75992bcd798363def57509b1600e14e3432316196e000f371d77de"
|
||||
},
|
||||
"full_production_log_sha256": "f9a92347e491173ed11398257aac8cadd098ba9af175958ae920f4ed5339c051",
|
||||
"source_execution_passes": [
|
||||
"basic",
|
||||
"basic-optimized",
|
||||
"construction",
|
||||
"construction-optimized",
|
||||
"capacity",
|
||||
"capacity-optimized",
|
||||
"holes",
|
||||
"holes-optimized",
|
||||
"structural-growth",
|
||||
"structural-growth-optimized",
|
||||
"cursor-empty",
|
||||
"cursor-empty-optimized",
|
||||
"cursor-single",
|
||||
"cursor-single-optimized",
|
||||
"cursor-many",
|
||||
"cursor-many-optimized",
|
||||
"snapshot",
|
||||
"snapshot-optimized",
|
||||
"false-present",
|
||||
"false-present-optimized",
|
||||
"shared-optional",
|
||||
"shared-optional-optimized",
|
||||
"identity",
|
||||
"identity-optimized",
|
||||
"tuple",
|
||||
"tuple-optimized",
|
||||
"nested-array",
|
||||
"nested-array-optimized",
|
||||
"function",
|
||||
"function-optimized",
|
||||
"evaluation",
|
||||
"evaluation-optimized",
|
||||
"vec2",
|
||||
"vec2-optimized",
|
||||
"pixel",
|
||||
"pixel-optimized",
|
||||
"contract",
|
||||
"contract-optimized",
|
||||
"fault-read",
|
||||
"fault-read-optimized",
|
||||
"fault-write",
|
||||
"fault-write-optimized",
|
||||
"fault-negative",
|
||||
"fault-negative-optimized",
|
||||
"fault-insert",
|
||||
"fault-insert-optimized",
|
||||
"fault-length",
|
||||
"fault-length-optimized",
|
||||
"fault-overflow",
|
||||
"fault-overflow-optimized",
|
||||
"fault-long-index",
|
||||
"fault-long-index-optimized",
|
||||
"fault-constructor",
|
||||
"fault-constructor-optimized"
|
||||
],
|
||||
"common_ir_execution_passes": [
|
||||
"common-storage",
|
||||
"common-storage-optimized"
|
||||
],
|
||||
"distribution_execution_passes": [
|
||||
"imports",
|
||||
"installed"
|
||||
],
|
||||
"atomic_refusals": [
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 9736,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 9887,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 10038,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 10339,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 5,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 6,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 1408,
|
||||
"opcode": "Call"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 1640,
|
||||
"opcode": "GetLocal"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 504,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 2698,
|
||||
"opcode": "StoragePublish"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 4892,
|
||||
"opcode": "StoragePublish"
|
||||
},
|
||||
{
|
||||
"operation": "insert",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 9279,
|
||||
"opcode": "StoragePublish"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 9736,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 10127,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 10518,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 11299,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 5,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 6,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 7,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 8,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 9,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 1408,
|
||||
"opcode": "Call"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 1760,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 2112,
|
||||
"opcode": "GetLocal"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 504,
|
||||
"opcode": "GetLocal"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 2678,
|
||||
"opcode": "StoragePublish"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 4852,
|
||||
"opcode": "StoragePublish"
|
||||
},
|
||||
{
|
||||
"operation": "remove",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 9199,
|
||||
"opcode": "StoragePublish"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 5640,
|
||||
"opcode": "ArrayNew"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 7401,
|
||||
"opcode": "ArrayNew"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 9162,
|
||||
"opcode": "ArrayNew"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 12683,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 5,
|
||||
"opcode": "ArrayNew"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 6,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 7,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 1408,
|
||||
"opcode": "Call"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 1640,
|
||||
"opcode": "GetLocal"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 504,
|
||||
"opcode": "ArrayCopy"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 2938,
|
||||
"opcode": "ArrayCopy"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 5372,
|
||||
"opcode": "ArrayCopy"
|
||||
},
|
||||
{
|
||||
"operation": "growth",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 10239,
|
||||
"opcode": "ArrayCopy"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 9736,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 59424,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 109112,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "GuestBytes",
|
||||
"limit": 208487,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 5,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 6,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 7,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 8,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 9,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 10,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 11,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 12,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 13,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 14,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 15,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 16,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 17,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 18,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 19,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 20,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 165,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 326,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "HandleSlots",
|
||||
"limit": 646,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 1408,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 16648,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "AuxiliaryBytes",
|
||||
"limit": 31888,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 504,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 8058,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 15612,
|
||||
"opcode": "StructNew"
|
||||
},
|
||||
{
|
||||
"operation": "cursor",
|
||||
"resource": "TemporaryBytes",
|
||||
"limit": 30719,
|
||||
"opcode": "StructNew"
|
||||
}
|
||||
],
|
||||
"refusal_observation": "Independent typed List fields, backing identity, capacity and all stored groups before/after each refusal; all resource usage zero after VM drop.",
|
||||
"gc_safepoints": [
|
||||
{
|
||||
"round": 0,
|
||||
"nodes": 1200,
|
||||
"items": 1200,
|
||||
"collected": 6003
|
||||
},
|
||||
{
|
||||
"round": 1,
|
||||
"nodes": 1,
|
||||
"items": 1,
|
||||
"collected": 13197
|
||||
},
|
||||
{
|
||||
"round": 2,
|
||||
"nodes": 1,
|
||||
"items": 1,
|
||||
"collected": 15597
|
||||
},
|
||||
{
|
||||
"round": 3,
|
||||
"nodes": 0,
|
||||
"items": 0,
|
||||
"collected": 16803
|
||||
}
|
||||
],
|
||||
"gc_assertions": [
|
||||
"Consumed prefix reclaimable",
|
||||
"Final current value 1199 retained after repeated next",
|
||||
"No source or snapshot Array remains live for Item payload",
|
||||
"Last node/item released after dropping Cursor"
|
||||
],
|
||||
"gates": [
|
||||
{
|
||||
"command": "cargo test -p prometeu-bytecode -p prometeu-vm --lib --features prometeu-vm/resource-diagnostics --locked --offline",
|
||||
"result": "passed",
|
||||
"working_directory": "../runtime",
|
||||
"passed": 308,
|
||||
"ignored": 2,
|
||||
"environment": {
|
||||
"CARGO_TARGET_DIR": "/tmp/pln153-provider-final-target"
|
||||
}
|
||||
},
|
||||
{
|
||||
"command": "./gradlew -q test :prometeu-app:installedKnowledgeTest --console=plain",
|
||||
"result": "passed",
|
||||
"notes": "Full repository regression and installed gate; 13 existing skipped tests. Subsequent UI projection and positive construction additions also passed the focused gates below."
|
||||
},
|
||||
{
|
||||
"command": "./gradlew -q :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-lsp:prometeu-lsp-v1:test --console=plain",
|
||||
"result": "passed",
|
||||
"notes": "Final frontend/editor and LSP regression."
|
||||
},
|
||||
{
|
||||
"command": "./gradlew -q :prometeu-architecture-tests:test --tests '*PbsListCursorTest' :prometeu-app:installedKnowledgeTest --console=plain",
|
||||
"result": "passed",
|
||||
"notes": "Final source corpus generation and both installed-knowledge tests."
|
||||
},
|
||||
{
|
||||
"command": "python3 tools/pbx-conformance/run.py --runtime ../runtime",
|
||||
"result": "passed",
|
||||
"exit_code": 0,
|
||||
"environment": {
|
||||
"CARGO_TARGET_DIR": "/tmp/pln153-conformance-target"
|
||||
},
|
||||
"notes": "Full mandatory harness, including existing suites, with the final generated and installed List corpus."
|
||||
},
|
||||
{
|
||||
"command": "python3 tools/runtime-catalog/verify.py --runtime ../runtime",
|
||||
"result": "passed",
|
||||
"notes": "Clean committed provider; both catalog hashes and actual provider exporter parity match."
|
||||
}
|
||||
],
|
||||
"limitations": [
|
||||
"Qualification applies to the recorded macOS/arm64 dev runtime profile; no release or cross-platform claim.",
|
||||
"Two pre-existing full-harness response-schema gaps, LifecycleRole and NonFiniteValue, remain reported with original payloads; no new List/Cursor case is skipped.",
|
||||
"Quota matrix intentionally lowers only GuestBytes, HandleSlots, AuxiliaryBytes and TemporaryBytes at each recorded limit; other resource ceilings are unchanged."
|
||||
],
|
||||
"workflow_cli_gap": "No create-lesson/next-id command. LSN-0090 was read from the framework model without mutation; discussion housekeep registers the lesson and updates the index/counter.",
|
||||
"workflow_completion": {
|
||||
"discussion_status": "done",
|
||||
"plan_status_before_housekeeping": "done",
|
||||
"lesson": "LSN-0090",
|
||||
"housekeeping": "discussion housekeep DSC-0090 --lesson discussion/lessons/DSC-0090-pbs-sdk-list/LSN-0090-mutable-lists-and-stable-snapshot-cursors.md",
|
||||
"removed_control_artifacts": 3,
|
||||
"validation_after_housekeeping": "passed"
|
||||
}
|
||||
}
|
||||
+223
@@ -0,0 +1,223 @@
|
||||
---
|
||||
id: LSN-0091
|
||||
ticket: pbs-sdk-linked
|
||||
title: Private Linked Nodes and Atomic Publication
|
||||
created: 2026-10-23
|
||||
tags: [compiler-pbs, collections, snapshot-cursor, atomic-publication, runtime-conformance]
|
||||
---
|
||||
|
||||
## Original problem and final result
|
||||
|
||||
Owner: `compiler/pbs`. Transversal owners: `compiler/general` for neutral IR/PBX
|
||||
and the provider for typed storage, faults, ownership, GC and resource accounting.
|
||||
DSC-0091 executed accepted DEC-0076 through PLN-0154, covering R1–R12. Their
|
||||
workflow control artifacts are disposable; the [Linked specification](../../../docs/compiler/pbs/specs/sdk-linked-and-cursor.md)
|
||||
is the durable normative reference.
|
||||
|
||||
PBS needed a dense sequence with private doubly linked nodes and useful end
|
||||
operations, while preserving the shared snapshot traversal already delivered for
|
||||
List. `linked<T>` now supplies that sequence through executable SDK source.
|
||||
Forward and reverse captures both return the existing Cursor<T> contract. A
|
||||
neutral FIELDS_PUBLISH operation provides complete publication across the collection
|
||||
and its neighbors, without moving node algorithms into the VM.
|
||||
|
||||
The selected provider is clean commit `57992cf214e8a5f9de53a40dba9aaa7fab038c91`.
|
||||
Studio changes were qualified over base `c410e3500150de5e6d55c1da8f9b22076ca84251`.
|
||||
[Machine-readable evidence](runtime-conformance-evidence.json) records source/PBX
|
||||
hashes, commands, configuration, lowered refusal limits and observed GC states.
|
||||
|
||||
## Dense positions do not change the optional API
|
||||
|
||||
A Linked contains one present value per private node. Its size counts nodes;
|
||||
capacity, holes, reserve, trim, resize and clearAt do not exist. Valid indexed
|
||||
reads/removals return a present optional, and invalid indices fault even when
|
||||
empty. First/last and their removal operations return none for an empty collection.
|
||||
This preserves the accepted API rather than changing return types because a
|
||||
particular representation cannot contain holes.
|
||||
|
||||
Construction is empty and takes no capacity. Explicit and contextual applications
|
||||
follow the existing generic struct rules. Directly optional elements are rejected,
|
||||
including through grouping, just as in Array/List. An optional collection and an
|
||||
otherwise valid element containing optional fields remain valid.
|
||||
|
||||
The executable API includes size, first/last, bracket read/write, add/addFirst,
|
||||
insert, removeAt/removeFirst/removeLast, clear and both capture methods. Adding
|
||||
appends, while addFirst prepends. Replacement preserves size; insertion/removal
|
||||
changes following logical indices. Read/replace/remove require an index below
|
||||
size; insert also accepts size. Long indices are not truncated, int arguments have
|
||||
the same localized lossless promotion as List, and growth is checked before signed
|
||||
long overflow without inheriting Array's structural size maximum.
|
||||
|
||||
Preserving inserted object identity is separate from choosing a comparison policy.
|
||||
There is no remove(value), generic equality or uniqueness rule in this delivery.
|
||||
Repeated occurrences, including repeated references to one instance, remain
|
||||
independent sequence positions. List similarly leaves value search/removal outside
|
||||
its current contract.
|
||||
|
||||
## Keep collection topology separate from traversal topology
|
||||
|
||||
Linked nodes have reciprocal previous/next links. The SDK locates indexed values
|
||||
from the nearer end, so search remains O(n) in the worst case; end operations do
|
||||
not search. A constant number of link updates does not make indexed access O(1).
|
||||
|
||||
Snapshot nodes are different objects: private immutable singly linked nodes with
|
||||
no circular links or editable source association. Forward capture walks Linked
|
||||
backwards and prepends; reverse capture walks it forwards and prepends. Both cost
|
||||
O(n) work and additional nodes, and both finish before returning a Cursor.
|
||||
|
||||
For a source `[20, 22]`, forward starts at 20 and reverse starts at 22. Replacing
|
||||
source values, removing elements or clearing the collection cannot change either
|
||||
captured sequence. Referenced objects remain shared, so later field mutations
|
||||
remain visible. Snapshots preserve occurrences and object identity, not deep copies.
|
||||
|
||||
The existing state table remains the only traversal protocol:
|
||||
|
||||
| State | hasNext() | current() | next() |
|
||||
| --- | --- | --- | --- |
|
||||
| Empty | false | none | No change |
|
||||
| Current node has a successor | true | Present current value | Follow successor |
|
||||
| Last node, including a singleton | false | Present final value | No change |
|
||||
|
||||
Process current before testing whether to advance. A hasNext-only loop omits the
|
||||
last element; waiting for current to become absent never finishes a nonempty
|
||||
snapshot. There is no removal/reset through Cursor.
|
||||
|
||||
The [distributed example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/linked.pbs)
|
||||
captures both orders, then replaces a source element and clears Linked. Both
|
||||
traversals still sum to 42, retaining final values 22 and 20 respectively.
|
||||
|
||||
## Prepare every object before changing any object
|
||||
|
||||
Insertion can update the collection's head/tail/size and two existing neighbors.
|
||||
Removal also prepares the returned optional value. Separate successful field
|
||||
stores are insufficient: a later allocation or frame/operand refusal could leave
|
||||
half of a neighbor pair updated.
|
||||
|
||||
The existing range-based STORAGE_PUBLISH operation covered an Array and two
|
||||
fields of one owner. Its guarantee did not automatically extend to Linked.
|
||||
The new generic FIELDS_PUBLISH uses a normal Struct TypeId as a schema: each
|
||||
schema field names one destination Struct type. The stack supplies each nullable
|
||||
destination followed by all its complete field groups. No request object, new
|
||||
Registry category or public preparation token is needed.
|
||||
|
||||
All non-null destinations must have the exact concrete type and live provenance.
|
||||
All supplied value groups are validated, including those paired with a null
|
||||
(skipped) destination. The original operands stay rooted and unconsumed until the
|
||||
whole attempt is admitted. The VM then commits in schema order without allocation,
|
||||
validation, callbacks or GC/scheduler interleaving, and consumes the operands.
|
||||
Repeated destinations have ordered last-write semantics using pre-captured inputs.
|
||||
|
||||
The SDK selects topology and values. It allocates and initializes a private
|
||||
candidate node before publishing an insertion. Removal prepares its optional
|
||||
result first. Private helper bindings lower those source-selected values to the
|
||||
neutral operation. A refusal preserves the old roots, size, values and reciprocal
|
||||
links; already evaluated caller argument effects remain ordinary source effects.
|
||||
|
||||
Publication itself needs no heap object or scratch. This does not make a source
|
||||
mutation allocation-free: optional carriers, candidate nodes, packing and call
|
||||
preparation still have their normal costs. Provider tests execute publication at
|
||||
already exhausted allocation ceilings, preserve native String/reference identity
|
||||
and multi-slot groups, and reject a late invalid group before every shared write.
|
||||
|
||||
## GC proofs require an actual collection, not only a safepoint
|
||||
|
||||
Removal disconnects a node from the collection. Clear removes the collection's
|
||||
roots to the whole chain. Unreachable double-link cycles are handled by the normal
|
||||
tracing collector; neither operation promises immediate collection or quota return.
|
||||
A retained snapshot owns captured values through its own nodes and does not need
|
||||
the editable Linked nodes.
|
||||
|
||||
A controlled fixture uses normal GC safepoints and independent non-owning storage
|
||||
observations. With no snapshot, nodes and payloads fall from 1,200 to 1,197 after
|
||||
three removals, then to zero after clear. A second fixture clears the source while
|
||||
retaining its snapshot: original Linked nodes disappear, captured nodes/items go
|
||||
from 1,200/1,200 to 1/1 after traversal, stay at 1/1 after repeated next, and reach
|
||||
0/0 after the final Cursor owner is dropped.
|
||||
|
||||
A safepoint alone does not force this collector to run. The removal/clear fixture
|
||||
therefore creates ordinary garbage pressure and asserts that the collection
|
||||
counter advances at each observed round. Without that check, a test can mistake
|
||||
an uncollected unreachable node for a retention bug. The observer introduces no
|
||||
guest root or mutation.
|
||||
|
||||
## Compiler, tooling and distribution
|
||||
|
||||
Linked reuses ordinary generic specialization, methods, field groups and imports.
|
||||
Origin-checked SDK metadata adds constructor/index integration and the same
|
||||
localized int-to-long argument promotion as List. User homonyms or copied
|
||||
attributes do not acquire those privileges.
|
||||
|
||||
Public projections show concrete Linked methods, optional results and source SDK
|
||||
locations. They hide head/tail/length, private nodes and storage adapters, including
|
||||
the internal nearest-end lookup method. Negative workspace cases reject optional
|
||||
elements, capacity construction, unsupported APIs and private access. Invalid
|
||||
constructor selection now reports diagnostics instead of throwing from lowering.
|
||||
|
||||
The normative English spec and example ship with installed knowledge. An isolated
|
||||
installDist JVM, outside the checkout, loads the actual JAR resources and compiles
|
||||
the Linked example. The production harness executes its emitted PBX and observes
|
||||
both completed traversals. Imports/reexports are qualified separately.
|
||||
|
||||
The full harness also needed its original scalar/input corpus selector to exclude
|
||||
the new Linked fixture prefix. Linked cases remain mandatory in their dedicated
|
||||
validator; they are not silently treated as older scalar fixtures or skipped.
|
||||
|
||||
## Qualification and limits
|
||||
|
||||
| Gate | Observed result |
|
||||
| --- | --- |
|
||||
| Full Studio regression | 1,030 tests; no failures/errors; 13 existing skips |
|
||||
| Installed knowledge | Both tests passed, including standalone Linked PBX generation |
|
||||
| Provider bytecode/VM libraries | 6 + 305 passed; 2 existing measurement tests ignored |
|
||||
| Linked source to production VM | 26 cases in each producer mode: 52 passed |
|
||||
| Neutral storage/publication | Four common-IR fixtures executed, including ordinary/optimized FIELDS_PUBLISH |
|
||||
| Whole-operation refusals | 231; all ten mutation/capture boundaries preserved previous source state |
|
||||
| Linked removal/clear GC | 1,200 → 1,197 → 0 → 0 nodes and payloads |
|
||||
| Snapshot GC | 1,200 → 1 → 1 → 0 captured nodes/payloads, with no retained Linked topology |
|
||||
| Imports/installed traversal | Passed; installed forward/reverse final values 22/20 |
|
||||
| Catalogs and canonical mirrors | Clean selected provider; catalog/exporter parity and all four mirrors match |
|
||||
|
||||
The refusal matrix observed GuestBytes, HandleSlots and AuxiliaryBytes refusals.
|
||||
TemporaryBytes was checked against the measured setup/success peaks; no additional
|
||||
peak required a lowered refusal case in this Linked corpus. FIELDS_PUBLISH has no
|
||||
scratch allocation, and the direct provider test proves publication succeeds with
|
||||
TemporaryBytes already capped at current usage. This is not a claim that general
|
||||
source preparation never needs temporary resources.
|
||||
|
||||
Qualification used macOS 27.0.1 arm64, Rust 1.98.1/LLVM 22.1.8, the dev runtime
|
||||
profile with resource-diagnostics, capabilities NONE, Gradle 9.3.1 and the Java 21
|
||||
toolchain; the installed JVM was Corretto 21.0.4. No release or cross-platform claim
|
||||
is made. Two pre-existing full-harness response-schema gaps, LifecycleRole and
|
||||
NonFiniteValue, remain explicitly reported with original payloads.
|
||||
|
||||
## Pitfalls to preserve
|
||||
|
||||
- Do not implement a multi-object mutation as a sequence of fallible stores.
|
||||
- Prepare the optional removed-value carrier before publishing the removal.
|
||||
- Preserve every field group and native/reference identity, including unchanged
|
||||
payloads when updating neighbor links.
|
||||
- Never expose source nodes to support traversal. Snapshot and collection links
|
||||
have different mutability and lifetime responsibilities.
|
||||
- Keep optional results despite dense positions, and faults distinct from absence.
|
||||
- Keep private SDK authority tied to origin through aliases and specialization.
|
||||
- Check GC collection counters when asserting reclamation at a safepoint.
|
||||
- Record clean provider provenance, explicit lowered limits and mandatory fixture
|
||||
counts; metadata defaults or small unit tests alone do not qualify execution.
|
||||
|
||||
## References and reproduction
|
||||
|
||||
- [Linked specification](../../../docs/compiler/pbs/specs/sdk-linked-and-cursor.md),
|
||||
[List/shared Cursor](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md),
|
||||
[generic structs](../../../docs/compiler/pbs/specs/generic-structs-and-free-functions.md)
|
||||
and [generic Registry/PBX publication](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
- [SDK source](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs),
|
||||
[source corpus](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsLinkedTest.java),
|
||||
[neutral producer](../../../prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/registry/StoragePublicationPipelineTest.java)
|
||||
and [production harness instructions](../../../tools/pbx-conformance/README.md).
|
||||
- [Provider publication implementation](../../../../runtime/crates/console/prometeu-vm/src/virtual_machine/storage_publication.rs)
|
||||
and [previous List/Cursor lesson](../DSC-0090-pbs-sdk-list/LSN-0090-mutable-lists-and-stable-snapshot-cursors.md).
|
||||
|
||||
Run `./gradlew test :prometeu-app:installedKnowledgeTest --console=plain`, followed
|
||||
by `python3 tools/pbx-conformance/run.py --runtime ../runtime`, after selecting the
|
||||
recorded provider. The evidence file retains command/configuration details and
|
||||
R1–R12 traceability after removal of the completed workflow controls.
|
||||
File diff suppressed because it is too large
Load Diff
+202
@@ -0,0 +1,202 @@
|
||||
---
|
||||
id: LSN-0089
|
||||
ticket: pbs-generic-structs
|
||||
title: Concrete Generic State and Bodies in PBS
|
||||
created: 2026-10-22
|
||||
tags: [compiler-pbs, generic-structs, generic-functions, nominal-identity, runtime-conformance]
|
||||
---
|
||||
|
||||
## Original problem and final result
|
||||
|
||||
Owner: `compiler/pbs`. Studio/LSP receives source projections; the common backend
|
||||
and runtime continue to execute concrete types and functions. DSC-0094 implemented
|
||||
accepted DEC-0073 through PLN-0152, covering requirements R1–R14. The disposable
|
||||
workflow artifacts are removed by housekeeping; specifications remain normative.
|
||||
|
||||
Generic contracts could describe a strategy but could not provide parameterized
|
||||
state or algorithms. PBS now supports generic structs, owner-dependent methods
|
||||
and constructors, restricted owner-bound implementations, and named generic free
|
||||
functions with explicit arguments. SDK and project code use the same frontend
|
||||
mechanism. No runtime source, opcode, descriptor category or PBX format changed.
|
||||
|
||||
```pbs
|
||||
declare struct Box<T>(value: T) {
|
||||
ctor make(value: T) { this.value = value; }
|
||||
fn get() -> T { return this.value; }
|
||||
}
|
||||
declare contract Reader<T> { fn read() -> T; }
|
||||
implements<T> Reader<T> for Box<T> using box {
|
||||
fn read() -> T { return box.get(); }
|
||||
}
|
||||
fn read<T>(reader: Reader<T>) -> T { return reader.read(); }
|
||||
fn example() -> int {
|
||||
let box = new Box<int>.make(42);
|
||||
let reader: Reader<int> = box;
|
||||
let invoke: Fn(Reader<int>) -> int = read<int>;
|
||||
return invoke(reader);
|
||||
}
|
||||
```
|
||||
|
||||
The combined program executes through production PBX and the provider VM. A
|
||||
separate multi-module variant uses aliases, reexports and private definition-side
|
||||
helpers while preserving the result 42.
|
||||
|
||||
## Decisions that shape the implementation
|
||||
|
||||
Application identity is source nominal origin plus ordered canonical logical
|
||||
arguments. It is independent of layout width and presentation. Two homonymous
|
||||
Enemy declarations must yield distinct Box<Enemy> types; two aliases of the same
|
||||
declaration share one application. Phantom arguments also remain significant.
|
||||
Function applications preserve their declaration and argument identity even when
|
||||
several targets share a compatible structural Fn descriptor.
|
||||
|
||||
Definition scope and argument scope are separate. A parameter is bound by its
|
||||
declaration/binder and position. Resolve the caller's arguments before constructing
|
||||
the callee's substitution environment. Private helpers remain in their definition
|
||||
module. Generated imports connect concrete instances without publishing helpers
|
||||
as source exports. Explicit barrels retain the template and its ordered parameters.
|
||||
|
||||
Explicit struct construction provides its own arguments. Diamond and omission
|
||||
require an existing expected application; values do not infer T. Generic functions
|
||||
always require explicit arguments, including when converted to Fn. Explicit
|
||||
applications filter generic overloads by type arity; ordinary calls use ordinary
|
||||
overloads. Renaming binders alone does not create a new overload.
|
||||
|
||||
Concrete specialization increases frontend work and potentially image size, but
|
||||
reuses the established runtime value model. It avoids requiring a Dynamic generic
|
||||
argument ABI or adapter objects. Existing Array packing still follows Array rules.
|
||||
No performance or byte-for-byte image equivalence is promised.
|
||||
|
||||
## Checking and materializing the graph
|
||||
|
||||
`PbsGenericInstantiation` owns the interacting concrete graph. Shared
|
||||
`PbsContractTypes`, `PbsInstantiationBudget` and application provenance support
|
||||
contracts, structs and functions. Register anchors before traversing dependencies:
|
||||
revisiting the same application closes a finite graph, whereas requesting new
|
||||
applications indefinitely produces a bounded expansion diagnostic.
|
||||
|
||||
The current frontend budget bounds depth at 256, instances at 65,536, work at
|
||||
1,048,576 visits and accounted specialization storage at 64 MiB. These analysis
|
||||
ceilings do not enlarge provider admission or execution limits.
|
||||
|
||||
Validation has two distinct purposes. Symbolic capability checking prevents T
|
||||
from gaining arithmetic, comparison, members or construction from a chosen concrete
|
||||
argument. Opaque nominal witnesses also run unused template bodies through the
|
||||
ordinary declaration and flow validators, catching ordinary errors such as wrong
|
||||
returns and incomplete constructors. Dependency shapes provide their declared
|
||||
capabilities without recursively executing every unused template family.
|
||||
|
||||
Each required concrete owner then validates fields, constructors and every method,
|
||||
including uncalled methods. Substitute entire bodies, annotations, nested calls,
|
||||
constructions, lambdas and captures. Revalidate positions after substitution:
|
||||
Box<optional int> can have a T field, but array<T> cannot accept that substitution.
|
||||
Reject overloads that collapse after substitution; never prefer an int overload
|
||||
over set(T) merely because T became int.
|
||||
|
||||
Owner-bound implementation rules bind every parameter through distinct direct
|
||||
owner arguments. Symbolic unification detects generic/generic, generic/closed and
|
||||
closed/closed overlap before any conflicting application is requested. A closed
|
||||
rule has no priority over a family. Implementations remain exact and module-owned;
|
||||
their methods do not enter the struct's direct method namespace.
|
||||
|
||||
Specialized free-function references use ordinary Closure values with empty
|
||||
environments. Lambdas inside specialized bodies keep explicit snapshot captures
|
||||
and complete logical groups. Struct values retain reference identity; assignment
|
||||
does not copy their state.
|
||||
|
||||
## Constructor initialization and Random
|
||||
|
||||
Implementation exposed a conflict: the static semantics required every field
|
||||
initialized on each completing constructor path, while Random fixtures used an
|
||||
empty constructor to obtain the provider's null reference default. The user
|
||||
explicitly chose complete initialization and authorized revising Random's spec
|
||||
and fixtures. This clarification applies to ordinary and generic structs.
|
||||
|
||||
The flow check intersects assignments across branches and accounts for loop exits
|
||||
and short-circuit logical operands.
|
||||
An assignment in a loop that might run zero times is insufficient. Deferred lambda
|
||||
bodies do not initialize the enclosing constructor's fields. A constructor that
|
||||
cannot complete has no completing path to check.
|
||||
|
||||
Valid Random source fixtures now initialize their fields explicitly. Four null
|
||||
and typed-null checks remain controlled provider fixtures: compile valid source,
|
||||
suppress the unique named-constructor field store in test bytecode, then run the
|
||||
production verifier/VM. Runtime field defaults, typed Array presence and null
|
||||
faults are still tested without making incomplete PBS constructors legal.
|
||||
|
||||
## Editor and diagnostic projections
|
||||
|
||||
Keep original declarations and spans alongside the specialized semantic projection.
|
||||
Navigation and references distinguish symbolic parameters, concrete arguments and
|
||||
generic origins. Concrete hover/completion/signature help use the applied type;
|
||||
template bodies retain symbolic field and method presentation. Source formatting,
|
||||
document/workspace symbols, rename references, inline hints and semantic overlays
|
||||
continue through the existing frontend/LSP surfaces.
|
||||
|
||||
Pass the current application into declaration and flow diagnostics. Merely replacing
|
||||
generated names at file scope is insufficient: field-position errors also need
|
||||
related spans for the original definition and requesting use. Display a short
|
||||
source chain and canonical application names rather than internal identities.
|
||||
|
||||
## Qualification and requirement coverage
|
||||
|
||||
The final reports contain 1,004 general tests, zero failures/errors and 13 existing
|
||||
skips, plus two passing installed-knowledge tests. The complete Gradle regression
|
||||
passed; final affected gates were repeated after improving diagnostic provenance
|
||||
and finalizing installed spec references. One earlier external-source LSP failure
|
||||
passed in isolation and in the complete repetition; no unrelated LSP code changed.
|
||||
|
||||
Production qualification used runtime revision
|
||||
`f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, Rust 1.98.1, macOS arm64, dev profile,
|
||||
`resource-diagnostics`, default limits and `NONE` capabilities, with explicitly
|
||||
lowered quota cases. All 16 mandatory generic fixtures passed. The full existing
|
||||
PBX harness also passed, including 227 Random cases. This evidence does not qualify
|
||||
another platform, a release runtime profile or the reference game.
|
||||
|
||||
| Requirements | Final evidence |
|
||||
| --- | --- |
|
||||
| R1–R2 | Exact arguments, origin/phantom/reference identity, contextual and named construction, complete initialization |
|
||||
| R3–R5 | Composed multi-slot storage, symbolic capability errors, complete bodies, unused-method and overload failures |
|
||||
| R6–R7 | Restricted coherent owner rules, overlap before use, anchored recursion and bounded expanding bodies |
|
||||
| R8 | Production concrete Registry/PBX/VM, implementation zero, retained captures through GC and quota refusals |
|
||||
| R9–R10 | Explicit free functions, concrete Fn/empty closures, nested captures and ordinary apply |
|
||||
| R11–R12 | Homonymous binders/origins, definition-side helpers, aliases/reexports, barrels, duplicates and comparisons |
|
||||
| R13 | Symbolic/concrete navigation and editor tests; diagnostic definition/use spans and readable applications |
|
||||
| R14 | Shared infrastructure, isolated/combined modules, installed example/specs and complete regressions |
|
||||
|
||||
The 16 fixtures cover basic/manual objects, constructors/Self, phantom applications,
|
||||
tuple, optional, Array, nominal recursion, combined dispatch, generic/manual Fn,
|
||||
GC, imports/reexports, installed example, multiple parameters and homonymous origins.
|
||||
Specialized and handwritten object/Fn fixtures execute under a one-handle limit
|
||||
and use equal guest heap resources. All observed resources return to zero after
|
||||
VM disposal. Refused allocation publishes no partial object. Full fixture sizes,
|
||||
type/implementation counts, hashes, commands and log fingerprints are retained in
|
||||
[evidence.json](evidence.json).
|
||||
|
||||
## Pitfalls and subsequent work
|
||||
|
||||
- Checking only requested templates or called methods changes source acceptance.
|
||||
- Rewriting only signatures loses local annotations, construction contexts and captures.
|
||||
- Using simple names or physical slots as identity merges distinct applications.
|
||||
- Resolving private helpers at the caller makes imports change template meaning.
|
||||
- Choosing a closed implementation over a family hides an incoherent program.
|
||||
- Treating a provider's reference default as a PBS constructor exemption creates
|
||||
incompatible source rules.
|
||||
- Maintaining normative chapters in both `docs/specs/compiler-languages/pbs` and
|
||||
`docs/compiler/pbs/specs` permits contradictions. The canonical owner is the
|
||||
latter; existing distribution still merges both roots. Consolidating the legacy
|
||||
chapters and their links/build inputs remains a separate repository migration.
|
||||
|
||||
The next collection discussion is List (DSC-0090 / AGD-0092). Its API, iteration,
|
||||
logical bounds and private slot-transfer decisions remain open. Completing this
|
||||
language prerequisite does not approve those collection proposals.
|
||||
|
||||
## References
|
||||
|
||||
- [Generic structs and free functions](../../../docs/compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
- [Generic contracts](../../../docs/compiler/pbs/specs/generic-contracts.md).
|
||||
- [Arrays and optional](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
|
||||
- [Functions and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
- [Random integration](../../../docs/compiler/pbs/specs/runtime-random-integration.md).
|
||||
- [Concrete common Registry/PBX](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
- Historical execution plan: PLN-0152, completed and removed by discussion housekeeping.
|
||||
@@ -0,0 +1,185 @@
|
||||
{
|
||||
"date": "2026-10-22",
|
||||
"owner": "compiler/pbs",
|
||||
"discussion": "DSC-0094",
|
||||
"decision": "DEC-0073",
|
||||
"plan": "PLN-0152",
|
||||
"runtime_revision": "f7d7c167531bb662a1af9d73fc326bb476bf8aa7",
|
||||
"runtime_profile": "dev",
|
||||
"runtime_features": [
|
||||
"resource-diagnostics"
|
||||
],
|
||||
"runtime_limits": "default; explicit lower GuestBytes/HandleSlots refusal cases",
|
||||
"capabilities": "NONE",
|
||||
"platform": "macOS-27.0.1-arm64-arm-64bit-Mach-O",
|
||||
"rustc": "rustc 1.98.1 (48a229cea 2026-09-01)",
|
||||
"java_tests": {
|
||||
"test": {
|
||||
"tests": 1004,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 13
|
||||
},
|
||||
"installedKnowledgeTest": {
|
||||
"tests": 2,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
}
|
||||
},
|
||||
"generic_fixtures": [
|
||||
{
|
||||
"name": "basic",
|
||||
"types": 3,
|
||||
"implementations": 0,
|
||||
"bytes": 1278,
|
||||
"sha256": "c6b72687525737aa6626ca5cea47e11498d68df0c6463ab04293062915d80409"
|
||||
},
|
||||
{
|
||||
"name": "manual",
|
||||
"types": 3,
|
||||
"implementations": 0,
|
||||
"bytes": 1216,
|
||||
"sha256": "485c560ef569d07e46f2ce90a4b9814f68fc59a76b3a274e9f023985091fcd38"
|
||||
},
|
||||
{
|
||||
"name": "constructor",
|
||||
"types": 3,
|
||||
"implementations": 0,
|
||||
"bytes": 1329,
|
||||
"sha256": "9274c106cba055f608e400a3fb033522e9a1e4d485cba85583ad813ddffc54e3"
|
||||
},
|
||||
{
|
||||
"name": "phantom",
|
||||
"types": 4,
|
||||
"implementations": 0,
|
||||
"bytes": 1094,
|
||||
"sha256": "ccc6e25213c69e5b6c9c9b0089304d8d168584d5779f5f43e6289f9bf6d67b9f"
|
||||
},
|
||||
{
|
||||
"name": "tuple",
|
||||
"types": 4,
|
||||
"implementations": 0,
|
||||
"bytes": 2244,
|
||||
"sha256": "7ee8ffb76df45de6a8824aa2b871763d47fd264e6024f5f6c89f6b1fded865cd"
|
||||
},
|
||||
{
|
||||
"name": "optional",
|
||||
"types": 5,
|
||||
"implementations": 0,
|
||||
"bytes": 1708,
|
||||
"sha256": "bd662f86db9f53f882dd74c7728d0f48f98d25b3bbf5cc70111ed1472d6de81f"
|
||||
},
|
||||
{
|
||||
"name": "array",
|
||||
"types": 8,
|
||||
"implementations": 0,
|
||||
"bytes": 2186,
|
||||
"sha256": "e5f1815ddca28177bba0af27297b25c039ffcde1402d374dd858c8f59dbe5c9e"
|
||||
},
|
||||
{
|
||||
"name": "recursive",
|
||||
"types": 5,
|
||||
"implementations": 0,
|
||||
"bytes": 1116,
|
||||
"sha256": "0527985e60ab6a41f94122b7f88d62e4ffd237f887b0af23c01886f4a818658c"
|
||||
},
|
||||
{
|
||||
"name": "combined",
|
||||
"types": 5,
|
||||
"implementations": 1,
|
||||
"bytes": 1935,
|
||||
"sha256": "2d5b9c9a501a66b951a7708523a3c0f02cba9d9f2fd3fcd7444b8359a701d63b"
|
||||
},
|
||||
{
|
||||
"name": "function",
|
||||
"types": 3,
|
||||
"implementations": 0,
|
||||
"bytes": 806,
|
||||
"sha256": "32b80c1dc6be78db679d31bb0393362afca01354727aa8ba81dc8f92de6e2280"
|
||||
},
|
||||
{
|
||||
"name": "function-manual",
|
||||
"types": 3,
|
||||
"implementations": 0,
|
||||
"bytes": 773,
|
||||
"sha256": "60f8fe92f39e0b5b531cdfefd1cee9d40377253fb6d7db80202ebf4b5becadf3"
|
||||
},
|
||||
{
|
||||
"name": "gc",
|
||||
"types": 6,
|
||||
"implementations": 0,
|
||||
"bytes": 2169,
|
||||
"sha256": "9f292f40c4bfb6a6c6f734130d877abf2ce809da1665dd54bbb352d328aaa59e"
|
||||
},
|
||||
{
|
||||
"name": "imports",
|
||||
"types": 4,
|
||||
"implementations": 1,
|
||||
"bytes": 2493,
|
||||
"sha256": "3ac928d8feebed5414aebe595c90ce08062903c0e5a9e198ba6365dc0f88c55e"
|
||||
},
|
||||
{
|
||||
"name": "installed",
|
||||
"types": 5,
|
||||
"implementations": 1,
|
||||
"bytes": 2142,
|
||||
"sha256": "41af3aaeca0c39267543af3e79bc5f40b0846f66f448aa74afd2adcade3039b1"
|
||||
},
|
||||
{
|
||||
"name": "multiple",
|
||||
"types": 3,
|
||||
"implementations": 0,
|
||||
"bytes": 1305,
|
||||
"sha256": "a59365588676083b8d9e078f869828067ed48f881252da4ad5b904f800f7d2b9"
|
||||
},
|
||||
{
|
||||
"name": "origins",
|
||||
"types": 5,
|
||||
"implementations": 0,
|
||||
"bytes": 2484,
|
||||
"sha256": "ed3fcfdcab2aabe98ae525c67c688e3d7bec7bc757bb127b82ee652b4322ecb6"
|
||||
}
|
||||
],
|
||||
"generic_fixtures_passed": 16,
|
||||
"random_fixtures_passed": 227,
|
||||
"source_fingerprints": {
|
||||
"tools/pbx-conformance/main.rs": "322a772b4353c90d6acc54f90a0136eef544f92dd7434c7244762abb0125553e",
|
||||
"tools/pbx-conformance/run.py": "7d4817b40371847c3debe1524f253354ca919cbda986349770647c3841a3eedb",
|
||||
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsGenericStructsTest.java": "a2ecc312075009e052994a47cf7b52037ef545882865991adbcb328a5a27a665",
|
||||
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeRandomTest.java": "ba0b3de2e0aa7177fa71b5a837a56bc262a080717df3276c3a73b67b33dcb384",
|
||||
"docs/compiler/pbs/specs/generic-structs-and-free-functions.md": "517cf07f7543a6ab261b1fdd177985b047b62fdb624bda40a63f61e28fa11263",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsGenericInstantiation.java": "4047b14f11aca83b62c5247233a941502cdedb462c887ec6032d2d0c5e308ee5",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsCtorInitializationAnalyzer.java": "5a4a134324b2effce4c9e8ed66d1025e393c0fe61959190586d7ea103ad06f47",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGenericStructsTest.java": "dc21746271b26bf0c7af191eeae70b1308dc322bedbdd0e3bcceda7c734bf14a"
|
||||
},
|
||||
"provider_fingerprints": {
|
||||
"Cargo.lock": "cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795",
|
||||
"docs/vm-arch/INTRINSICS.csv": "0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa",
|
||||
"docs/vm-arch/BUILTIN_CONSTANTS.csv": "e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039",
|
||||
"crates/console/prometeu-vm/tests/fixtures/numeric-conformance.tsv": "5536ee18cadaf32e3719b0e8d541dfcf1a84a49ea978a702101547c5ccdee3fe",
|
||||
"crates/console/prometeu-vm/tests/fixtures/random-conformance.tsv": "0bee1cd0366f1716687aee8c7ac39dd495da5fe2908cce37b1443cb04fac542f"
|
||||
},
|
||||
"commands": [
|
||||
"./gradlew test :prometeu-app:installedKnowledgeTest --console=plain --continue",
|
||||
"./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test :prometeu-lsp:prometeu-lsp-v1:test :prometeu-app:installedKnowledgeTest --console=plain",
|
||||
"python3 tools/pbx-conformance/run.py --runtime ../runtime",
|
||||
"discussion validate",
|
||||
"git diff --check",
|
||||
"./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test --console=plain"
|
||||
],
|
||||
"logs": {
|
||||
"dec73-regression-final.log": "2a90cbace3db898da9b445aba9c21be2b4f0c3d22724e1763fc9a0f3e52e7947",
|
||||
"dec73-vm-regression.log": "159c6e0928a7d69aecb8660221135c1fa166e8e59212c5a3778883796170ea7e",
|
||||
"dec73-final-provenance.log": "84168ed25ad52a98fbc3de7e0574d2bbbe1ba57cba47c066f09c26e0173d17b9",
|
||||
"dec73-final-ctor-branches.log": "f32a83cf9084e4def4c1f12c2d3cce43b2254e217d57b9076f1707338afda3a9"
|
||||
},
|
||||
"notes": [
|
||||
"One initial external-source LSP failure passed in isolated reproduction and complete regression repetition; no unrelated LSP code changed.",
|
||||
"Final affected suite repeats include the declaration/use provenance correction and final installed spec cross-references.",
|
||||
"Null and typed-null Random cases are controlled provider bytecode fixtures; ordinary and generic PBS constructors require complete field initialization.",
|
||||
"Existing LifecycleRole and NonFiniteValue provider schema gaps remain reported by the common harness.",
|
||||
"Qualification is local macOS arm64 dev profile, not another platform, release profile or reference-game qualification.",
|
||||
"Final constructor analysis includes symbolic and/or short-circuit branches; frontend and architecture passed. All 16 regenerated artifact hashes match the production-VM-qualified PBX files."
|
||||
]
|
||||
}
|
||||
+210
@@ -0,0 +1,210 @@
|
||||
---
|
||||
id: LSN-0092
|
||||
ticket: runtime-storage-isa-consumer-migration
|
||||
title: Sequential collection mutations need explicit failure boundaries
|
||||
created: 2026-10-24
|
||||
tags: [compiler, compiler-pbs, runtime-integration, storage, collections]
|
||||
---
|
||||
|
||||
## Original problem and ownership
|
||||
|
||||
Owner: `compiler`, with propagation to `compiler/pbs` and `vm-arch`.
|
||||
|
||||
The delivered runtime removed logical guard and compound publication opcodes
|
||||
0xA7/0xA8/0xAA/0xAB. Studio's List/Linked SDK still depended on them and promised
|
||||
that every refused method preserved the complete collection. Pinning the new
|
||||
provider alone would therefore invalidate emitted PBX and leave the source
|
||||
contract unsupported. The provider also moved intrinsic metadata to schema 2.
|
||||
|
||||
AGD-0098 converged into accepted DEC-0077 and implementation PLN-0155. The user
|
||||
explicitly accepted the recommendations inspired by OpenJDK 25 and .NET 10, then
|
||||
authorized planning and implementation. These identifiers record workflow
|
||||
provenance; the completed control artifacts are removed by CLI housekeeping.
|
||||
The durable normative surfaces are the specifications linked below.
|
||||
|
||||
The entire migration belongs to Studio. Runtime revision
|
||||
`dcf6561ea73446e0a3e1cf1c73eda20923b38df0` is consumed unchanged. No runtime code,
|
||||
manifest, lockfile, instruction, quota or commit is a write target. External Cargo
|
||||
projects/targets qualify the production loader/VM without editing that checkout.
|
||||
|
||||
## Consolidated decision
|
||||
|
||||
Keep List's private array/logical size and Linked's private doubly linked nodes,
|
||||
collection identity, capacity policy and shared snapshot Cursor. Prepare logical
|
||||
checks, next sizes, values, candidates and return carriers before visible mutation;
|
||||
then use ordinary typed stores and retained ARRAY_COPY. Do not reconstruct a
|
||||
whole collection on every update to simulate the retired publication mechanism.
|
||||
|
||||
The accepted contract distinguishes three outcomes:
|
||||
|
||||
| Outcome | Guarantee |
|
||||
| --- | --- |
|
||||
| Rejection/preparation failure before the first visible mutation | The prior collection remains unchanged; argument effects and provisional allocations are not rolled back. |
|
||||
| Successful method return | All size/storage/topology, group, identity, cleanup and snapshot invariants hold. |
|
||||
| Internal/resource fault after visible mutation starts | Earlier writes can remain and invariants can be incomplete. There is no whole-method rollback, safe-reuse, retry or automatic-recovery guarantee. |
|
||||
|
||||
The last row deliberately replaces the old stronger promise. It is not a basic
|
||||
consistency guarantee. A single instruction still preserves its own entry state
|
||||
when it fails; that does not undo previous successful instructions.
|
||||
|
||||
BudgetExhausted and debugger pauses are instruction-boundary suspensions, not
|
||||
faults. Normal resumption continues the method at its current PC. Source methods
|
||||
are not atomic observation regions for the host/debugger. No user callback or
|
||||
explicit suspension is inserted into the sequence that completes mutation.
|
||||
|
||||
Java and C# informed the prepare-then-update structure, not a universal error
|
||||
recovery claim. Their ordinary iterators are also not a reason to replace an
|
||||
already accepted PBS snapshot protocol with fail-fast behavior.
|
||||
|
||||
## Final algorithms and costs
|
||||
|
||||
### List prepares packed values before shifting
|
||||
|
||||
For insertion with growth, build a private backing and copy the prefix and suffix
|
||||
directly into their final positions. For `[A,B,C]` with insertion of X at index 1,
|
||||
the candidate becomes `[A,X,B,C,...]` before storage/length are installed. Existing
|
||||
stored groups move intact, including holes, tags and identities.
|
||||
|
||||
Without growth, PBS Array assignment accepts T, whereas clearing uses
|
||||
`array.clear(index)`. Packing a new generic value can allocate. The SDK therefore
|
||||
prepares that value in a private one-slot array, shifts the suffix with ARRAY_COPY,
|
||||
copies the complete prepared slot, then updates logical length. This creates a
|
||||
charged temporary allocation and additional copy scratch; it does not clone the
|
||||
whole list or promise allocation-free insertion. A later copy/operand failure
|
||||
retains earlier writes under the accepted phase contract.
|
||||
|
||||
Removal prepares the optional result, shifts the suffix, clears the old tail and
|
||||
updates length. Clear and in-capacity resize clear their intervals in index order
|
||||
before setting length. Growing resize prepares/copies its private candidate;
|
||||
reserve/trim prepare candidates and replace storage without changing size.
|
||||
Indexed replacement and clearAt affect one checked position.
|
||||
|
||||
The policy remains capacity 16 by default, exact explicit capacity including zero,
|
||||
approximately 1.5x automatic growth with checked/clamped valid requirements,
|
||||
nonshrinking exact reserve and trim to size. Successful shrink/removal/clear never
|
||||
resurrect discarded values on regrowth. Old/candidate/temporary arrays coexist
|
||||
under ordinary quotas and tracing; reclamation is not immediate.
|
||||
|
||||
### Linked prepares nodes/results, then updates links
|
||||
|
||||
Insertion locates neighbors, checks the next signed-long size and prepares the new
|
||||
node before updating previous.next or head, next.previous or tail, then length.
|
||||
Removal prepares the optional result and neighbor values before updating those
|
||||
two sides and length. Replacement changes value only; clear changes head, tail,
|
||||
then length. Linked does not inherit Array's u32 length bound.
|
||||
|
||||
Some later source operand/carrier preparation can still refuse resources. The
|
||||
implementation and tests do not rename sequential link stores as atomic
|
||||
publication or assume that prepared source values make the remaining code
|
||||
infallible. A fault can occur after a successful earlier write.
|
||||
|
||||
### Cursor remains an independent snapshot
|
||||
|
||||
Capture constructs private immutable singly linked nodes and exposes only a
|
||||
complete result. Capture failure leaves the source unchanged. Forward and reverse
|
||||
Linked captures preserve their respective orders. Captured references preserve
|
||||
identity and observe later mutations of the referenced objects, while collection
|
||||
replacement/insertion/removal does not rewrite the captured sequence.
|
||||
|
||||
A nonempty Cursor starts at the first value. hasNext tests for a successor; next
|
||||
without one retains the last value; only an empty-born Cursor reports current
|
||||
absent. Prefixes become collectible as traversal advances, and the final current
|
||||
node/value remains retained until the Cursor releases it. No live/fail-fast
|
||||
iterator, public node or deep freeze was added.
|
||||
|
||||
## Logical refusals and the neutral terminal path
|
||||
|
||||
Bounds and length checks execute as PBS comparisons/branches. Reads/writes require
|
||||
`0 <= index < size`; insertion allows `index == size`. Negative or above-u32
|
||||
Array length/capacity requests and invalid logical indices terminate through the
|
||||
trusted private SDK fail binding, lowered to existing TRAP 0x05.
|
||||
|
||||
Common IR, IRVM, validation, optimization, emission and source spans now carry
|
||||
that zero-operand terminal operation. It raises TRAP_EXPLICIT rather than
|
||||
pretending to preserve retired guard diagnostics/costs. Physical Array operations
|
||||
that actually execute retain their own faults and resource context. None remains
|
||||
legitimate absence, not a replacement for a fault.
|
||||
|
||||
The four retired Registry kinds, publication schema builder and dedicated extra
|
||||
publication immediate fields were removed. Producer preload rejects the retired
|
||||
encodings even in dead code. Decoding actual instruction positions avoids false
|
||||
positives when an Int32 immediate contains the same numeric bytes.
|
||||
|
||||
## Copy attempt boundaries and schema 2
|
||||
|
||||
ARRAY_COPY remains u16 LE 0xA9 plus Array TypeId u32 LE, consuming source,
|
||||
sourceStart, target, targetStart, count. Exact receivers and Int64 offsets/count,
|
||||
strict physical ranges, overlap snapshots, complete groups/native owners and
|
||||
scratch cleanup remain provider responsibilities.
|
||||
|
||||
For valid selectable N and Registry width W, attempted cost is `4 + 2*N*W`, charged
|
||||
before receiver/range/group/scratch refusal. N=10/W=1 costs 24 on success and the
|
||||
specified refusals; W=2 costs 44. Empty copies validate and cost 4. Negative or
|
||||
above-u32 counts select base 4 and ordinary fault precedence. Zero budget executes
|
||||
nothing; positive budget admits the full attempt with overshoot, and a failed
|
||||
attempt is Trap with zero successful target steps. Checked arithmetic overflow
|
||||
using synthetic internal widths is separately qualified provider evidence, not a
|
||||
claim that admitted consumer descriptors can reach those widths.
|
||||
|
||||
All 108 intrinsic definitions retain all 25 schema-2 fields. A dedicated profile
|
||||
value validates schema, ordered nullable bits, invocation/scratch/context tuples
|
||||
and fixed/rejection/UTF-8 cost parameters. Deterministic does not mean pure.
|
||||
Known null String admission follows each entry: hash.string admits it and returns
|
||||
the provider's zero hash vector, while older non-nullable String entries reject
|
||||
it at load. Importing hash metadata does not deliver PBS hashing facades or Set/Map.
|
||||
|
||||
Catalogs, SHA/digests, compiler and SDK packaged resources now agree with the
|
||||
selected clean provider. Runtime architecture mirrors are copied byte-for-byte;
|
||||
ordinary compilation/parity tests continue using only local versioned resources.
|
||||
|
||||
## Qualification and reproducible evidence
|
||||
|
||||
The [qualification record](runtime-conformance-evidence.json) identifies source
|
||||
fingerprints, provider revision/clean state, toolchains, fixture digests, commands,
|
||||
log hashes, test totals and observed execution/refusal counts. Full raw logs are
|
||||
compressed losslessly as `.log.gz` files beside it; the record includes both
|
||||
compressed-file and original uncompressed SHA-256 values. The evidence separates the normal test suite, installed-JAR examples,
|
||||
explicit exporter parity, debug/release conformance and focused unchanged-provider
|
||||
copy defenses. Historical List/Linked evidence remains tied to its original pins.
|
||||
|
||||
The consumer harness measures refusal limits from setup/success peaks, then
|
||||
single-steps operations and compares every original-object state with the same
|
||||
successful instruction prefix. It asserts complete prior-state preservation only
|
||||
before visible mutation, and records completed writes afterward. Source snapshots
|
||||
are non-owning observations; they neither add guest roots nor write the collection.
|
||||
This catches both accidental early mutation and accidental claims of rollback.
|
||||
|
||||
The corpus includes normal/optimized source methods, 28 phase-marker variants,
|
||||
neutral store/copy/terminal fixtures, 22 copy cases across paired producer paths, dead retired opcodes
|
||||
versus immediate bytes, zero-budget/overshoot/fault precedence, quotas, GC,
|
||||
import/reexport and actual packaged examples compiled outside the checkout.
|
||||
Existing unrelated headless-schema gaps are reported explicitly by the harness;
|
||||
they are not silently relabeled as schema conformance or fixed in runtime here.
|
||||
|
||||
## Pitfalls and maintenance guidance
|
||||
|
||||
- Preparing a value is not proof that every later load, carrier, call or store
|
||||
sequence cannot fail. Publish the actual failure boundary.
|
||||
- Do not assert unchanged collections after every refusal once the accepted
|
||||
contract permits prior writes. Compare the real instruction prefix instead.
|
||||
- Do not unpack/rebox all shifted values or discard empty-copy validation/cycles.
|
||||
- Do not count frame locals as missing copy operands or confuse a pause with a fault.
|
||||
- Do not infer nullable admission, purity or zero scratch from names/determinism.
|
||||
- Updating a CSV/pin alone is not a consumer integration. Code, installed
|
||||
resources, source execution and provenance must move together.
|
||||
- Set/Map still need their own contracts and algorithms. The retired publication
|
||||
instructions are not available to their future implementations, and this work
|
||||
does not accept their pending product choices.
|
||||
- Changing the runtime to rescue an incomplete producer is outside this delivery.
|
||||
|
||||
## Durable references
|
||||
|
||||
- [Common Registry/PBX](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
- [Runtime catalog consumer](../../../docs/compiler/general/specs/runtime-catalog-support.md).
|
||||
- [List/Cursor](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md),
|
||||
[Linked](../../../docs/compiler/pbs/specs/sdk-linked-and-cursor.md) and
|
||||
[Array/optional](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
|
||||
- [Conformance commands and coverage](../../../tools/pbx-conformance/README.md).
|
||||
- [Selected provider pin](../../../docs/vm-arch/runtime-catalog.properties).
|
||||
- Original decisions/planning: accepted DEC-0077 and completed PLN-0155 in DSC-0096,
|
||||
consolidated here before their required housekeeping removal.
|
||||
BIN
Binary file not shown.
BIN
Binary file not shown.
+1143
File diff suppressed because it is too large
Load Diff
BIN
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
+260
@@ -0,0 +1,260 @@
|
||||
{
|
||||
"discussion": "DSC-0096",
|
||||
"decision": "DEC-0077",
|
||||
"plan": "PLN-0155",
|
||||
"qualified_at": "2026-10-24T00:03:03.883761+00:00",
|
||||
"owner": "compiler",
|
||||
"propagation": [
|
||||
"compiler/pbs",
|
||||
"vm-arch"
|
||||
],
|
||||
"studio_source_base_revision": "77aada62592c10e97cbabf4386e0d6e98f12a9f4",
|
||||
"studio_qualification_is_working_tree_not_committed_provider": true,
|
||||
"studio_changed_file_sha256": {
|
||||
"docs/compiler/general/specs/runtime-catalog-support.md": "7f0b30bad26db25d4f689238da197095e4fae10cb8dfad6fd571e60644207880",
|
||||
"docs/compiler/general/specs/typed-registry-and-pbx-v0.md": "93f3ac04f5fa08ebde8ef11aa39c0ca43ffefb345ae0730c3c39557b8cce2a0f",
|
||||
"docs/compiler/pbs/specs/sdk-linked-and-cursor.md": "bd399f1923353390c6bd7e8613c53a1656e99fbb37e750abd840ceee77dd4c68",
|
||||
"docs/compiler/pbs/specs/sdk-list-and-cursor.md": "01acfa69abf381687b8a83291599506b3b95fc220e35f63f6585876649db8571",
|
||||
"docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md": "68be43bef791d8e620e7398f9d5a3abd5a197342cc70b0c2f606d985fcdc3b35",
|
||||
"docs/vm-arch/ARCHITECTURE.md": "d7e3487bb2d9718bba810cf4cfaec175dcbf9b079f7df12a4fad537bd1606146",
|
||||
"docs/vm-arch/INTRINSICS.csv": "7c1c363f5f0f941b3ab27cfc72af41e13e44cd4371c687db8300721288f47e63",
|
||||
"docs/vm-arch/ISA_CORE.md": "6b3207f81d3bd782e4f9b445b19c80b64bc599d8aebc5f01d8627a477bd09c8b",
|
||||
"docs/vm-arch/README.md": "2b08f106aa952f5acf062d7bdae1a63eca5a0104a956603c5400b3d6615ba1ab",
|
||||
"docs/vm-arch/runtime-catalog.properties": "ee236a887514d31f8996c5186796fee353ad89d112614ebbf23c9ed17a84deed",
|
||||
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsListCursorTest.java": "59a331c52ca8e74ec30fef5783e0c960b641820df2679b90a0463a05002c8610",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java": "8bc5c877ee991281d9ec74dc0a2a89acd857bee777d6b7a5102caf3abb2bd921",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableStackAnalyzer.java": "23aadaf62f902165a20f07f55fbcd468651c9e56017a8eba834ad487e4902c18",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsRuntimeTypes.java": "20504d33df9f01aa387985b3b5abb275951d6ad52e95fd09d001189ba503afcb",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs": "e6a2df250ad2da7c98d953117fc5c7fdc3e053a1539707f10bfcb3239228cdb1",
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java": "74a45482c2794996188b90be3b58bd0d5a0ac8b265671dc89b061da85dd4e73c",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/bytecode/BytecodeEmitter.java": "e1dac43d9a5c413d67f56ae331176e95ef3116526cebfb99612486603d5e4b19",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/bytecode/BytecodeOpcodeLayout.java": "4f2ac0a755820a3496d74b9dddfd65db855bc6a9f8ffc3989a9f3230f67c38ca",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/bytecode/BytecodePreloadVerifierService.java": "f2248cebce4677368bc52ca2885ab0abf1cad506974029ea09d4dd93196784a6",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMInstruction.java": "c925849d14d39943154d061bcdc15639d73963a7fc8b9adee74038f1cf677e26",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMIntrinsicDefinition.java": "4a03263237b9c305d6104187d6841d0db17ec5640347f7fb03ff019e622dd176",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMIntrinsicProfile.java": "a35a01a35a0aac341bf3c79555192d3c167609f80e607dd0ad72872722434a07",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMOp.java": "e7fc4c73d8e044d65b2d7c74a909ff550aaae098031d8cc8cb616e12b3d42dd8",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMProfileFeatureGate.java": "67b6a4c080aa15a90545ebe4bf1c72992905b9dac57e3df1e555e43cfe9afc27",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMProgram.java": "83f08c234860d92f8dc23a6cfa55b8594218dbc6861365376c11e4d29700d3eb",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMValidator.java": "086a17958152aeabf84d1f551fbc549eb7ca4ac2a4546c324cfb640a97c86d38",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/LowerToIRVMService.java": "bdf241ddc192eaf6987312a672a163f7b5cf97d58e2fbefa809c4649db35447c",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/OptimizeIRVMService.java": "ce1a90e37542a34c1f9803f50407a1fe6f63bdb7adcf41ad5641c39034a192a0",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/registry/RegistryInstructionLowerer.java": "044bf756a89a88aa3f6833caf6c181c06b1fe44acb4dab58c1ee97da23b053b8",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/IRVMInstructionTest.java": "02aa2021c2351e416969055b247eac4b1bd16174a99262dc60e84b59a9e118a9",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/IRVMIntrinsicProfileTest.java": "7c5cf20642e1f41d22bb94a397a844c1452f62db70c6c1ac89af4c9011b1de58",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/IRVMIntrinsicRegistryParityTest.java": "8618ea1901e7cca90ba071523be4b74b24259374f23623c12a02588cb6444ea5",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/RuntimeCatalogPipelineTest.java": "990e8e7410cf53431d577d996b07e00cf1b4db29ca55fb3e7b2c88dba66536eb",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/registry/ArrayCopyPipelineTest.java": "b21184e96d5ae04ef07f8454caa33ba1c3c4463200f1ff70926766fa6d80f597",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/registry/PbxRegistryConformanceTest.java": "f91e030e0db28288743cba4be616c68d10c9ce2f95ce3346a0886a431587d9c0",
|
||||
"prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/registry/StoragePublicationPipelineTest.java": "e587739fe79fa4b9f4a42eefac572b3974a31611634af537e5feac57b61f55b5",
|
||||
"prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend.java": "a835b94ee7f15e26616463900368d100c0c7f08782a5d0baa2a3f6adbe1c3d6d",
|
||||
"prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackendExecutableFunction.java": "ad4f023a8bf800a2d4ea09c2d5e14471c9e9b36ae82d84c8ed0acae954255e97",
|
||||
"prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/registry/IRRegistryInstruction.java": "4c8fd165d5790aaf475ad614fc9cd39fc6d0cf26bb85478d3a9dea9a30bd905f",
|
||||
"tools/pbx-conformance/README.md": "da79187f717f441e20a19dca6eeaef8e0736ae1cd89fd85fc916575f5fd9bc76",
|
||||
"tools/pbx-conformance/main.rs": "4509722b8746ccce4425dfc00582002a6782140af7b1ae43b7aaced6d8722222",
|
||||
"tools/pbx-conformance/run.py": "e66b38e6396e4afa7f1c63af157568cb37a3328a1c65057783aae3eefb7cee45"
|
||||
},
|
||||
"runtime": {
|
||||
"revision": "dcf6561ea73446e0a3e1cf1c73eda20923b38df0",
|
||||
"working_tree": "clean",
|
||||
"written_or_committed_by_this_delivery": false,
|
||||
"cargo_build_outputs": "external temporary directories only"
|
||||
},
|
||||
"catalogs_and_mirrors_sha256": {
|
||||
"INTRINSICS.csv": "7c1c363f5f0f941b3ab27cfc72af41e13e44cd4371c687db8300721288f47e63",
|
||||
"BUILTIN_CONSTANTS.csv": "e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039",
|
||||
"ARCHITECTURE.md": "d7e3487bb2d9718bba810cf4cfaec175dcbf9b079f7df12a4fad537bd1606146",
|
||||
"ISA_CORE.md": "6b3207f81d3bd782e4f9b445b19c80b64bc599d8aebc5f01d8627a477bd09c8b"
|
||||
},
|
||||
"commands": [
|
||||
{
|
||||
"command": "./gradlew test :prometeu-app:installedKnowledgeTest --console=plain",
|
||||
"exit_code": 0,
|
||||
"log": "gradle-regression.log.gz",
|
||||
"sha256": "85eb690857eea9e1961cf1011fff23c2f9e66185868a38681624c66a7cea3e92",
|
||||
"uncompressed_sha256": "70ecdc56dc94c7cc4544098d283d9ebc068ad692f8cc3ce7fcbafc3d6ac8af64",
|
||||
"log_encoding": "gzip"
|
||||
},
|
||||
{
|
||||
"command": "./gradlew :prometeu-compiler:prometeu-build-pipeline:test :prometeu-app:installedKnowledgeTest --console=plain",
|
||||
"exit_code": 0,
|
||||
"log": "gradle-packaged-final.log.gz",
|
||||
"sha256": "dc391a4532e28387573f4b65b02395b38ed164fd851d0b4423a4408396a46bd0",
|
||||
"uncompressed_sha256": "8b0a56da56456977455323d2e321a7291f110d57ca4e3836bd81dea2b5f1e785",
|
||||
"log_encoding": "gzip"
|
||||
},
|
||||
{
|
||||
"command": "python3 tools/runtime-catalog/verify.py --runtime ../runtime",
|
||||
"exit_code": 0,
|
||||
"log": "provider-catalog.log.gz",
|
||||
"sha256": "bab6e8190952884c3a24cf2f0cdf46890f294b150ff6accfb60f58a82aabacc3",
|
||||
"uncompressed_sha256": "28ebcd83d8c9195422e3f8d2c7a1a0be5cb52723d2789e094c60d50f7d8ad7b4",
|
||||
"log_encoding": "gzip"
|
||||
},
|
||||
{
|
||||
"command": "cargo test --manifest-path ../runtime/Cargo.toml --locked --offline --target-dir /tmp/studio-storage-provider-155 -p prometeu-vm --lib array_copy_tests",
|
||||
"exit_code": 0,
|
||||
"log": "provider-copy-tests.log.gz",
|
||||
"sha256": "a0b8f2692556846cd7b418ae91993ddd3d0c6fef1f6fb2aa4551b962996b4d3e",
|
||||
"uncompressed_sha256": "30497f7edcd3f019f99d7f9166f4b12542d931999faa32c9c912ac1dd97de308",
|
||||
"log_encoding": "gzip"
|
||||
},
|
||||
{
|
||||
"command": "CARGO_TARGET_DIR=/tmp/studio-storage-conformance-155 python3 tools/pbx-conformance/run.py --runtime ../runtime",
|
||||
"exit_code": 0,
|
||||
"log": "conformance-debug.log.gz",
|
||||
"sha256": "df08969fd266c7b8844146a42bcfc63d078792d0fa69441c5660a553a73e0255",
|
||||
"uncompressed_sha256": "40a4b73d7796eb16f9099166d794ed3bb0ccf412c8a373b016d30bd5303f78df",
|
||||
"log_encoding": "gzip"
|
||||
},
|
||||
{
|
||||
"command": "CARGO_TARGET_DIR=/tmp/studio-storage-conformance-155 python3 tools/pbx-conformance/run.py --runtime ../runtime --release",
|
||||
"exit_code": 0,
|
||||
"log": "conformance-release.log.gz",
|
||||
"sha256": "346711a7d78590e803d478520423584d60501fc70ea4856a1ed4b565ba25c7d1",
|
||||
"uncompressed_sha256": "6d7fa765a6e14626b697efb2b88b4b85ad44845ba12d72b6e98eb16907de114a",
|
||||
"log_encoding": "gzip"
|
||||
}
|
||||
],
|
||||
"latest_normal_test_reports": {
|
||||
"prometeu-studio-api": {
|
||||
"tests": 2,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-infra": {
|
||||
"tests": 7,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-app": {
|
||||
"tests": 81,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-studio-ui-javafx": {
|
||||
"tests": 20,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-architecture-tests": {
|
||||
"tests": 97,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-studio-core": {
|
||||
"tests": 110,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-compiler/prometeu-build-pipeline": {
|
||||
"tests": 197,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 12
|
||||
},
|
||||
"prometeu-compiler/prometeu-frontend-registry": {
|
||||
"tests": 8,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-compiler/prometeu-frontend-api": {
|
||||
"tests": 29,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-compiler/prometeu-compiler-core": {
|
||||
"tests": 21,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-compiler/prometeu-deps": {
|
||||
"tests": 9,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-compiler/frontends/prometeu-frontend-pbs": {
|
||||
"tests": 297,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-packer/prometeu-packer-v1": {
|
||||
"tests": 119,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
},
|
||||
"prometeu-lsp/prometeu-lsp-v1": {
|
||||
"tests": 41,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 1
|
||||
}
|
||||
},
|
||||
"installed_knowledge_test_reports": {
|
||||
"p.studio.app.compiler.InstalledKnowledgeTest": {
|
||||
"tests": 2,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"skipped": 0
|
||||
}
|
||||
},
|
||||
"normal_test_report_note": "Latest reports combine full normal regression and final backend/installed rerun; existing disabled tests remain explicitly counted, not newly skipped for this migration.",
|
||||
"conformance_profiles": {
|
||||
"debug": {
|
||||
"PBS MATH": 1,
|
||||
"PBS LIST/CURSOR SOURCE/LOAD/EXEC PASS": 54,
|
||||
"PBS LINKED SOURCE/LOAD/EXEC PASS": 52,
|
||||
"COMMON COPY COST/FAULT/GROUP PASS": 22,
|
||||
"COMMON PARTIAL FAULT PASS": 2,
|
||||
"PBS LIST PHASE REFUSAL": 136,
|
||||
"PBS LINKED PHASE REFUSAL": 406,
|
||||
"PHASE CORPUS list": 8,
|
||||
"PHASE CORPUS linked": 20,
|
||||
"UPSTREAM SCHEMA GAP": 2,
|
||||
"post_mutation_refusals": 34,
|
||||
"MATH PASS": 0,
|
||||
"RANDOM PASS": 227
|
||||
},
|
||||
"release": {
|
||||
"PBS MATH": 1,
|
||||
"PBS LIST/CURSOR SOURCE/LOAD/EXEC PASS": 54,
|
||||
"PBS LINKED SOURCE/LOAD/EXEC PASS": 52,
|
||||
"COMMON COPY COST/FAULT/GROUP PASS": 22,
|
||||
"COMMON PARTIAL FAULT PASS": 2,
|
||||
"PBS LIST PHASE REFUSAL": 136,
|
||||
"PBS LINKED PHASE REFUSAL": 406,
|
||||
"PHASE CORPUS list": 8,
|
||||
"PHASE CORPUS linked": 20,
|
||||
"UPSTREAM SCHEMA GAP": 2,
|
||||
"post_mutation_refusals": 34,
|
||||
"MATH PASS": 0,
|
||||
"RANDOM PASS": 227
|
||||
}
|
||||
},
|
||||
"generated_fixture_manifest": "generated-pbx-manifest.json",
|
||||
"generated_fixture_count": 1141,
|
||||
"generated_fixture_manifest_note": "All generated PBX files are fingerprinted; execution scope and mandatory fixture sets are defined by the harness and logs, not by directory presence alone.",
|
||||
"limitations": [
|
||||
"Qualification is local macOS/arm64, not new cross-platform evidence.",
|
||||
"The existing harness reports two unrelated headless-schema enum gaps (LifecycleRole and NonFiniteValue) explicitly; original payloads are not claimed conformant to the unmodified schema.",
|
||||
"Checked cost overflow and internally malformed/late groups are separately covered by 11 unchanged-provider copy unit tests; this does not claim synthetic widths are admitted consumer layouts.",
|
||||
"Set/Map, PBS hashing facades, live iterator semantics and runtime modifications are excluded."
|
||||
],
|
||||
"outcome": "passed",
|
||||
"generated_fixture_manifest_sha256": "f2679f21014e51812a5a79e8de26297828a7ba8685142811bff786f5fd5f5453",
|
||||
"executed_plan_sha256_before_housekeeping": "453bb2f2291c7fe188032550dcfeb2c91c0368f5112a8f28edcae14c47e9780c",
|
||||
"accepted_decision_sha256_before_housekeeping": "ab08576555aadb95769232a4ccdadcf3d717c1fa1c73ace563891cbd50b7d4f7",
|
||||
"lesson_sha256": "3ef5ede442ab9f202faead2f6ce34ebaf1e1ed2c115d49c419ce5b743a213c01"
|
||||
}
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0044
|
||||
ticket: pbs-lsp-document-symbols-outline
|
||||
title: PBS LSP Document Symbols and Outline
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, outline, document-symbols]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS files do not populate a reliable VS Code outline, forcing users to navigate long source files manually instead of scanning declarations and members structurally.
|
||||
|
||||
## Context
|
||||
|
||||
The parser and semantic surfaces know top-level declarations and many member declarations. The LSP currently does not announce documentSymbolProvider and does not map PBS declarations to DocumentSymbol or SymbolInformation payloads.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should the first outline be syntactic, semantic, or hybrid?
|
||||
- [ ] Which hierarchy should be shown for structs, services, hosts, contracts, builtin types, enums, and methods?
|
||||
- [ ] How should invalid or partially parsed files contribute to outline during editing?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - AST-only outline
|
||||
|
||||
- **Approach:** Map parsed declarations and member spans directly to LSP `DocumentSymbol`.
|
||||
- **Pro:** Works even when semantic analysis is incomplete and gives immediate editor value.
|
||||
- **Con:** Cannot classify every symbol with semantic precision.
|
||||
- **Maintainability:** Good if kept as structural outline, not overloaded with semantic behavior.
|
||||
|
||||
### Option B - Semantic outline
|
||||
|
||||
- **Approach:** Build outline from semantic symbols after analysis.
|
||||
- **Pro:** More accurate kinds and can hide invalid/unresolved surfaces.
|
||||
- **Con:** More fragile during active editing and depends on full semantic success.
|
||||
- **Maintainability:** Good for final precision, but heavier than needed for outline.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Outline should remain available during broken intermediate edits. Semantic precision is useful, but not at the cost of disappearing structure while typing.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option A with semantic enrichment where available. Use AST spans as the stable backbone.
|
||||
|
||||
## Discussion
|
||||
|
||||
Document symbols are relatively independent and can be implemented before definition/references.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide hierarchy and symbol kinds for PBS declarations and members.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0045
|
||||
ticket: pbs-lsp-workspace-symbols
|
||||
title: PBS LSP Workspace Symbols
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, workspace-symbols]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
VS Code cannot search PBS symbols across the workspace, so users cannot quickly jump to functions, services, structs, constants, or stdlib-exposed APIs by name.
|
||||
|
||||
## Context
|
||||
|
||||
Document-level editorial features exist, but the LSP does not announce workspaceSymbolProvider and the compiler pipeline does not expose a project-wide symbol index designed for editor queries.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should workspace symbols include only project files or also imported stdlib and SDK surfaces?
|
||||
- [ ] What symbol kinds and ranking should be returned for duplicate names or overloads?
|
||||
- [ ] Should the symbol index be cached from analysis snapshots or rebuilt per request in the first implementation?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Project source index only
|
||||
|
||||
- **Approach:** Index project-owned declarations from analysis snapshots and expose `workspace/symbol`.
|
||||
- **Pro:** Clear ownership and physical locations.
|
||||
- **Con:** Does not help users discover stdlib/SDK symbols.
|
||||
- **Maintainability:** Strong as a first wave.
|
||||
|
||||
### Option B - Project plus stdlib index
|
||||
|
||||
- **Approach:** Include project declarations and imported stdlib/SDK surfaces in the workspace symbol result set.
|
||||
- **Pro:** Better discovery, especially for new users.
|
||||
- **Con:** Requires a navigation policy for stdlib source or virtual targets.
|
||||
- **Maintainability:** Good if stdlib target handling is solved; awkward otherwise.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Workspace symbols are partly navigation and partly discovery. Including stdlib too early can create broken jumps if target locations are not defined.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option A first, then add stdlib once definition has a target policy.
|
||||
|
||||
## Discussion
|
||||
|
||||
This should follow document symbols and the semantic location/index work.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide whether first-wave workspace search includes stdlib or project-only symbols.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0046
|
||||
ticket: pbs-lsp-rename-symbol
|
||||
title: PBS LSP Rename Symbol
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, rename]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS users cannot safely rename a symbol through the editor, so they must edit text manually and risk missing references or changing unrelated overloads and same-name declarations.
|
||||
|
||||
## Context
|
||||
|
||||
Rename requires the same semantic identity and reference machinery needed by definition/references, plus workspace edits and conflict detection. The current LSP does not announce renameProvider.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Which symbols should be renameable in the first wave, and which should be protected such as stdlib, generated, host, or builtin declarations?
|
||||
- [ ] How should rename handle overloads, member methods, imports, and labels with the same text?
|
||||
- [ ] What validation should run before returning a WorkspaceEdit?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Local file rename
|
||||
|
||||
- **Approach:** Rename only references in the current file using local semantic resolution.
|
||||
- **Pro:** Smaller blast radius and easier conflict handling.
|
||||
- **Con:** Incomplete for imported symbols and project-wide APIs.
|
||||
- **Maintainability:** Acceptable only if explicitly presented as limited.
|
||||
|
||||
### Option B - Workspace semantic rename
|
||||
|
||||
- **Approach:** Use a project-wide reference index and return a `WorkspaceEdit` for all usage and declaration sites.
|
||||
- **Pro:** Matches user expectations for editor rename.
|
||||
- **Con:** Requires reliable references, collision checks, and write-safety across files.
|
||||
- **Maintainability:** Strong once references exist.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Rename is high trust. A partial or text-based rename can corrupt code silently, so scope must be explicit and conservative.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option B after semantic references are implemented. If delivered earlier, ship only a clearly limited local rename.
|
||||
|
||||
## Discussion
|
||||
|
||||
Do not implement rename before definition/references are resolved.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide whether rename waits for workspace references or ships a limited local-only wave.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0047
|
||||
ticket: pbs-lsp-code-actions
|
||||
title: PBS LSP Code Actions and Quick Fixes
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, code-actions, quick-fix]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS diagnostics are visible, but users do not get actionable quick fixes for common compiler/editor problems, making simple repairs slower than necessary.
|
||||
|
||||
## Context
|
||||
|
||||
The LSP maps diagnostics but does not announce codeActionProvider. Compiler diagnostics already carry codes and ranges, but not every diagnostic has enough structured repair data to generate safe edits.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Which diagnostics should receive quick fixes first?
|
||||
- [ ] Should code actions be produced from diagnostic codes only, or from structured compiler repair hints?
|
||||
- [ ] How should imports, reserved attributes, missing methods, and invalid Doc shapes be prioritized?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Diagnostic-code quick fixes
|
||||
|
||||
- **Approach:** Map known diagnostic codes to simple edits in the LSP layer.
|
||||
- **Pro:** Fast for a small set of obvious repairs.
|
||||
- **Con:** Couples fixes to diagnostic text/ranges and can become brittle.
|
||||
- **Maintainability:** Moderate if limited to trivial edits.
|
||||
|
||||
### Option B - Compiler repair hints
|
||||
|
||||
- **Approach:** Extend diagnostics with structured repair metadata and let the LSP map hints to code actions.
|
||||
- **Pro:** Keeps product logic close to compiler knowledge.
|
||||
- **Con:** Requires a new diagnostic/repair contract.
|
||||
- **Maintainability:** Strong for non-trivial fixes and future frontends.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Quick fixes are only useful if safe. Simple code-based fixes can ship first, but imports and generated stubs need stronger compiler context.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option B as the target design, with Option A allowed only for a small bootstrap set of unambiguous repairs.
|
||||
|
||||
## Discussion
|
||||
|
||||
This should follow diagnostics UX and import assistance for the first high-value fixes.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Pick the first three diagnostic codes eligible for safe quick fixes.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0048
|
||||
ticket: pbs-lsp-formatting
|
||||
title: PBS LSP Formatting
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, formatting]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS formatting is not automated, so style drifts across files, especially around attributes, services, blocks, imports, and multi-line Doc text blocks.
|
||||
|
||||
## Context
|
||||
|
||||
The LSP does not announce documentFormattingProvider. PBS has a parser and AST, but formatting must preserve documentation text block content while normalizing surrounding syntax and indentation.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should formatting be AST-based, token-based, or hybrid to preserve comments and text blocks?
|
||||
- [ ] What canonical style should PBS use for attributes, braces, imports, params, and text blocks?
|
||||
- [ ] Should the first wave support full document formatting only, or also range/on-type formatting?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Token-preserving formatter
|
||||
|
||||
- **Approach:** Format from tokens and trivia, preserving comments and documentation text block contents.
|
||||
- **Pro:** Safer for active editing and text blocks.
|
||||
- **Con:** Harder to enforce deep structural layout.
|
||||
- **Maintainability:** Good if PBS formatting remains mostly syntactic.
|
||||
|
||||
### Option B - AST pretty-printer
|
||||
|
||||
- **Approach:** Reprint code from the AST using canonical style rules.
|
||||
- **Pro:** Produces consistent output.
|
||||
- **Con:** Risks losing comments/trivia and cannot handle malformed files well.
|
||||
- **Maintainability:** Strong only after AST/trivia ownership is explicit.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Formatting must not damage `Doc` text blocks. That makes trivia preservation a first-class requirement rather than an implementation detail.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option A or a hybrid token/AST formatter. Avoid a pure AST pretty-printer until comments/trivia are modeled.
|
||||
|
||||
## Discussion
|
||||
|
||||
Formatter decision should define canonical style before implementation.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide PBS canonical formatting rules for attributes, braces, imports, params, and text blocks.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0049
|
||||
ticket: pbs-lsp-import-assistance
|
||||
title: PBS LSP Import Assistance
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, imports, completion]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS users do not get import-aware assistance, so discovering exported symbols and adding the right import from barrels, stdlib, or project modules remains manual.
|
||||
|
||||
## Context
|
||||
|
||||
Completion already exists for local/editorial contexts, and stdlib imports are understood by the compiler pipeline. The LSP does not yet provide auto-import completion, organize imports, or import quick fixes.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should auto-import target project modules, stdlib modules, or both in the first wave?
|
||||
- [ ] How should barrels and explicit module imports be ranked and rendered in completion?
|
||||
- [ ] Should organize imports be a code action, source action, formatter responsibility, or separate feature?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Import completion only
|
||||
|
||||
- **Approach:** Suggest symbols from known modules and include import detail, but do not edit imports automatically.
|
||||
- **Pro:** Low risk and improves discovery.
|
||||
- **Con:** Still leaves manual import edits.
|
||||
- **Maintainability:** Good as a stepping stone.
|
||||
|
||||
### Option B - Auto-import and organize imports
|
||||
|
||||
- **Approach:** Completion/code actions insert missing imports and source actions sort/remove unused imports.
|
||||
- **Pro:** Matches modern editor expectations.
|
||||
- **Con:** Requires robust module export indexing and edit placement rules.
|
||||
- **Maintainability:** Strong if built on a proper import graph.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Auto-import depends on knowing canonical exports and choosing an edit location. Doing that ad hoc in completion would create formatting and duplicate import issues.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option B as the target, but start with import-aware suggestions plus a limited missing-import quick fix.
|
||||
|
||||
## Discussion
|
||||
|
||||
This should be coordinated with code actions and formatter.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide first-wave import sources: stdlib only, project modules only, or both.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0050
|
||||
ticket: pbs-lsp-semantic-tokens-semantic-classification
|
||||
title: PBS LSP Semantic Token Classification
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, semantic-tokens]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS semantic highlighting exists, but parts of the token classification can remain lexical or superficial, which limits visual accuracy for same-looking identifiers with different semantic roles.
|
||||
|
||||
## Context
|
||||
|
||||
The current LSP announces full semantic tokens and maps frontend semantic presentation to VS Code. The compiler has semantic read surfaces that can classify symbols more accurately than raw tokenization.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Which token categories must become semantic identity-based first?
|
||||
- [ ] Should semantic tokens be produced from compiler semantic surfaces, parser AST, lexer tokens, or layered output?
|
||||
- [ ] How should tokens behave in files with syntax or semantic errors during active editing?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Lexical tokens with semantic overlays
|
||||
|
||||
- **Approach:** Keep lexer-based tokenization as baseline and overlay semantic categories where resolution succeeds.
|
||||
- **Pro:** Stable during broken edits and incremental to improve.
|
||||
- **Con:** Some unresolved identifiers remain visually generic.
|
||||
- **Maintainability:** Strong because fallback behavior is explicit.
|
||||
|
||||
### Option B - Fully semantic token stream
|
||||
|
||||
- **Approach:** Generate all semantic tokens from compiler semantic surfaces.
|
||||
- **Pro:** Maximum accuracy when analysis succeeds.
|
||||
- **Con:** Highlighting may disappear or degrade sharply on incomplete code.
|
||||
- **Maintainability:** Risky unless snapshot/error recovery is excellent.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Highlighting must be resilient while the user is typing. A perfect semantic pass that fails on partial code is worse than a layered model.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option A: lexical baseline plus semantic overlays from resolved symbols.
|
||||
|
||||
## Discussion
|
||||
|
||||
This can proceed independently but benefits from LSP snapshot/cache work.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Choose semantic overlay categories for the first pass.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0051
|
||||
ticket: pbs-lsp-performance-cache-and-snapshots
|
||||
title: PBS LSP Performance Cache and Snapshots
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, performance, caching]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
Several PBS LSP requests rebuild or reanalyze substantial project state, which can become slow or jittery as projects grow and as richer features are added.
|
||||
|
||||
## Context
|
||||
|
||||
The current bridge favors correctness and simplicity by invoking compiler pipeline analysis for diagnostics and editorial documents. A complete LSP needs snapshot caching, invalidation, cancellation, and predictable latency.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] What is the canonical project/document snapshot boundary for LSP requests?
|
||||
- [ ] Which requests can reuse semantic read surfaces safely across document changes?
|
||||
- [ ] How should cancellation, stale responses, and background reanalysis be handled?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Request-local analysis
|
||||
|
||||
- **Approach:** Keep each LSP request self-contained and rebuild analysis as needed.
|
||||
- **Pro:** Simple, deterministic, and less stateful.
|
||||
- **Con:** Latency grows with project size and feature richness.
|
||||
- **Maintainability:** Good for correctness, weak for interactive performance.
|
||||
|
||||
### Option B - Project snapshot cache
|
||||
|
||||
- **Approach:** Maintain per-project analysis snapshots with document overlays, invalidation, and cancellation-aware request handling.
|
||||
- **Pro:** Required for responsive definition, references, rename, and semantic tokens.
|
||||
- **Con:** Introduces lifecycle complexity and stale-result risks.
|
||||
- **Maintainability:** Strong if snapshot ownership and invalidation are explicit.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
A complete LSP needs shared state, but shared state must not leak stale analysis into edits. The decision is about the boundary, not just caching.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option B before implementing workspace-wide features like references and rename.
|
||||
|
||||
## Discussion
|
||||
|
||||
Define snapshot lifecycle, invalidation triggers, and cancellation policy.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide whether snapshot caching is a prerequisite for references/rename or can be staged later.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0052
|
||||
ticket: pbs-lsp-completion-depth
|
||||
title: PBS LSP Completion Depth
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, completion]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS completion works for core cases, but a complete daily-use experience needs ranking, resolve details, snippets, overload handling, context-aware suggestions, and richer documentation.
|
||||
|
||||
## Context
|
||||
|
||||
The current LSP announces completion with trigger character '.' and returns detail/documentation for resolved compiler candidates. It does not use resolveProvider, snippets, broad trigger contexts, or advanced ranking.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Which completion contexts should be supported first beyond member access?
|
||||
- [ ] Should completion use resolveProvider for expensive documentation/details or return everything eagerly?
|
||||
- [ ] How should overloads, snippets, imports, keywords, and stdlib candidates be ranked?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Eager rich completion
|
||||
|
||||
- **Approach:** Return labels, details, docs, and snippets directly in every completion response.
|
||||
- **Pro:** Simple client behavior and immediate docs.
|
||||
- **Con:** Can become expensive for broad/global completion.
|
||||
- **Maintainability:** Good while candidate sets remain small.
|
||||
|
||||
### Option B - Completion resolve provider
|
||||
|
||||
- **Approach:** Return lightweight candidates first and populate expensive docs/details through `completionItem/resolve`.
|
||||
- **Pro:** Scales better for large candidate sets and import-aware suggestions.
|
||||
- **Con:** Requires client/server resolve plumbing and stable candidate identities.
|
||||
- **Maintainability:** Strong for a full LSP.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
The current eager model is fine for scoped completions, but global/import-aware completion may need resolve to avoid latency.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer a staged approach: keep eager for current contexts, design resolve before broad workspace/import completion.
|
||||
|
||||
## Discussion
|
||||
|
||||
Define completion contexts and ranking before adding snippets or resolve.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
List first-wave completion contexts beyond member access.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0053
|
||||
ticket: pbs-lsp-folding-and-selection-ranges
|
||||
title: PBS LSP Folding and Selection Ranges
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, folding, selection-range]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS users do not get structural folding or smart selection ranges, so navigating and selecting nested functions, blocks, services, attributes, and Doc text blocks is more manual than it should be.
|
||||
|
||||
## Context
|
||||
|
||||
The parser knows syntactic spans for declarations and blocks. The LSP currently does not announce foldingRangeProvider or selectionRangeProvider.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should folding ranges be computed from AST spans, token pairs, or a hybrid that handles malformed files?
|
||||
- [ ] Which constructs should fold in the first wave: imports, declarations, blocks, attributes, text blocks, or all of them?
|
||||
- [ ] What selection range hierarchy should VS Code expose for identifiers, calls, params, blocks, and declarations?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Parser span ranges
|
||||
|
||||
- **Approach:** Use AST spans for declarations, blocks, parameter lists, and text blocks.
|
||||
- **Pro:** Accurate for well-formed code and easy to map to LSP ranges.
|
||||
- **Con:** Can degrade when parsing fails mid-file.
|
||||
- **Maintainability:** Good because parser owns structure.
|
||||
|
||||
### Option B - Token pair scanning
|
||||
|
||||
- **Approach:** Compute ranges from brace/paren/text-block tokens without relying on full AST validity.
|
||||
- **Pro:** More resilient during malformed edits.
|
||||
- **Con:** Less semantically meaningful and can produce noisy ranges.
|
||||
- **Maintainability:** Good only as fallback.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Folding and selection should keep working while typing. AST ranges are higher quality, but token fallback may be needed for broken files.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer a hybrid: AST ranges first, token fallback for unmatched/incomplete constructs.
|
||||
|
||||
## Discussion
|
||||
|
||||
This is an editor UX feature with low semantic dependency and can be planned independently.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide first-wave foldable constructs and selection hierarchy.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0054
|
||||
ticket: pbs-lsp-diagnostics-ux
|
||||
title: PBS LSP Diagnostics UX
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, diagnostics, ux]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS diagnostics reach VS Code, but the editor experience can still be hard to act on when ranges, related information, severity, and phase context are too generic.
|
||||
|
||||
## Context
|
||||
|
||||
The LSP maps compiler diagnostics to LSP diagnostics. Compiler diagnostics include phase/code/message/range in several paths, but not all editor-friendly fields are consistently exposed.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Which diagnostics need better ranges or related information first?
|
||||
- [ ] Should diagnostic source include compiler phase, frontend, or both?
|
||||
- [ ] What structured diagnostic metadata is needed for future quick fixes without coupling UI to text messages?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Mapper-only UX improvements
|
||||
|
||||
- **Approach:** Improve LSP diagnostic mapping using existing diagnostic fields.
|
||||
- **Pro:** Quick improvements to source, severity, and display consistency.
|
||||
- **Con:** Cannot add missing related spans or repair metadata that compiler diagnostics do not expose.
|
||||
- **Maintainability:** Good for presentation-only changes.
|
||||
|
||||
### Option B - Structured diagnostic contract
|
||||
|
||||
- **Approach:** Extend compiler diagnostics with editor-facing metadata such as phase, related locations, stable quick-fix hints, and refined ranges.
|
||||
- **Pro:** Enables better diagnostics and future code actions without parsing message text.
|
||||
- **Con:** Requires compiler/core diagnostic API changes.
|
||||
- **Maintainability:** Strong as the foundation for quick fixes and richer UX.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Some improvements belong in the LSP mapper, but the most valuable changes require structured information at diagnostic creation time.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option B as the target, with mapper-only cleanup allowed for low-risk display fixes.
|
||||
|
||||
## Discussion
|
||||
|
||||
This agenda should inform code actions before quick fixes become broad.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Inventory high-frequency diagnostics and identify which need better ranges, related information, or repair hints.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0055
|
||||
ticket: pbs-lsp-document-links
|
||||
title: PBS LSP Document Links
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, document-links, imports]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS import/module references and asset-like surfaces are plain text in VS Code, so users cannot click through to imported modules or related project resources.
|
||||
|
||||
## Context
|
||||
|
||||
The compiler understands module references and project files. The LSP does not announce documentLinkProvider, and the VS Code extension delegates all language behavior to the server.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Which references should become document links first: imports, barrels, stdlib modules, assets/addressables, or docs?
|
||||
- [ ] How should virtual or stdlib resources be represented as link targets?
|
||||
- [ ] Should document links overlap with go-to-definition or remain a separate lightweight navigation feature?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Import/module links only
|
||||
|
||||
- **Approach:** Expose `documentLink` for module references such as `@sdk:gfx` and barrel paths.
|
||||
- **Pro:** Narrow, useful, and mostly aligned with existing module resolution.
|
||||
- **Con:** Does not cover assets/addressables or documentation links.
|
||||
- **Maintainability:** Strong first wave.
|
||||
|
||||
### Option B - General resource links
|
||||
|
||||
- **Approach:** Link imports, stdlib modules, assets, addressables, and possibly documentation/resource surfaces.
|
||||
- **Pro:** Richer navigation across project resources.
|
||||
- **Con:** Requires resource-specific target policy and may overlap with definition.
|
||||
- **Maintainability:** Good only after resource ownership is defined.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Document links should remain lightweight. If a link requires semantic identity and symbol resolution, it may belong in go-to-definition instead.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option A first: imports and module references only.
|
||||
|
||||
## Discussion
|
||||
|
||||
Coordinate stdlib target handling with go-to-definition.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide first-wave link targets and how stdlib/module URIs are represented.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: AGD-0056
|
||||
ticket: pbs-lsp-call-and-type-hierarchy
|
||||
title: PBS LSP Call and Type Hierarchy
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, lsp, vscode, compiler-pbs, editor, call-hierarchy, type-hierarchy]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio/lsp`
|
||||
|
||||
PBS users cannot inspect call relationships or type/member relationships from the editor, which limits understanding of larger projects after basic navigation exists.
|
||||
|
||||
## Context
|
||||
|
||||
Call hierarchy and type hierarchy are advanced LSP features. They depend on reliable semantic identity, references, callsite classification, and type ownership surfaces, so they should probably follow definition/references rather than precede them.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should call hierarchy and type hierarchy be one discussion or split after dependencies are clearer?
|
||||
- [ ] Which relationships are valuable for PBS: function call graph, service method calls, struct methods, contract implementations, host/intrinsic calls, or all of them?
|
||||
- [ ] What prerequisite symbol/reference infrastructure must be completed before this feature is safe to implement?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Call hierarchy only
|
||||
|
||||
- **Approach:** Implement incoming/outgoing calls for functions and methods after callsite references are stable.
|
||||
- **Pro:** Directly useful and builds on executable call resolution.
|
||||
- **Con:** Does not cover type ownership, contracts, or implementations.
|
||||
- **Maintainability:** Strong if based on the reference/callsite index.
|
||||
|
||||
### Option B - Split call hierarchy and type hierarchy
|
||||
|
||||
- **Approach:** Treat call graph and type/member/contract hierarchy as separate decisions and implementations.
|
||||
- **Pro:** Avoids mixing two different semantic models.
|
||||
- **Con:** Creates more workflow artifacts and sequencing work.
|
||||
- **Maintainability:** Strong; each feature can evolve on its own contract.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Call hierarchy and type hierarchy share LSP vocabulary but not the same compiler data. Coupling them too early would make the first implementation harder to reason about.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option B: split after this agenda confirms dependencies, likely implementing call hierarchy first.
|
||||
|
||||
## Discussion
|
||||
|
||||
This should wait until definition and references are complete.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Decide whether to split into two discussions before moving to decisions.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Runtime catalog support
|
||||
|
||||
Status: normative. Owner: `compiler/general`.
|
||||
|
||||
## Authority and update boundary
|
||||
|
||||
The runtime owns intrinsic identities, ABI layouts, effects, costs and builtin
|
||||
constants. Studio MUST keep byte-identical copies of the selected provider's
|
||||
`INTRINSICS.csv` and `BUILTIN_CONSTANTS.csv` under `docs/vm-arch`. The sibling
|
||||
`runtime-catalog.properties` records the provider revision and SHA-256 of both
|
||||
files. These mirrors are reference data, not an independent runtime contract.
|
||||
|
||||
An update MUST import both catalogs, inventory additions/removals and field
|
||||
changes, manually port the compiler consumers, verify behavior and update the
|
||||
packaged provenance together. A CSV-only change is not a completed integration.
|
||||
Read the selected runtime's implementation and tests when porting behavior;
|
||||
CSV fields alone do not explain dispatch, reference validation or charging.
|
||||
|
||||
Normal builds MUST use local versioned sources and resources. They MUST NOT
|
||||
query the latest runtime or depend on a sibling runtime checkout. An explicit
|
||||
provider verification command requires the recorded revision and fails when
|
||||
the source is missing, modified or different. That evidence requirement does
|
||||
not make a different runtime revision inherently incompatible.
|
||||
|
||||
## Manual intrinsic representation
|
||||
|
||||
`IRVMIntrinsicDefinition` is the explicit compiler representation of its runtime
|
||||
target. It MUST preserve every published record and field: IDs, canonical
|
||||
identity/version, owner/name, argument/result counts and layouts, determinism,
|
||||
allocation, parameter names, guest-state mutation, base/fixed cycles, cost model,
|
||||
attempt cycles and maximum attempts. `IRVMIntrinsicRegistry` resolves exact
|
||||
identities and IDs. Retired entries MUST NOT survive as aliases.
|
||||
|
||||
Lowering MUST validate caller-supplied counts against the selected definition.
|
||||
Validation and emission MUST reject unknown IDs and inconsistent signatures,
|
||||
including unknown IDs in unreachable bytecode. A name retained by the provider
|
||||
does not imply an unchanged ABI; input touch coordinates illustrate a change
|
||||
from receiver-based calls to zero-argument queries.
|
||||
|
||||
Carrier mappings MUST be explicit. Int32 and Int64 remain distinct despite equal
|
||||
slot widths. Layout order and complete groups MUST be preserved. Native color
|
||||
and Random contracts MUST NOT be inferred from arbitrary one-slot integers or
|
||||
references. Producer checks validate proven carrier facts; runtime admission
|
||||
and execution remain authoritative for reference identity, session ownership,
|
||||
platform availability and traps. Unsupported carrier tokens MUST fail explicitly.
|
||||
|
||||
Intrinsic arguments MUST use each schema-2 entry's ordered nullable mask.
|
||||
A proven null is admitted for hash.string's String slot; older String entries
|
||||
remain non-nullable. Random nullable reference admission does not remove runtime
|
||||
receiver/provenance checks. Do not infer nullable admission from carrier width,
|
||||
name, determinism or a different entry using the same ABI atom.
|
||||
|
||||
Determinism MUST NOT be interpreted as purity. In particular, all Random calls
|
||||
mutate guest state. Reachable calls cannot be removed, merged or reordered in a
|
||||
way that changes effects, traps or charged work, even when their results are
|
||||
discarded. Variable-cost descriptors MUST remain variable: `random.range` has
|
||||
base cost 4, cost 8 per attempt and a maximum of 64 attempts in the selected
|
||||
contract. The runtime performs charging; Java metadata does not implement a
|
||||
second scheduler or random algorithm.
|
||||
|
||||
## Schema 2 invocation and cost metadata
|
||||
|
||||
Every entry MUST preserve all 25 CSV columns, including schema_version=2,
|
||||
arg_nullable, invocation_model, scratch_model, context_access, cost_arg_index and
|
||||
cost_per_byte in addition to the original 18 fields. Nullable bits are lowercase
|
||||
booleans in flattened argument order, exactly one per slot; zero arguments use
|
||||
an empty mask. Numeric carriers cannot be nullable.
|
||||
|
||||
Supported coherent profiles are host_buffered_v1/existing_contract_v1/host,
|
||||
vm_owned_v1/existing_contract_v1/vm_state and borrowed_inline_v1/none/none.
|
||||
The borrowed profile requires its separately declared deterministic/nonallocating/
|
||||
nonmutating effects; existing Host/VM entries do not acquire borrowed semantics.
|
||||
Unsupported schemas, models, profiles and incoherent layouts, masks, indices or
|
||||
cost parameters MUST fail explicitly.
|
||||
|
||||
Fixed costs have no argument index, zero per-byte/attempt cost and zero attempts.
|
||||
random_rejection_v1 retains base 4, attempt cost 8 and at most 64 draws with the
|
||||
VM-owned profile. argument_utf8_bytes_v1 selects String argument zero with the
|
||||
borrowed profile, base 8, one cycle per UTF-8 byte and zero attempt fields. Empty
|
||||
or null String costs base 8 and remains subject to that entry's nullable mask.
|
||||
No consumer-side scheduler or hash implementation is added by importing metadata.
|
||||
All 108 provider entries, including hash.i64/hash.float/hash.string, are represented;
|
||||
metadata parity does not declare PBS hashing facades delivered.
|
||||
|
||||
## Constants
|
||||
|
||||
Builtin constants have their own lookup identity `(target, name, version)` and
|
||||
ordered slot values. They MUST NOT be resolved by inventing an intrinsic with
|
||||
the same name. Some color names have both a constant and a separately published
|
||||
intrinsic; this does not establish a generic equivalence.
|
||||
|
||||
The manual constant representation MUST preserve all carriers and exact values.
|
||||
Float constants are materialized from published IEEE-754 bits. `vec2.zero` is
|
||||
two ordered Float slots and has no intrinsic ID. Materialization and emission
|
||||
MUST preserve the whole group; source-language exposure remains frontend-owned.
|
||||
|
||||
## Distribution and conformance
|
||||
|
||||
The compiler JAR packages the two catalogs and provenance at
|
||||
`runtime-catalog/compiler/`; the PBS SDK JAR packages the same three files at
|
||||
`runtime-catalog/pbs-sdk/`. Both copies MUST derive from the checked-in mirrors
|
||||
and agree byte-for-byte. The metadata identifies the represented target contract;
|
||||
it does not assert that every catalog entry already has a PBS facade.
|
||||
|
||||
Normal tests MUST compare every manually maintained field with the independently
|
||||
published CSV, verify constant bits/groups and check packaged hashes. They MUST
|
||||
run without a runtime checkout and MUST NOT be disabled or silently skip parity.
|
||||
Explicit provider checks also run the real runtime catalog exporter test;
|
||||
parsing only one Rust table is insufficient because the catalog spans several
|
||||
implementation modules.
|
||||
|
||||
Behavioral tests MUST cover changed signatures, retired IDs, scalar carriers,
|
||||
complete groups, stateful call order and emitted values. Evidence from the
|
||||
selected runtime MUST identify revision, platform and configuration and distinguish
|
||||
catalog comparison, image loading and execution. PBS facade delivery and
|
||||
installed-runtime qualification remain separate consumer claims.
|
||||
|
||||
See [typed common Registry and PBX v0](typed-registry-and-pbx-v0.md) for the
|
||||
frontend/backend boundary and [mirror policy](../../../vm-arch/README.md) for
|
||||
explicit verification commands.
|
||||
|
||||
|
||||
## PBS consumer
|
||||
|
||||
The [PBS input and value alignment contract](../../pbs/specs/input-and-existing-type-runtime-alignment.md)
|
||||
requires typed Pad/Button dispatch, direct LowPad endpoints and complete builtin
|
||||
value groups. Frontend numeric literal and builtin-constant operations retain
|
||||
explicit identity and width; common lowering resolves constant groups against
|
||||
`IRVMBuiltinConstantDefinition` and checks the declared result width. PBS does
|
||||
not introduce another catalog. Source execution and the full installed example
|
||||
are separate consumer gates beyond CSV parity.
|
||||
@@ -0,0 +1,253 @@
|
||||
# Typed common Registry and PBX v0
|
||||
|
||||
Status: normative. Owner: `compiler/general`. Runtime contract reference:
|
||||
`runtime` revision `d9b9eeb171d2861ec660d4cf5703b0795eac49a9`,
|
||||
`docs/specs/runtime/02c-program-registry-and-pbx-v0.md` and
|
||||
`docs/vm-arch/ISA_CORE.md` in that repository.
|
||||
|
||||
## Ownership and handoff
|
||||
|
||||
Every executable frontend MUST provide its semantic types through the common
|
||||
`IRRegistry` model and typed `FunctionMetadata`. The backend MUST NOT inspect
|
||||
language ASTs, PBS names, Optional/Result syntax, or frontend-specific classes.
|
||||
Language carriers and their lowering remain owned by the frontend. A carrier
|
||||
can use ordinary Struct, Array, Trait, Fn and Builtin declarations without
|
||||
introducing a language category in the backend.
|
||||
|
||||
The public model consists of immutable values and ordered `ReadOnlyList`
|
||||
collections. References use explicit declaration keys and callable IDs, not
|
||||
object identity or recursive object graphs. It is serializable by design;
|
||||
no concrete IR codec, wire format or persistence protocol is selected.
|
||||
|
||||
A function declares ordered named parameters, ordered logical results, ordered
|
||||
captures, a lifecycle role and an optional name. Empty names differ from absent
|
||||
names. Captures are an environment, never hidden parameters. Slot counts are
|
||||
derived from types; existing count fields are checked caches, not semantic
|
||||
input. Missing nonempty type metadata is an invalid handoff, not a request to
|
||||
infer types from counts. Optimizers MUST preserve metadata and typed operands.
|
||||
|
||||
## Identity and linking
|
||||
|
||||
TypeId, FunctionId and ImplementationId are separate dense image-local index
|
||||
domains. Index zero is valid. Trait references use TypeIds; field and method
|
||||
indices are local to their owner. Source declaration keys MUST identify the
|
||||
same declaration across repeated module imports and distinguish unrelated
|
||||
nominal declarations, even when names and shapes coincide.
|
||||
|
||||
Linking is deterministic. The selected physical entry is FunctionId zero;
|
||||
remaining functions follow canonical module/callable/source ordering. Struct
|
||||
and Trait retain nominal identity. Builtin imports deduplicate by BuiltinId,
|
||||
Array by canonical element identity, and Fn by ordered parameter/result type
|
||||
identities, excluding names. Forward references and recursion through nominal
|
||||
anchors are valid. Pure Array/Fn cycles are invalid. Every reference must
|
||||
resolve before emission. Frontends should supply only used imports.
|
||||
|
||||
File-local global slots MUST be relocated to unique image-wide slots when common
|
||||
IR files are merged. Every GET_GLOBAL and SET_GLOBAL operand must use the same
|
||||
relocation as its declaration. Lifecycle assembly preserves those linked slots
|
||||
and allocates its initialization guard after all existing image globals. Module
|
||||
boundaries do not create separate runtime global namespaces.
|
||||
|
||||
| BuiltinId | Type | Slots |
|
||||
| --- | --- | --- |
|
||||
| `0x0001` | color | 1 |
|
||||
| `0x0002` | vec2 | 2 |
|
||||
| `0x0003` | pixel | 3 |
|
||||
| `0x0010` | Int32 | 1 |
|
||||
| `0x0011` | Int64 | 1 |
|
||||
| `0x0012` | Float | 1 |
|
||||
| `0x0013` | Bool | 1 |
|
||||
| `0x0014` | String | 1 |
|
||||
| `0x0015` | Dynamic | 2 |
|
||||
| `0x0016` | Random | 1 |
|
||||
|
||||
The retired input IDs `0x0100`–`0x0102` have no aliases. Struct, Array and Fn
|
||||
values occupy one reference slot; Trait values occupy two slots. Width does
|
||||
not establish type identity or authorize conversion.
|
||||
|
||||
## Binary contract
|
||||
|
||||
All fields are little-endian. The header is 32 bytes: `PBX\0`, u16 version zero,
|
||||
zero endian/reserved bytes, u32 section count and twenty zero reserved bytes.
|
||||
Directory entries are u32 kind, file-relative offset and length. Ranges must
|
||||
not overlap or overflow. The version remains zero; no legacy fallback exists.
|
||||
|
||||
Mandatory sections are constants (0), functions (1), Code (2), exports (4),
|
||||
syscalls (5), types (6), implementations (7) and captures (8). Debug (3) is
|
||||
optional. Empty tables contain a u32 zero count. Code is raw bytes, not a
|
||||
counted table. An empty table set is serializable but is not an executable
|
||||
program: production loading requires a valid ordinary entry.
|
||||
|
||||
Lists have u32 counts. Optional names use u8 presence 0/1, then u32 UTF-8 byte
|
||||
length and bytes when present. UTF-8 is strict. Named types contain TypeId then
|
||||
optional name; results and captures contain TypeIds without names.
|
||||
|
||||
| Record | Ordered payload |
|
||||
| --- | --- |
|
||||
| Type | u8 tag, optional name, category payload |
|
||||
| Builtin (tag 0) | u32 BuiltinId |
|
||||
| Struct (tag 1) | named fields |
|
||||
| Array (tag 2) | u32 element TypeId |
|
||||
| Trait (tag 3) | methods: optional name, parameters, results |
|
||||
| Fn (tag 4) | parameters, results |
|
||||
| Function | u8 role, optional name, parameters, results, u32 Code offset, length, extra locals, max temporaries |
|
||||
| Implementation | u32 owner TypeId, trait TypeId, method count, ordered FunctionIds |
|
||||
| Captures | function count and one ordered TypeId list per function, including empty lists |
|
||||
|
||||
Function Code offsets are Code-relative. Parameter/result slot counts MUST NOT
|
||||
be serialized. Max temporaries zero means zero. Signature names are independent
|
||||
of debug names. Constants retain tags Null 0, Int64 1, Float64 2, Boolean 3,
|
||||
String 4 and Int32 5. Float payloads must be finite. Constant deduplication
|
||||
requires relocating every PUSH_CONST index; changing only the table is invalid.
|
||||
|
||||
Roles are None 0, BeforePause 1, BeforeResume 2 and MemcardBoot 3. Nonzero roles
|
||||
are unique, cannot target entry zero and cannot capture. Pause/resume have empty
|
||||
signatures; MemcardBoot has `(Int64) -> Int32`. This metadata does not implement
|
||||
frontend hook selection, mem.bootstrap gating or persistence.
|
||||
|
||||
Implementations are unique per Struct/Trait pair, complete and ordered. Each
|
||||
method target has an exact signature with a concrete Struct receiver first,
|
||||
followed by the trait method's explicit parameters. Targets cannot capture.
|
||||
|
||||
## Instructions and verification
|
||||
|
||||
Instructions use u16 opcodes. Jump operands are absolute u32 byte offsets from
|
||||
the current function start, not displacements from the next instruction.
|
||||
A taken jump to the current function end is a return boundary; ordinary
|
||||
fallthrough past the end is invalid.
|
||||
|
||||
| Opcode | Typed operands |
|
||||
| --- | --- |
|
||||
| MAKE_CLOSURE `0x52` | FunctionId, Fn TypeId |
|
||||
| CALL_CLOSURE `0x53` | expected Fn TypeId |
|
||||
| GET_CAPTURE `0x57` | capture group index |
|
||||
| CALL_TRAIT `0x58` | Trait TypeId, method index |
|
||||
| DYN_PACK/UNPACK/CAN_UNPACK `0x90`–`0x92` | TypeId |
|
||||
| Reference operations `0x93`–`0x96` | source TypeId, target TypeId |
|
||||
| STRUCT_NEW `0xa0` | Struct TypeId |
|
||||
| STRUCT_GET/SET `0xa1`–`0xa2` | Struct TypeId, field index |
|
||||
| Array operations `0xa3`–`0xa6` | Array TypeId |
|
||||
|
||||
Direct CALL cannot target a capturing body. Closure signatures match exactly.
|
||||
Retired SPAWN/YIELD/SLEEP (`0x54`–`0x56`) and raw producer SYSCALL are invalid,
|
||||
even when unreachable. All function ranges must decode completely; references,
|
||||
categories, operand boundaries, finite immediates and branch destinations are
|
||||
checked even in unreachable instructions.
|
||||
|
||||
Reachable analysis uses a bounded worklist. Parameters initialize local facts;
|
||||
extra locals start Null and may change type. Joins require equal temporary
|
||||
heights. Equal facts survive; conflicting facts widen to Unknown. Type errors
|
||||
are diagnosed after convergence. Unknown alone neither proves compatibility
|
||||
nor justifies rejection. Runtime group checks remain authoritative. RET and
|
||||
jump-to-end require exact result width and compatible known facts. GET/SET_LOCAL
|
||||
address only parameters plus extra locals. No implicit numeric, trait or Dynamic
|
||||
conversion is introduced by linking, writing or verification.
|
||||
|
||||
HOSTCALL references a declared canonical `(module, name, version)` identity
|
||||
with exact argument/result slot ABI. Duplicate identities with conflicting ABI,
|
||||
unused declarations and invalid indices are rejected. Only the runtime loader
|
||||
binds capabilities and rewrites HOSTCALL to SYSCALL. Intrinsic signatures are
|
||||
explicit compiler metadata; their IDs and definitive ABI remain runtime-owned.
|
||||
|
||||
## Bounds and diagnostics
|
||||
|
||||
Product ceilings: PBX 64 MiB, Code 32 MiB, 65,536 types and functions each,
|
||||
262,144 implementations, 1,048,576 nested records, names 4,096 bytes individually
|
||||
and 4 MiB aggregate, frame 16,384 slots and results 1,024 slots. Runtime admission
|
||||
also owns retained Registry 64 MiB, scratch 128 MiB and work 268,435,456. A guest
|
||||
cannot raise these limits. Java validation is not a substitute for runtime
|
||||
allocation accounting or final `ValidatedProgramImage::load` admission.
|
||||
|
||||
Compilation failures use common LOWER_IRVM/MARSHAL stage diagnostics. Load,
|
||||
binding and resource failures remain distinct from executed traps. Studio
|
||||
preserves the full runtime error envelope in `AutomationFailure.runtimeError`,
|
||||
including null fields and native binding details. The outer initialization
|
||||
fault PC remains null. A verifier PC stays in `initError.load.pc`; a file offset
|
||||
MUST NOT become an executed PC.
|
||||
|
||||
## Reproducible conformance
|
||||
|
||||
Run the focused common tests, then the production harness:
|
||||
|
||||
```sh
|
||||
./gradlew :prometeu-compiler:prometeu-build-pipeline:test --tests '*LinkedRegistryTest' --tests '*PbxRegistryConformanceTest' --tests '*TypedCommonPipelineTest'
|
||||
python3 tools/pbx-conformance/run.py --runtime ../runtime
|
||||
```
|
||||
|
||||
The Java tests write `build/registry-conformance` inside the build-pipeline
|
||||
module. The harness builds outside the runtime checkout using its Cargo.lock,
|
||||
loads Java-produced bytes, executes admitted zero-argument fixtures, validates
|
||||
structured failures against the published schema and records the runtime hash,
|
||||
platform, capabilities and limits. Parsing, loading and execution are separate
|
||||
claims. The vec2 signature fixture is load-only; it is not a zero-argument boot.
|
||||
|
||||
The fixed 194-byte minimal image comes from the independent runtime test oracle.
|
||||
Synthetic common IR additionally exercises linking, lowering, optimization and
|
||||
emission without PBS. Frontend migration and integrated release readiness are
|
||||
tracked separately in AGD75; passing common conformance does not claim complete
|
||||
PBS lowering or complete Studio/runtime integration.
|
||||
|
||||
|
||||
## Minimal typed storage and range copy
|
||||
|
||||
The supported collection storage operations are STRUCT_NEW/GET/SET (0xA0–0xA2),
|
||||
ARRAY_NEW/LEN/GET/SET (0xA3–0xA6) and ARRAY_COPY (0xA9). Logical bounds and
|
||||
multi-owner collection algorithms belong to producers. Encodings 0xA7, 0xA8,
|
||||
0xAA and 0xAB MUST be rejected at actual instruction positions, including dead
|
||||
code; identical bytes in immediates or data are not opcodes. No guard, publication
|
||||
schema, batch transaction or atomic region replaces the retired instructions.
|
||||
|
||||
ARRAY_COPY encodes u16 LE 0xA9 followed by Array TypeId u32 LE. Its five operands,
|
||||
bottom to top, are source, sourceStart, target, targetStart and count, with no
|
||||
result. Receivers MUST match the exact Array descriptor; offsets/count MUST use
|
||||
Int64. Ranges are physical, nonnegative and strict; an empty range may start at
|
||||
length. Snapshot source groups before writing for overlap. Preserve complete
|
||||
presence tags, immutable boxes, native owners and identities without unpacking
|
||||
and repacking existing values.
|
||||
|
||||
Reserve the complete TemporaryBytes scratch before writing and release it on
|
||||
success or failure. A refused instruction preserves its own operands, complete
|
||||
destinations and owners. No callback, GC or scheduler interleaves its preparation
|
||||
and commit. This guarantee covers that instruction only, not earlier instructions
|
||||
in a source method.
|
||||
|
||||
For N=count and Registry-derived element width W, attempted work is C=4+2*N*W.
|
||||
With five temporary operands and exact Int64 N in 0..u32::MAX, precharge the whole
|
||||
representable C before receiver/range/group/scratch validation and retain it on
|
||||
refusal. Underflow, wrong count carrier or count outside that interval costs base
|
||||
4 and follows ordinary fault precedence, without reading frame locals or
|
||||
converting N. Checked C overflow costs 4 and raises SizeOverflow before ordinary
|
||||
validation. Above-u32 N is not automatically an allocation SizeOverflow.
|
||||
|
||||
Otherwise fault order is height, source, target, offset/count carriers in source
|
||||
order, source range, target range, scratch reservation, source groups in order.
|
||||
N=0 still validates receivers/ranges and costs 4; aliases give no discount.
|
||||
N=10/W=1 costs 24 on success or receiver/range/scratch refusal. Zero budget does
|
||||
nothing; positive budget admits the full instruction with overshoot. A failed
|
||||
attempt reports Trap rather than BudgetExhausted and is not a successful step.
|
||||
Optimizers MUST NOT erase empty-copy validation, faults or required charged work.
|
||||
|
||||
## Neutral terminal failure and producer mutation boundaries
|
||||
|
||||
Common executable IR and IRVM represent existing TRAP (0x05) as a zero-operand,
|
||||
zero-result block terminator, preserving its source span. It raises
|
||||
TRAP_EXPLICIT, distinct from a debugger breakpoint. It neither returns nor falls
|
||||
through, and optimization MUST retain its observable failure. There is no new
|
||||
runtime opcode or encoded error argument.
|
||||
|
||||
Source producers implement logical checks with comparisons and branches. A
|
||||
trusted private PBS SDK failure binding selects this terminal instruction, not
|
||||
a backend-implemented bounds algorithm. Physical ARRAY operations retain their
|
||||
own faults/resource context. Per-instruction cycle costs and real emitted work
|
||||
apply; the retired guard costs are not simulated.
|
||||
|
||||
Collection methods prepare bounds, next sizes, values, candidates and optional
|
||||
results before the first visible mutation. A refusal before that boundary MUST
|
||||
preserve the previous collection. A fault after it may leave earlier writes and
|
||||
incomplete collection invariants; no whole-method rollback, retry or safe-reuse
|
||||
guarantee exists. Successful methods MUST restore all published invariants.
|
||||
Prepare-before-mutation does not prove every later operand/call/store infallible.
|
||||
BudgetExhausted and debugger pauses can occur between instructions and resume at
|
||||
the current PC; they neither roll back nor complete a method. No atomic observation
|
||||
of source operations by host/debugger is promised. SDK methods introduce no user
|
||||
callbacks or explicit suspension during the updates that complete their invariants.
|
||||
@@ -0,0 +1,89 @@
|
||||
# First-class functions and explicit value captures
|
||||
|
||||
Owner: `compiler/pbs`. This specification defines PBS function values and closures. Runtime Registry/PBX layout, allocation, GC, resource limits and faults remain governed by the runtime contracts. It supersedes the retired nominal callback and `bind` model.
|
||||
|
||||
## Types and calls
|
||||
|
||||
`Fn(T1, T2) -> R` is a structural function type. Its identity is the ordered logical parameter and result types, excluding parameter names, target identity and captures. Named functions and lambdas with the same signature have the same function type. Incompatible signatures do not convert implicitly. Physical slot count alone is not a type identity.
|
||||
|
||||
A function value can be assigned, passed, returned and stored in a collection or object. A named top-level function is referenced by its identifier without an address operator. When overloaded, its expected function type must select exactly one compatible overload. Calls use ordinary parentheses.
|
||||
|
||||
```pbs
|
||||
fn twice(value: int) -> int { return value * 2; }
|
||||
fn invoke(value: int, transform: Fn(int) -> int) -> int {
|
||||
return transform(value);
|
||||
}
|
||||
fn example() -> int {
|
||||
let transform: Fn(int) -> int = twice;
|
||||
return invoke(21, transform);
|
||||
}
|
||||
```
|
||||
|
||||
Function-returning functions use `-> Fn(int) -> int`. Function array elements use grouping, for example `array<(Fn(int) -> int)>`. Existing array vacancy and optional-read rules apply; accessing an empty slot does not fabricate a callable.
|
||||
|
||||
## Lambdas
|
||||
|
||||
The sole lambda form is `fn [captures](parameter: Type) -> Return { body }`. The capture list is mandatory, including `[]` for no captures. Parameter types and return type are explicit. The body is a block and values use explicit `return`; a trailing expression is not an implicit return. The initialized variable's type may be inferred from the lambda signature.
|
||||
|
||||
```pbs
|
||||
fn createMultiplier(factor: int) -> Fn(int) -> int {
|
||||
return fn [factor](value: int) -> int { return value * factor; };
|
||||
}
|
||||
```
|
||||
|
||||
A lambda may only access outer local bindings through its explicit capture list. Capture entries name unique available outer bindings. Parameters and local declarations have their ordinary lexical scopes. Captures are not hidden public parameters and do not affect the public Fn signature.
|
||||
|
||||
## Snapshot capture and object identity
|
||||
|
||||
Each capture fixes the binding's value when the closure is created. This includes mutable outer bindings: later assignment to the outer binding does not modify the capture. Assigning to a captured binding inside the closure is invalid. There are no automatic captures, reference captures or implicit shared cells for local variables.
|
||||
|
||||
```pbs
|
||||
fn snapshot() -> int {
|
||||
let bonus = 5;
|
||||
let add = fn [bonus](value: int) -> int { return value + bonus; };
|
||||
bonus = 20;
|
||||
return add(10); // 15
|
||||
}
|
||||
```
|
||||
|
||||
Capturing an object reference preserves that reference's identity; it does not deep-copy the object. Field mutation remains governed by the object's field access rules. Closures sharing the same object observe its mutations. Separate object instances retain separate state. Adapting a method to Fn requires an explicit lambda capturing its receiver; bare method extraction is not introduced.
|
||||
|
||||
```pbs
|
||||
declare struct Counter(pub mut value: int);
|
||||
fn createCounter() -> Fn() -> int {
|
||||
let counter = new Counter(0);
|
||||
return fn [counter]() -> int {
|
||||
counter.value += 1;
|
||||
return counter.value;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Object lifetime and frame execution
|
||||
|
||||
Closures are managed objects. They may escape their creator and remain reachable through globals, fields, arrays or other captures across frames. The GC traces their captures; unreachable closures and environments are collectible under the ordinary runtime contract.
|
||||
|
||||
An invocation runs to completion within its logical frame. PBS offers no coroutine, suspension/resumption construct or `sync` syntax. The existing frontend publishes FRAME_ROOT and the existing lifecycle assembler creates the guarded frame wrapper. This feature must reuse that lifecycle without adding an alternative frame loop or synthetic integration. Retaining a closure object across frames is different from retaining a suspended invocation.
|
||||
|
||||
## Lowering and validation
|
||||
|
||||
The frontend emits typed Fn descriptors and capture metadata, MAKE_CLOSURE, GET_CAPTURE and CALL_CLOSURE through the common IR. Named function values also use runtime Closure objects with empty captures. Captured multi-slot groups and function parameters/results must remain complete. Nested invocations use their own environments. Receiver adapters preserve receiver identity and contract dispatch order.
|
||||
|
||||
Function creation and calls remain subject to existing resource checks and runtime faults. No quota relaxation, allocation rescue GC, automatic scheduler or special fault isolation is introduced.
|
||||
|
||||
`declare callback`, callback barrel exports and `bind(context, function)` are retired source forms and must be rejected. Existing programs and examples must use structural Fn and explicit lambdas. Historical provenance and negative tests may mention the removed forms.
|
||||
|
||||
Conformance must compile actual PBS through production PBX and execute it in the production VM. Required cases include signature errors, explicit capture enforcement, snapshots, escaped closures, shared and isolated objects, collection transport, nested closures and function captures, receiver/contract integration, and reachable/unreachable closure behavior across the existing frame lifecycle and GC. Installed knowledge must package this specification and a compilable example.
|
||||
|
||||
See [Runtime Random integration](runtime-random-integration.md) for opaque generator aliases in typed storage and captures.
|
||||
|
||||
|
||||
## Parameterized contract integration
|
||||
|
||||
[Generic contracts](generic-contracts.md) extend nominal contract declarations with explicit type arguments. Valid Array/Fn/optional/tuple compositions preserve their existing logical and physical rules after substitution. No generic-only Dynamic transport, view wrapper, altered resource limit or new runtime opcode is introduced.
|
||||
|
||||
[Generic structs and free functions](generic-structs-and-free-functions.md) extend
|
||||
that concrete model to state and bodies. A closed free-function application such
|
||||
as `identity<int>` supplies an ordinary concrete Fn through an empty-environment
|
||||
Closure. Lambdas inside specialized bodies preserve explicit captures and complete
|
||||
logical value groups. The open template never becomes a polymorphic Fn value.
|
||||
@@ -0,0 +1,74 @@
|
||||
# PBS Generic Contracts
|
||||
|
||||
Owner: `compiler/pbs`. This specification extends nominal contracts with explicit type parameters. Registry, PBX, instruction, ownership and resource contracts remain governed by the runtime provider. Collections and object-identity hashing are separate consumers.
|
||||
|
||||
## Declaration and application
|
||||
|
||||
```pbs
|
||||
declare contract Identity<T> {
|
||||
fn hash(e: T) -> int;
|
||||
fn equals(a: T, b: T) -> bool;
|
||||
}
|
||||
|
||||
declare contract Converter<A, B> {
|
||||
fn convert(value: A) -> B;
|
||||
}
|
||||
```
|
||||
|
||||
A parameterized declaration has one or more distinct ordered type parameters. Their scope is the contract's signatures, including nested type references. A type parameter is not the receiver. `Self` retains its existing meaning and validity restrictions.
|
||||
|
||||
Applications supply explicit ordered type arguments with exact arity: `Identity<int>` and `Converter<Enemy, str>`. The declaration's raw name, omitted arguments, `<>`, default arguments and blanket generic implementations are not value types or inference mechanisms. Nonparameterized contracts remain valid. [Generic structs and free functions](generic-structs-and-free-functions.md) add restricted owner-bound implementation families; they do not introduce blanket implementations for arbitrary owners.
|
||||
|
||||
The same compositional type grammar applies in annotations, nested applications, implementation targets and expression-form `as`. Existing contextual angle closers and expression comparisons retain their meanings. A barrel exports the declaration, for example `pub contract Identity<T>;`, preserving its origin and ordered parameters rather than exporting a particular application.
|
||||
|
||||
## Identity and compatibility
|
||||
|
||||
An application's identity is the defining nominal contract declaration plus its ordered canonical logical argument identities. Import aliases resolve before this identity is formed. If `Opponent` aliases the same `Enemy` declaration, `Identity<Opponent>` and `Identity<Enemy>` are identical. Equal names, method shapes or physical layouts do not merge different declarations or applications. Phantom arguments still distinguish applications.
|
||||
|
||||
Applications are invariant. A conversion between argument types does not establish a conversion between their contract applications. Existing explicit reference-view conversion can select another implementation actually supplied by the concrete receiver; it does not manufacture variance.
|
||||
|
||||
## Substitution and composition
|
||||
|
||||
Substitution traverses every type position in each signature, preserving parameter names, tuple labels, order and source provenance. It supports valid composition with existing builtins, nominal values, arrays, other applied contracts, Fn, optional and named tuples. Each resulting position remains subject to the existing type, return, optional/result and storage rules; substitution does not legalize an otherwise invalid position.
|
||||
|
||||
Normalize substituted signatures before deriving physical parameter/result groups. One logical parameter can contain several physical values. A shared physical carrier does not erase logical argument identity: distinct `Identity<array<X>>` applications remain nominally distinct even when their arrays share internal storage representation.
|
||||
|
||||
## Implementations and values
|
||||
|
||||
```pbs
|
||||
declare service IntIdentity {}
|
||||
|
||||
implements Identity<int> for IntIdentity using strategy {
|
||||
fn hash(e: int) -> int { return e; }
|
||||
fn equals(a: int, b: int) -> bool { return a == b; }
|
||||
}
|
||||
|
||||
fn equalSeven() -> bool {
|
||||
let identity: Identity<int> = IntIdentity;
|
||||
return identity.equals(7, 7);
|
||||
}
|
||||
```
|
||||
|
||||
Structs and services are the supported owners. An implementation belongs to the owner's declaring module and follows existing visibility rules. Implementations are complete and unique per `(owner, instantiated contract)`. One owner may implement several applications of the same contract. Implementation/callable identities include the full application, preventing collisions between those methods. Contract methods are not injected into the direct method namespace of their owner.
|
||||
|
||||
Named service singletons and constructed struct values supply strategies. Contextual assignments, arguments and returns, and explicit `value as Identity<int>`, select the concrete implementation. Conversion preserves the receiver and selected implementation without allocating an adapter wrapper or duplicating a singleton. Associated members such as `Enemy.identity` are not introduced.
|
||||
|
||||
## Recursion and bounded analysis
|
||||
|
||||
Register a nominal application anchor before expanding its signatures. A recurrence to an existing key forms a finite graph and is valid within existing resource limits. An application family that continually introduces new arguments, such as `Growing<T>` returning `Growing<array<T>>`, must be rejected with a clear expansion diagnostic.
|
||||
|
||||
Expansion, substitution and identity processing are bounded in work, storage and depth. Resource exhaustion and nonterminating specialization must not become hangs, host stack overflows, missing-method errors or ordinary argument-mismatch diagnostics.
|
||||
|
||||
## Execution and tooling
|
||||
|
||||
The frontend emits a concrete nominal Trait descriptor for each distinct required application, sharing the descriptor for equivalent uses across modules. Open type parameters do not reach executable signatures. Implementation functions receive the concrete owner first, followed by complete substituted argument/result groups.
|
||||
|
||||
Existing Registry/PBX and `REF_TO_TRAIT`/`CALL_TRAIT` mechanisms execute these records. Preserve typed absence, valid ImplementationId zero, receiver identity, rooting, GC, native ownership and quotas. Generic calls do not introduce a Dynamic argument ABI or boxing merely because an argument was a type parameter. Existing storage-specific packing remains governed by that storage's contract.
|
||||
|
||||
Navigation reaches generic declarations, parameters and argument declarations. Hover, completion and signature help show instantiated signatures with canonical source names. Arity, unresolved parameters, invalid applications/coercions, incomplete or duplicate implementations and expansion failures have localized diagnostics. Compilation and editor projections share the same type resolution.
|
||||
|
||||
## Conformance
|
||||
|
||||
Compile real PBS through typed IR and production PBX into the production loader, verifier and VM. Cover multiple parameters/applications, several applications on one owner, imports/aliases/reexports, nominal origin, phantom arguments, composed and multi-slot payloads, finite recursion, expanding recursion rejection, service/struct views, typed absence, implementation zero, GC and resource refusal.
|
||||
|
||||
A specialized contract and a manually written concrete equivalent must exhibit the same behavior without generic-only adaptation/boxing. Identical image bytes and a performance improvement are not required. Installed knowledge packages this specification and a runnable source example. Generic structs/functions are defined by the separate [owner specification](generic-structs-and-free-functions.md), sharing canonical identities, provenance and bounded expansion with contracts. Bounds, variance, inheritance/default methods, generic reflection, runtime instantiation and collection algorithms remain outside these extensions.
|
||||
@@ -0,0 +1,271 @@
|
||||
# Concrete Generic Structs and Free Functions
|
||||
|
||||
Owner: `compiler/pbs`. This specification adds parameterized state and executable
|
||||
bodies to the nominal, concrete application model of generic contracts. It applies
|
||||
uniformly to SDK modules and program sources. Registry, PBX, VM admission, resource
|
||||
limits and instruction semantics remain governed by the existing provider contracts.
|
||||
|
||||
## Declarations and identity
|
||||
|
||||
Structs and module-level named free functions may declare one or more distinct,
|
||||
ordered type parameters. Applications have exact arity. Type parameters have
|
||||
identity by declaration or binder and ordinal position; their spelling is lexical
|
||||
presentation, not a globally substitutable symbol.
|
||||
|
||||
```pbs
|
||||
declare struct Box<T>(value: T) {
|
||||
fn get() -> T { return this.value; }
|
||||
fn set(value: T) { this.value = value; }
|
||||
}
|
||||
declare struct Pair<K, V>(key: K, value: V);
|
||||
fn identity<T>(value: T) -> T { return value; }
|
||||
```
|
||||
|
||||
An application is identified by its nominal source declaration and ordered,
|
||||
canonical logical arguments after alias resolution. Aliases and reexports of the
|
||||
same declaration share applications. Homonymous declarations from different
|
||||
origins, phantom arguments and logically different types remain distinct even
|
||||
when fields, signatures or physical carriers coincide. Applications are invariant;
|
||||
numeric or reference conversions between arguments do not convert their containers.
|
||||
Struct assignment shares the existing object reference and does not deep-copy it.
|
||||
|
||||
The raw name of a parameterized struct is not a closed type, including inside its
|
||||
own declaration. Open parameters exist only in the authorized declaration scopes
|
||||
and must not reach executable metadata.
|
||||
|
||||
## Construction and expected types
|
||||
|
||||
```pbs
|
||||
let a = new Box<int>(42);
|
||||
let b: Box<int> = new Box<>(42);
|
||||
let c: Box<int> = new Box(42);
|
||||
```
|
||||
|
||||
Explicit construction supplies its application. Diamond and omitted arguments
|
||||
require a sufficient, compatible expected application at the existing contextual
|
||||
Array positions: annotated bindings, assignments, resolved callable parameters,
|
||||
returns and value expressions with an expected type. Values do not infer type
|
||||
arguments: `let d = new Box(42);` is invalid. There is no partial inference, default
|
||||
argument or additional overload search to discover generic arguments.
|
||||
|
||||
Named constructors use the applied owner, for example `new Box<int>.make(42)`.
|
||||
Substitution preserves existing constructor selection, evaluation order, definite
|
||||
field initialization, visibility, `this` and completion rules. A parameter has no
|
||||
implicit constructor or universal default; `new T()` is invalid.
|
||||
|
||||
Every completing constructor path MUST explicitly assign every field, in ordinary
|
||||
and generic structs, including fields of opaque builtin type Random. Assignment
|
||||
in only one conditional branch or in a loop that may execute zero times is
|
||||
insufficient. Runtime reference defaults are provider behavior and do not exempt
|
||||
PBS constructors from this rule. Controlled null-provider fixtures are described
|
||||
in [Runtime Random integration](runtime-random-integration.md).
|
||||
|
||||
## Composition and symbolic capabilities
|
||||
|
||||
Arguments and substituted uses compose with valid builtins, nominal values,
|
||||
applied structs/contracts, Array, Fn, optional, tuples and existing return/result
|
||||
positions. Each position retains its existing restrictions. Normalize logical
|
||||
types before deriving physical groups, preserving labels, names, order and every
|
||||
slot of a multi-slot value.
|
||||
|
||||
Array's element restriction is not a global generic restriction. A T field can
|
||||
hold `Box<optional int>`; a field declared `array<T>` makes the application with
|
||||
T=optional int invalid. Revalidate all concrete positions after substitution.
|
||||
|
||||
Templates are validated symbolically before relying on concrete arguments. An
|
||||
unconstrained T can be stored, assigned compatibly, passed and returned. It gains
|
||||
no arithmetic, comparison, members or construction from a particular application.
|
||||
`value + value` on T is invalid even when the only requested application uses int.
|
||||
Known operations of declared containers remain available; indexing array<T>, for
|
||||
example, produces optional T. Additional capabilities require explicit composition:
|
||||
|
||||
```pbs
|
||||
declare struct ComparedBox<T>(value: T, identity: Identity<T>) {
|
||||
fn matches(other: T) -> bool {
|
||||
return this.identity.equals(this.value, other);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This does not introduce bounds, implicit equality/hash or opportunistic member
|
||||
lookup on an argument.
|
||||
|
||||
## Complete substitution, validation and Self
|
||||
|
||||
Substitute fields, constructor/method signatures and complete bodies, including
|
||||
local annotations, nested applications and constructions, references/calls,
|
||||
lambdas and capture environments. Rewriting signatures alone is insufficient.
|
||||
Ordinary methods use their owner's type parameters; they do not declare another
|
||||
generic parameter list.
|
||||
|
||||
Self denotes the complete applied owner in its existing valid locations. It means
|
||||
Box<int> inside that application and Box<Enemy> inside the other. Header fields
|
||||
must still spell recursive types explicitly, such as `optional Node<T>`; the
|
||||
feature does not expand Self's valid locations. Existing privacy, pub/pub mut,
|
||||
receiver and direct-versus-contract method rules remain unchanged.
|
||||
|
||||
For every required owner application, validate its fields, constructors and all
|
||||
methods, including uncalled methods. Dead-code elimination must not change source
|
||||
acceptance. Method/constructor identities include their source declaration,
|
||||
applied owner and existing signature identity. Distinct overloads that collapse
|
||||
after substitution reject the application and identify both declarations. In
|
||||
particular, set(T) and set(int) collide at T=int without an implicit preference.
|
||||
|
||||
## Owner-bound implementations and coherence
|
||||
|
||||
```pbs
|
||||
declare contract Reader<T> { fn read() -> T; }
|
||||
implements<T> Reader<T> for Box<T> using box {
|
||||
fn read() -> T { return box.get(); }
|
||||
}
|
||||
```
|
||||
|
||||
A parameterized implementation's owner must directly apply a declared generic
|
||||
struct. Every owner argument is a distinct binder parameter, and all binder
|
||||
parameters are bound through the owner. Binder names need not match the struct's
|
||||
parameter names. Arbitrary owners, unbound parameters, narrower patterns such as
|
||||
Box<array<T>>, and repeated arguments restricting the family are invalid.
|
||||
|
||||
The rule belongs to the owner's declaration module. Its target resolves to a
|
||||
contract and may compose the owner-bound parameters under existing type rules.
|
||||
Implementations are complete with exact substituted signatures. Emitted owners,
|
||||
targets and methods are concrete. Contract methods are not injected into the
|
||||
owner's direct namespace. Views preserve receiver, implementation and identity
|
||||
without a wrapper required by parameterization.
|
||||
|
||||
Uniqueness is by concrete (owner, contract) pair. Two declarations overlap if an
|
||||
admissible application could produce the same pair. Compare canonical nominal
|
||||
origins and arguments with symbolically owner-bound parameters. Detect
|
||||
generic/generic, generic/closed and closed/closed collisions before the conflicting
|
||||
application is used. Different contract applications for an owner remain valid
|
||||
when their pairs cannot coincide. Bounded analysis must not enumerate only used
|
||||
applications, choose file/import order, prefer closed rules or silently succeed
|
||||
after exhausting its budget.
|
||||
|
||||
## Free functions, overloads and Fn
|
||||
|
||||
References and calls provide explicit type arguments, such as identity<int>(42).
|
||||
An argument may mention a parameter in an enclosing template but must become
|
||||
concrete before emission. There is no value, result or expected-Fn inference,
|
||||
function diamond or default generic argument. `identity<>` and a polymorphic Fn
|
||||
value for open `identity` are invalid.
|
||||
|
||||
An applied function's identity includes its source declaration and ordered logical
|
||||
arguments, including phantom arguments. Equivalent uses share the application;
|
||||
different declarations remain different targets despite identical concrete
|
||||
signatures. Symbolic validation, definition scope, complete body substitution,
|
||||
normalization and bounded expansion apply to required function applications too.
|
||||
|
||||
`f<int>` considers generic free functions with matching type arity. A reference
|
||||
or call without type arguments does not select a generic template. Ordinary
|
||||
overloads remain subject to existing rules. After explicit binding, use existing
|
||||
concrete signature resolution. Consistent renaming does not create overloads:
|
||||
f<T>(value:T) and f<U>(value:U) are duplicates when otherwise signature-equivalent.
|
||||
Substituted collisions in the filtered generic candidate set are errors.
|
||||
|
||||
```pbs
|
||||
let transform: Fn(int) -> int = identity<int>;
|
||||
let answer = transform(42);
|
||||
```
|
||||
|
||||
Closed references use the existing Closure mechanism with an empty environment.
|
||||
Fn stays structural by logical parameters/results, excluding target identity,
|
||||
names and captures. Distinct targets may share a compatible Fn descriptor.
|
||||
Lambdas in specialized bodies preserve explicit capture semantics and complete
|
||||
groups. Bare method extraction remains invalid. Calls preserve canonical apply,
|
||||
existing named/positional forms, order and single evaluation.
|
||||
|
||||
## Definition scope, imports and barrels
|
||||
|
||||
Each declaration/binder has its own substitution environment. Names in a template
|
||||
body bind in its definition scope; type argument names bind at the use. Caller
|
||||
and callee parameters with the same spelling must not capture one another.
|
||||
Instantiation does not resolve private helpers in the caller or export them.
|
||||
|
||||
```pbs
|
||||
pub struct Box<T>;
|
||||
pub struct Pair<K, V>;
|
||||
pub fn identity<T>(value: T) -> T;
|
||||
```
|
||||
|
||||
Barrels export the parameterized declaration, ordered parameters and signature,
|
||||
not an enumeration of closed instances. Preserve the original definition through
|
||||
imports/aliases/reexports and make the necessary body available to the compiler
|
||||
under existing visibility rules. This does not add an open-template PBX format.
|
||||
|
||||
The application grammar extends the existing ordered type argument syntax to
|
||||
struct/free-function declarations, barrels, owner-bound implements and named
|
||||
function reference expressions. Calls continue to use ordinary parentheses/apply.
|
||||
Nested applications and adjacent closers preserve spans. Complete type-argument
|
||||
references must remain distinct from ordinary <, > and >= comparisons without
|
||||
changing their meanings or adding shifts. Malformed source retains localized
|
||||
diagnostics and recovery. Fields, ordinary Fn values and methods gain no generic
|
||||
parameter list from this grammar.
|
||||
|
||||
## Expansion, diagnostics and concrete execution
|
||||
|
||||
Share logical identity, substitution environments, provenance and bounded
|
||||
expansion infrastructure across PBS structs, functions and contracts. Keep each
|
||||
category's layout/callable rules explicit and keep PBS rules in the frontend.
|
||||
Register nominal and callable anchors before expanding dependencies. Revisiting
|
||||
the same application forms a finite graph, including cross-category field/body
|
||||
dependencies. Families requiring indefinitely new applications are diagnosed,
|
||||
including growth through uncalled methods of a used owner.
|
||||
|
||||
Analysis, normalization, substitution, coherence and materialization are bounded
|
||||
in depth, work and storage. Exhaustion must not become a hang, host stack overflow,
|
||||
misleading missing method or ordinary argument mismatch. Frontend budgets do not
|
||||
increase provider limits.
|
||||
|
||||
Errors preserve the original declaration and requesting use, with a short chain
|
||||
such as `main -> wrap<Enemy> -> Box<Enemy>`. Cover unbound/duplicate parameters,
|
||||
arity, raw/inferred application, invalid positions/capabilities, incomplete
|
||||
construction, overload collisions, invalid implementation owners/rules, overlap
|
||||
and expansion. Generated names and Java stacks do not replace source explanation.
|
||||
Navigation, references/rename, hover, completion, signature help, symbols,
|
||||
formatting and semantic tokens share compilation resolution/substitution. Distinguish
|
||||
symbolic parameter, concrete argument and generic origin, including imported code.
|
||||
|
||||
Emit only concrete Struct/Trait/Fn descriptors, callables, fields, signatures,
|
||||
capture environments and implementation functions. Preserve logical identity
|
||||
independently of storage width. Existing Struct/Array/Trait/Fn, direct calls,
|
||||
REF_TO_TRAIT/CALL_TRAIT and Closure execute the result. Preserve receiver,
|
||||
singletons where applicable, typed absence, valid ImplementationId zero, rooting,
|
||||
GC, ownership, faults, evaluation and quotas. Genericity must not impose Dynamic,
|
||||
reboxing or an adapter wrapper as its argument ABI; existing storage packing
|
||||
retains its own contract. No new opcode, PBX category or runtime instantiation
|
||||
engine is required. A provider-contract gap requires explicit decision revision.
|
||||
|
||||
## Qualification and boundaries
|
||||
|
||||
Conformance compiles real source through typed IR and production PBX into the
|
||||
production loader, verifier and VM. Cover multiple arguments/applications, origin,
|
||||
aliases/reexports/phantom identity, constructors/Self/all methods, composition and
|
||||
multi-slot groups, free functions/apply/Fn, captures, finite/expanding recursion,
|
||||
coherence, GC, ownership and quota refusal. Include negative cases for symbolic
|
||||
operations, unused invalid methods, inferred applications, alpha-equivalent
|
||||
duplicates and provenance diagnostics.
|
||||
|
||||
A complete multi-module fixture must combine Box<T>, Reader<T>, owner-bound
|
||||
implements<T>, read<T>, read<int> as Fn and imports/aliases, returning 42. Compare
|
||||
specialized structs/functions with handwritten concrete equivalents for behavior,
|
||||
identity/lifetime and absence of adaptation imposed solely by T. Record provider
|
||||
revision/configuration, complete fixture counts, metadata counts and artifact
|
||||
sizes. Identical PBX bytes and a performance improvement are not required.
|
||||
|
||||
Ship and verify specifications and executable examples in installed knowledge.
|
||||
Regress Array, ordinary/applied structs/contracts, Self, constructors, Fn/captures
|
||||
and lifecycle. No mandatory requirement is deferred to a collection implementation.
|
||||
|
||||
Independent generic methods, generic contract methods/lambdas, polymorphic Fn,
|
||||
function type inference, bounds, variance, defaults, user specialization and
|
||||
blanket/narrower implementation patterns are outside this feature. Lifecycle
|
||||
signatures remain concrete. Collection APIs/algorithms, default equality/hash,
|
||||
iteration protocols and List logical bounds/slot transfer are separate decisions.
|
||||
|
||||
## Related specifications
|
||||
|
||||
- [Generic contracts](generic-contracts.md).
|
||||
- [Typed arrays and optional execution](typed-arrays-and-optional-execution.md).
|
||||
- [First-class functions and captures](first-class-functions-and-captures.md).
|
||||
- [Concrete Registry and PBX handoff](../../general/specs/typed-registry-and-pbx-v0.md).
|
||||
@@ -0,0 +1,136 @@
|
||||
# PBS input and existing value runtime alignment
|
||||
|
||||
Status: normative. Owner: `compiler/pbs`. Common ABI authority:
|
||||
[typed Registry/PBX](../../general/specs/typed-registry-and-pbx-v0.md) and
|
||||
[runtime catalogs](../../general/specs/runtime-catalog-support.md).
|
||||
|
||||
## Source types and exact carriers
|
||||
|
||||
| PBS source | Runtime identity | Ordered slots |
|
||||
| --- | --- | --- |
|
||||
| `int` | Int32 | Int32 |
|
||||
| `long` | Int64 | Int64 |
|
||||
| `float` | Float | Float (binary64) |
|
||||
| `bool` | Bool | Bool |
|
||||
| `str` | String | String |
|
||||
| builtin `color` shell | color | Int64 constrained to RGBA8888 |
|
||||
| builtin `vec2` shell | vec2 | Float x, Float y |
|
||||
| builtin `pixel` shell | pixel | Int64 x, Int64 y, Int64 color |
|
||||
|
||||
The canonical builtin metadata determines a shell's identity; its source name
|
||||
is not an ABI lookup rule. Equal widths do not permit substitution. Function
|
||||
metadata MUST declare ordered parameter and result identities. Slot counts are
|
||||
checked caches derived from those identities. Calls, locals and returns MUST
|
||||
preserve entire value groups. A vec2 is one logical value with two slots;
|
||||
a named output tuple is a fixed sequence of logical results, not a heap object.
|
||||
|
||||
`int` and `long` are distinct. Integer literals default to `int`; explicit
|
||||
`long` contexts (annotations, parameters and results) validate literals in the
|
||||
Int64 range and materialize them with that carrier. Out-of-range literals MUST
|
||||
be diagnosed, never replaced by zero. A typed variable does not change type
|
||||
because it appears in another expected context. Mixed int/long operations
|
||||
require an explicit conversion. Existing `as` syntax expresses conversion:
|
||||
|
||||
```pbs
|
||||
let frames: long = 2147483648;
|
||||
let offset: int = 10;
|
||||
let wide = offset as long;
|
||||
let narrow = frames as int;
|
||||
```
|
||||
|
||||
The final conversion faults if its value is outside Int32 range. Numeric
|
||||
conversions use published math/mathf conversion intrinsics, without adding
|
||||
math service facades. Int32/Int64 arithmetic preserves runtime wrapping;
|
||||
Float overflow and range-invalid conversions preserve runtime faults.
|
||||
Defaults are owned by the runtime storage contract: numeric zero, Float +0,
|
||||
Bool false, nullable String null, transparent color, zero vec2 and zero pixel.
|
||||
This does not introduce implicit source-variable initialization: VM locals
|
||||
start null and PBS definite-assignment rules still apply. NaN/infinity are not
|
||||
valid guest numeric defaults.
|
||||
|
||||
## Public input API
|
||||
|
||||
Import `Pad`, `Button` and `Touch` from `@sdk:input`. Button is a closed nominal
|
||||
PBS enum with cases Up, Down, Left, Right, A, B, X, Y, L, R, Start and Select.
|
||||
It identifies a button; it does not contain input state or perform a query.
|
||||
Locals and typed function parameters may carry Button values, including values
|
||||
selected during execution. Strings, integer indices and unrelated enums are
|
||||
not valid Button arguments.
|
||||
|
||||
| Public operation | Result |
|
||||
| --- | --- |
|
||||
| `Pad.pressed(button: Button)` | bool |
|
||||
| `Pad.released(button: Button)` | bool |
|
||||
| `Pad.down(button: Button)` | bool |
|
||||
| `Pad.hold(button: Button)` | long, held logical frames |
|
||||
| `Touch.pressed()`, `Touch.released()`, `Touch.down()` | bool |
|
||||
| `Touch.hold()` | long, held logical frames |
|
||||
| `Touch.x()`, `Touch.y()` | long |
|
||||
|
||||
```pbs
|
||||
import { Pad, Button, Touch } from @sdk:input;
|
||||
|
||||
fn jump(button: Button) -> bool {
|
||||
return Pad.pressed(button);
|
||||
}
|
||||
|
||||
fn held() -> long {
|
||||
let jump_button = Button.A;
|
||||
return Pad.hold(jump_button);
|
||||
}
|
||||
```
|
||||
|
||||
Pad dispatches to `LowPad.<button>_<query>()`, for example
|
||||
`LowPad.a_pressed()`. All 48 combinations map to the published direct endpoint.
|
||||
Each call MUST evaluate its selector once and execute exactly one chosen
|
||||
query. It MUST NOT read unselected buttons, speculate input faults or collect
|
||||
all button states. Constant specialization is optional; dynamic dispatch must
|
||||
work without optimization.
|
||||
|
||||
All 54 VM queries take zero arguments and no receiver. Button never crosses
|
||||
the intrinsic boundary as a selector. Touch x/y use current IDs 0x2134/0x2135
|
||||
and Int64 results. No new device, button-state object, snapshot or multi-pad
|
||||
contract is introduced. Known input without an available platform faults with
|
||||
TRAP_UNAVAILABLE; it never fabricates false or zero. Unknown and retired IDs
|
||||
are invalid even in unreachable code.
|
||||
|
||||
## Migration and diagnostics
|
||||
|
||||
The old Input root and intermediate InputPad/InputTouch/InputButton objects
|
||||
are removed. Replace `Input.pad().a().pressed()` with
|
||||
`Pad.pressed(Button.A)` and `Input.touch().x()` with `Touch.x()`.
|
||||
`let button = Input.pad().a();` is invalid; `let button = Button.A;` is valid.
|
||||
Migration diagnostics must point to the replacement surface. Hover, completion,
|
||||
exports and examples must advertise the same API and exact return types.
|
||||
When a consumer requires int coordinates, explicitly narrow a Touch result
|
||||
with `as int`; do not silently change the query's ABI.
|
||||
|
||||
## Lowering and observable order
|
||||
|
||||
PBS owns source enum dispatch and typed metadata. Common code owns catalog
|
||||
resolution, PBX validation and emission. The frontend MUST NOT maintain a
|
||||
second intrinsic or constant catalog. SDK executable methods admit the existing
|
||||
switch expression with value arms, apply and explicit numeric conversions
|
||||
needed by this facade; other unsupported SDK constructs remain diagnosed.
|
||||
|
||||
For named application such as `f apply (y: effect_y(), x: effect_x())`, evaluate
|
||||
Y then X exactly once, store complete groups in temporary locals, and reload
|
||||
in x,y parameter order. Reordering expressions instead of values is invalid.
|
||||
|
||||
Builtin constants are groups resolved by the shared constant catalog.
|
||||
`vec2.zero` materializes two Float slots; no intrinsic endpoint is invented.
|
||||
Colors may use a published constant or an independently published intrinsic.
|
||||
Function metadata must cover SDK wrappers such as Gfx.clear. Validation must
|
||||
not infer missing identities from widths or omit the full installed example.
|
||||
Preserve the existing lifecycle assembly and physical boot FunctionId zero.
|
||||
|
||||
## Conformance
|
||||
|
||||
The PBS source-to-production-PBX corpus and production runtime harness must
|
||||
cover all 54 input queries with controlled input and exactly-one-query checks,
|
||||
known-unavailable behavior, typed selectors, int/long boundaries and explicit
|
||||
conversions, Float/String/Bool, color/vec2/pixel groups, multiple returns and
|
||||
named-argument effects. Keep common registry wrong-carrier, retired-ID and stale
|
||||
signature tests active. Record runtime hash, Studio revision, platform and
|
||||
configuration. A catalog-only pass does not replace successful PBS execution
|
||||
or `:prometeu-app:installedKnowledgeTest`.
|
||||
@@ -0,0 +1,71 @@
|
||||
# PBS Runtime Random Integration
|
||||
|
||||
Owner: `compiler/pbs`. This specification defines the PBS projection of runtime Random v1. The runtime owns the algorithm, heap identity, validation, atomicity, resource accounting and virtual cycles. The common catalog is the binding authority; the frontend does not implement a generator.
|
||||
|
||||
## Source surface
|
||||
|
||||
```pbs
|
||||
import { Random, random } from @sdk:random;
|
||||
|
||||
fn draw() -> long {
|
||||
let seed: long = 42;
|
||||
let generator: Random = random.new(seed);
|
||||
let alias = generator;
|
||||
random.next(generator);
|
||||
return random.range(alias, 0 as long, 100 as long);
|
||||
}
|
||||
```
|
||||
|
||||
Game SDK 1 exports the opaque builtin `Random` and service namespace `random` from `@sdk:random`. Both may be imported with aliases. The exact v1 signatures are:
|
||||
|
||||
| Operation | PBS signature | Runtime result/cost |
|
||||
| --- | --- | --- |
|
||||
| `random.new` | `(seed: long) -> Random` | New independent generator; 32 cycles |
|
||||
| `random.next` | `(rng: Random) -> long` | Next word reinterpreted as signed Int64; 8 cycles |
|
||||
| `random.nextf` | `(rng: Random) -> float` | Exact binary64 grid value in `[0,1)`; 12 cycles |
|
||||
| `random.range` | `(rng: Random, min: long, max: long) -> long` | Integer in `[min,max)`; `4 + 8*N` cycles |
|
||||
|
||||
`new` is accepted as a callable declaration/member name; the `new Type(...)` allocation expression remains distinct. `new Random()` is invalid. The builtin has no public fields, source constructor, implicit Struct/Trait adaptation, receiver defaults or hidden seed. Only `random.new` allocates a generator. The API does not expose helpers, clone, reseed, split, snapshot or a global generator. Seeds are Int64 bit patterns: zero, negatives and extrema are valid. An existing `int` binding requires an explicit conversion to `long`; contextual long literals remain governed by the numeric specification.
|
||||
|
||||
## Identity and storage
|
||||
|
||||
Random is runtime BuiltinId `0x0016`, with one opaque nullable reference slot. Program TypeIds are local identities, not BuiltinIds. The frontend MUST register this exact builtin and MUST NOT model its payload as a source Struct or emit `NEW` to construct it.
|
||||
|
||||
Assignment, parameter passing, returns and capture copy a reference to the same state. Calling `random.new` twice with the same seed creates equal initial sequences that evolve independently. Copying an existing handle does not fork the sequence. All output operations consume the same stream, including a unit-width range and calls whose results are discarded.
|
||||
|
||||
The reference MUST retain identity and ownership in locals, globals, fields, arrays, function parameters/results and captures. Captures use the existing snapshot rules: the copied reference continues to identify the shared generator. Reachable references MUST remain valid across runtime collection.
|
||||
|
||||
PBS does not expose a `null` literal or a public `Dynamic` type. Runtime reference defaults remain null at the provider boundary. PBS constructors MUST explicitly initialize every field on every completing path, including Random fields; an empty constructor cannot expose that runtime default. Existing global-initializer restrictions remain unchanged; an unsupported arbitrary call in a global initializer does not become legal because it returns Random.
|
||||
|
||||
Typed arrays use their existing private `Array<Dynamic>` representation. Packing Random MUST preserve its exact runtime TypeId and direct reference without cloning state or adding a multi-slot box. A present typed-null Random element MUST remain distinguishable from an empty array position: presence is checked by tag before exact extraction. Consuming that null generator raises the runtime null-reference fault rather than treating the element as absent.
|
||||
|
||||
## Evaluation, faults and billing
|
||||
|
||||
All four operations are deterministic and mutate guest state; only `new` may allocate. Determinism means reproducibility from the same state and ordered inputs. The compiler MUST NOT execute, fold, eliminate or reorder these calls based on literals, seeds or the deterministic flag. Discarding a result MUST retain the call and its mutation.
|
||||
|
||||
Arguments MUST be evaluated in source order. Named application may rearrange already evaluated carriers into signature order but MUST NOT change the order of their effects.
|
||||
|
||||
`range` requires `min < max`, with exact long arguments and no swapping, clamping, absolute-value or Float conversion. The runtime charges base 4 before checks and 8 for each attempted draw. Acceptance on attempt 64 succeeds; 64 rejections raise the rejection-limit trap at 516 intrinsic cycles. A unit interval consumes a word and costs 12. Argument evaluation, calls, storage and other bytecode instructions have their own costs.
|
||||
|
||||
The runtime contract governs fault precedence and atomicity: wrong carriers, null/invalid references, invalid limits and resource refusals retain the applicable identities. Failed operations do not publish partial state or handles, but executed cycles are not refunded. Compiler and SDK MUST preserve these semantics without a second validator, generator or cycle emulator in production.
|
||||
|
||||
## Conformance
|
||||
|
||||
The source corpus MUST run the production PBS → common IR → PBX → runtime path with optimization on and off, and repeat equal ordered inputs to compare exact bits, faults and cycles. Required coverage includes:
|
||||
|
||||
- all four signatures, real SDK imports/aliases and incompatible-source diagnostics;
|
||||
- provider vectors for seeds `0`, `1`, `42`, `-1`, Int64 MIN/MAX, integer and Float draws;
|
||||
- aliases, independent equal-seed objects, mixed outputs, discarded draws and positional/named argument effects;
|
||||
- locals/globals/fields/arrays/parameters/results/captures, private Dynamic and retained roots across collection;
|
||||
- unit/extreme intervals, excluded upper bound, invalid bounds and real rejection followed by acceptance;
|
||||
- exact intrinsic charges and replay/optimizer agreement.
|
||||
|
||||
Null receivers and present typed-null Array elements MUST be covered by separately identified controlled provider fixtures. Such fixtures may suppress a fully initialized field store after compilation to exercise provider reference defaults; they MUST NOT depend on accepting incomplete source constructors. Rare synthetic rejection paths, cap rollback, malformed carriers and native reference provenance remain separately identified provider evidence. Tests MUST reuse the provider's controlled fixtures without adding injection or alternate algorithms to the public SDK. Record runtime revision, platform, profiles, toolchain, features and source/catalog/oracle/lockfile fingerprints. Local results do not qualify unexecuted platforms or the reference game.
|
||||
|
||||
## References
|
||||
|
||||
- [Typed arrays and optional execution](typed-arrays-and-optional-execution.md).
|
||||
- [First-class functions and captures](first-class-functions-and-captures.md).
|
||||
- [Runtime math and exact numeric carriers](service-constants-and-runtime-math.md).
|
||||
- [Runtime Random v1](../../../../../runtime/docs/specs/runtime/02e-vm-owned-random-core.md).
|
||||
- [Provider handoff](../../../../../runtime/docs/vm-arch/random-producer-handoff.md).
|
||||
@@ -0,0 +1,135 @@
|
||||
# SDK Linked and bidirectional snapshot capture
|
||||
|
||||
Owner: `compiler/pbs`. Linked algorithms belong to executable PBS SDK source.
|
||||
Typed storage, faults, ownership, GC and quotas remain generic
|
||||
compiler/provider mechanisms. This contract builds on [generic structs](generic-structs-and-free-functions.md),
|
||||
[arrays and optional](typed-arrays-and-optional-execution.md) and the
|
||||
[shared Cursor protocol](sdk-list-and-cursor.md#cursor-protocol).
|
||||
|
||||
## Type, identity and construction
|
||||
|
||||
The collections SDK exports `linked<T>`. It is an ordinary invariant generic
|
||||
struct with stable reference identity: aliases observe mutations of the same
|
||||
collection. `new linked<T>()` creates an empty collection. Contextual construction
|
||||
follows generic struct rules, requiring a concrete expected application; constructor
|
||||
values do not infer T. There is no capacity argument.
|
||||
|
||||
A directly optional element, including through grouping, is invalid.
|
||||
`optional (linked<T>)` remains valid, as do otherwise valid element types containing
|
||||
optional fields. Values retain their complete groups and normal identities,
|
||||
including tuples, native values, arrays, functions and contract views. No public
|
||||
Dynamic, universal Element or wrapper node is introduced.
|
||||
|
||||
Storage consists of private doubly linked nodes, each containing one present
|
||||
value. Logical size equals node count. Empty collections have no head or tail;
|
||||
one-node collections have the same head and tail. Neighbor links are reciprocal,
|
||||
forward and backward traversals agree, and there are no extra predecessor or
|
||||
successor nodes beyond the ends. Nodes and private helpers are not a public API.
|
||||
|
||||
## Operations and bounds
|
||||
|
||||
| Operation | Result | Behavior |
|
||||
| --- | --- | --- |
|
||||
| `size()` | long | Number of elements |
|
||||
| `first()` / `last()` | optional T | End value, or none when empty |
|
||||
| `xs[i]` | optional T | Present value at a valid index |
|
||||
| `xs[i] = value` | unit | Replace a valid position without changing size |
|
||||
| `add(value)` | unit | Append |
|
||||
| `addFirst(value)` | unit | Prepend |
|
||||
| `insert(i, value)` | unit | Insert at `0 <= i <= size` |
|
||||
| `removeAt(i)` | optional T | Remove and return a valid position |
|
||||
| `removeFirst()` / `removeLast()` | optional T | Remove and return end value, or none when empty |
|
||||
| `clear()` | unit | Remove all elements and set size to zero |
|
||||
| `cursor()` | Cursor<T> | Capture first to last |
|
||||
| `reverseCursor()` | Cursor<T> | Capture last to first |
|
||||
|
||||
Reading, replacing and removing by index require `0 <= i < size`; invalid indices
|
||||
raise TRAP_EXPLICIT even when empty. Insertion accepts size, including zero in an empty
|
||||
collection. Other insertion indices raise TRAP_EXPLICIT. Every valid position contains
|
||||
an element, so indexed read/removal returns a present optional. Zero and false are
|
||||
present values. Empty-end results do not suppress type or resource faults.
|
||||
|
||||
Insertion/removal changes the logical indices of following elements. Replacement
|
||||
preserves size. There are no holes, clearAt, capacity, reserve, trim or resize.
|
||||
Duplicate occurrences are preserved; no equality or uniqueness rule is imposed.
|
||||
Value search/removal is outside this API, consistently with List.
|
||||
|
||||
Size is nonnegative long. Indices accept int and long with localized lossless
|
||||
promotion, without general numeric conversion or truncation. The SDK checks the
|
||||
current size against the maximum signed long before incrementing, using SDK comparisons
|
||||
and terminal TRAP_EXPLICIT; an unrepresentable next size is rejected before arithmetic or
|
||||
mutation. Array's u32 structural maximum is not a Linked size limit. Provider
|
||||
quotas and applicable structural limits can refuse allocation much earlier.
|
||||
Receiver/arguments evaluate once in source order, including named application.
|
||||
|
||||
## Snapshots and costs
|
||||
|
||||
Both capture methods return the existing Cursor<T> contract and preserve its
|
||||
complete state table. A nonempty cursor starts on its first captured value;
|
||||
hasNext asks whether a successor exists; next without a successor does nothing.
|
||||
Only a snapshot born empty has an absent current. Repeated next retains the final
|
||||
value. Capturing `[A, B, C]` produces `[A, B, C]` or `[C, B, A]` respectively.
|
||||
|
||||
Each capture completes before return and owns private immutable singly linked,
|
||||
non-circular snapshot nodes, independent of the collection's doubly linked nodes.
|
||||
It uses no snapshot array or live association with editable source nodes.
|
||||
Subsequent insertion, replacement, removal and clear cannot change the captured
|
||||
sequence. Shared objects retain identity and later field changes remain visible.
|
||||
There is no removal/reset through Cursor or public node access.
|
||||
|
||||
End operations locate their nodes without traversal. Indexed operations search
|
||||
from the nearer end and remain O(n) in the worst case. Both captures cost O(n)
|
||||
work and O(n) additional nodes; next follows one link in O(1). Allocation,
|
||||
optional-carrier preparation, ownership and eventual GC retain their normal
|
||||
costs. Repeated indexed reads are not an efficient traversal strategy.
|
||||
|
||||
## Mutation phases and lifetime
|
||||
|
||||
Before the first visible write, prepare bounds, next size, candidate nodes,
|
||||
optional results and complete field values. Insertion updates previous.next or
|
||||
head, then next.previous or tail, then length. Removal prepares its result and
|
||||
neighbors, updates the same two sides, then length. Indexed replacement updates
|
||||
only value; clear assigns head, tail and length in that order. Source algorithms
|
||||
own these choices; the VM has no Linked instruction, publication schema or syscall.
|
||||
|
||||
A logical rejection or preparation refusal before mutation preserves the previous
|
||||
head/tail/size, elements and neighbor links. Successful return restores all public
|
||||
invariants. An internal/resource fault after the first visible write propagates
|
||||
without rollback: earlier writes may remain and topology/size can be incomplete.
|
||||
No safe reuse, retry or automatic recovery is promised. This explicitly replaces
|
||||
the former whole-method refusal guarantee, and is not a basic-consistency claim.
|
||||
Previously evaluated argument effects remain ordinary source effects.
|
||||
|
||||
Individual instruction failures preserve their own entry state. Operand/call/
|
||||
optional preparation remains charged and can fail; sequential stores are not a
|
||||
transaction. No user callback or explicit suspension is inserted during updates.
|
||||
BudgetExhausted and debugger pauses can stop between instructions and resume at
|
||||
the current PC without completing or undoing the method. Host/debugger observation
|
||||
is not atomic. No catch, poison flag or recovery API is introduced.
|
||||
|
||||
Unpublished candidates follow normal ownership and quotas. Capture failure returns
|
||||
no partial Cursor and does not change the source. Removal and clear release
|
||||
collection references to discarded nodes and payloads. Doubly linked cycles are
|
||||
collected by normal tracing when unreachable; no immediate reclamation is promised.
|
||||
Snapshots retain payloads, not the editable source topology; consumed prefixes
|
||||
become collectible while the last current value stays retained until released.
|
||||
|
||||
## Conformance and distribution
|
||||
|
||||
Qualification executes real PBS through common IR/PBX and the production verifier
|
||||
and VM, with ordinary and optimized producer paths. Cover the full API in empty,
|
||||
single and multi-node states, reciprocal links and size, nearest-end lookup, all
|
||||
bounds, int/long and single/named evaluation, complete groups and identity,
|
||||
optional-element diagnostics, both Cursor orders/states and mutation independence.
|
||||
|
||||
Independently observe all original fields, link carriers, nodes and groups around
|
||||
quota refusals, including node/result/operand preparation. Exercise ordinary GC
|
||||
safepoints for removed nodes/values, clear, snapshots and prefix/final release.
|
||||
Neutral stores/copy/terminal failure also require non-PBS producers and
|
||||
malformed/dead instruction coverage. Regress shared Array/List/generic/contract/Cursor behavior and editor/LSP
|
||||
projections. Ship the specification and executable example with installed SDK
|
||||
knowledge, compile the actual packaged example outside the checkout and execute
|
||||
its emitted PBX with the production provider.
|
||||
|
||||
See [generic Registry/PBX storage](../../general/specs/typed-registry-and-pbx-v0.md)
|
||||
for the language-neutral instruction contract.
|
||||
@@ -0,0 +1,199 @@
|
||||
# SDK List and snapshot Cursor
|
||||
|
||||
Owner: `compiler/pbs`. List and Cursor algorithms belong to the executable PBS
|
||||
SDK. Typed storage, complete stored-group transfers and terminal failure are
|
||||
language-neutral compiler/runtime mechanisms. Logical checks are SDK algorithms. This contract builds on
|
||||
[arrays and optional](typed-arrays-and-optional-execution.md),
|
||||
[generic structs](generic-structs-and-free-functions.md) and
|
||||
[generic contracts](generic-contracts.md).
|
||||
|
||||
## Type, identity and construction
|
||||
|
||||
The SDK exports the ordinary generic struct `list<T>` and contract `Cursor<T>`
|
||||
from its collections module. Applications are invariant. A directly optional
|
||||
element, including through grouping, is invalid; `optional (list<T>)` is valid.
|
||||
Nested valid arrays, structs, contracts, functions and value groups keep their
|
||||
normal types and identities. An unrelated user declaration named list does not
|
||||
acquire SDK behavior.
|
||||
|
||||
`new list<T>()` creates size zero and capacity 16. `new list<T>(capacity)` creates
|
||||
size zero with exactly that capacity, including zero. Contextual `new list()`
|
||||
and `new list(capacity)` require an expected concrete List type. Constructor
|
||||
values do not infer T. Only the backing array is allocated; elements are absent.
|
||||
|
||||
List has stable reference identity. Assignment and parameter passing share that
|
||||
identity; aliases observe mutations even when growth replaces its private backing
|
||||
array. Storage, internal nodes and private compiler bindings are inaccessible to
|
||||
clients. No public Dynamic or universal element type is introduced.
|
||||
|
||||
## Logical positions and operations
|
||||
|
||||
Every observable List satisfies `0 <= size <= capacity`. Size includes holes.
|
||||
Capacity is physical storage and never makes additional indices accessible.
|
||||
Zero and false are present values, distinct from holes.
|
||||
|
||||
| Operation | Result | Behavior |
|
||||
| --- | --- | --- |
|
||||
| `size()` | long | Logical positions, including holes |
|
||||
| `capacity()` | long | Physical backing length |
|
||||
| `xs[i]` | optional T | Present value or hole at `0 <= i < size` |
|
||||
| `xs[i] = value` | unit | Replace one valid position without extending size |
|
||||
| `add(value)` | unit | Append at size; do not fill earlier holes |
|
||||
| `insert(i, value)` | unit | Insert at `0 <= i <= size`; shift slots and holes right |
|
||||
| `clearAt(i)` | unit | Clear a valid position without shifting or changing size |
|
||||
| `removeAt(i)` | optional T | Return old content, shift left, clear old tail, decrement size |
|
||||
| `clear()` | unit | Clear all contents and size, preserve capacity |
|
||||
| `resize(n)` | unit | Grow with holes or clear discarded suffix; set logical size |
|
||||
| `reserve(n)` | unit | Grow exactly to n only when n exceeds capacity |
|
||||
| `trim()` | unit | Set capacity exactly to size, including zero |
|
||||
| `cursor()` | Cursor<T> | Complete immediate snapshot of present occurrences |
|
||||
|
||||
Removing a hole still removes its position and decrements size. Shrink, removal
|
||||
and clear discard all hidden suffix references: regrowing must not resurrect old
|
||||
values. Physical shrinking occurs only through trim. `resize(0)` preserves capacity.
|
||||
|
||||
Receiver and arguments are evaluated once in source order. Indices, lengths and
|
||||
capacities accept int and long with localized lossless promotion; this does not
|
||||
add general numeric conversion. No long value may be truncated.
|
||||
|
||||
SDK checks reject invalid logical indices, negative lengths/capacities and requests
|
||||
above Array's u32 structural maximum before mutation with TRAP_EXPLICIT and a
|
||||
source location. This includes indices inside physical capacity. Physical Array
|
||||
instructions that actually execute retain their own fault/resource classification.
|
||||
Failures are never translated into none. Growth arithmetic must not overflow or
|
||||
truncate; clamping applies only to a valid requested length.
|
||||
|
||||
## Capacity policy
|
||||
|
||||
When required size r exceeds capacity c, automatic growth is:
|
||||
|
||||
```text
|
||||
candidate = max(r, c + max(1, ceil(c / 2)))
|
||||
new capacity = min(Array structural maximum, candidate)
|
||||
```
|
||||
|
||||
Calculate without overflow. Clamp only if r itself fits the structural maximum;
|
||||
otherwise raise the applicable provider failure. Explicit reserve uses exactly n,
|
||||
never shrinks and preserves size. Trim uses exactly size. Old and candidate arrays
|
||||
may coexist; neither discarded references nor replaced storage promise immediate
|
||||
GC or immediate quota recovery.
|
||||
|
||||
## Mutation preparation, visible writes and faults
|
||||
|
||||
Transfer whole stored groups, presence tags and reference identities; do not
|
||||
unpack and rebox all existing elements during shifting. Prepare validation,
|
||||
next size, inserted values, candidates and optional return carriers before the
|
||||
first visible write. This preparation does not prove all later instructions
|
||||
infallible. Values/receiver/argument effects already evaluated are not rolled back.
|
||||
|
||||
With growth, construct a private candidate and copy prefix/suffix directly into
|
||||
their final positions; store the new value privately, then install storage and
|
||||
length in sequence. Without growth, prepare the inserted stored group in a private
|
||||
one-slot array, shift with overlap-safe ARRAY_COPY, copy that complete prepared
|
||||
slot, then update length. Both copies retain scratch, validation and charging,
|
||||
including empty copies. This one-slot preparation is charged allocation, not a
|
||||
promise of allocation-free insertion or whole-array reconstruction.
|
||||
|
||||
Removal prepares its optional result, shifts the suffix, clears the old tail and
|
||||
updates length. Clear and in-capacity resize clear the selected interval in index
|
||||
order before assigning length. Growing resize prepares/copies a private candidate
|
||||
before installing storage and length. Reserve/trim prepare/copy candidates and
|
||||
replace storage only. Indexed replacement/clearAt alter a single checked position.
|
||||
|
||||
| Outcome | Guarantee |
|
||||
| --- | --- |
|
||||
| Logical rejection or preparation refusal before the first visible write | Preserve previous size, backing, capacity, slots and collection roots. Unpublished candidates obey normal ownership/quotas; immediate quota recovery is not promised. |
|
||||
| Successful return | All collection invariants, cleanup, groups, identity and snapshot contracts hold. |
|
||||
| Internal/resource fault after the first visible write | Propagate the fault; earlier writes can remain and collection invariants can be incomplete. No rollback, safe reuse, retry or automatic recovery is promised. |
|
||||
|
||||
The last row explicitly replaces the former whole-mutation refusal guarantee.
|
||||
Individual instruction failure still preserves its own entry operands/storage.
|
||||
No catch, poison flag or recovery API is introduced. The SDK inserts no user
|
||||
callbacks or explicit suspension during mutation updates. BudgetExhausted and
|
||||
pauses are resumable instruction boundaries, not faults or rollback. The host or
|
||||
debugger may observe intermediate state; a method is not an atomic region.
|
||||
|
||||
## Cursor protocol
|
||||
|
||||
```pbs
|
||||
declare contract Cursor<T> {
|
||||
fn hasNext() -> bool;
|
||||
fn next();
|
||||
fn current() -> optional T;
|
||||
}
|
||||
```
|
||||
|
||||
The shared SDK implementation captures one private immutable singly linked,
|
||||
non-circular node per present occurrence. It uses no snapshot array and retains
|
||||
no source-slot or editable source-node association. List capture scans logical
|
||||
positions and preserves increasing index order, duplicates and complete values.
|
||||
Capture finishes before returning; failure exposes no partial Cursor.
|
||||
|
||||
A nonempty Cursor starts on its first node. `hasNext()` tests for a successor.
|
||||
`next()` advances only when a successor exists; otherwise it does nothing.
|
||||
`current()` reports the current node without advancing. Only a snapshot born
|
||||
empty reports none. Repeated calls never advance beyond the last node.
|
||||
|
||||
| Snapshot and position | hasNext() | current() |
|
||||
| --- | --- | --- |
|
||||
| Empty, initially or after any next | false | none |
|
||||
| [A], initially or after any next | false | some(A) |
|
||||
| [A, B], initially | true | some(A) |
|
||||
| [A, B], after one or any further next | false | some(B) |
|
||||
|
||||
Consume the current value before deciding whether to advance:
|
||||
|
||||
```pbs
|
||||
while true {
|
||||
if let value = cursor.current() {
|
||||
// Consume value.
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
if cursor.hasNext() {
|
||||
cursor.next();
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A hasNext-only loop skips the last element. Waiting for current to become none
|
||||
does not terminate a nonempty snapshot. There is no index, reset, removal, clone
|
||||
or new for-in protocol. Another complete traversal creates another snapshot.
|
||||
|
||||
Captured object references preserve identity and observe subsequent field mutation.
|
||||
Later List insertions, replacements, removals, clear, resize and backing changes
|
||||
do not alter the captured sequence. Snapshot links and captured values are not
|
||||
rewritten. The Cursor retains only its current node and suffix, allowing consumed
|
||||
prefixes to become unreachable. It keeps the final node/value while reachable.
|
||||
Other owners remain independent; reclamation happens through normal GC.
|
||||
|
||||
The outer optional describes node existence. A future producer with optional T
|
||||
must distinguish `some(none)` from an empty Cursor. Type/resource faults remain
|
||||
faults. List itself rejects directly optional elements.
|
||||
|
||||
## Reuse, costs and conformance
|
||||
|
||||
The shared implementation is independent of List representation.
|
||||
[Linked](sdk-linked-and-cursor.md) uses Cursor<T> for forward and reverse captures.
|
||||
Future Set<T> producers use Cursor<T>; Map<K,V> uses Cursor<keyval<K,V>>. Set/Map gain
|
||||
no ordering guarantee between captures. A captured keyval association is read-only
|
||||
and does not follow later association replacement; referenced objects stay shared.
|
||||
Set/Map and keyval are separate deliveries.
|
||||
|
||||
For n logical List positions and k present occurrences, capture takes O(n) work
|
||||
and O(k) additional nodes; next follows one link in O(1). Each node costs allocation,
|
||||
ownership and eventual GC work. Do not promise lower memory than arrays, zero
|
||||
allocation or allocation-free optional results. All complete groups remain rooted
|
||||
through allocations and calls; provider quotas remain unchanged.
|
||||
|
||||
Conformance must execute real PBS through common IR and PBX in the production VM.
|
||||
It covers every operation, constructor/type rule, logical bounds, exact growth,
|
||||
holes and full groups, aliases, the entire Cursor table, snapshot independence,
|
||||
shared object mutation, non-List producers, refusals before and after visible mutation with and without
|
||||
growth, prefix reclamation, last-node retention, editor projections and installed
|
||||
SDK/spec/example distribution. Neutral storage/copy/terminal paths also require non-PBS tests.
|
||||
|
||||
Value search/removal, sorting, bulk APIs, new equality, public nodes, deep freezing,
|
||||
general effect/transaction syntax and Linked/Set/Map implementations are out of scope.
|
||||
@@ -0,0 +1,118 @@
|
||||
# Service constants and runtime math
|
||||
|
||||
Owner: compiler/pbs. Common catalog authority: compiler/general. Numeric behavior,
|
||||
exact identities, faults and virtual costs remain owned by the runtime.
|
||||
|
||||
## Services are the public namespaces
|
||||
|
||||
A service groups methods and immutable constants. The service barrel entry exports
|
||||
both; constants are not independently exported as top-level symbols. This applies
|
||||
to project code and SDK interfaces. Import aliases preserve the service identity.
|
||||
|
||||
```pbs
|
||||
// @app:settings/main.pbs; mod.barrel contains: pub service Settings;
|
||||
declare service Settings {
|
||||
declare const base: int = 40;
|
||||
declare const answer: int = base + 2;
|
||||
fn read() -> int { return answer; }
|
||||
}
|
||||
```
|
||||
|
||||
Consumers can import `Settings` and read `Settings.answer`. Constants use the same
|
||||
explicit type and constant-expression rules as top-level constants. Constant
|
||||
initializers cannot invoke functions. Qualified dependencies are permitted;
|
||||
unqualified names inside a constant initializer resolve in its owning service
|
||||
before the top-level constant scope. Duplicate constants, a constant sharing a
|
||||
method name, unresolved references, type mismatches and dependency cycles are
|
||||
compile-time errors. Assignments to constants are invalid.
|
||||
|
||||
Reading `Service.constant` materializes its value without creating a singleton or
|
||||
calling a getter. Ordinary methods retain existing service semantics. Constant
|
||||
members are included in completion, hover, definition and document symbols.
|
||||
|
||||
## SDK math services
|
||||
|
||||
```pbs
|
||||
import { math } from @sdk:math;
|
||||
import { mathf as numbers } from @sdk:mathf;
|
||||
|
||||
fn example(counter: long, angle: float) -> float {
|
||||
let bounded = math.clamp(counter, 0 as long, 100 as long);
|
||||
return math.to_float(bounded) + numbers.sin(angle) + numbers.pi;
|
||||
}
|
||||
```
|
||||
|
||||
`math` supplies `min`, `max`, `clamp` and `abs`, each with exact `int` and `long`
|
||||
overloads. `mathf` supplies `min`, `max`, `clamp`, `abs`, `floor`, `ceil`, `trunc`,
|
||||
`round`, `sqrt`, `sin`, `cos` and `atan2`, all with `float` arguments and results.
|
||||
`atan2` takes `(y, x)`; angles are radians. `float` is the runtime's finite binary64.
|
||||
|
||||
The six conversions are:
|
||||
|
||||
| Source call | Argument | Result |
|
||||
| --- | --- | --- |
|
||||
| `math.to_i64` | int | long |
|
||||
| `math.to_i32` | long | int |
|
||||
| `math.to_float` | int | float |
|
||||
| `math.to_float` | long | float |
|
||||
| `mathf.to_i32` | float | int |
|
||||
| `mathf.to_i64` | float | long |
|
||||
|
||||
These are 26 exact intrinsic signatures in total. There are no identity
|
||||
conversions. A mixed `int`/`long` call to `math.min` is invalid; the diagnostic
|
||||
requires explicit conversion. Existing contextual integer literal rules do not
|
||||
authorize implicit conversion of an already typed argument. Arithmetic opcode
|
||||
promotion rules are unchanged.
|
||||
|
||||
## Binding and materialization
|
||||
|
||||
SDK service method signatures may carry `[IntrinsicCall(name = "...", version = 1)]`
|
||||
and terminate with `;`. They have no PBS body or implicit numeric receiver in their
|
||||
runtime signature. This reserved declaration form is restricted to SDK interfaces.
|
||||
The generated callable loads its ordered arguments and invokes the exact common
|
||||
catalog identity. No frontend numeric ID/cost map or host math implementation is
|
||||
introduced. Normal compilation uses local versioned resources, not a runtime checkout.
|
||||
|
||||
SDK service constants may use `BuiltinConst` and omit their initializer:
|
||||
|
||||
```pbs
|
||||
declare service mathf {
|
||||
[BuiltinConst(target = "mathf", name = "pi", version = 1)]
|
||||
declare const pi: float;
|
||||
}
|
||||
```
|
||||
|
||||
`mathf.pi` and `mathf.tau` MUST materialize `IRVMBuiltinConstantDefinition` values:
|
||||
`0x400921FB54442D18` and `0x401921FB54442D18`. They are ordinary constant loads,
|
||||
never synthetic intrinsic calls or host-calculated values. A constant expression
|
||||
cannot replace a mathematical call: executable calls with literal arguments MUST
|
||||
remain executable, including when their result is discarded or optimization runs.
|
||||
|
||||
## Numeric conformance
|
||||
|
||||
The runtime contract specifies signed zeros, subnormals, finite overflow, checked
|
||||
conversions and ties-to-even rounding. For example, `sqrt(-0)` preserves -0,
|
||||
`abs(-0)` produces +0, `round(2.5)` produces 2 and `round(3.5)` produces 4. Negative
|
||||
nonzero sqrt and inverted clamp limits trap NUMERIC_DOMAIN. Integer abs(MIN) and
|
||||
out-of-range conversions trap NUMERIC_RANGE. The frontend MUST preserve these
|
||||
outcomes, argument order and virtual cycle accounting.
|
||||
|
||||
Integration evidence MUST begin with PBS source and end at the production VM.
|
||||
The checked-in independent corpus combines provider MPFR-verified rows with exact
|
||||
published contract examples. Tests require all 26 signatures, constants, mixed-type
|
||||
rejections, explicit conversions, signed zeros, subnormals, extrema, range/domain
|
||||
faults and atan2 axes. Both optimized and unoptimized emission are exercised.
|
||||
The harness compares exact result bits and trap codes, and checks each executed
|
||||
instruction's charge against the provider opcode contract and each numeric call
|
||||
against its independent fixture cost. A full-budget run must charge their sum.
|
||||
Constant-only probes additionally require exactly a load and root return cost.
|
||||
|
||||
Local qualification requires macOS/arm64 dev and release with runtime revision,
|
||||
configuration and catalog/oracle hashes recorded. macOS/x86_64 and Linux/x86_64
|
||||
remain separately pending; local results and cross-compilation do not qualify them.
|
||||
|
||||
## References
|
||||
|
||||
- [Common runtime catalog support](../../general/specs/runtime-catalog-support.md)
|
||||
- [Runtime numeric contract](../../../../../runtime/docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md)
|
||||
- [Production conformance harness](../../../../tools/pbx-conformance/README.md)
|
||||
@@ -0,0 +1,105 @@
|
||||
# Typed arrays and optional execution
|
||||
|
||||
Owner: `compiler/pbs`. This specification defines the source contract for typed arrays and their integration with existing optional, struct and contract semantics. Runtime Registry, PBX, ownership, limits and faults remain governed by the runtime specifications. The completed implementation and conformance gates are recorded in [LSN-0083](../../../../discussion/lessons/DSC-0079-pbs-typed-collections-and-dynamic/LSN-0083-pbs-arrays-optional-and-contract-execution.md) and its evidence.
|
||||
|
||||
## Types and construction
|
||||
|
||||
`array<T>` denotes a fixed-length reference to positions holding values of T or no value. Nesting is compositional: `array<array<Enemy>>` holds array references. The compiler bounds structural type nesting to 256 nodes and diagnoses excessive depth without expanding an unbounded AST. Allocation length belongs to the constructor, not the type.
|
||||
|
||||
```pbs
|
||||
let enemies = new array<Enemy>(10);
|
||||
let contextual: array<Enemy> = new array<>(10);
|
||||
let omitted: array<Enemy> = new array(10);
|
||||
let groups: array<array<Enemy>> = new array<>(3);
|
||||
let scores: array<int> = [10, 20, 30];
|
||||
let empty: array<Enemy> = [];
|
||||
```
|
||||
|
||||
`new array<T>(length)` supplies its own type, including when the binding has no annotation. T must resolve to a valid element type. `new array<>(length)` and `new array(length)` are equivalent sugars requiring an expected array type. The length never supplies element-type information. All forms allocate only the outer array: each position is empty, with no implicit subarray, element construction or callback.
|
||||
|
||||
Every array literal, including a nonempty literal, requires an expected array type. The compiler must not infer its type from its elements. Expected types propagate through annotated local/global bindings, assignments, arguments with a resolved single callable signature, returns and nested value expressions. This migration does not expand overload resolution; contextual construction without sufficient expected type is an error. Incompatible explicit constructor types and literal elements are errors; they do not produce a public Dynamic type.
|
||||
|
||||
Arrays are invariant in element type and nesting. Assignment and argument passing share the array reference. The runtime's shared storage carrier must not make different PBS array types interchangeable. `array<optional T>` is invalid, including through grouped types. `optional (array<T>)` remains valid and distinguishes an absent array from a present array whose positions are empty.
|
||||
|
||||
Type delimiters can be adjacent to assignment: `let a: array<array<int>>=new array<>(3);` is valid. Parsing consumes type closers contextually while preserving expression comparisons such as `x >= y`. This does not introduce shift operators. Optional, `result<Error>` and `Fn(...) -> ...` retain their existing spellings.
|
||||
|
||||
Legacy `array T`, `array[N] T`, and `array<T>[N]` are rejected. `T[]`, `[]T`, `array !! T`, `new T[n]` and `new array[n]` are not alternative spellings. PBS exposes neither a null value nor a Dynamic type.
|
||||
|
||||
The frontend AST retains recursive element types and their spans. Constructor nodes distinguish explicit type arguments, diamond and omission; explicit construction types must reach semantic analysis, source tooling and PBS lowering without relying on a destination annotation. Common backend IR and runtime storage do not acquire PBS syntax rules.
|
||||
|
||||
## Operations and ordering
|
||||
|
||||
- `values.length` returns long and includes empty positions. Length is fixed; zero is valid.
|
||||
- `values[index]` returns `optional T`. Empty positions return none; populated positions return some(value). Numeric zero is present.
|
||||
- `values[index] = value` stores T and replaces the previous position.
|
||||
- `values.clear(index)` empties a position without changing length and returns unit.
|
||||
|
||||
Allocation lengths, indices and clear indices accept int and long literals, variables and expressions. The compiler promotes int to long without loss in these operations only. This does not introduce general implicit numeric conversions. Lengths must satisfy the runtime's u32 and resource bounds; long values must not be truncated.
|
||||
|
||||
Receiver, index and value expressions are evaluated once, left to right. Array literals evaluate elements in source order. Invalid indices fault, including accesses to a zero-length array; they must never be reported as none. Runtime type and resource failures retain their original meanings.
|
||||
|
||||
## Optional control flow
|
||||
|
||||
```pbs
|
||||
if let enemy = enemies[1] {
|
||||
enemy.takeDamage(10);
|
||||
} else {
|
||||
// Runs only when the position is empty.
|
||||
}
|
||||
```
|
||||
|
||||
`if let name = expression` requires optional T and evaluates its expression once. For some, the success block receives name of type T. For none, the success block is skipped and the optional else branch runs. The binding exists only inside the success block and must not leak into else or following statements. Outer bindings retain their identities after the conditional.
|
||||
|
||||
`value else fallback` evaluates fallback only for none. `some(value)`, contextual `none`, optional parameters/results, tuple payloads and nested optional values preserve their complete source types and groups. The existing `hasSome()` and `hasNone()` methods take no arguments and return bool. Optional function fallthrough yields none, following existing PBS rules; a trailing expression in a function body is not an implicit return.
|
||||
|
||||
## Runtime representation
|
||||
|
||||
Array positions use runtime `Array<Dynamic>` internally. An empty position is the untyped-null group `[Null, Null]`. A present position carries the exact runtime TypeId and payload for its statically checked PBS value. Runtime-supported single-slot payloads, including numeric values, are stored directly. Runtime multi-slot values use its immutable Dynamic boxing contract; the compiler must not introduce a heap box per single-slot integer.
|
||||
|
||||
Presence must be checked using the Dynamic tag before extraction. `DYN_CAN_UNPACK` alone is insufficient because untyped null can be compatible with nullable types. Type incompatibility must fault rather than becoming absence. Clearing restores the complete empty Dynamic group.
|
||||
|
||||
PBS optional values use private nullable Struct carriers: null denotes none and a private instance contains the full payload for some. Named tuples remain flattened at callable boundaries and use private storage carriers where a single Registry type is required. These private carriers are inaccessible to source programs. They preserve nested optional distinctions, tuple value behavior and reference aliases within payloads.
|
||||
|
||||
Lowering must keep complete receiver/index/value groups rooted across allocations, calls and collection operations. GC, native ownership, quota accounting, costs and per-instruction refusal preservation remain runtime contracts. No failure may publish partially initialized handles or be suppressed as none; no quota may be relaxed to satisfy conformance.
|
||||
|
||||
## Struct and contract integration
|
||||
|
||||
Existing PBS struct and contract rules apply unchanged: structs have reference identity; field visibility and `pub mut` control access; positional and named constructors obey overload selection and definite assignment; receiver `this`, fields and grouped values must execute faithfully. Runtime default initialization does not authorize exposure of a partially constructed source value.
|
||||
|
||||
`contract` and `implements` lower to typed Registry Trait descriptors and implementation tables. Adaptations preserve receiver and ImplementationId, including valid ID zero. `CALL_TRAIT` must use the selected method signature and complete argument/result groups. Struct and service owners are supported; service adaptations preserve singleton identity. This execution base is independent of future closure support.
|
||||
|
||||
## Diagnostics, tooling and conformance
|
||||
|
||||
Diagnostics must reject missing expected array types for contextual construction, unresolved explicit element types, excessive nesting, removed syntax, optional elements, incompatible invariant arrays, non-integral sizes/indices and non-optional if-let operands. Editor types and hints use PBS array notation. Hover, completion, definitions, references and rename must respect success-only binding scope and source element identity.
|
||||
|
||||
Conformance must compile real PBS through typed IR and production PBX into the production loader/VM. Required cases include vacancy versus zero, alias mutation, contextual literals, nested arrays, int/long bounds, lazy and single evaluation, multi-slot groups, constructors and contract dispatch, service identity, resource refusal and GC/ownership. Assembly-only probes are insufficient. Installed knowledge must package this specification and executable examples.
|
||||
|
||||
## Related specifications
|
||||
|
||||
- [Core syntax](../../../specs/compiler-languages/pbs/3.%20Core%20Syntax%20Specification.md)
|
||||
- [Static semantics](../../../specs/compiler-languages/pbs/4.%20Static%20Semantics%20Specification.md)
|
||||
- [Dynamic semantics](../../../specs/compiler-languages/pbs/9.%20Dynamic%20Semantics%20Specification.md)
|
||||
- [Existing type runtime alignment](input-and-existing-type-runtime-alignment.md)
|
||||
|
||||
[SDK List and Cursor](sdk-list-and-cursor.md) define logical size, growth and
|
||||
snapshot traversal above private fixed-length arrays. List capacity does not
|
||||
create logical elements; fixed array length does. Set/Map, equality and hashing
|
||||
policies remain separate concerns.
|
||||
|
||||
See [Runtime Random integration](runtime-random-integration.md) for opaque generator aliases in typed storage and captures.
|
||||
|
||||
|
||||
## Parameterized contract integration
|
||||
|
||||
[Generic contracts](generic-contracts.md) extend nominal contract declarations with explicit type arguments. Valid Array/Fn/optional/tuple compositions preserve their existing logical and physical rules after substitution. No generic-only Dynamic transport, view wrapper, altered resource limit or new runtime opcode is introduced.
|
||||
|
||||
[Generic structs and free functions](generic-structs-and-free-functions.md) reuse
|
||||
these contextual construction positions and storage rules. A generic T field can
|
||||
hold an optional value, but substituting an optional value type into array<T>
|
||||
remains invalid. Array's private packing does not become a generic argument ABI.
|
||||
|
||||
SDK collections add logical checks before physical Array operations and terminate
|
||||
logical refusals with TRAP_EXPLICIT. Their multi-instruction methods use the
|
||||
[List mutation-phase contract](sdk-list-and-cursor.md#mutation-preparation-visible-writes-and-faults)
|
||||
and [Linked contract](sdk-linked-and-cursor.md#mutation-phases-and-lifetime);
|
||||
per-instruction storage guarantees do not imply whole-method rollback.
|
||||
@@ -47,7 +47,7 @@ It must feel fluid for frame-driven gameplay code while remaining strict enough
|
||||
|
||||
- Runtime and bytecode authority override language preferences.
|
||||
- Closed VM compatibility is mandatory.
|
||||
- `FRAME_SYNC`-based execution semantics are preserved.
|
||||
- The existing synthetic frame lifecycle is preserved; PBS exposes no sync or coroutine construct.
|
||||
- Host API usage remains capability-gated and versioned.
|
||||
- Canonical host primitive bindings remain reserved to SDK/toolchain-controlled `declare host` surfaces.
|
||||
|
||||
|
||||
@@ -69,7 +69,7 @@ The following inputs are already fixed elsewhere and must not be contradicted he
|
||||
- Struct values are reference-like and identity-bearing in v1 core.
|
||||
- Service values are canonical module-owned singleton values in v1 core.
|
||||
- `declare const` values are compile-time constants rather than mutable runtime module storage.
|
||||
- `FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
- PBS uses the existing synthetic frame lifecycle. Runtime GC opportunities, including successful root return, follow the runtime contract; there is no PBS sync statement.
|
||||
- Core PBS v1 does not expose explicit lifetime-control syntax in ordinary user code.
|
||||
|
||||
## 6. Runtime Memory Spaces
|
||||
@@ -124,16 +124,9 @@ Contract values do not introduce a new user-visible identity distinct from the u
|
||||
|
||||
They are runtime views over an underlying identity-bearing value together with the selected contract implementation used for dispatch.
|
||||
|
||||
### 7.5 Callback values
|
||||
### 7.5 Function values and closures
|
||||
|
||||
Callback values are first-class callable values in PBS v1.
|
||||
|
||||
They may be assigned, passed, and returned, but callback identity is not promoted as a separate user-visible identity concept.
|
||||
|
||||
When formed through `bind(context, fn_name)`, a callback value retains:
|
||||
|
||||
- the target function,
|
||||
- and the same captured struct context identity without copying it.
|
||||
Closures are ordinary managed objects retaining their typed captures. Reachable closures may survive across frames; unreachable closures are eligible for GC. Their invocations do not suspend across frames. See [First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
|
||||
## 8. Identity, Aliasing, and Copy Behavior
|
||||
|
||||
@@ -201,11 +194,11 @@ The language does not promise:
|
||||
|
||||
### 9.3 Safepoint relationship
|
||||
|
||||
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
PBS uses the existing synthetic frame lifecycle. Runtime GC opportunities, including successful root return, follow the runtime contract; there is no PBS sync statement.
|
||||
|
||||
No user-visible program rule may depend on another safepoint existing.
|
||||
|
||||
Implementations may perform internal GC work outside `FRAME_SYNC` only if doing so creates no additional user-visible semantic effects.
|
||||
GC timing remains a runtime concern and introduces no user callback or observable scheduling operation.
|
||||
|
||||
### 9.4 Observability
|
||||
|
||||
@@ -250,15 +243,9 @@ The normatively relevant cost facts in PBS v1 are:
|
||||
- whether an operation crosses the host boundary,
|
||||
- whether an operation may trap.
|
||||
|
||||
### 11.2 `bind`
|
||||
### 11.2 Explicit capture storage
|
||||
|
||||
`bind(context, fn_name)` is retention-bearing and requires runtime storage sufficient to preserve:
|
||||
|
||||
- the callback target identity,
|
||||
- the captured context,
|
||||
- and the captured context's continued liveness while the callback value remains alive.
|
||||
|
||||
This document does not freeze the exact runtime layout used to implement that storage.
|
||||
Closure creation retains the values named in its explicit capture list, including shared object identities. Lifetime follows ordinary reachability and runtime resource limits. Captured bindings cannot be reassigned.
|
||||
|
||||
### 11.3 Non-allocation-bearing surfaces by themselves
|
||||
|
||||
@@ -335,3 +322,7 @@ This document is ready to move beyond temporary draft status only when:
|
||||
3. the VM heap versus host-memory boundary is normatively described,
|
||||
4. memory-related cost facts are specified well enough for diagnostics/tooling hooks,
|
||||
5. the remaining TODO items are reduced to editorial integration or future optional work rather than semantic uncertainty.
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
|
||||
@@ -99,7 +99,7 @@ The v1 AST must represent, at minimum, declaration families for:
|
||||
- `service`,
|
||||
- `error`,
|
||||
- `enum`,
|
||||
- `callback`,
|
||||
- structural `Fn` types and lambda expressions with explicit captures,
|
||||
- `declare global`,
|
||||
- `declare const`,
|
||||
- and declaration nodes required by barrel/linking flow.
|
||||
@@ -176,3 +176,23 @@ This document is healthy when:
|
||||
2. recovery/rejection invariants are explicit and test-backed,
|
||||
3. attribution invariants are explicit and test-backed,
|
||||
4. lowering preconditions consumed by `13` are unambiguous.
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
|
||||
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
Contract declarations and barrel items preserve ordered type-parameter names and individual spans. Applied type references preserve ordered child arguments and spans. Implements and as carry a complete target type reference. Semantic imported bindings retain the original declaration and importing lexical scope rather than inventing nominal origins. Existing visitors must traverse type arguments as well as inner/group/Fn/tuple children.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
|
||||
|
||||
## Concrete generic structs and free functions
|
||||
|
||||
Structs and free functions preserve ordered parameter declarations and spans. Explicit applied function references preserve type arguments and their source span. Implements preserves its binder, full applied owner and target. Substitution rewrites every field, signature, annotation and executable body/capture position with a declaration-local environment. Concrete application provenance retains original declaration, canonical logical arguments and requesting use; it is not an executable runtime template.
|
||||
|
||||
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
|
||||
@@ -258,7 +258,7 @@ The mandatory warning identity for this rule is `W_SEM_IGNORED_VALUE`.
|
||||
|
||||
Tooling may surface qualitative cost facts as warnings or notes, especially for:
|
||||
|
||||
- retention-bearing `bind`,
|
||||
- retention-bearing explicit closure captures,
|
||||
- observable copy-versus-alias semantics,
|
||||
- and host-boundary crossings.
|
||||
|
||||
@@ -296,3 +296,27 @@ This document is ready to move beyond temporary status only when:
|
||||
2. diagnostic identity, metadata, and attribution rules are explicit enough for conformance, including locale-agnostic token/template identity,
|
||||
3. the backend-originated failure boundary is explicit enough that PBS-facing diagnostics can be distinguished from internal tool failures,
|
||||
4. and cost/warning expectations are explicit where they are intended to be normative for v1.
|
||||
|
||||
## Existing values and input runtime alignment
|
||||
|
||||
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
|
||||
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
Parameterized contract diagnostics distinguish exact arity (E_SEM_CONTRACT_ARITY), undeclared/duplicate parameters (E_SEM_CONTRACT_PARAMETER), invalid applications (E_SEM_CONTRACT_ARGUMENT), incompatible or incomplete implementations (E_SEM_CONTRACT_SIGNATURE), duplicate pairs (E_SEM_CONTRACT_DUPLICATE_IMPLEMENTATION), invalid owners/modules (E_SEM_CONTRACT_OWNER / E_SEM_CONTRACT_OWNER_MODULE), invalid coercions (E_SEM_CONTRACT_COERCION), and bounded expansion/resource exhaustion (E_SEM_CONTRACT_EXPANSION). Barrel parameter disagreement uses E_LINK_CONTRACT_PARAMETERS. Existing invalid Array/Fn/optional/Self diagnostics also apply after substitution.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
|
||||
|
||||
## Concrete generic structs and free functions
|
||||
|
||||
Generic diagnostics distinguish duplicate/unbound parameters, exact arity, raw or improperly inferred application, unjustified symbolic capabilities, invalid substituted positions, constructor errors, collapsed overloads, invalid bound owners, overlap and bounded expansion. Preserve declaration and requesting-use locations with a short instantiation chain. Editor projections retain symbolic parameter, concrete argument and generic origin identities. Generated instance names and host stacks do not replace source explanations.
|
||||
|
||||
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
|
||||
@@ -238,3 +238,27 @@ At frontend `IRBackend` emission time:
|
||||
4. module order in the declaration MUST propagate the explicit dependency order already derived from resolved project/module data, without sorting by `FileId`, textual module name, or synthetic callable name,
|
||||
5. PBS MUST NOT emit module init, project-init wrapper, published frame wrapper, physical entrypoint, or boot guard,
|
||||
6. and common lifecycle assembly remains the owner of derived artifacts, including the published wrapper that becomes the physical entrypoint and owns the final frame return.
|
||||
|
||||
## Existing values and input runtime alignment
|
||||
|
||||
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
|
||||
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
The frontend substitutes each closed application and emits a concrete nominal Trait descriptor shared by equivalent uses. Distinct logical applications remain distinct despite shared physical carriers. Concrete implementation functions take the receiver first. CALL_TRAIT evaluates and roots the receiver before arguments, evaluates arguments left to right, then places the complete receiver/ImplementationId view after the argument groups as required by the runtime ABI. Preserve exact signatures, absence, ImplementationId zero, ownership, GC and quotas; generic calls do not add a Dynamic ABI or adaptation wrapper.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
|
||||
|
||||
## Concrete generic structs and free functions
|
||||
|
||||
Instantiate structs, free functions and owner-bound implementations within PBS before publishing executable descriptors. Registry receives concrete fields, signatures, bodies, capture groups and targets. Specialized free-function references use existing empty-environment Closure values; Fn remains structural. Preserve receiver identity, implementation zero, singletons, rooting, GC, ownership, evaluation/fault order and quotas. No generic Dynamic/boxing ABI, opcode, descriptor category or runtime instantiation engine is introduced.
|
||||
|
||||
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
|
||||
@@ -163,19 +163,17 @@ BarrelItem ::= BarrelFnItem
|
||||
| BarrelServiceItem
|
||||
| BarrelGlobalItem
|
||||
| BarrelConstItem
|
||||
| BarrelCallbackItem
|
||||
BarrelVisibility ::= 'mod' | 'pub'
|
||||
|
||||
BarrelFnItem ::= BarrelVisibility 'fn' Identifier ParamList ReturnAnn? ';'
|
||||
BarrelStructItem ::= BarrelVisibility 'struct' Identifier ';'
|
||||
BarrelContractItem ::= BarrelVisibility 'contract' Identifier ';'
|
||||
BarrelFnItem ::= BarrelVisibility 'fn' Identifier TypeParameters? ParamList ReturnAnn? ';'
|
||||
BarrelStructItem ::= BarrelVisibility 'struct' Identifier TypeParameters? ';'
|
||||
BarrelContractItem ::= BarrelVisibility 'contract' Identifier TypeParameters? ';'
|
||||
BarrelHostItem ::= BarrelVisibility 'host' Identifier ';'
|
||||
BarrelErrorItem ::= BarrelVisibility 'error' Identifier ';'
|
||||
BarrelEnumItem ::= BarrelVisibility 'enum' Identifier ';'
|
||||
BarrelServiceItem ::= BarrelVisibility 'service' Identifier ';'
|
||||
BarrelGlobalItem ::= BarrelVisibility 'global' Identifier ';'
|
||||
BarrelConstItem ::= BarrelVisibility 'const' Identifier ';'
|
||||
BarrelCallbackItem ::= BarrelVisibility 'callback' Identifier ';'
|
||||
```
|
||||
|
||||
Rules:
|
||||
@@ -191,11 +189,10 @@ Rules:
|
||||
- Multiple `fn` barrel entries with the same identifier are allowed only when signatures differ (overload set).
|
||||
- Barrel labels MAY differ from the implementation labels.
|
||||
- A `fn` barrel entry must resolve to exactly one declaration in module scope.
|
||||
- A `callback` barrel entry must resolve to exactly one top-level callback declaration in module scope.
|
||||
- A `host` barrel entry must resolve to exactly one top-level `declare host` declaration in module scope.
|
||||
- A `struct` barrel entry governs the visibility of the struct declaration and of all methods declared directly in that struct body.
|
||||
- A `host` barrel entry governs the visibility of the host declaration and of all method signatures declared directly in that host body.
|
||||
- A `service` barrel entry governs the visibility of the service declaration, its canonical singleton value, and all methods declared directly in that service body.
|
||||
- A `service` barrel entry governs the visibility of the service declaration, its canonical singleton value, and all methods and constants declared directly in that service body.
|
||||
- A `global` barrel entry governs visibility of one top-level `declare global` declaration.
|
||||
- Methods declared inside a `struct`, `host`, or `service` are never exported independently through `mod.barrel`.
|
||||
|
||||
@@ -210,7 +207,6 @@ pub host Gfx;
|
||||
pub enum GameState;
|
||||
pub service Physics;
|
||||
pub global Palette;
|
||||
pub callback TickCb;
|
||||
```
|
||||
|
||||
## 6. File grammar
|
||||
@@ -272,7 +268,7 @@ Rules:
|
||||
### 6.2 Top-level declarations
|
||||
|
||||
```ebnf
|
||||
TopDecl ::= TypeDecl | CallbackDecl | FunctionDecl | GlobalDecl | ConstDecl | ImplDecl
|
||||
TopDecl ::= TypeDecl | FunctionDecl | GlobalDecl | ConstDecl | ImplDecl
|
||||
```
|
||||
|
||||
Top-level `let` forms and top-level executable statements are forbidden.
|
||||
@@ -284,9 +280,11 @@ Top-level `let` forms and top-level executable statements are forbidden.
|
||||
|
||||
```ebnf
|
||||
TypeDecl ::= StructDecl | ServiceDecl | ContractDecl | HostDecl | BuiltinTypeDecl | ErrorDecl | EnumDecl
|
||||
StructDecl ::= 'declare' 'struct' Identifier '(' StructFieldList? ')' (StructMethodBody | ';')
|
||||
StructDecl ::= 'declare' 'struct' Identifier TypeParameters? '(' StructFieldList? ')' (StructMethodBody | ';')
|
||||
ServiceDecl ::= 'declare' 'service' Identifier ServiceBody
|
||||
ContractDecl ::= 'declare' 'contract' Identifier ContractBody
|
||||
ContractDecl ::= 'declare' 'contract' Identifier TypeParameters? ContractBody
|
||||
TypeParameters ::= '<' Identifier (',' Identifier)* '>'
|
||||
TypeArguments ::= '<' TypeRef (',' TypeRef)* '>'
|
||||
HostDecl ::= 'declare' 'host' Identifier HostBody
|
||||
BuiltinTypeDecl ::= AttrList? 'declare' 'builtin' 'type' Identifier '(' BuiltinFieldList? ')' BuiltinTypeBody
|
||||
ErrorDecl ::= 'declare' 'error' Identifier ErrorBody
|
||||
@@ -366,43 +364,33 @@ Rules:
|
||||
- Contract values are formed from struct values or service singleton values by explicit or contextual conversion, as defined by static semantics.
|
||||
- Structs do not have static methods in v1 core.
|
||||
|
||||
### 7.2 Callbacks
|
||||
### 7.2 First-class function values
|
||||
|
||||
```ebnf
|
||||
CallbackDecl ::= 'declare' 'callback' Identifier ParamList ReturnAnn? ';'
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- A callback declaration introduces a nominal callback type.
|
||||
- A callback declaration defines exactly one callable signature.
|
||||
- A callback declaration has no body.
|
||||
- A callback declaration is distinct from `contract` and `fn`.
|
||||
- A callback declaration may be exported through `mod.barrel` using `callback`.
|
||||
- Callback values may be formed either by assigning a compatible top-level `fn` or by using `bind(context, fn_name)` under a callback-typed context.
|
||||
Function types use `Fn(T1, T2) -> R`. Lambdas use `fn [captures](name: Type) -> Return { ... }`; `[]` and all signature annotations are mandatory. See [First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
|
||||
### 7.3 Services
|
||||
|
||||
```ebnf
|
||||
ServiceDecl ::= 'declare' 'service' Identifier ServiceBody
|
||||
ServiceBody ::= '{' ServiceMember* '}'
|
||||
ServiceMember ::= 'fn' Identifier ParamList ReturnAnn? Block
|
||||
ServiceMember ::= 'fn' Identifier ParamList ReturnAnn? Block | ConstDecl
|
||||
// SDK only: an IntrinsicCall-attributed service signature may end in ';'.
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare service Name { ... }` declares a nominal service type together with its canonical module-owned singleton value `Name`.
|
||||
- A service body contains only method declarations.
|
||||
- A service body contains method declarations and `declare const` members. SDK service intrinsic signatures may terminate with `;`; see [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
|
||||
- Service methods have an implicit receiver binding `this` of type `Self` and do not declare `this: Self` explicitly.
|
||||
- Services do not declare fields.
|
||||
- Services do not declare `ctor`.
|
||||
- Services are never constructed with `new`.
|
||||
- Service method visibility follows the `service` entry for that declaration in `mod.barrel`; service methods are never exported independently.
|
||||
- Service method visibility follows the `service` entry for that declaration in `mod.barrel`; service methods and constants are never exported independently.
|
||||
|
||||
### 7.4 Functions
|
||||
|
||||
```ebnf
|
||||
FunctionDecl ::= 'fn' Identifier ParamList ReturnAnn? Block
|
||||
FunctionDecl ::= 'fn' Identifier TypeParameters? ParamList ReturnAnn? Block
|
||||
ParamList ::= '(' (Param (',' Param)*)? ')'
|
||||
Param ::= Identifier ':' TypeRef
|
||||
ReturnAnn ::= '->' ReturnSpec
|
||||
@@ -464,9 +452,9 @@ Rules:
|
||||
|
||||
```ebnf
|
||||
TypeRef ::= OptionalType | TypePrimary
|
||||
TypePrimary ::= SelfType | SimpleType | NamedTupleType | GroupType | UnitType
|
||||
TypePrimary ::= FnType | SelfType | SimpleType | NamedTupleType | GroupType | UnitType
|
||||
SelfType ::= 'Self'
|
||||
SimpleType ::= Identifier
|
||||
SimpleType ::= Identifier TypeArguments?
|
||||
NamedTupleType ::= '(' NamedTupleField (',' NamedTupleField){0,5} ')'
|
||||
NamedTupleField ::= Identifier ':' TypeRef
|
||||
GroupType ::= '(' TypeRef ')'
|
||||
@@ -479,7 +467,7 @@ Rules:
|
||||
- Named tuple arity is 1..6 in v1 core syntax.
|
||||
- Tuple types in PBS core are always named.
|
||||
- Single-slot tuple types are allowed only in type/signature surface, not as tuple literals.
|
||||
- General user-defined generics are not part of PBS core v1.
|
||||
- User-defined parameterized declarations are supported for contracts. Generic structs and explicit generic free functions follow the concrete generic application extension linked below.
|
||||
- `SimpleType` may denote either a visible nominal type identifier or one of the predeclared builtin simple types.
|
||||
- The predeclared builtin simple types in v1 core are `int`, `float`, `bool`, and `str`.
|
||||
- Builtin simple types are always available in type position and do not require import.
|
||||
@@ -586,11 +574,13 @@ ArgList ::= Expr (',' Expr)*
|
||||
|
||||
Literal ::= IntLit | FloatLit | StringLit | BoolLit
|
||||
BoolLit ::= 'true' | 'false'
|
||||
PrimaryExpr ::= Literal | Identifier | ThisExpr | NewExpr | BindExpr | SomeExpr | NoneExpr | OkExpr | ErrExpr | UnitExpr | TupleExpr | GroupExpr | Block
|
||||
PrimaryExpr ::= Literal | Identifier TypeArguments? | ThisExpr | NewExpr | LambdaExpr | SomeExpr | NoneExpr | OkExpr | ErrExpr | UnitExpr | TupleExpr | GroupExpr | Block
|
||||
ThisExpr ::= 'this'
|
||||
NewExpr ::= 'new' NewTarget '(' ArgList? ')'
|
||||
NewTarget ::= Identifier ('.' Identifier)?
|
||||
BindExpr ::= 'bind' '(' Expr ',' Identifier ')'
|
||||
NewTarget ::= Identifier (TypeArguments | '<' '>')? ('.' Identifier)?
|
||||
LambdaExpr ::= 'fn' '[' CaptureNames? ']' ParamList '->' TypeRef Block
|
||||
CaptureNames ::= Identifier (',' Identifier)*
|
||||
FnType ::= 'Fn' '(' (TypeRef (',' TypeRef)*)? ')' '->' TypeRef
|
||||
SomeExpr ::= 'some' '(' Expr ')'
|
||||
NoneExpr ::= 'none'
|
||||
OkExpr ::= 'ok' '(' Expr ')'
|
||||
@@ -622,7 +612,7 @@ Rules:
|
||||
- `new Type.ctorName(args...)` is the canonical named-constructor surface.
|
||||
- Struct construction arguments are positional and follow the declared struct field order.
|
||||
- `as` is reserved in expressions for explicit contract-view conversion only; it does not denote a general cast surface in v1 core.
|
||||
- The right operand of expression-form `as` is a simple contract identifier already visible in scope, never a qualified module path.
|
||||
- A contract-view `as` target is a visible contract type, including explicit arguments such as `Identity<int>`, never a qualified module path. Existing numeric conversions retain their value-alignment rules.
|
||||
- `this` is an implicit receiver name available only inside struct method, service method, and `ctor` bodies.
|
||||
- `Self` is valid only inside struct method declarations, service method declarations, and `ctor` declarations.
|
||||
- `apply` is right-associative: `f1 apply f2 apply x` parses as `f1 apply (f2 apply x)`.
|
||||
@@ -635,9 +625,6 @@ Rules:
|
||||
- Tuple expressions may be written with explicit labels (`(a: 1, b: 2)`) or positional sugar (`(1, 2)`).
|
||||
- Positional tuple expression sugar requires an expected named tuple shape supplied by context.
|
||||
- No single-slot tuple literal exists in v1 core syntax.
|
||||
- `bind(context, fn_name)` is the canonical surface for explicit callback context binding.
|
||||
- `bind(context, fn_name)` binds only the first parameter of `fn_name`.
|
||||
- The second operand of `bind` is a function identifier, not an arbitrary expression.
|
||||
- Mixing labeled and unlabeled tuple items in the same `TupleExpr` is a syntax error.
|
||||
- Member selection of a struct, service, host, or contract method is valid only as an immediate call target; bare method extraction such as `let m = s.compute;` is invalid.
|
||||
|
||||
@@ -677,14 +664,12 @@ Diagnostics that require name resolution, overload resolution, or type context a
|
||||
- invalid `ok(...)` construction form,
|
||||
- invalid `err(...)` construction form,
|
||||
- use of `ok(...)` or `err(...)` outside allowed result-flow positions,
|
||||
- invalid `bind(...)` construction form,
|
||||
- invalid `else` extraction form,
|
||||
- invalid `if` expression form,
|
||||
- invalid `switch` expression form,
|
||||
- invalid `for` loop form,
|
||||
- invalid `new` construction form,
|
||||
- invalid enum case path,
|
||||
- invalid callback declaration shape,
|
||||
- invalid struct field access modifier surface,
|
||||
- invalid struct method declaration shape,
|
||||
- invalid service method declaration shape,
|
||||
@@ -923,7 +908,6 @@ This section is the canonical reference example set for PBS v1 syntax.
|
||||
It consolidates the primary surface forms used by tooling and conformance for:
|
||||
|
||||
- `apply` and call sugar,
|
||||
- `bind` and nominal callbacks,
|
||||
- overloads that differ by return shape,
|
||||
- `optional`,
|
||||
- `result<Error>`,
|
||||
@@ -1019,45 +1003,21 @@ declare service Physics {
|
||||
}
|
||||
```
|
||||
|
||||
### 15.6 Nominal callback
|
||||
### 15.6 Function values
|
||||
|
||||
```pbs
|
||||
declare callback TickCb(dt: int) -> void;
|
||||
|
||||
fn on_tick(dt: int) -> void {
|
||||
let _ = dt;
|
||||
}
|
||||
|
||||
fn install(cb: TickCb) -> void {
|
||||
cb apply 16;
|
||||
cb(16);
|
||||
}
|
||||
|
||||
fn demo_callback() -> void {
|
||||
let cb: TickCb = on_tick;
|
||||
install(cb);
|
||||
fn twice(x: int) -> int { return x * 2; }
|
||||
fn demo_function() -> int {
|
||||
let f: Fn(int) -> int = twice;
|
||||
return f(21);
|
||||
}
|
||||
```
|
||||
|
||||
### 15.7 Bound callback
|
||||
### 15.7 Explicit captures
|
||||
|
||||
```pbs
|
||||
declare callback UpdateCb(dt: int) -> void;
|
||||
|
||||
declare struct Enemy(pub hp: int);
|
||||
|
||||
fn enemy_tick(self: Enemy, dt: int) -> void {
|
||||
let _ = self.hp;
|
||||
let _ = dt;
|
||||
}
|
||||
|
||||
fn install_update(cb: UpdateCb) -> void {
|
||||
cb apply 16;
|
||||
}
|
||||
|
||||
fn demo_bind(enemy: Enemy) -> void {
|
||||
let cb: UpdateCb = bind(enemy, enemy_tick);
|
||||
install_update(cb);
|
||||
fn create_adder(n: int) -> Fn(int) -> int {
|
||||
return fn [n](x: int) -> int { return n + x; };
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1236,3 +1196,25 @@ fn test(e: Enum) -> str {
|
||||
return label;
|
||||
}
|
||||
```
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
|
||||
Retired `declare callback`, callback exports and `bind(...)` are rejected. They do not provide alternative spellings for Fn or lambdas.
|
||||
|
||||
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
Parameterized contracts use explicit angular arguments in annotations, nested types, implements and as. Barrels export the ordered parameter list. Raw generic uses, empty argument lists and default arguments are invalid; existing contextual closers and Array construction sugars remain unchanged.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
|
||||
|
||||
## Concrete generic structs and free functions
|
||||
|
||||
Struct and module-level free-function declarations and their barrel items accept ordered type parameters. Explicit function applications are reference expressions; calls use existing parentheses/apply. Generic construction supports explicit arguments and contextual diamond/omission. Owner-bound `implements` accepts its own parameter binder and a full applied owner. Independent method parameters, function diamond/inference and polymorphic Fn remain invalid. The owner specification defines exact arity, comparison disambiguation and recovery.
|
||||
|
||||
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
|
||||
@@ -38,17 +38,17 @@ PBS distinguishes at least:
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare struct`, `declare service`, `declare contract`, `declare error`, `declare enum`, `declare callback`, and `declare builtin type` introduce names in the type namespace.
|
||||
- `declare struct`, `declare service`, `declare contract`, `declare error`, `declare enum`, and `declare builtin type` introduce names in the type namespace.
|
||||
- `declare host` introduces names in the host-owner namespace.
|
||||
- `let`, parameters, `declare const`, and `declare global` introduce names in the value namespace.
|
||||
- `declare service Name` also introduces the canonical singleton value `Name` in the value namespace.
|
||||
- Top-level `fn`, service methods, and host methods participate in the callable namespace.
|
||||
- `fn` declarations are not first-class values in v1 core and therefore do not become ordinary value expressions.
|
||||
- `bind(...)` is a callback-formation construct, not a general function-value construct.
|
||||
- Named top-level functions can form first-class Fn values with structural signatures.
|
||||
- Function values use structural `Fn` types and explicit lambda captures.
|
||||
- `declare host` declarations are reserved to SDK/toolchain-controlled modules and are not formable in ordinary user-authored PBS source.
|
||||
- `declare builtin type` declarations are reserved to SDK/toolchain-controlled modules and are not formable in ordinary user-authored PBS source.
|
||||
- A host owner name is not an ordinary value expression in v1 core; it is used only as a qualified host-call owner.
|
||||
- The builtin simple types `int`, `float`, `bool`, and `str` are always present in the type namespace.
|
||||
- The builtin simple types `int`, `long`, `float`, `bool`, and `str` are always present in the type namespace.
|
||||
- Builtin simple types are resolved without import or declaration.
|
||||
- User-authored type declarations must not reuse builtin simple type names.
|
||||
|
||||
@@ -96,7 +96,7 @@ Rules:
|
||||
- The `Host` attribute syntax itself is not exported as runtime metadata; instead, its canonical identity participates in PBX host-binding emission as defined by the Host ABI Binding specification.
|
||||
- `BuiltinType` is valid only on a reserved top-level `declare builtin type` declaration.
|
||||
- `BuiltinConst` is valid only on a reserved top-level `declare const` declaration that omits an initializer.
|
||||
- `IntrinsicCall` is valid only on a method signature declared directly inside a reserved `declare builtin type` body.
|
||||
- `IntrinsicCall` is valid on a method signature inside a reserved `declare builtin type` body or an SDK service body. SDK service signatures have no implementation body and bind their exact declared argument/result carriers to the common intrinsic catalog.
|
||||
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
|
||||
- `Init` and `Frame` are consumed by lifecycle analysis and lowering rather than by ordinary runtime reflection.
|
||||
- `InitAllowed` is consumed by init-time host-admission analysis and does not become ordinary userland metadata.
|
||||
@@ -207,12 +207,12 @@ Rules:
|
||||
- Each semantic parameter record MUST carry its canonical source/API name, zero-based order, type when known, and origin/source sufficient for implementation and diagnostics.
|
||||
- A struct method is identified by `(struct type, method name, input tuple shape excluding the receiver slot, output tuple shape)`.
|
||||
- A contract value is identified at the type level by its contract type and at runtime by an underlying concrete struct instance or service singleton value plus its selected implementation.
|
||||
- A callback declaration defines a nominal callable type with exactly one input/output tuple shape.
|
||||
- A function type defines an ordered parameter/result signature independent of names or captures.
|
||||
- A service method is identified by `(service name, method name, input tuple shape, output tuple shape)`.
|
||||
- A host method is identified by `(host owner name, method name, input tuple shape, output tuple shape)` within the PBS declaration surface.
|
||||
- A builtin intrinsic method is identified within PBS declaration surface by `(builtin type name, method name, input tuple shape, output tuple shape)` and lowers further by canonical builtin/intrinsic metadata.
|
||||
- A top-level `fn` is identified by `(name, input tuple shape, output tuple shape)`.
|
||||
- A callback value is identified at the type level by its declared callback type and signature.
|
||||
- Function value compatibility uses its structural signature.
|
||||
- Contract signatures and barrel signatures must preserve the same callable shape.
|
||||
- Canonical host primitive identity and binding are governed by the Host ABI Binding specification rather than by ordinary v1 core declaration identity alone.
|
||||
- The compiler semantic model is the canonical owner of callable parameter names for completion, signature help, hover, diagnostics, and other editor-facing surfaces.
|
||||
@@ -312,7 +312,6 @@ Rules:
|
||||
- A non-builtin `declare const` initializer must not use:
|
||||
- callable application or call sugar,
|
||||
- `new`,
|
||||
- `bind(...)`,
|
||||
- `some(...)` or `none`,
|
||||
- tuple expressions,
|
||||
- block expressions,
|
||||
@@ -350,6 +349,11 @@ Rules:
|
||||
|
||||
### 3.6 Structs, services, methods, and contracts
|
||||
|
||||
Service constants follow [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
|
||||
They are immutable members exported with their service. Qualified constant reads
|
||||
materialize the constant without constructing a singleton or invoking a method.
|
||||
|
||||
|
||||
Rules:
|
||||
|
||||
- Struct values are heap-backed reference values in v1 core.
|
||||
@@ -384,7 +388,7 @@ Rules:
|
||||
- Services do not have fields.
|
||||
- Services do not declare named constructors and are never targets of `new`.
|
||||
- Contract implementations do not inject their methods into the direct method namespace of the concrete struct or service.
|
||||
- `implements Contract for Owner using s { ... }` is unique per `(Contract, Owner)` pair, where `Owner` is a declared struct or service.
|
||||
- `implements Contract for Owner using s { ... }` is unique per `(instantiated Contract, Owner)` pair, where `Owner` is a declared struct or service.
|
||||
- A contract for a struct or service may be implemented only in the module where that owner itself is declared.
|
||||
- Contracts may be declared in other modules and implemented for the local struct or service in its owner module.
|
||||
- An `implements` block has no independent visibility; its observability follows the visibility of the owner declaration, and the contract must also be nameable at the use site.
|
||||
@@ -392,7 +396,7 @@ Rules:
|
||||
- A struct value or service singleton value may be coerced to a contract value when exactly one visible `implements Contract for Owner ...` applies.
|
||||
- Contract coercion may happen by explicit `expr as ContractType` or by contextual typing in assignments, parameter passing, and returns.
|
||||
- `as` in expression position is reserved for explicit contract coercion only; no other cast semantics exist in v1 core.
|
||||
- The contract name in `expr as ContractName` must be a simple visible identifier resolved through ordinary scope and import rules.
|
||||
- The contract in `expr as ContractType` is resolved through ordinary scope/import rules and may carry explicit type arguments. Aliases preserve declaration identity.
|
||||
- A contract value carries the underlying struct reference or service singleton value together with the selected contract implementation for runtime dispatch.
|
||||
- Calling `contractValue.method(...)` uses dynamic dispatch through the contract value.
|
||||
- Calling `structValue.contractMethod(...)` is not valid unless that method is also declared directly on the struct.
|
||||
@@ -436,70 +440,9 @@ fn demo() -> int {
|
||||
}
|
||||
```
|
||||
|
||||
### 3.7 Nominal callbacks
|
||||
### 3.7 Structural function values
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare callback Name(params...) -> R;` introduces a nominal callback type `Name`.
|
||||
- A callback type is not a `fn`, and a `fn` declaration does not implicitly define a callback type.
|
||||
- A value of callback type may be formed only from a compatible top-level `fn` in v1 core.
|
||||
- A value of callback type may also be formed by `bind(context, fn_name)` when the surrounding static type context expects a callback type.
|
||||
- Service methods are not assignable to callback values in v1 core.
|
||||
- Host methods are not assignable to callback values in v1 core.
|
||||
- Callback values do not capture local environment implicitly.
|
||||
- Assignment of a top-level `fn` to a callback type succeeds only when exactly one visible overload matches the callback signature.
|
||||
- `bind(context, fn_name)` succeeds only when exactly one visible top-level `fn` overload matches after consuming the first parameter with `context`.
|
||||
- Valid expected callback contexts for `bind(context, fn_name)` include variable initialization with an explicit callback type, assignment to an explicitly typed callback location, argument passing to a callback-typed parameter, and return from a callback-typed function.
|
||||
- The context expression in `bind(context, fn_name)` is evaluated once at bind time and stored explicitly in the resulting callback value.
|
||||
- When that stored context is identity-bearing, the resulting callback preserves the same captured identity rather than copying an independent underlying object.
|
||||
- `bind(context, fn_name)` does not introduce general closures; it is explicit partial binding of the first parameter only.
|
||||
- Callback compatibility ignores labels and compares ordered input/output slot types plus the return-surface kind.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
declare callback TickCb(dt: int) -> void;
|
||||
|
||||
fn on_tick(dt: int) -> void {
|
||||
}
|
||||
|
||||
fn install_tick() -> void {
|
||||
let cb: TickCb = on_tick;
|
||||
let _ = cb;
|
||||
}
|
||||
```
|
||||
|
||||
Bound example:
|
||||
|
||||
```pbs
|
||||
declare callback UpdateCb(dt: int) -> void;
|
||||
|
||||
declare struct Enemy(hp: int);
|
||||
|
||||
fn update_enemy(self: Enemy, dt: int) -> void {
|
||||
}
|
||||
|
||||
fn install_update(enemy: Enemy) -> void {
|
||||
let cb: UpdateCb = bind(enemy, update_enemy);
|
||||
let _ = cb;
|
||||
}
|
||||
```
|
||||
|
||||
Ambiguous overload example:
|
||||
|
||||
```pbs
|
||||
declare callback TickCb(dt: int) -> void;
|
||||
|
||||
fn tick(dt: int) -> void {
|
||||
}
|
||||
|
||||
fn tick(time: int) -> void {
|
||||
}
|
||||
|
||||
fn install_tick() -> void {
|
||||
let cb: TickCb = tick; // error: ambiguous overloaded fn assignment
|
||||
}
|
||||
```
|
||||
[First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md) defines structural Fn compatibility, explicit snapshot captures and lambda typing. Assignment of a named function requires exactly one matching overload. Bare method extraction remains invalid; use an explicit receiver-capturing lambda.
|
||||
|
||||
### 3.8 Canonical application
|
||||
|
||||
@@ -801,7 +744,6 @@ At minimum, deterministic static diagnostics are required for:
|
||||
- invalid contract coercion from concrete struct or service value,
|
||||
- unresolved barrel function signature after label-insensitive matching,
|
||||
- unresolved host barrel entry,
|
||||
- unresolved callback barrel entry,
|
||||
- invalid enum case path,
|
||||
- invalid enum intrinsic member call,
|
||||
- invalid named constructor target,
|
||||
@@ -811,9 +753,6 @@ At minimum, deterministic static diagnostics are required for:
|
||||
- ambiguous overloaded top-level `fn` assignment to callback type,
|
||||
- attempted assignment of service method to callback type,
|
||||
- attempted assignment of host method to callback type,
|
||||
- use of `bind(...)` without an expected callback type,
|
||||
- incompatible `bind(...)` context type for callback target,
|
||||
- ambiguous overloaded top-level `fn` target in `bind(...)`,
|
||||
- `apply` on a non-callable target,
|
||||
- arity mismatch in `apply`,
|
||||
- argument type mismatch in `apply`,
|
||||
@@ -874,3 +813,27 @@ At minimum, deterministic static diagnostics are required for:
|
||||
- invalid optional intrinsic member call,
|
||||
- invalid builtin intrinsic member call,
|
||||
- member projection on a missing named output label.
|
||||
|
||||
## Existing values and input runtime alignment
|
||||
|
||||
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
|
||||
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
Application identity combines the defining nominal declaration with ordered canonical logical arguments after alias resolution. Applications are invariant. Substitution preserves existing type-position restrictions, names, labels and complete groups across Array, Fn, optional, tuples and nested contracts. A struct/service may implement several applications, with complete unique implementations in its owner module. Finite instance recursion is accepted within resource limits; unbounded expansion receives a bounded diagnostic.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
|
||||
|
||||
## Concrete generic structs and free functions
|
||||
|
||||
Templates are checked symbolically in definition scope. Required concrete owners validate all methods and constructors, including unused methods. Substitute complete bodies and applied Self; preserve position restrictions, invariant nominal/phantom identity and logical groups. Explicit function applications filter generic overloads by type arity; ordinary calls never infer them. Bound owner implementations require complete exact signatures and symbolic overlap rejection before use. Finite recursive applications are anchored; expanding type/body families are bounded errors.
|
||||
|
||||
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
|
||||
+33
@@ -537,3 +537,36 @@ The current PBS design direction is:
|
||||
10. `declare host` remains reserved to stdlib/toolchain interface modules.
|
||||
11. Reserved attributes such as `[Host(...)]` are compile-time metadata, not runtime objects.
|
||||
12. The compiler consumes `Host` metadata to produce runtime-facing host-binding artifacts defined elsewhere.
|
||||
|
||||
## Editorial exposure of external sources
|
||||
|
||||
SDK/core remain reserved bundled sources. Editorial navigation MUST NOT extract
|
||||
or copy them into a project or disk cache. Compiler-known dependency sources,
|
||||
including those under `.workspace`, and SDK/core are exposed as read-only external
|
||||
documents with revision-consistent text, ranges and frontend semantic context.
|
||||
Hover and continued definition use that retained context. Compilation, module
|
||||
admission, ABI and linking rules are unchanged. See Compiler Spec 23 §8.3 and
|
||||
Studio Spec 11 for the consumer protocol and atomic write restrictions (DEC-0062).
|
||||
|
||||
PBS project hover, definition, completion and signature help MUST share receiver
|
||||
type resolution using PBS expression parsing and semantic overload rules. Coverage
|
||||
includes function/method chains with known return types, nested call arguments,
|
||||
explicitly typed and inferred variables, parentheses, completion after a trailing
|
||||
dot and signature help during incomplete arguments. An unrelated parse error MUST
|
||||
NOT invalidate a recoverable receiver. Unknown or ambiguous receivers MUST NOT
|
||||
invent a type or overload. Indexing/operator-produced receivers are outside the
|
||||
new coverage; existing behavior MUST NOT regress.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
A barrel exports a parameterized contract declaration with the same ordered parameters as its source declaration. Imported bindings retain the original declaration and lexical source scope, including aliases in signatures of dependencies. A local alias never creates another nominal type. Implementations remain in the declaring module of the concrete struct/service owner.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
|
||||
|
||||
## Concrete generic structs and free functions
|
||||
|
||||
Generic struct/function barrels export declarations and ordered parameters, including complete function signatures, rather than enumerated specializations. Imports and aliases preserve nominal origins and definition-scoped bodies/private helpers. Specializations are shared across equivalent uses and do not export private dependencies. SDK and program sources use the same language machinery.
|
||||
|
||||
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
|
||||
+9
-5
@@ -263,13 +263,13 @@ Example:
|
||||
```pbs
|
||||
[BuiltinType(name="color", version=1)]
|
||||
declare builtin type Color(
|
||||
pub raw: int,
|
||||
pub raw: long,
|
||||
);
|
||||
|
||||
[BuiltinType(name="pixel", version=1)]
|
||||
declare builtin type Pixel(
|
||||
pub x: int,
|
||||
pub y: int,
|
||||
pub x: long,
|
||||
pub y: long,
|
||||
pub color: Color,
|
||||
);
|
||||
```
|
||||
@@ -277,13 +277,13 @@ declare builtin type Pixel(
|
||||
Canonical semantic layout:
|
||||
|
||||
```text
|
||||
Pixel -> [int, int, Color]
|
||||
Pixel -> [long, long, Color]
|
||||
```
|
||||
|
||||
Canonical flattened slot layout:
|
||||
|
||||
```text
|
||||
Pixel -> [int, int, int]
|
||||
Pixel -> [long, long, long]
|
||||
```
|
||||
|
||||
## 13. Member Categories
|
||||
@@ -560,3 +560,7 @@ The current temporary contract is:
|
||||
7. `BuiltinConst(target, name, version)` exposes VM-owned builtin constants through reserved top-level `declare const` shells.
|
||||
8. Builtin projections, constants, and intrinsic calls must not lower through `SYSC`, `HOSTCALL`, or `SYSCALL`.
|
||||
9. Runtime-facing intrinsic artifacts are distinct from host-binding artifacts.
|
||||
|
||||
## Existing values and input runtime alignment
|
||||
|
||||
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
|
||||
|
||||
+43
@@ -323,3 +323,46 @@ The current Studio direction is:
|
||||
4. the compiler should use explicit abstractions such as `StdlibEnvironment` and `StdlibModuleResolver`,
|
||||
5. stdlib interface modules are parsed with the normal PBS parser and validated in interface-module mode,
|
||||
6. reserved attributes such as `[Host(...)]` are extracted as compile-time metadata for later lowering.
|
||||
|
||||
## 13. Installed Language and SDK Reference Bundle
|
||||
|
||||
The PBS frontend distribution MUST provide local, indexed documentation through
|
||||
the frontend reference-provider contract. This packaging does not create a new
|
||||
normative specification: the numbered PBS documents in their owner directory
|
||||
remain authoritative, and the quickstart/example remain informative.
|
||||
|
||||
The build MUST generate the reference index from owner-maintained sources:
|
||||
|
||||
- this directory's numbered specifications and README quickstart;
|
||||
- the frontend's example manifest, PBS source and barrel;
|
||||
- the actual packaged SDK `.pbs` and `.barrel` files, including their documentation.
|
||||
|
||||
Generated copies MUST NOT be edited independently. SDK declarations MUST NOT be
|
||||
rewritten to manufacture a documentation-only API. The index MUST contain stable
|
||||
reference identities, titles, kinds, packaged-resource identities, content hashes
|
||||
and applicable SDK major/target. The loader MUST reject missing/corrupted indexed
|
||||
content instead of advertising unreadable references or consulting a checkout.
|
||||
|
||||
For the current distribution, SDK/example selection is Game / major 1. The general
|
||||
PBS specifications remain available for other selections, but Game SDK 1 references
|
||||
MUST NOT be presented as another SDK version or target. An absent SDK reference
|
||||
set MUST be explicit to consumers.
|
||||
|
||||
Language, compiler, SDK and index-schema versions remain independent. General
|
||||
specification references use an unknown release version when owner release
|
||||
metadata is absent; SDK-associated references identify the installed SDK major.
|
||||
Content hashes identify the packaged texts, not a semantic language release.
|
||||
|
||||
Conformance MUST include reading all indexed references from installed JARs outside
|
||||
the repository and compiling the shipped example against the installed SDK. No
|
||||
network access or source checkout may be required by that reference-read path.
|
||||
|
||||
## Editorial exposure of external sources
|
||||
|
||||
SDK/core remain reserved bundled sources. Editorial navigation MUST NOT extract
|
||||
or copy them into a project or disk cache. Compiler-known dependency sources,
|
||||
including those under `.workspace`, and SDK/core are exposed as read-only external
|
||||
documents with revision-consistent text, ranges and frontend semantic context.
|
||||
Hover and continued definition use that retained context. Compilation, module
|
||||
admission, ABI and linking rules are unchanged. See Compiler Spec 23 §8.3 and
|
||||
Studio Spec 11 for the consumer protocol and atomic write restrictions (DEC-0062).
|
||||
|
||||
@@ -67,7 +67,7 @@ This document integrates the following accepted decisions:
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- PBS prioritizes determinism and compatibility over ergonomics when the two conflict.
|
||||
- `FRAME_SYNC`-based execution semantics remain preserved.
|
||||
- The existing synthetic frame lifecycle remains preserved; PBS exposes no sync or coroutine construct.
|
||||
- No non-deterministic async execution model is part of PBS v1.
|
||||
- Function application is defined on the canonical `apply` surface, with call sugar desugaring to `apply`.
|
||||
- `optional T` function fallthrough yields `none`.
|
||||
@@ -93,7 +93,7 @@ User-visible sequencing is defined by:
|
||||
|
||||
VM-internal frame layout, temporary storage, and lowering steps are not observable unless they change one of the semantic effects above.
|
||||
|
||||
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
PBS uses the existing synthetic frame lifecycle. Runtime GC opportunities, including successful root return, follow the runtime contract; there is no PBS sync statement.
|
||||
|
||||
## 6.1 Lifecycle bootstrap
|
||||
|
||||
@@ -161,7 +161,7 @@ The following expressions are evaluated exactly once where they appear:
|
||||
- the payload expression of `some(expr)`,
|
||||
- the operand of `expr!`,
|
||||
- the operand of `handle expr { ... }`,
|
||||
- the context expression of `bind(context, fn_name)`,
|
||||
- explicit closure capture values,
|
||||
- call receivers, callees, and argument expressions as required by the call rule above.
|
||||
|
||||
## 8. Blocks and Abrupt Completion
|
||||
@@ -253,7 +253,7 @@ For the remap-only case, a short form such as `E1.case -> E2.case` is sugar for
|
||||
|
||||
`handle` does not intercept or convert traps.
|
||||
|
||||
## 11. `apply`, Call Sugar, and `bind`
|
||||
## 11. Function application and closures
|
||||
|
||||
### 11.1 Canonical role of `apply`
|
||||
|
||||
@@ -279,22 +279,9 @@ If a callable returns:
|
||||
- `optional<P>`, extraction remains explicit through `else`,
|
||||
- `result<E> P`, propagation or processing remains explicit through `!` or `handle`.
|
||||
|
||||
### 11.3 `bind`
|
||||
### 11.3 Closure creation and invocation
|
||||
|
||||
`bind(context, fn_name)` is the explicit callback-formation mechanism in PBS v1.
|
||||
|
||||
It:
|
||||
|
||||
- evaluates `context` exactly once,
|
||||
- captures the same struct context identity without copying it,
|
||||
- attaches that context to the resolved top-level function target,
|
||||
- produces a callback value whose invocation behaves as if the target function were called with the captured context as its first argument.
|
||||
|
||||
At the language-semantics level, `bind` is trap-free.
|
||||
|
||||
Incompatible binding shape remains a compile-time matter rather than a runtime failure mode.
|
||||
|
||||
Retention and storage consequences of `bind` belong to `Memory and Lifetime Specification.md`.
|
||||
Explicit capture lists snapshot values at creation. Object references retain identity. Calls complete within the current frame; objects may remain reachable between frames. See [First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
|
||||
## 12. Branch Selection
|
||||
|
||||
@@ -387,3 +374,11 @@ This document is ready to move beyond temporary draft status only when:
|
||||
3. host-call interaction rules are stated without relying on informal prose elsewhere,
|
||||
4. the document can drive runtime conformance tests without decision backfill,
|
||||
5. the remaining TODO items are reduced to editorial integration rather than semantic uncertainty.
|
||||
|
||||
## Existing values and input runtime alignment
|
||||
|
||||
The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-and-existing-type-runtime-alignment.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
|
||||
@@ -2,6 +2,73 @@
|
||||
|
||||
This directory contains the normative PBS specification set.
|
||||
|
||||
## Installed Quickstart (Informative)
|
||||
|
||||
This guide and the numbered specifications are packaged with the PBS frontend.
|
||||
They describe the installed distribution, not a promise of a numbered language
|
||||
release. A spec's `Draft v1` status is not the compiler version or SDK version.
|
||||
The project manifest selects the SDK major with `stdlib`; current packaged
|
||||
Game SDK resources use major `1`. Unknown language/compiler versions remain
|
||||
unknown in Studio's context.
|
||||
|
||||
For an external coding agent:
|
||||
|
||||
1. Request `studio_project_context` for the absolute root of the open project.
|
||||
2. Read `pbs:quickstart`, `pbs:spec:3` (syntax), `pbs:spec:4` (static semantics)
|
||||
and the relevant SDK reference IDs returned in that context. Continue pages
|
||||
until `nextOffset` is null. References are IDs, not filesystem paths.
|
||||
3. Inspect the project and its dependencies before changing source. Only edit
|
||||
the project's editable scope, excluding read-only SDK/external libraries.
|
||||
4. Use the installed LSP and compiler to check changes. When the corresponding
|
||||
MCP tools are available, acquire project control after the developer's DEV
|
||||
grant, then use the advertised language/build tools. Documentation reads do
|
||||
not require that grant. Missing tools/capabilities must not be assumed.
|
||||
5. Build and test small changes. Runtime execution also requires a compatible
|
||||
configured runtime; reading references does not install one.
|
||||
|
||||
### Small Game Project
|
||||
|
||||
The installed example has three separately indexed files:
|
||||
|
||||
- `pbs:example:game:1:prometeu.json`: a Game manifest with `language: pbs`,
|
||||
`stdlib: 1` (serialized as a string), and no external dependencies;
|
||||
- `pbs:example:game:1:src/main.pbs`: `[Init]` and `[Frame]` functions drawing a
|
||||
moving rectangle through `Gfx` and constructing colors through `Color`;
|
||||
- `pbs:example:game:1:src/mod.barrel`: the module's public declarations.
|
||||
|
||||
Copy these reference texts to the corresponding paths only when creating that
|
||||
example in your editable project. The example is compiled in the test suite;
|
||||
it is not a complete game or a claim that every requested gameplay abstraction
|
||||
already exists. If a project has no external dependencies, no registry is needed.
|
||||
For dependencies, follow the installed compiler's manifest/registry requirements.
|
||||
|
||||
PBS source lives under `src` for the installed provider. Functions use `fn`,
|
||||
typed parameters and `->` return types. `let` declares a local binding;
|
||||
`declare global` declares persistent global state. Imports name exports and a
|
||||
module address, for example `import { Gfx } from @sdk:gfx;`. A `mod.barrel`
|
||||
describes a module's public surface. Read the syntax/static-semantics chapters
|
||||
for exact rules rather than inferring compatibility with another language.
|
||||
|
||||
### SDK Navigation and Limits
|
||||
|
||||
`pbs:sdk:game:1:sdk/gfx/main.pbs` exposes the actual installed Gfx source,
|
||||
including documentation comments and signatures. Its `mod.barrel` reference
|
||||
defines exports. Equivalent references exist for `sdk/asset`, `sdk/composer`,
|
||||
`sdk/input`, `sdk/log`, `sdk/math`, `sdk/mathf`, `sdk/random`, and `core/color`. Read those interfaces before calling
|
||||
them. Game SDK 1 does not currently ship `audio` or `core/math` modules.
|
||||
|
||||
Ordinary game source uses public services such as `Gfx`; it must not manufacture
|
||||
host bindings or mutate SDK declarations. Asset/composer workflows require their
|
||||
real asset/scene data and runtime capabilities. Reference availability does not
|
||||
guarantee those project resources exist. SDK or tooling limitations should be
|
||||
reported for separate work, not patched in read-only dependencies.
|
||||
|
||||
The reference index is generated from these owner-maintained documents and the
|
||||
frontend's SDK/example resources. The index schema revision is not a language
|
||||
version. Source hashes bind texts to the installed bundle; no repository checkout
|
||||
or network is needed to read them. The numbered specifications remain normative;
|
||||
this onboarding section and example are explanatory, not a second specification.
|
||||
|
||||
## Purpose
|
||||
|
||||
Specs define the official PBS language/frontend contract.
|
||||
@@ -68,3 +135,14 @@ That means:
|
||||
- PBS semantic highlight resources belong to PBS rather than to Studio or LSP,
|
||||
- PBS publishes that contract through `FrontendSpec`,
|
||||
- and Studio/LSP consume that contract without becoming owners of PBS semantic presentation assets.
|
||||
|
||||
The `@sdk:random` module exports `Random` and `random`. Use an explicit long seed;
|
||||
copying a generator shares its state. Read `pbs:spec:runtime-random-integration.md`
|
||||
and `pbs:example:game:1:src/random.pbs` for the exact contract and a small example.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
Parameterized nominal contracts, concrete frontend specialization, implementation/coercion rules, composition, recursion and production conformance are defined by the owner specification.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
# Bytecode and PBX Mapping Specification
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
Status: Draft v1 (Backend Baseline)
|
||||
Applies to: mapping from lowered/optimized backend programs into PBX sections, bytecode-facing artifacts, and source-to-artifact invariants required by loader/verifier/runtime
|
||||
|
||||
@@ -74,7 +79,8 @@ Emitter output must map to a `BytecodeModule` shape containing:
|
||||
3. `code`,
|
||||
4. `exports`,
|
||||
5. `syscalls`,
|
||||
6. optional `debug_info` that still satisfies v1 minimum debug obligations.
|
||||
6. typed Registry declarations, implementations and per-function capture lists,
|
||||
7. optional `debug_info` that still satisfies v1 minimum debug obligations.
|
||||
|
||||
### 6.2 Function ordering and IDs
|
||||
|
||||
@@ -168,7 +174,6 @@ At minimum, artifact conformance checks should assert:
|
||||
The following remain deferred:
|
||||
|
||||
- richer optional debug/source-map formats,
|
||||
- additional PBX section-level contracts beyond current baseline,
|
||||
- and profile-specific binary compatibility policy details beyond current v1 baseline.
|
||||
|
||||
## 11. Non-Goals
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
# Compiler Verification and Safety Checks Specification
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
Status: Draft v1 (Quality-Gate Baseline)
|
||||
Applies to: test-backed safety gates for common compiler stages, validation ownership across executable frontends, and integration regression safety checks against runtime
|
||||
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
# IRBackend to IRVM Lowering Specification
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
Status: Draft v1 (Backend Baseline)
|
||||
Applies to: executable-backend lowering from the common `IRBackend` handoff into `IRVM`
|
||||
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
# Backend Spec-to-Test Conformance Matrix
|
||||
|
||||
The current typed Registry/PBX v0 contract is normative in
|
||||
[Typed common Registry and PBX v0](../../compiler/general/specs/typed-registry-and-pbx-v0.md).
|
||||
Its complete typed function records, mandatory sections and verification rules
|
||||
replace the earlier slot-only artifact baseline.
|
||||
|
||||
Status: Draft v1 (Traceability Baseline)
|
||||
Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts
|
||||
|
||||
@@ -140,3 +145,19 @@ Matrix integrity is enforced by automated document lint:
|
||||
- if `PROMETEU_MATRIX_HARD_GATE=true` and `PROMETEU_CHANGED_FILES` contains a path under conformance-relevant FE/BE prefixes,
|
||||
- then this matrix file MUST be present in `PROMETEU_CHANGED_FILES`, otherwise the gate fails.
|
||||
- CI policy uses strict Gate I mode via `PROMETEU_GATE_I_STRICT=true` (or `CI=true`) and requires `PROMETEU_RUNTIME_CHECK_CMD` for runtime-backed evidence.
|
||||
|
||||
## 7. Typed Registry/PBX v0 qualification (2026-10-14)
|
||||
|
||||
Owner: compiler/general. These rows supersede slot-only PBX coverage claims;
|
||||
frontend syntax and lowering remain consumer-owned.
|
||||
|
||||
| Requirement | Evidence | Status | Scope |
|
||||
| --- | --- | --- | --- |
|
||||
| Stable declarations, nominal identity, structural deduplication and cycles | LinkedRegistryTest; IRBackendExecutableContractTest | pass | Common API and linking |
|
||||
| Complete typed signatures, captures, roles and implementations | PbxRegistryConformanceTest; TypedCommonPipelineTest | pass | Common IR through emission |
|
||||
| Exact PBX mandatory tables and multi-slot signatures | Independent 194-byte oracle; fixed vec2 function bytes | pass | Wire format, not a self round-trip |
|
||||
| Runtime final admission and execution | tools/pbx-conformance/run.py | pass | Closure, trait, array, Dynamic, intrinsic, roles, joins, native binding; vec2 load-only |
|
||||
| Invalid structures, references, code and resource refusal | tools/pbx-conformance/main.rs mutation corpus | pass | Production loader, default/lowered limits |
|
||||
| Structured initialization and binding diagnostics | HeadlessProcessSessionTest; observed runtime JSON fixtures | pass | Preserves full payload through MCP, including null outer PC |
|
||||
| Published schema covers current runtime reasons | Actual LifecycleRole/NonFiniteValue payloads against runtime schema | partial | Runtime enum/schema mismatch recorded in AGD75; no payload rewriting |
|
||||
| PBS migration and integrated delivery | AGD75 and consumer tickets | partial | Existing PBS suite passing is not complete executable lowering evidence |
|
||||
|
||||
@@ -272,12 +272,46 @@ Absent editor capabilities MUST have deterministic fallback behavior at tooling
|
||||
3. host protocols that can represent unsupported operations SHOULD do so explicitly;
|
||||
4. and absent editor capability MUST NOT be reported as a compiler failure.
|
||||
|
||||
When a frontend exposes definition or navigation, each returned location MUST identify a compiler-known physical source file. A resolved symbol without a physical file MUST produce an empty definition response. Tooling MUST NOT require virtual documents, untitled buffers, or synthetic URIs for this capability.
|
||||
When a frontend exposes definition or navigation, each returned location MUST identify a compiler-known source in the analyzed revision. Editable main-project locations use `file:`. Bundled SDK/core and ordinary dependency sources use server-issued `prometeu-source:` identities for consumers that negotiate external-source support. Ownership, not physical containment or `SourceKind.PROJECT`, determines editability. Clients without support receive only editable physical project destinations; absent frontend support retains the empty fallback. This explicitly supersedes the earlier physical-only definition policy (DEC-0062).
|
||||
|
||||
`FrontendLanguageService.supportsExternalSources` and `sourceDocument` are optional,
|
||||
with false/empty defaults. `FrontendDefinitionLocation.source`, when present,
|
||||
contains the known source's exact text, origin, name, language, read-only ownership
|
||||
and opaque frontend context. Compiler contracts do not mint session URIs; that is
|
||||
the project host's responsibility. The content digest is not an SDK version.
|
||||
|
||||
External source snapshots MUST retain the exact analyzed text, source origin and frontend semantic context together. Declaration offsets and UTF-16 protocol positions MUST be calculated from that text. The frontend owns hover and continued definition inside external documents; adapters MUST NOT resolve language semantics. SDK/core MUST remain bundled without editorial extraction. Unknown, expired, unreadable or unauthorized identities MUST report unavailable without arbitrary path fallback.
|
||||
|
||||
External URIs are scoped to a project-server session and a content revision, not an SDK semantic version. A project-owned registry retains snapshots per consumer, independently of transport connections. Last release or project shutdown releases text and semantic context together. Reconnection MUST revalidate before queries resume; changed revisions require fresh navigation, never old positions applied to new text. One consumer closing MUST NOT invalidate another. All edit proposals touching an external source, including physical aliases, MUST be refused atomically. References, workspace symbols, document links and hierarchies retain their existing physical scopes; external navigation does not expand them.
|
||||
|
||||
When a frontend exposes find-references, each returned usage or declaration location MUST identify a compiler-known physical source file. A cursor offset whose definition response is empty MUST produce an empty references response. Host `includeDeclaration` MAY add the canonical declaration location only when that declaration is a compiler-known physical source file; it MUST NOT invent a virtual, untitled, or synthetic location.
|
||||
|
||||
When a frontend exposes document symbols or outline, the result MUST be the named declaration tree of the requested document. Presence, hierarchy, and ranges MUST come from that document's recovered syntax tree. Semantic success MUST NOT be required. Semantic enrichment MUST NOT drop a named declaration that the syntax tree still exposes. A missing syntax tree MUST produce an empty list. Document symbols MUST NOT be a workspace symbol index, folding ranges, or a navigation list of foreign files.
|
||||
|
||||
When a frontend exposes workspace symbols, the result MUST be a flat search of named declarations whose locations identify compiler-known physical source files of the current analysis. Presence, names, kinds, details, and ranges MUST come from the recovered syntax of those files. Semantic success MUST NOT be required. Semantic enrichment MUST NOT drop a named declaration that the syntax tree still exposes. A missing analysis surface MUST produce an empty list. The workspace-symbol request MUST NOT require an open text document. A declaration without a compiler-known physical file MUST be omitted. Tooling MUST NOT require virtual documents, untitled buffers, or synthetic URIs for this capability. Workspace symbols MUST NOT be a document outline, folding ranges, a persistent symbol index, or a navigation list of virtual locations.
|
||||
|
||||
When a frontend exposes rename, the result MUST be a validated workspace edit of identifier spans whose locations identify compiler-known physical source files. Identity MUST be the physical declaration locations that definition returns at the cursor. A local or parameter name span MUST still be renameable when definition at that offset is empty. Each rewritten location MUST identify a compiler-known physical source file. A cursor that is not renameable, including builtins, virtual paths, unresolved names, keywords, comments, strings, import aliases and uses of those aliases, error case labels without their own span, and barrel files, MUST produce a protocol error or a null prepareRename result. Tooling MUST NOT return a successful empty workspace edit for a refused cursor or an invalid new name. The new name MUST be a language identifier that is not a keyword and MUST NOT collide in the same binding space, ignoring the sites being rewritten and the overload set being renamed. The server MUST NOT write files and MUST NOT rename file paths. Host prepareRename MUST advertise a prepareProvider when rename is exposed. Tooling MUST NOT require virtual documents, untitled buffers, or synthetic URIs for this capability.
|
||||
|
||||
When a frontend exposes code actions, the result MUST be quick fixes only: one workspace edit tied to a diagnostic of the requested physical document. The frontend MUST produce each repair from that document's syntax. Each repair MUST name the stable diagnostic code, the primary span, and exactly one local text edit. Tooling MUST transport that repair. Tooling MUST NOT choose the edit by parsing the diagnostic message or by a diagnostic-code table. A repair MUST NOT be a required field of compiler diagnostics and MUST NOT be published inside diagnostic data. The published diagnostic MUST carry the stable code so a later code-action request can match it. A repair MUST be returned only when the request context contains a diagnostic with the same code and the same primary range. An empty diagnostic context MUST produce an empty list. The edit MUST change only the requested physical source file. The server MUST NOT write files, MUST NOT return a command, and MUST NOT require a resolve round trip. A missing code-action capability MUST NOT advertise code actions and MUST produce an empty list rather than a protocol error. Virtual, untitled, or synthetic documents MUST NOT receive an edit. Code actions MUST NOT include organize-imports, source actions, refactors, or generated stubs unless a future accepted decision says so.
|
||||
|
||||
Compiler diagnostics and editor diagnostics are distinct ownership surfaces. Diagnostics returned by `analyze`, `compile`, and `build` are compiler contract output. Editor diagnostics MAY reuse compiler analysis results, live overlays, caches, or cancellation-aware tooling state, but a frontend MUST NOT be required to provide editor diagnostics in order to compile.
|
||||
|
||||
When tooling publishes an editor diagnostic, `source` MUST be the `languageId` of the bound frontend project. `code` MUST be the stable compiler diagnostic code when one exists, and MUST be empty when the compiler diagnostic has none. Tooling MUST NOT copy that code into `source`. Tooling MUST NOT publish related locations, compiler phase, or a repair payload on the editor diagnostic.
|
||||
|
||||
When a frontend exposes document links, each link MUST cover the span of a module reference whose resolved destination is a compiler-known regular file. A module reference that does not resolve to a regular file MUST produce no link. Tooling MUST NOT target virtual, untitled, or synthetic URIs, including virtual stdlib documents. Document links MUST NOT replace definition. A missing document-link capability MUST NOT be advertised and MUST produce an empty list rather than a protocol error.
|
||||
|
||||
When a frontend exposes folding ranges, the ranges MUST come from recovered syntax spans for top-level `fn`, `struct`, `service`, `contract`, `enum`, `error`, `callback`, and `host` declarations, their bodies, and `Doc` text blocks. A parameter list MUST fold from the parenthesis pair. A brace, parenthesis, or text-block delimiter that the recovered tree does not cover MUST still produce a token range, including an unmatched opener through the end of the text. Folding ranges MUST NOT be document symbols.
|
||||
|
||||
When a frontend exposes selection ranges, the chain at a cursor MUST run from the inside outward in this order: identifier, argument or parameter list, block or `Doc` text block, declaration. A layer that does not contain the cursor MUST be omitted. A missing folding or selection capability MUST NOT be advertised and MUST produce an empty list rather than a protocol error.
|
||||
|
||||
When a frontend exposes call hierarchy, incoming and outgoing calls MUST be callsites found by walking call expressions in the syntax tree. The references index MUST NOT be used as the call graph. A cursor that is not on a function, method, or constructor MUST produce an empty prepare result. Type hierarchy MUST NOT be advertised. A missing call-hierarchy capability MUST NOT be advertised and MUST produce an empty list rather than a protocol error.
|
||||
|
||||
When a frontend exposes completion inside a module reference, the candidates MUST be project and stdlib modules the current module resolver can already name. Completion outside a module reference MUST keep its existing member and general candidates. Completion items MUST stay eager. `resolveProvider` MUST stay false. Snippets and a new ranking score MUST NOT be added.
|
||||
|
||||
When a frontend exposes semantic tokens, the lexical token provider remains the baseline. An identifier token MAY be replaced with an existing semantic key when the same resolution used by hover names that symbol and an existing key matches it. Resolution failure, a broken file, or a symbol with no existing key MUST keep the baseline token. This overlay MUST NOT add a semantic-token key.
|
||||
|
||||
When a frontend exposes formatting, it MUST be full-document formatting only. Range formatting and on-type formatting MUST NOT be advertised. The formatter MUST reprint the existing token stream. It MUST NOT reorder declarations, join lines, or split lines. Indentation MUST be four spaces and MUST change only where brace or parenthesis nesting changes. The interior of a `Doc` text block MUST be copied unchanged. A comment MUST stay on the line of the token it already follows. A missing formatting capability MUST NOT be advertised and MUST produce an empty edit list rather than a protocol error.
|
||||
|
||||
`FrontendSpec` remains the source of static frontend-owned presentation metadata such as semantic vocabularies, host projections, and visual themes. Producing semantic tokens for a live document is an optional editor-facing capability; the existence of static presentation metadata MUST NOT imply that every frontend can provide live semantic-token results.
|
||||
|
||||
The frontend registry MUST resolve providers by `languageId`. A lookup for an unknown `languageId` MUST fail explicitly with a diagnostic-friendly error. Unknown languages MUST NOT silently fall back to PBS or to any other frontend.
|
||||
|
||||
@@ -25,6 +25,9 @@ Runtime-side reading semantics for `assets.pa` are defined upstream in `../runti
|
||||
5. A future shipper is a consumer of packer artifacts, not a co-author of the asset contract.
|
||||
6. Runtime reading semantics are not redefined by the packer.
|
||||
7. The packer must stop at artifact publication, not cartridge assembly.
|
||||
8. The packer's Java package root is `p.packer`; it must not be moved under `p.studio` or treated as a Studio subdomain.
|
||||
9. The packer must remain independently consumable by Studio, command-line tooling, build tooling, and future automation adapters.
|
||||
10. No Packer module may depend on `p.studio`, Studio UI, or Studio application modules.
|
||||
|
||||
## Packer-Owned Artifacts
|
||||
|
||||
@@ -57,6 +60,18 @@ Rules:
|
||||
- shipper-specific workflow detail is deferred;
|
||||
- published artifact names and meanings must remain documented and stable enough for later consumption.
|
||||
|
||||
## Studio Consumption Boundary
|
||||
|
||||
Studio is a consumer of Packer capabilities, not the owner of Packer semantics.
|
||||
|
||||
Rules:
|
||||
|
||||
- Studio should consume a stable, neutral, use-case-oriented public Packer API directly;
|
||||
- Studio must not add a gateway that merely mirrors an already suitable public Packer API;
|
||||
- when only concrete, static, infrastructure-oriented, unstable, or excessively broad integration is available, the Studio consumer may define a narrow consumer-owned gateway;
|
||||
- implementations of Studio-owned gateways must stay outside Packer and outside the Studio Core functional contract;
|
||||
- Studio projections and orchestration must not duplicate Packer validation, packing, diagnostic, concurrency, or artifact semantics.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- cartridge assembly flow
|
||||
|
||||
+16
-2
@@ -60,10 +60,24 @@ When the packer is embedded inside another host such as Studio, the host must bo
|
||||
|
||||
Rules:
|
||||
|
||||
- the embedded packer runtime must receive a typed event bus reference from the host when shared host visibility is part of the integration contract;
|
||||
- the embedded packer runtime must receive a typed event sink or adapter from the host when shared host visibility is part of the integration contract;
|
||||
- that reference is the baseline path for packer publish/subscribe integration in the embedded host;
|
||||
- the embedded packer runtime must not quietly create a disconnected parallel event system when host integration expects shared operational visibility;
|
||||
- in Studio, this shared typed event bus reference is owned by the Studio `Container`.
|
||||
- in Studio, bootstrap, shutdown, and event adaptation are owned by the `prometeu-app` composition root;
|
||||
- the embedded integration must not use `p.studio.Container`, Spring context lookup, or another static service locator.
|
||||
|
||||
### Studio Dependency Rule
|
||||
|
||||
The dependency direction is always Studio to Packer.
|
||||
|
||||
Rules:
|
||||
|
||||
- Studio Core may consume stable public contracts from `prometeu-packer-api` directly;
|
||||
- a Studio-owned gateway is required only when an integration is concrete, static, infrastructure-oriented, unstable, excessively broad, or leaks provider lifecycle details;
|
||||
- such a gateway must expose only the capabilities required by its consuming Studio module;
|
||||
- gateway implementations and Packer bootstrap belong in `prometeu-app` or another explicit infrastructure adapter;
|
||||
- the JavaFX adapter must consume neutral Studio API contracts and must not call Packer directly;
|
||||
- Packer must not depend on `p.studio` and must not publish Studio UI events as part of its domain contract.
|
||||
|
||||
Baseline core services:
|
||||
|
||||
|
||||
@@ -52,6 +52,10 @@ Specs should normally be fed by:
|
||||
|
||||
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
|
||||
|
||||
## Integration Boundary
|
||||
|
||||
The Packer package root is `p.packer`, and Packer remains autonomous from Studio. Studio consumes stable public Packer APIs directly and introduces a narrow consumer-owned gateway only for concrete, static, unstable, or infrastructure-specific integration. Packer never depends on `p.studio`.
|
||||
|
||||
## Current Corpus
|
||||
|
||||
The current packer core corpus is:
|
||||
|
||||
@@ -6,7 +6,7 @@ Purpose: Define the normative shell structure of the Studio UI.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio shell decision into normative form.
|
||||
This specification consolidates the accepted Studio shell decision into normative form. DEC-0060 adds DEV and project-scoped automation authority; its detailed behavior is owned by the [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md).
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
@@ -46,10 +46,13 @@ The baseline workspace set includes:
|
||||
|
||||
- Asset Management;
|
||||
- Debugger/Profiler;
|
||||
- DEV, for granting/reclaiming project control and observing external-agent automation;
|
||||
- Shipper, temporarily represented by the current `BuilderWorkspace`.
|
||||
|
||||
`BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface.
|
||||
|
||||
DEV MUST remain separate from human Debug and MUST NOT offer chat or manual Play/input for the headless session. Selecting, hiding or switching away from DEV MUST NOT grant or release project authority. The shell's always-visible run surface remains visible, but conflicting manual actions MUST be unavailable while project control is ceded, including while waiting for an agent. Services MUST enforce the same exclusion; shell bindings alone are insufficient.
|
||||
|
||||
## Workspace Architecture Model
|
||||
|
||||
The shell-level workspace host exists to mount independently authored workspaces under one Studio contract.
|
||||
@@ -57,11 +60,13 @@ The shell-level workspace host exists to mount independently authored workspaces
|
||||
Baseline workspace architecture rules are:
|
||||
|
||||
- each workspace should have a composition root that mounts the workspace into the shell;
|
||||
- the shell and workspace composition roots must receive neutral Studio API services through explicit constructor or factory injection;
|
||||
- a workspace composition root should coordinate workspace services, state orchestration, and structural sync, but it should not own every local render path directly;
|
||||
- project-session services that must survive workspace focus changes should be owned above individual workspace focus lifecycles and then consumed by workspace composition roots;
|
||||
- event-observing workspace controls must be lifecycle-managed;
|
||||
- workspace-local updates should flow through the Studio event system rather than ad hoc imperative redraw chains;
|
||||
- future workspaces should consume shared Studio workspace framework primitives where those primitives already cover the needed behavior.
|
||||
- shell and workspace code must not resolve application services through a static container or Spring application-context lookup.
|
||||
|
||||
The shell must not encourage a workspace model where every interaction falls back to whole-workspace refresh.
|
||||
|
||||
@@ -137,3 +142,23 @@ This specification is complete enough when:
|
||||
- workspace and shell responsibilities are clearly separated;
|
||||
- the shell-level expectations for workspace architecture are explicit;
|
||||
- the baseline Studio frame is stable enough for implementation planning.
|
||||
|
||||
## Project Assistant Preparation (DEC-0061)
|
||||
|
||||
Project creation MUST scaffold neutral agent-integration intent in
|
||||
`.studio/setup.json` and invoke the same preparation port used by existing
|
||||
projects in DEV. Application infrastructure resolves installed Studio and client
|
||||
configuration; the wizard/Core MUST NOT serialize provider TOML or launch an
|
||||
agent. Failed preparation leaves a usable project with actionable incomplete
|
||||
readiness in DEV, never a false ready claim. Runtime/editor settings and unrelated
|
||||
client configuration MUST survive. Preparation grants no project control.
|
||||
|
||||
### Automatic preparation when opening a project
|
||||
|
||||
Opening a project MUST prepare its enabled MCP integration using the same neutral
|
||||
port as scaffold and DEV retry. Desktop composition MUST start the shared loopback
|
||||
server before project sessions become available; no external command or separate
|
||||
per-project desktop Run is required. Explicitly disabled integration MUST remain
|
||||
disabled. Preparation failure MUST remain visible in DEV readiness without blocking
|
||||
project use. Opening MUST NOT publish credentials or grant/acquire agent control.
|
||||
The coding client continues to own its configured stdio process and initial trust.
|
||||
|
||||
@@ -0,0 +1,401 @@
|
||||
# DEV and Automation Specification
|
||||
|
||||
## Status
|
||||
|
||||
Active normative baseline; implementation is delivered in ordered phases.
|
||||
This status does not claim that the DEV workspace, MCP endpoint or integrated
|
||||
agent loop is already available in an installed Studio.
|
||||
|
||||
## Scope and Ownership
|
||||
|
||||
Owner: **studio**, including neutral API/Core services, the JavaFX DEV workspace
|
||||
and application/infrastructure adapters. Runtime owns execution and its external
|
||||
headless protocol. Compiler, language/SDK references, LSP and Packer retain their
|
||||
existing domain ownership.
|
||||
|
||||
## Purpose
|
||||
|
||||
Allow a developer to grant control of an open project to an external coding
|
||||
agent, observe managed operations and canonical runtime images, and explicitly
|
||||
reclaim control. Studio provides specialized project services through MCP, not
|
||||
an embedded agent or a second editor.
|
||||
|
||||
## Authority and Normative Inputs
|
||||
|
||||
This specification implements accepted **DEC-0060**, including D1–D7 and B1–B9.
|
||||
PLN-0139 sequences its implementation; it does not redefine this contract.
|
||||
|
||||
- [Core and Adapter Architecture](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md): dependency direction, composition and shared operations.
|
||||
- [Shell and Workspace Layout](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md): workspace mounting and project lifetime.
|
||||
- [Project-Local State](8.%20Project-Local%20Studio%20State%20Specification.md): configuration and restoration exclusions.
|
||||
- [Runtime Headless Automation Protocol](../../../../runtime/docs/specs/runtime/11a-headless-automation-protocol.md): runtime-owned wire, commands, framing, limits and execution meanings.
|
||||
|
||||
MUST, MUST NOT and MAY express requirements, prohibitions and permissions.
|
||||
Implementation MUST NOT weaken this accepted baseline; substantive ambiguity
|
||||
requires explicit decision review rather than a guessed implementation rule.
|
||||
|
||||
## 1. Shared Services and Protocol Boundaries
|
||||
|
||||
JavaFX and MCP MUST consume the same neutral API/Core authority, sessions,
|
||||
operations and orchestration. Neither adapter MAY simulate UI actions or
|
||||
implement a parallel permission/build/pack/execution system.
|
||||
|
||||
| Boundary | Owner and responsibility |
|
||||
| --- | --- |
|
||||
| Studio API | Plain-Java contracts, identities, snapshots, typed outcomes, diagnostics and ports; no toolkit, framework or concrete wire DTOs |
|
||||
| Studio Core | Project/session authority, guards, operations, build/pack/runtime coordination and ordered cleanup; testable without JavaFX or Spring |
|
||||
| JavaFX DEV | Human grant/reclaim actions, presentation, localization, canvas, subscriptions and FX-thread projection |
|
||||
| Application/infrastructure | MCP HTTP transport, process supervision, runtime JSONL translation, existing project LSP client, lifecycle and packaging |
|
||||
| Runtime | Firmware/VM execution, input sampling, logical frames, ticks, rendering, watchdogs and faults |
|
||||
| External coding client | Agent/chat, model/provider credentials, native file editing, budget, iterations and simple task stopping criteria |
|
||||
|
||||
MCP Streamable HTTP, runtime JSONL/stdio, and human Debug/DevTools MUST remain
|
||||
distinct protocols with distinct lifecycles. A native Rust/Java binding is not
|
||||
the chosen runtime boundary. Compiler, LSP, Packer and runtime semantics MUST
|
||||
NOT be reimplemented in Studio.
|
||||
|
||||
The functional dependency graph in spec 9 MUST remain unchanged. Services
|
||||
requiring guards MUST receive shared authority through neutral contracts and
|
||||
composition, not depend on concrete session implementations or UI state.
|
||||
|
||||
## 2. Project Authority and Control States
|
||||
|
||||
Authority MUST belong to an open project session, not a tab, focused window,
|
||||
HTTP connection or UI component. The agent MUST supply a project root; Studio
|
||||
MUST validate it against an open project and use explicit project identity.
|
||||
Window focus MUST NOT implicitly select a call's target.
|
||||
|
||||
Connection authentication, human project grant and task control identity MUST
|
||||
be separate checks. At most one task MAY own a project's grant. Acquisition
|
||||
without a prior human grant MUST fail. A task identity MUST be required for
|
||||
authorized work and MUST NOT be reusable for another project or revoked task.
|
||||
|
||||
| State | Admission and permitted behavior | Exit |
|
||||
| --- | --- | --- |
|
||||
| Manual control | Human editing/Debug; grant only with no active Debug or conflicting managed work, and successful document handoff | Human grant enters waiting |
|
||||
| Waiting for agent | Grant already blocks conflicting manual work; authenticated agent can acquire; human can reclaim without an agent connection | Acquisition enters working; reclaim enters returning |
|
||||
| Agent working | One acquired task uses its valid identity; developer can inspect, navigate and reclaim | Explicit task release or human revoke enters returning |
|
||||
| Returning control | Prior authority is invalid; stop managed work and refresh documents; manual conflicting actions remain blocked | Manual control only after cleanup/handoff |
|
||||
|
||||
Grant and acquisition MUST be enforced atomically with conflicting operation
|
||||
admission. Concurrent acquisition MUST NOT create two owners. Project-local
|
||||
authority MUST NOT become a global Studio lock.
|
||||
|
||||
Human Debug active MUST prevent grant. From grant onward, including waiting
|
||||
and silence, Studio MUST prevent manual editing, Debug, build and other
|
||||
conflicting project mutation. Guards MUST apply at service entry points as
|
||||
well as UI bindings. Navigation, inspection and monitoring remain available.
|
||||
|
||||
An operation finishing, failing compilation, raising a guest fault or losing
|
||||
its runtime session MUST NOT release task authority. Silence, client
|
||||
disconnection and waiting MUST NOT cause expiration or automatic resumption.
|
||||
There is no heartbeat or silence timeout in this baseline.
|
||||
|
||||
## 3. Grant and Saved-Document Handoff
|
||||
|
||||
Grant MUST cover Studio-owned unsaved buffers/drafts, including dirty asset
|
||||
editing surfaces; it MUST NOT assume that source files are the only editable
|
||||
project content.
|
||||
|
||||
If such content is dirty, DEV MUST offer **Save all and grant** or **Cancel**.
|
||||
Grant MUST follow successful saves; user cancellation or save failure MUST NOT
|
||||
cede control. Clean projects do not require a code snapshot, clean Git tree or
|
||||
commit. Document participants MUST use neutral handoff contracts without moving
|
||||
presentation buffers or JavaFX types into Core.
|
||||
|
||||
The agent edits the actual project folder with native external tools. Build
|
||||
MUST use saved files, and the existing project LSP client MUST synchronize
|
||||
saved content before semantic queries. Studio MUST NOT claim to save external
|
||||
unsaved buffers or protect against concurrent external writes.
|
||||
|
||||
On authority return, Studio MUST refresh open documents from disk and MUST NOT
|
||||
reapply stale buffers over agent changes. Revocation/cancellation MUST preserve
|
||||
edits already made. There is no later Apply/merge step or Studio-owned code
|
||||
rollback. Review, integrity, Git commits and recovery remain developer duties.
|
||||
|
||||
SDK/external libraries MUST be consultable but MUST NOT be edited by the
|
||||
game-authoring task. Editable local libraries MUST be inside project scope.
|
||||
Unsupported capabilities or required SDK changes MUST be reported as limitations,
|
||||
not silently implemented outside that scope. This does not prohibit the runtime
|
||||
engineering delivery that prepared this integration.
|
||||
|
||||
## 4. Return, Revocation and Closure
|
||||
|
||||
Explicit release and human reclaim MUST follow this order:
|
||||
|
||||
1. Invalidate task authority and reject new or delayed calls under the old identity.
|
||||
2. Cancel/stop managed work and shut down owned runtime processes.
|
||||
3. Refresh open documents from saved project content, without stale writeback.
|
||||
4. Release conflicting manual operations and present manual control.
|
||||
|
||||
Late completions MUST NOT resurrect a revoked task or restore its authority.
|
||||
Cleanup MUST NOT advertise manual control before managed work is stopped and
|
||||
document refresh is complete. Diagnostics MUST distinguish cleanup failure from
|
||||
a successful return; operation outcome and authorization state are not the same.
|
||||
|
||||
Reclaim MUST also work while waiting for an agent or after an operation failure.
|
||||
Another task MUST require a new human grant. Closing/hiding/switching DEV MUST
|
||||
NOT release control. Closing the project or Studio MUST revoke authority and
|
||||
stop managed processes before teardown of their providers/executors. Reopening
|
||||
MUST start in manual control, even when restoring DEV as the selected workspace.
|
||||
|
||||
The application-owned project-session factory tracks sessions and closes all of
|
||||
them before its LSP/executor dependencies are destroyed, including sessions not
|
||||
currently represented by a window. Closing one project removes it from that set;
|
||||
application teardown rejects new opens and attempts every remaining project even
|
||||
if another close reports failure.
|
||||
|
||||
If shutdown required forced termination, the first return attempt reports cleanup
|
||||
failure and retains the manual guard. A subsequent explicit human reclaim may
|
||||
acknowledge cleanup only after the gateway confirms that its owned process tree
|
||||
is dead. A cached failed shutdown must not make a dead session permanently
|
||||
unreclaimable. Cancellation racing a process crash must still allow the owner to
|
||||
await worker termination and shutdown; it must not bypass that cleanup sequence.
|
||||
|
||||
Studio cannot stop direct writes by the external coding client. The UI and
|
||||
connection instructions MUST tell the developer to stop that client separately;
|
||||
reclaim is not an operating-system filesystem lock or a rollback guarantee.
|
||||
|
||||
## 5. DEV Workspace Contract
|
||||
|
||||
DEV MUST expose:
|
||||
|
||||
- **Grant control to AI** (`Ceder controle à IA`) and **Interrupt and reclaim control** (`Interromper e retomar controle`);
|
||||
- the four control states, project identity, current managed operation and diagnostics;
|
||||
- a canonical-image canvas with session/build/logical-frame/render-frame identity and stale status;
|
||||
- a short history of Studio calls, not an independent code history;
|
||||
- **Prepare assistant**, plus short connection/use instructions when the real MCP composition is available.
|
||||
|
||||
Actions MUST reflect shared service authority. DEV MUST NOT own a duplicate
|
||||
lock or release authority when disposing visual subscriptions. Presentation
|
||||
updates MUST follow the existing FX-thread, theme, localization and workspace
|
||||
lifecycle rules.
|
||||
|
||||
DEV MUST NOT contain chat, provider settings, manual headless Play/input or
|
||||
concurrent human control of the agent's execution. Human play/testing remains
|
||||
in Debug with its existing host/protocol/lifecycle, subject to symmetric guards.
|
||||
“Agent working” means the task has been acquired; it is not a claim to observe
|
||||
all external edits, reasoning or conversation.
|
||||
|
||||
Preparation MUST report missing installation or configuration conflicts explicitly; it does not depend on a live grant or fabricate endpoint credentials. Test doubles MAY supply
|
||||
operations/captures to isolated tests, never masquerade as product execution.
|
||||
|
||||
## 6. Operations and Lost Responses
|
||||
|
||||
Automation MUST reuse the neutral operation executor/handle boundary: stable
|
||||
operation identity, observable snapshots/progress, cancellation, asynchronous
|
||||
completion and typed results. Build/pack diagnostics MUST be preserved.
|
||||
Success, lifecycle termination, guest fault, infrastructure/host failure and
|
||||
cancellation MUST remain distinguishable, including known partial progress.
|
||||
|
||||
Build and advance starts MUST return `operationId` promptly. Each start MUST
|
||||
accept `clientRequestId` and allow authorized lookup by that identity if the
|
||||
initial response is lost. Within the task:
|
||||
|
||||
- same identifier and same parameters MUST return the existing operation without reexecution;
|
||||
- same identifier with different parameters MUST fail;
|
||||
- deduplication and lookup MUST still validate project/task authority;
|
||||
- the registry MUST stay in memory only, without restart recovery or replay.
|
||||
|
||||
Runtime `requestId` correlates a wire call; it is not Studio operation
|
||||
deduplication. Neither transport error nor lost response authorizes blindly
|
||||
retrying an advance. A runtime crash requires an explicit new session, not
|
||||
restoration/replay; task authority remains governed by section 2.
|
||||
|
||||
## 7. Runtime Supervision and Canonical Capture
|
||||
|
||||
Studio MUST resolve `prometeu headless --stdio` from the configured runtime
|
||||
installation. It MUST NOT discover/download another runtime over the network.
|
||||
Missing or incompatible installations MUST fail explicitly. Each process owns
|
||||
one session; each task MUST have at most one active headless session.
|
||||
|
||||
The gateway MUST validate the runtime's protocol major/minor, real version,
|
||||
required capabilities and effective limits. Incompatible major or missing
|
||||
mandatory capability MUST block the session; compatible minor additions are
|
||||
permitted. It MUST obey complete UTF-8 JSONL framing and separate protocol
|
||||
stdout from stderr diagnostics. Invalid input/schema MUST not disappear silently.
|
||||
|
||||
The application adapter resolves the executable from `ProjectLocalStudioSetup`,
|
||||
launches it without a shell in the project root, and passes all six effective
|
||||
limits explicitly. Hello and initialize share one handshake deadline. Required
|
||||
hello limits must match the launch configuration; request IDs and session IDs
|
||||
are checked on every subsequent response. Partial lines, invalid UTF-8,
|
||||
duplicate JSON keys, uncorrelated replies and non-monotonic progress invalidate
|
||||
the process. Stderr is drained independently into bounded diagnostics.
|
||||
|
||||
The runtime-owned surface covers boot/reset, set/clear normalized input,
|
||||
advance, capture, state/fault, cancel and shutdown. Conflicting execution work
|
||||
MUST NOT execute concurrently or be silently queued. Advance MUST preserve
|
||||
requested/completed counts and stop reasons. Cancellation is observed between
|
||||
frames; the current frame retains its deterministic watchdog, not a wall-clock
|
||||
guest deadline. No background realtime game loop is introduced for automation.
|
||||
|
||||
Reset leaves the runtime unbooted and clears its capture. It does not implicitly
|
||||
boot the cartridge again. A subsequent explicit boot may reuse the session's
|
||||
known build cartridge; an invalidated process requires an explicit new session.
|
||||
|
||||
| Configurable, handshake-advertised limit | Default |
|
||||
| --- | --- |
|
||||
| Frames per advance | 600 |
|
||||
| Command message | 64 KiB |
|
||||
| Complete response including image/envelope | 32 MiB |
|
||||
| Handshake wait | 5 s |
|
||||
| Headless-call timeout | 60 s |
|
||||
| Cancel/shutdown grace before process termination | 5 s |
|
||||
|
||||
Oversized requests MUST fail, not be silently clamped. Responses MUST respect
|
||||
their complete serialized limit. Studio MUST supervise external-process
|
||||
deadlines and terminate only its owned process tree if cancellation/shutdown
|
||||
does not respond within the configured grace. Report infrastructure failure
|
||||
and only known progress. EOF closes the headless process; it never resumes it.
|
||||
|
||||
Screenshot means the runtime's canonical **RGBA8888 framebuffer bitmap**.
|
||||
Capture MUST use lossless PNG/base64 with dimensions, original stride/layout,
|
||||
runtime session, `logical_frame_index` and `FrameId`. These two frame identities
|
||||
MUST NOT be assumed numerically equal. Studio MUST attach build correlation.
|
||||
Both identities retain the full unsigned 64-bit range: Java uses `BigInteger`,
|
||||
and MCP serializes integer JSON values without conversion through floating point.
|
||||
Hashes MAY supplement but MUST NOT replace pixels. No desktop/window screenshot,
|
||||
temporary-image-file transport or continuous video is permitted.
|
||||
|
||||
The adapter validates base64, PNG signature, RGBA8 header, dimensions and decoded
|
||||
image consistency in memory, then forwards the original PNG bytes unchanged.
|
||||
Its decoder currently guards allocations at 16,777,216 pixels; exceeding this
|
||||
bound fails explicitly rather than resizing or substituting the image.
|
||||
|
||||
Agent and DEV MUST receive the same capture and correlation for requested
|
||||
advances. DEV MUST identify images from an older build/session as stale during
|
||||
edits/rebuilds. The previous execution MUST stop before rebuilding artifacts
|
||||
that it uses. Capture/build correlation MUST NOT introduce code snapshots.
|
||||
|
||||
## 8. Local MCP Admission and Functional Surface
|
||||
|
||||
Concrete tool names, input schemas, response envelopes and HTTP lifecycle are
|
||||
specified in [MCP Tools and Project Knowledge Contract](11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
|
||||
|
||||
The desktop MUST host Streamable HTTP at `127.0.0.1:<OS-assigned-port>/mcp`.
|
||||
DEC-0061 adds Studio-owned stdio discovery and one-time preparation as specified
|
||||
in spec 11. Each human grant publishes a fresh project-scoped credential through
|
||||
the required lifecycle participant in spec 8. Authentication, project scope and
|
||||
task identity remain separate checks. There is no global credential bypass.
|
||||
Restart invalidates old access and requires a fresh human grant, while the native
|
||||
client's command/configuration remains unchanged. No remote binding, accounts or
|
||||
OAuth are introduced. Preparation never grants editing authority.
|
||||
|
||||
| Tool group | Required capabilities | Required authority |
|
||||
| --- | --- | --- |
|
||||
| Context/references | Project identity, languages, versions, capabilities and paginated references | Project credential; no acquired task required |
|
||||
| Control | Acquire task and release control | Prior human grant for acquisition; valid task identity for release |
|
||||
| Language | Existing LSP diagnostics/navigation and supported capabilities | Valid project/task identity |
|
||||
| Build | Compile and pack | Valid project/task identity |
|
||||
| Headless | Boot/reset, input, advance, capture, state/fault and shutdown | Valid project/task identity |
|
||||
| Operations | Query, lookup by client request identity and cancel | Valid project/task identity |
|
||||
|
||||
MCP capture responses MUST expose image content plus structured metadata;
|
||||
clients MUST NOT need to parse logs or fetch a temporary file to obtain pixels.
|
||||
Generic shell, generic file editing, Git, publication and out-of-project changes
|
||||
MUST NOT be exposed as shortcuts around these specialized services. Studio
|
||||
grant does not override the external client's own permission policy or require
|
||||
a new human confirmation for every authorized Studio operation.
|
||||
|
||||
## 9. Project Language Context and References
|
||||
|
||||
The project manifest MUST be authoritative for primary language and dependencies;
|
||||
there is no parallel AI-only language configuration. PBS is the project-creation
|
||||
default, not a fallback for an unknown declared language. Installed compiler/LSP
|
||||
integrations MUST advertise their actual capabilities; unknown versions or
|
||||
capabilities MUST be reported as unknown, not invented.
|
||||
|
||||
Context MUST include:
|
||||
|
||||
- explicit project identity/root;
|
||||
- language list and primary designation, with separately identified known language/compiler/SDK versions;
|
||||
- source extensions/scope and actual LSP/build capabilities;
|
||||
- references, examples, libraries and editable versus read-only roots.
|
||||
|
||||
A one-entry PBS list is valid; extensibility does not require another language
|
||||
or a multilingual compiler. LSP MUST use the existing project server and support
|
||||
project/library navigation through the diagnostics, definitions, references,
|
||||
symbols and other queries/refactorings it actually supports. It MUST NOT
|
||||
advertise nonexistent features or apply edits outside authorized scope.
|
||||
|
||||
The matching language/SDK distribution MUST ship indexed local quickstart,
|
||||
syntax, semantics, examples and SDK reference material. Consultation MUST work
|
||||
without Studio/compiler checkouts. MCP MUST read references by identifier with
|
||||
pagination, not arbitrary paths. Documentation ownership remains with its
|
||||
language/SDK/library owner; packaging does not create parallel language semantics.
|
||||
|
||||
Connection guidance MUST describe: connect → consult current project/languages/
|
||||
references → acquire after human grant → work using saved files and validate
|
||||
through LSP/build → release. The agent need not know PBS in advance. Missing
|
||||
documentation or unsupported language MUST appear as explicit limitations;
|
||||
static copied instructions MUST NOT substitute for current project context.
|
||||
|
||||
## 10. Delivery Phases and Conformance Gates
|
||||
|
||||
The accepted slicing is runtime → DEV/shared services → MCP → integration.
|
||||
No intermediate phase constitutes complete delivery of this specification.
|
||||
|
||||
| Phase / plan steps | Required gate and limit |
|
||||
| --- | --- |
|
||||
| Runtime, 01–07 | Independent process client proves external contract, deterministic execution, canonical pixels, limits/failures and installed CLI; no Studio/AI dependency |
|
||||
| DEV/shared services, 08–14 | Neutral authority/operations and document handoff first, then DEV; test grant/reclaim, Debug exclusion, dirty buffers, revocation/closure, late calls and FX lifecycle; desktop navigation smoke; doubles only in tests, no fake product endpoint |
|
||||
| MCP, 15–21 | Automated MCP client proves authenticated discovery, real configuration, unauthorized rejection, exclusive acquisition, context/references, operations/deduplication, revocation and image contracts; no model required for this gate |
|
||||
| Integration, 22–28 | Real runtime/LSP/build and an external coding client prove edit → build/pack → boot/input/advance → matching agent/DEV image → release; corrective loops and cleanup preserve manual Debug |
|
||||
|
||||
Cross-phase conformance MUST prove API/Core neutrality, the unchanged Modulith
|
||||
dependency graph, application startup/shutdown, installed/offline references,
|
||||
packaging and desktop behavior. Real-client tool/image compatibility MUST be
|
||||
verified with the selected client, not promised uniformly across providers.
|
||||
The vertical slice MAY use a simple existing PBS program; a complete game or
|
||||
mature gameplay library is not a prerequisite.
|
||||
|
||||
### Decision Traceability
|
||||
|
||||
| Accepted requirement | Normative location |
|
||||
| --- | --- |
|
||||
| D1 architecture | Section 1 and spec 9 |
|
||||
| D2 runtime; B1–B3 entry/wire/order | Sections 6–7 and runtime-owned protocol |
|
||||
| D3 capture; B4 capture/limits | Sections 5 and 7 |
|
||||
| D4 DEV/authority | Sections 2–5; shell spec and state-restoration exclusions |
|
||||
| D5 files/LSP/write scope | Sections 3 and 9 |
|
||||
| D6 MCP/operations; B5–B7 | Sections 6 and 8; spec 9's HTTP exception |
|
||||
| D7 languages/onboarding; B8–B9 | Sections 8–9 |
|
||||
| Ordered slicing and acceptance | Section 10 |
|
||||
| Accepted exclusions | Section 11 |
|
||||
|
||||
## 11. Non-Goals
|
||||
|
||||
- Embedded agent, chat, provider adapter, provider credentials or cost/budget accounting.
|
||||
- Mirroring external conversation, reasoning or all filesystem activity.
|
||||
- Pixel-art generation, full-game libraries, audio capture or deep guest introspection.
|
||||
- Shared editing, isolated worktrees, code snapshots/journals/checkpoints, merge/apply, divergence recovery, undo/rollback or automatic commits/clean-tree gates.
|
||||
- Replacing compiler, Packer, LSP, VM or human Debug semantics; a new general-purpose Studio source editor.
|
||||
- Remote MCP, accounts/OAuth and network runtime discovery. Studio-owned stdio and local Codex preparation are the explicit DEC-0061 additions.
|
||||
- Additional language implementation, persistent operation recovery or automatic task resumption.
|
||||
- Integrated discussion-framework agendas/decisions/plans in the product; those are future work, not this runtime/DEV/MCP contract.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
Implementation is conformant only when all phase gates hold and:
|
||||
|
||||
1. Human grant, task acquisition, operation outcome and authority return are distinct and tested.
|
||||
2. Service-level guards prevent conflicting manual work from grant through cleanup without blocking read-only navigation globally.
|
||||
3. Save failure prevents grant; successful return refreshes documents without overwriting agent edits.
|
||||
4. Revoke invalidates old calls first, works while waiting and preserves edits; project/application closure cleans owned processes and never restores authority.
|
||||
5. DEV and the agent see the same canonical image with explicit build/session/frame correlation and stale labeling.
|
||||
6. Local transport authentication does not bypass project/task authorization or scope restrictions.
|
||||
7. Lost operation responses cannot duplicate execution; runtime crash cannot trigger replay or implicit authority release.
|
||||
8. Language context and indexed local references reflect real installed support and work without source checkouts.
|
||||
9. Manual Debug, architecture boundaries, packaging and real-client integration pass their regression gates.
|
||||
|
||||
## Integrated Connection Revision (DEC-0061)
|
||||
|
||||
Connection and authority MUST be displayed separately. Initialization/ping
|
||||
liveness determines connection, while Core determines waiting/working/manual
|
||||
control. A missing descriptor means waiting for access, not proof that Studio is
|
||||
closed. Preparation reports initial client trust/reload requirements without
|
||||
modifying approval policy. Revocation removes published access even before
|
||||
asynchronous worker/runtime cleanup finishes. New grants never restore old task
|
||||
IDs or receipts. Full integrated native-client acceptance belongs to PLN-0140;
|
||||
the prior HTTP acceptance alone is insufficient.
|
||||
@@ -0,0 +1,616 @@
|
||||
# MCP Tools and Project Knowledge Contract
|
||||
|
||||
## Status, Scope and Authority
|
||||
|
||||
Owner: **studio**, application adapter and neutral automation API. This document
|
||||
formalizes DEC-0060 B5–B9 and the integrated connection revision in DEC-0061 (PLN-0140). It complements
|
||||
[DEV and Automation](10.%20DEV%20and%20Automation%20Specification.md), which owns
|
||||
project authority, lifecycle, captures and phase gates. It does not change those
|
||||
rules or the runtime-owned headless protocol.
|
||||
|
||||
The packaged machine-readable input schemas, authority classification and
|
||||
examples are in `prometeu-app/src/main/resources/mcp/studio-tools-v1.json`.
|
||||
Contract version is `1.0`. Catalog membership is not runtime availability:
|
||||
HTTP `tools/list` MUST expose only composed handlers, never placeholder implementations. The offline Studio stdio entry MUST advertise the packaged catalog and report unavailable live capabilities explicitly.
|
||||
Steps 17–21 connect the functional providers and DEV configuration assistance;
|
||||
steps 22–28 provide the real runtime gateway and integrated acceptance.
|
||||
|
||||
## 1. Connection Contract
|
||||
|
||||
The app hosts `/mcp` on **127.0.0.1 with an OS-assigned port**, using the JSON
|
||||
response form of MCP Streamable HTTP, protocol revision `2025-06-18`. The
|
||||
initialization exchange negotiates that supported revision; no compatibility
|
||||
with other revisions or deprecated HTTP+SSE transport is claimed. An offered
|
||||
unsupported revision receives the supported revision in `InitializeResult`.
|
||||
|
||||
Each desktop start generates a new instance identity. Each human project grant
|
||||
publishes a fresh 256-bit bearer credential scoped to that canonical project root.
|
||||
Every HTTP request MUST include `Authorization: Bearer <credential>`; missing,
|
||||
wrong or revoked credentials return 401. Initialized HTTP sessions MUST be bound
|
||||
to that credential/root; mixing another credential with an existing session returns
|
||||
403. All tools, including knowledge reads, MUST enforce the authenticated root
|
||||
before dispatch. No instance-wide credential bypass is permitted.
|
||||
|
||||
There is no query-string token, OAuth, cookie authentication, remote bind option
|
||||
or wildcard listener. The endpoint has no query parameters. Studio also provides
|
||||
its own stdio mode, described below; it is part of the same artifact.
|
||||
|
||||
Native clients may omit `Origin`. If present, it MUST exactly equal the live
|
||||
endpoint's origin (`http://127.0.0.1:<port>`); `null`, other ports/hosts/schemes
|
||||
and multiple Origin headers fail. Host MUST match the live loopback authority.
|
||||
Unexpected origins/hosts return 403. No permissive browser CORS policy is emitted.
|
||||
Credentials MUST NOT appear in diagnostics, exception messages, object string
|
||||
representations, generated reports or versioned configuration. The project discovery file is the only secret-bearing setup output; persistent client configuration and clipboard assistance MUST NOT export secrets.
|
||||
|
||||
Initialization assigns a separate random `Mcp-Session-Id`. Subsequent requests
|
||||
include this header and the negotiated `MCP-Protocol-Version`. The server can
|
||||
recover the negotiated version from its connection session if the version header
|
||||
is absent; an explicitly unsupported header returns 400. Missing required
|
||||
session returns 400; an unknown/closed session returns 404. The client sends
|
||||
`notifications/initialized` before tools. `ping` is available after initialization.
|
||||
|
||||
POST requires UTF-8 JSON and Accept support for `application/json` and
|
||||
`text/event-stream`. Responses use JSON, not SSE. GET returns 405. DELETE closes
|
||||
only the connection session, not project authority. Accepted notifications and
|
||||
client responses return 202 without a body. Notification/disconnection alone
|
||||
MUST NOT revoke a task or cancel an operation already returned by operationId.
|
||||
|
||||
The transport bounds incoming bodies to 1 MiB, sessions to 128 and request
|
||||
handling to a bounded worker queue. Oversized bodies return 413; exhausted
|
||||
session capacity returns 503. Stalled exchanges close after 15 seconds. These
|
||||
are HTTP resource protections, **not** task expiration or guest/runtime timeouts.
|
||||
Build/advance MUST return operation identities promptly. A lost response is
|
||||
resolved by authorized lookup, not by assuming cancellation or replay.
|
||||
|
||||
These details follow the official MCP [transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports),
|
||||
[lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle)
|
||||
and [tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
|
||||
contracts. Optional SSE, server-initiated requests, sampling, prompts, resource
|
||||
subscriptions and list-change notifications are not advertised.
|
||||
|
||||
### 1.1 Integrated Studio Entry and Offline Catalog
|
||||
|
||||
`StudioLauncher mcp --project <absolute-root>` MUST dispatch before JavaFX or
|
||||
Spring desktop startup. The root MUST be canonicalized once, contain the project
|
||||
manifest and remain bound for the process lifetime, independently of client cwd.
|
||||
The mode MUST NOT open a desktop, LSP, runtime or another HTTP listener. It uses
|
||||
newline-framed UTF-8 JSON-RPC on stdin/stdout; stdout is protocol-only. Requests
|
||||
are bounded to 1 MiB. EOF closes transport resources without releasing task control.
|
||||
|
||||
Initialize, initialized notification, ping and tools/list MUST work before the
|
||||
desktop, descriptor or grant exists. Offline descriptors come from the same
|
||||
packaged catalog as HTTP. A deterministic fingerprint covers protocol and tool
|
||||
schemas. Before forwarding, the connector MUST validate the descriptor, initialize
|
||||
HTTP, check instance/root/fingerprint metadata, and compare live descriptors with
|
||||
the packaged catalog. Missing handlers return unsupported capability; incompatible
|
||||
protocol/schema fails explicitly rather than silently changing the client's tools.
|
||||
|
||||
Tool calls MUST preserve structuredContent, text/error blocks and native image
|
||||
blocks. Response bounds MUST support images above the 1 MiB request limit; the
|
||||
current response cap is 32 MiB, including a bounded body-read deadline. Network
|
||||
redirects MUST NOT be followed. The connector MUST reject another project root.
|
||||
|
||||
Discovery runs on calls and bounded background checks. Missing publication means
|
||||
waiting for access, not proof that the desktop is closed. Distinguish invalid
|
||||
file/permissions, stale credentials/instance, catalog incompatibility and transport
|
||||
reconnection. Calls cannot wait indefinitely for a grant. No reconnect path may
|
||||
resubmit a tool call. An uncertain response MUST retain available clientRequestId
|
||||
correlation and instruct receipt lookup within the same authorized task. A new
|
||||
desktop/task has no old receipt registry and requires a fresh human grant.
|
||||
|
||||
### 1.2 Stable Installation and Project Preparation
|
||||
|
||||
The initial delivery targets Codex on macOS. Studio owns a versioned installation
|
||||
under `~/Library/Application Support/Prometeu/Studio`, with an atomic `current`
|
||||
reference. Each version includes `lib` dependencies and a compatible Java runtime
|
||||
under `runtime`. Validate a staged version before switching `current`; retain
|
||||
previous versions for rollback and already-running processes. Failed validation
|
||||
MUST leave the existing reference intact. Registered commands MUST work without
|
||||
an interactive shell PATH, external JDK or developer checkout.
|
||||
|
||||
The client command is the absolute `current/runtime/bin/java`, with argument-array
|
||||
values `-cp`, `<current>/lib/*`, `p.studio.app.StudioLauncher`, `mcp`, `--project`,
|
||||
and the canonical root. No project-local executable, generated transport script,
|
||||
helper binary or separate launcher installation is allowed. The desktop and
|
||||
connector use the same Studio artifact. JDWP is an explicit development-only JVM
|
||||
option; IntelliJ attaches to the client-owned connector process separately from
|
||||
the desktop Debug configuration.
|
||||
|
||||
New-project scaffolding and existing-project preparation MUST use the same neutral
|
||||
preparation port. `.studio/setup.json` stores integration schema/enabled/profile
|
||||
intent, preserving runtime/editor settings; it contains no endpoint/credential/task.
|
||||
Application infrastructure owns `.codex/config.toml` serialization. Its managed
|
||||
`mcp_servers.prometeu_studio` table stores the stable command, arguments, project
|
||||
cwd and cold-start timeout. Preserve all unrelated tables, comments, approval
|
||||
policy and server entries byte-for-byte; validate edits with a TOML parser.
|
||||
Repetition with identical values MUST be a no-op. User-owned or modified managed
|
||||
entries and tracked client configuration MUST produce an actionable conflict,
|
||||
never an overwrite. Keep a protected recovery copy of the previous owned block
|
||||
without copying unrelated secrets. Precise ignore rules protect machine-local
|
||||
client configuration and transient discovery without deleting existing rules.
|
||||
|
||||
Preparation MUST report incomplete writes/installations truthfully. Trust/reload
|
||||
instructions apply to initial client registration only; no client trust or tool
|
||||
approval may be bypassed. Grant and desktop restart MUST NOT require changing the
|
||||
client configuration. A clone is prepared locally to resolve its own installation
|
||||
and project paths. No global client configuration is rewritten.
|
||||
|
||||
### 1.3 DEV Connection Assistance
|
||||
|
||||
DEV MUST expose preparation/readiness through neutral API contracts and show
|
||||
connection status separately from Core authority. Waiting for access, connected
|
||||
and reconnecting derive from project-scoped initialization/ping activity with a
|
||||
bounded liveness window; a retained HTTP session ID alone is insufficient. Working
|
||||
remains an authority/operation state. DEV MUST NOT invent knowledge of a client
|
||||
before it connects. A transport drop MUST NOT revoke a task or grant new control.
|
||||
|
||||
Preparation, labels, clipboard, diagnostics and history MUST NOT expose secrets.
|
||||
Closing/hiding DEV only unsubscribes visual listeners. Human grant/reclaim and
|
||||
project/application teardown retain their shared Core semantics. Instructions
|
||||
cover native file edits, project knowledge, grant/acquire, validation, receipt
|
||||
lookup, images and explicit release without generated transport clients.
|
||||
|
||||
## 2. Identity and Admission
|
||||
|
||||
All tool inputs require `projectRoot`: an absolute filesystem root resolving to
|
||||
an open project. UI focus never supplies it. Core services resolve the actual
|
||||
project, including canonical-path/scope checks; syntactic validation does not
|
||||
prove authorization.
|
||||
|
||||
The authority levels in the packaged catalog are:
|
||||
|
||||
- `authenticated`: connection authentication only; project/context/reference reads
|
||||
need no acquired task. HTTP access still requires the project credential published by human grant. Offline catalog discovery returns no task token.
|
||||
- `granted`: acquisition validates the prior human grant and atomically creates
|
||||
the sole task identity. The transport session ID is not that identity.
|
||||
- `task`: `projectRoot` and `taskId` must identify the current acquired task.
|
||||
Revalidate before admission, lookup and deduplication, including read-only LSP.
|
||||
|
||||
No MCP tool grants human permission or simulates pressing the DEV button.
|
||||
There are no arbitrary-file read/write, shell, Git or publication tools. Editing
|
||||
uses the external client's native tools within the context's editable scope.
|
||||
|
||||
## 3. v1 Tool Catalog
|
||||
|
||||
Fields below supplement `projectRoot`, and `taskId` where authority is `task`.
|
||||
Input objects reject undeclared fields. IDs are nonempty opaque strings.
|
||||
|
||||
| Tool | Authority | Additional input | Successful value |
|
||||
| --- | --- | --- | --- |
|
||||
| `studio_project_context` | authenticated | none | Project context in section 5 |
|
||||
| `studio_reference_read` | authenticated | referenceId; optional offset/limit | Indexed reference page |
|
||||
| `studio_control_acquire` | granted | none | taskId, state=AGENT_WORKING |
|
||||
| `studio_control_release` | task | none | state=MANUAL, only after ordered cleanup |
|
||||
| `studio_language_query` | task | operation, parameters | Supported LSP query/proposal result |
|
||||
| `studio_build_start` | task | clientRequestId | operationId, clientRequestId, state |
|
||||
| `studio_headless_boot` | task | buildId | sessionId, buildId; boot uses the task's known build |
|
||||
| `studio_headless_reset` | task | none | Current session/reset state |
|
||||
| `studio_headless_set_input` | task | input | Current session acknowledgement |
|
||||
| `studio_headless_clear_input` | task | none | Current session acknowledgement |
|
||||
| `studio_headless_advance` | task | clientRequestId, frames | operationId, clientRequestId, state |
|
||||
| `studio_headless_capture` | task | none | Canonical image and metadata in section 6 |
|
||||
| `studio_headless_state` | task | none | Current session and runtime state |
|
||||
| `studio_headless_fault` | task | none | fault object or null, preserving structural fault details |
|
||||
| `studio_headless_shutdown` | task | none | Session shutdown acknowledgement after managed cleanup |
|
||||
| `studio_operation_get` | task | exactly one of operationId/clientRequestId | State, known progress, typed result/failure |
|
||||
| `studio_operation_cancel` | task | operationId | operationId, cancellationRequested |
|
||||
|
||||
Boot MUST NOT accept an arbitrary cartridge path. The shared service resolves
|
||||
buildId to known project artifacts. Runtime limits/capabilities come from the
|
||||
actual runtime, not fixed MCP promises. Frames is a nonnegative integer (zero
|
||||
is valid); values beyond effective limits fail rather than being clamped.
|
||||
|
||||
Input is a replacement snapshot: booleans `up/down/left/right/a/b/x/y/l/r/start/
|
||||
select/touch`, signed 32-bit `touchX/touchY`. Omitted fields reset to false/zero.
|
||||
It preserves the runtime's normal sampling/edge semantics, not UI keyboard events.
|
||||
|
||||
Language queries use the capabilities returned by project context. Parameters
|
||||
may contain URI, zero-based UTF-16 position/range/positions, workspace query,
|
||||
newName, includeDeclaration or task-local itemId for multi-stage queries. The
|
||||
provider MUST validate the parameters needed by the selected operation and reject
|
||||
unsupported operations explicitly. Diagnostics, definitions, references and
|
||||
symbols reuse the existing project LSP. Other queries/refactoring proposals are
|
||||
exposed only when supported; returned edits MUST respect project versus read-only
|
||||
SDK/library scope. No query applies filesystem edits.
|
||||
|
||||
### 3.1 Language Query Operations
|
||||
|
||||
`studio_language_query` uses the existing project's LSP server via a real client,
|
||||
not a parallel language implementation or a direct call into compiler semantics.
|
||||
Its successful value is `{operation, result, limitations}`. `result` is the JSON
|
||||
projection of the existing LSP response (including null or an empty list when
|
||||
appropriate); LSP union wrappers are unwrapped. Provider classes remain inside
|
||||
the application adapter. Studio API/Core use maps, lists and scalar values only.
|
||||
|
||||
| Operation | Required parameters beyond projectRoot/taskId |
|
||||
| --- | --- |
|
||||
| `diagnostics`, `documentSymbols`, `documentLinks`, `foldingRanges`, `formatting`, `semanticTokens` | `parameters.uri` |
|
||||
| `hover`, `completion`, `signatureHelp`, `definition`, `references`, `prepareRename`, `prepareCallHierarchy` | `uri`, `position`; references optionally accepts `includeDeclaration` |
|
||||
| `rename` | `uri`, `position`, `newName` |
|
||||
| `workspaceSymbols` | optional `query`; no document URI is needed |
|
||||
| `selectionRanges` | `uri`, nonempty `positions` |
|
||||
| `codeActions` | `uri`, ordered `range`; diagnostics are obtained from the current saved file |
|
||||
| `incomingCalls`, `outgoingCalls` | task-local `itemId` from a hierarchy result |
|
||||
|
||||
Support MUST be checked against the running server's initialize response before
|
||||
dispatch. Unknown operations, including currently unsupported type hierarchy,
|
||||
return `UNSUPPORTED_CAPABILITY`. Context publishes the installed provider's
|
||||
capabilities, including semantic tokens; hierarchy and rename preparations use
|
||||
their corresponding server capability. Positions are zero-based UTF-16 offsets,
|
||||
must fit the saved file and must not split surrogate pairs. Reversed ranges and
|
||||
missing operation-specific parameters are rejected.
|
||||
|
||||
The application lifecycle supplies each open project's bound loopback LSP
|
||||
endpoint. Studio uses OS-assigned ports so different open projects do not compete
|
||||
for one fixed port. The public LSP configuration default remains unchanged for
|
||||
other hosts. A manifest language change requires reopening that project's server;
|
||||
the adapter MUST NOT send queries to a server bound to another language/root.
|
||||
|
||||
Each query uses a short-lived client connection. For physical document requests, the
|
||||
adapter opens exactly the saved UTF-8 text and waits for that connection's
|
||||
published diagnostics before issuing the semantic query. Other dependency files
|
||||
are read from disk by the existing compiler bridge. A fresh connection prevents
|
||||
reuse of stale overlays from previous requests or the human editor. Unsaved or
|
||||
concurrent external writes remain the developer's responsibility.
|
||||
|
||||
Queries require the current task, share the project's work admission/cancellation
|
||||
and DEV operation observation, and do not silently queue behind conflicting work.
|
||||
Return/reclaim invalidates the task immediately, waits for worker termination,
|
||||
then clears task-local hierarchy items before manual control is restored. Item
|
||||
IDs from another task or project cannot be used. Client sockets/listeners close
|
||||
on success, failure, timeout or cancellation; project-server shutdown closes its
|
||||
accepted sockets and executor. A lost client does not independently grant control.
|
||||
|
||||
The adapter bounds connect time to 2 seconds and the LSP exchange to 10 seconds;
|
||||
Core bounds the request worker wait to 12 seconds. Documents are limited to 4 MiB
|
||||
of UTF-8 and task-local hierarchy state to 1024 items. These are adapter resource
|
||||
guards, unrelated to the runtime's deterministic frame/watchdog semantics.
|
||||
|
||||
Document URIs must resolve to known physical project/dependency source files or to an external identity owned by the current task and project.
|
||||
Symlink targets are canonicalized before admission. External sources may be
|
||||
queried, but edit-producing queries on read-only roots are rejected. Every URI in
|
||||
returned workspace-edit proposals is checked against the same editable/read-only
|
||||
scope; an unsafe proposal is rejected as a whole. File-operation edits and
|
||||
executable commands are not offered; `workspace/applyEdit` is always refused.
|
||||
No query writes a file. `readExternalSource` reads the exact registered external
|
||||
revision; hover and definition on its URI use the retained frontend semantic
|
||||
context. Indexed SDK reference tools remain separate and available. MCP needs no
|
||||
VS Code connection and MUST retain its consumer across short-lived query sockets.
|
||||
Task return/cancellation releases that task's external uses; project shutdown
|
||||
invalidates all identities. Cross-task/project replay is refused.
|
||||
|
||||
### External-source protocol (DEC-0062)
|
||||
|
||||
Initialize negotiates `capabilities.experimental.prometeuExternalSources: true`;
|
||||
the server advertises the same flag only when supported. External definitions use
|
||||
`prometeu-source:` URIs minted by the project host. A descriptor carries `uri`,
|
||||
`revision` (content digest), `origin`, `name`, `languageId` and `readOnly: true`.
|
||||
Locations carry ordinary LSP UTF-16 ranges over that exact source text.
|
||||
|
||||
The `prometeu/readExternalSource`, `prometeu/retainExternalSource`,
|
||||
`prometeu/releaseExternalSource` and `prometeu/revalidateExternalSource` requests
|
||||
carry `uri` and a server-issued `consumerId`. Initialize returns that identity in
|
||||
`capabilities.experimental.prometeuExternalConsumerId`. Reconnecting clients pass
|
||||
it as `initializationOptions.prometeuExternalConsumerId`; MCP also requests
|
||||
`initializationOptions.prometeuExternalPersistentConsumer: true` on first use.
|
||||
`releaseExternalSource` with `uri: null` releases the consumer and all its sources.
|
||||
A read or explicit retain acknowledges a navigation result; unacknowledged results
|
||||
are released when the socket closes. MCP acknowledges returned definitions before
|
||||
closing its query connection and rolls back newly retained results on failure.
|
||||
Read-only edit refusal uses LSP error `-32010`, mapped to MCP `READ_ONLY_SCOPE`.
|
||||
Consumer identity is scoped to the
|
||||
project session; the MCP adapter additionally binds it to its authorized task.
|
||||
Read returns the descriptor plus `text`. Retain/release are idempotent per consumer.
|
||||
Revalidation confirms the same admitted origin and revision before queries resume;
|
||||
a changed revision reports unavailable and requires new navigation. Unknown,
|
||||
expired, unauthorized and unreadable sources are explicit errors, never disk reads
|
||||
chosen by client paths. Consumers are created by the server, not caller-selected.
|
||||
|
||||
VS Code uses a read-only text content provider, with the source language and no
|
||||
save-back path. Disconnect may leave the immutable text visible, but blocks
|
||||
semantic queries until revalidation. No content-change event may replace the old
|
||||
revision under old positions. Closing the last consumer releases the snapshot;
|
||||
one reader closing must not invalidate another reader. Edit operations and mixed
|
||||
workspace edits are rejected in their entirety, including physical aliases.
|
||||
Packaged Studio validation is excluded from this delivery; development tests must
|
||||
exercise both VS Code and independent MCP navigation.
|
||||
|
||||
## 4. Result, Error and Operation Contracts
|
||||
|
||||
Successful tools return `isError:false` with structuredContent
|
||||
`{"status":"ok","value":{...}}`. Domain/admission failures return
|
||||
`isError:true` with `{"status":"error","error":{"code":"...","message":"..."}}`.
|
||||
Both include a text content block serializing the same structured data for clients
|
||||
that do not render structuredContent. Clients use error codes, not parsed prose.
|
||||
|
||||
`AutomationFailure.Code` defines domain codes, including project-not-open,
|
||||
not-granted, invalid-task, busy, unsupported language/capability, missing
|
||||
reference/documentation, out-of-scope/read-only scope, missing operation/build/
|
||||
runtime session, duplicate-ID parameter conflict, unavailable/incompatible runtime,
|
||||
missing frame, exceeded limit, not-cancelable and infrastructure failure.
|
||||
Unknown methods, malformed JSON-RPC and schema-invalid arguments remain protocol
|
||||
errors (-32601, -32600/-32700 and -32602); unexpected internals use sanitized
|
||||
-32603 responses, never request bodies, stack traces or credentials.
|
||||
|
||||
Build failure and guest fault are **operation outcomes**, not implicit release.
|
||||
`TrackedOperation` carries the existing `OperationSnapshot`, clientRequestId,
|
||||
known progress and either the existing typed build result or runtime outcome.
|
||||
Unknown requested/completed frame counts are null. Terminal infrastructure
|
||||
failure/cancellation MUST preserve only known progress. Cancellation acknowledgement
|
||||
does not assert worker termination or grant manual control.
|
||||
|
||||
The wire receipt flattens operationId/state from the neutral operation snapshot.
|
||||
Polling additionally returns progress and typed result/failure; incomplete results
|
||||
are null. Build results retain diagnostics/artifact correlation. Runtime results
|
||||
retain requested/completed frames and distinguish success, guest fault,
|
||||
termination, cancellation and infrastructure failure. Captured results include
|
||||
the same MCP image block used by direct capture.
|
||||
|
||||
`clientRequestId` deduplication is task-local and in-memory. Same ID plus same
|
||||
effective parameters returns the same operation; changed parameters fail with
|
||||
CLIENT_REQUEST_CONFLICT. Operation lookup accepts exactly one key. Revoked,
|
||||
cross-project or old task identities cannot read/cancel cached work. Neither MCP
|
||||
JSON-RPC IDs nor runtime requestIds replace this identity. Restart never restores
|
||||
the registry, replays an advance or recovers authorization.
|
||||
|
||||
### 4.1 Task Work and Correlation
|
||||
|
||||
`TaskTools` is the neutral service surface; MCP only validates schemas and projects
|
||||
its results. The Core implementation admits work through `AutomationSession.submit`
|
||||
and the existing operation executor, sharing DEV's busy state and cancellation.
|
||||
Acquisition requires the prior human grant. Release reports `MANUAL` only after
|
||||
managed cleanup and document refresh succeed; cleanup failures remain explicit.
|
||||
|
||||
Admission and request registration are atomic per project. Deduplication uses the
|
||||
operation kind and effective parameters, including requested frames. It is checked
|
||||
after task authority and before busy/active-runtime validation, so a repeated
|
||||
accepted start still resolves its original operation after that work has ended.
|
||||
Rejected starts do not reserve clientRequestIds. Distinct requests cannot silently
|
||||
queue behind busy work. Other projects remain independent.
|
||||
|
||||
Polling returns `workerTerminated` separately from operation state. `CANCELLED`
|
||||
may acknowledge interruption before the worker exits; it does not permit another
|
||||
conflicting operation or manual control. Final results remain null until worker
|
||||
termination. Progress contains only provider-reported counts and can be unknown.
|
||||
A cooperative final capture is published to DEV before termination while the task
|
||||
is still valid. A revoked task cannot publish a late frame or retrieve cached work.
|
||||
Historical operation images are marked stale when they no longer match DEV's
|
||||
current session/build/frame, or DEV has marked that capture stale.
|
||||
|
||||
Build executes the same saved-project compiler/packer preparation as manual
|
||||
Shipper, under task admission rather than a manual lease. It checks cancellation
|
||||
between compilation, validation and packaging phases. A successful build receives
|
||||
a task-local buildId; failed builds retain typed diagnostics and do not release
|
||||
control. Before rebuilding, the managed runtime must finish shutdown and detach.
|
||||
Old buildIds are invalidated before overwriting artifacts, including when the new
|
||||
build fails. This is artifact correlation, not source snapshots or recovery.
|
||||
|
||||
Headless handlers consume a neutral `HeadlessGateway` session port. Boot accepts
|
||||
only a current successful task build; one runtime session may be attached at a
|
||||
time. Input is normalized to a complete replacement snapshot. Advance limits come
|
||||
from that session and are enforced without clamping. Shutdown detaches only after
|
||||
managed cleanup finishes. Runtime process supervision and protocol mapping belong
|
||||
to the application gateway delivered in step 22, not to MCP or the test doubles.
|
||||
|
||||
Reset leaves the attached process unbooted, marks the previous capture stale and
|
||||
retains its build association. A subsequent explicit `studio_headless_boot` with
|
||||
that same current buildId reboots the known cartridge within the session. Boot
|
||||
without reset while a runtime is attached is rejected as busy. Reset does not
|
||||
change task authority or implicitly start execution. Rebuilding ends and detaches
|
||||
that process, invalidates previous buildIds and requires a fresh explicit boot.
|
||||
Synchronous headless failures finish their worker before returning the error,
|
||||
so a corrective call cannot race the failed worker's admission lock.
|
||||
|
||||
Task-local operation/build records are discarded after worker termination on
|
||||
return, revocation or project closure. Cleanup failures never restore authority;
|
||||
the records are still discarded after managed work stops. Neither connection
|
||||
disconnect nor polling silence discards an authorized task's records.
|
||||
|
||||
## 5. Project Knowledge DTOs
|
||||
|
||||
Neutral `ProjectKnowledge.Context` contains projectRoot/projectName, languages,
|
||||
libraries, editableRoots/readOnlyRoots, indexed references and explicit limitations.
|
||||
Its source is the project manifest and installed providers, never an AI-only file.
|
||||
|
||||
Each language includes id/primary, separately identified languageVersion,
|
||||
compilerVersion and sdkVersion, source extensions/roots, real capabilities and
|
||||
reference IDs. Version has `value` and `source`; unknown value is null with
|
||||
source `unknown`. Capability support distinguishes SUPPORTED/UNSUPPORTED/UNKNOWN
|
||||
and can explain a limitation. Unknown declared language MUST NOT fall back to PBS.
|
||||
|
||||
Libraries include identity, known version, roots and whether they belong to the
|
||||
editable project. External libraries and SDK remain read-only. Reference entries
|
||||
identify id/title/owner/kind/version; kinds include QUICKSTART, SYNTAX, SEMANTICS,
|
||||
EXAMPLE, SDK and LIBRARY. Indexed content belongs to its language/SDK owner.
|
||||
|
||||
Reference reads take an opaque ID from that index, not a path or arbitrary URI.
|
||||
Offset defaults to 0; limit defaults to 4000 and accepts 1–16000 Unicode code
|
||||
points. A page returns referenceId, offset, total, text and nextOffset (null at
|
||||
end). Invalid pagination fails; unknown/traversal-like IDs cannot escape the
|
||||
index. Installed reference content is resolved through the frontend's owner-maintained
|
||||
reference provider, not a Studio-maintained language specification.
|
||||
|
||||
### 5.1 Manifest and Provider Resolution
|
||||
|
||||
`studio_project_context` resolves an exact, canonical root registered by an open
|
||||
project session. It does not use the focused window, accept a source-directory
|
||||
path as a project root, acquire a manual lease, or acquire task authority. The HTTP boundary separately requires the grant-published project credential. A session
|
||||
is discoverable only after successful opening and until closure begins.
|
||||
Unregistered/closed roots return `PROJECT_NOT_OPEN`.
|
||||
|
||||
Each call reads the saved `prometeu.json` and dependency manifests again. Missing
|
||||
or invalid primary manifests fail explicitly instead of returning cached language
|
||||
metadata. Languages are grouped by declared ID, with the primary flag derived
|
||||
from the main manifest. Unknown IDs retain their identity and expose unsupported
|
||||
build/LSP support; no default frontend is consulted.
|
||||
|
||||
Extensions and source roots come from the installed frontend specification.
|
||||
LSP feature support comes from the same compiler bridge description used by the
|
||||
existing LSP server, not from a duplicated PBS capability list. If that provider
|
||||
cannot describe its LSP, support is UNKNOWN with an explicit limitation. These
|
||||
are installed-provider capabilities, not a promise that the MCP language-query
|
||||
tool is already composed or that any particular source file will compile.
|
||||
|
||||
Language versions remain unknown when no owner metadata exists. Compiler versions
|
||||
use the installed frontend package's `Implementation-Version` only when present.
|
||||
The requested SDK version has manifest provenance; the context distinguishes
|
||||
versions supported by the installed provider from unsupported requests. Multiple
|
||||
SDK requests for the same language yield an unknown aggregate version, an explicit
|
||||
limitation and separate SDK library entries. These identifiers MUST NOT be
|
||||
substituted for one another.
|
||||
|
||||
Dependency paths and registry entries use the compiler's existing resolver,
|
||||
including its main-root-relative local path semantics and registry requirement.
|
||||
Discovery does not create a registry, install dependencies or build sources.
|
||||
Unresolved declarations remain visible with empty roots and limitations. Mixed
|
||||
language graphs are described but reported as unsupported for the current build
|
||||
pipeline. Discovery is bounded to 256 projects and 256 declarations per manifest.
|
||||
|
||||
The editable scope is the canonical project root **minus** read-only roots.
|
||||
Read-only scope takes precedence: external/registry libraries and their transitive
|
||||
dependencies remain protected even when stored beneath the project root or also
|
||||
reachable through a local declaration. Source roots are canonicalized, including
|
||||
symlink targets. SDK entries are always read-only; packaged SDK resources need not
|
||||
have filesystem roots. Scope metadata does not sandbox an external agent's own
|
||||
filesystem tools; the developer remains responsible for those tools and Git.
|
||||
|
||||
Paths in MCP results are absolute filesystem strings, not `file:` URIs.
|
||||
|
||||
### 5.2 Installed References and Pagination
|
||||
|
||||
An installed frontend MAY implement `FrontendReferenceProvider` through
|
||||
`FrontendProvider.documentation()`. That compiler-side contract supplies indexed,
|
||||
owner-maintained texts for an SDK major and project target. It does not depend on
|
||||
Studio API or MCP. Studio projects these into neutral reference descriptors;
|
||||
full texts MUST NOT be included in project context. Reference IDs are namespaced
|
||||
by language (`<languageId>:`), unique within the selected project index and opaque
|
||||
to callers. Studio MUST NOT interpret an ID as a filename, URI or URL.
|
||||
|
||||
PBS packages its numbered specifications and informative quickstart from their
|
||||
owner directory, plus a compilable Game example and actual SDK sources/barrels.
|
||||
A build-generated index binds these texts to the installed frontend using content
|
||||
hashes. Distribution-only reads MUST work without a checkout or network. SDK and
|
||||
example references identify their SDK major and target; unsupported selections
|
||||
MUST NOT silently reuse another SDK/target. Numbered spec/draft revisions and the
|
||||
reference-index schema revision MUST NOT be reported as language/compiler versions.
|
||||
|
||||
`studio_reference_read` is authenticated but does not require an acquired task; the transport still requires a grant-published project credential. It resolves the explicit open root and its current saved manifest selection
|
||||
on every read. Changing SDK/target can invalidate previously advertised IDs.
|
||||
Only IDs in that project's installed index can be read, including when other
|
||||
languages/providers are installed globally. SDK and external-library texts remain
|
||||
consultable, not editable through this surface.
|
||||
|
||||
Pagination counts Unicode code points: an astral character occupies one offset,
|
||||
not two UTF-16 units. Offset 0/limit 4000 are defaults; limit MUST be 1–16000.
|
||||
An offset equal to total returns empty text and null nextOffset. Offsets beyond
|
||||
total, negative offsets, nonintegral values and integers beyond the implementation's
|
||||
signed 32-bit range are invalid parameters, never wrapped/truncated to another page.
|
||||
|
||||
Missing or unreadable provider documentation yields `DOCUMENTATION_UNAVAILABLE`
|
||||
limitations, not promised references. An uninstalled primary language yields
|
||||
`UNSUPPORTED_LANGUAGE` for reference reads; an available index without the requested
|
||||
ID yields `REFERENCE_NOT_FOUND`. Closed projects yield `PROJECT_NOT_OPEN` before
|
||||
reference lookup. These failures do not grant/revoke task authority.
|
||||
|
||||
## 6. Image Contract
|
||||
|
||||
MCP image content has `type:image`, `mimeType:image/png`, and base64 `data` of
|
||||
the unchanged `CanonicalCapture.png` bytes. No screenshot, log scraping, temporary
|
||||
path or network fetch is required. The structured value includes sessionId,
|
||||
buildId, logicalFrameIndex, frameId, width, height, stridePixels, pixelFormat
|
||||
`RGBA8888`, mimeType and stale. Stride describes the original framebuffer, not PNG
|
||||
compression/padding. Logical and render frame counters are independent.
|
||||
|
||||
The adapter MUST NOT invent a frame when none exists or substitute another
|
||||
session's image. The same neutral capture feeds DEV and MCP. Real runtime
|
||||
production/cross-language equality is verified by the phase 4 desktop integration
|
||||
gate below; encoding test pixels in contract tests alone does not satisfy it.
|
||||
|
||||
## 7. Conformance and Delivery Boundary
|
||||
|
||||
Contract tests validate every tool's example, authority level, required project/
|
||||
task IDs, invalid types/unknown fields, exclusive operation lookup, input ranges,
|
||||
pagination, result envelopes, PNG bytes and independent frame identities.
|
||||
HTTP tests use a real loopback listener/client and exercise initialization,
|
||||
authentication, Origin, endpoint/method/version handling, tool dispatch, malformed
|
||||
or oversized input, closure, restart and old-token rejection. Provider doubles
|
||||
exist only in tests. Composition starts/closes transport with Studio.
|
||||
|
||||
The production registry composes all 17 tools as of step 23, including headless
|
||||
handlers bound to the actual `HeadlessProcessGateway`. Missing project runtime
|
||||
configuration fails at boot with `RUNTIME_UNAVAILABLE`; tool discovery does not
|
||||
grant authority or launch a process. No fake runtime is shipped.
|
||||
The former configuration-copy flow is superseded by DEC-0061 permanent preparation and grant-time discovery. The automated HTTP conformance
|
||||
gate exercises all 17 tool contracts using real project knowledge/LSP and test-only
|
||||
build/runtime ports; a separate HTTP test uses the real compiler/packer. This
|
||||
completes MCP-phase conformance. The packaged-runtime gate additionally exercises
|
||||
actual app composition, project LSP, compiler/packer, saved edits, explicit
|
||||
reset/reboot, build identity invalidation and corrective loops after compile
|
||||
errors/guest faults.
|
||||
|
||||
Step 24 adds `headlessMcpDesktopTest`: a real HTTP client drives the composed app,
|
||||
installed compiler/packer/LSP and packaged Rust runtime, while the actual JavaFX
|
||||
DEV view observes the shared session. An independent test-only JSONL client runs
|
||||
the same saved cartridge and input timeline in another real process, without the
|
||||
Studio process adapter or capture DTOs. Raw PNG bytes and each capture metadata
|
||||
field match MCP; all decoded framebuffer pixels and the visible identity/stale
|
||||
labels match DEV. State/fault and deterministic reset/fresh-session repetitions
|
||||
are also checked. Rebuilding changes pixels/build identity and visibly marks the
|
||||
old capture stale. Images remain in memory; window screenshots are not evidence.
|
||||
|
||||
The fixture uses supported project-source LSP definition/symbol navigation and
|
||||
indexed SDK reads. The historical probe of the former SDK `Input.pad()` definition returned
|
||||
an empty result (the current facade is Pad/Button and Touch); the gate does not claim SDK
|
||||
symbol navigation where no location is returned. This is a language tooling
|
||||
limitation, not a headless or MCP execution fallback.
|
||||
|
||||
Step 25 extends that real desktop/HTTP gate with active-operation cancellation,
|
||||
connection deletion/reconnection and duplicate receipts, waiting/active revoke,
|
||||
late-call rejection, project closure/reopening and application-context shutdown.
|
||||
A controlled document participant delays refresh acknowledgement to prove that
|
||||
manual control remains blocked until process cleanup and disk refresh complete;
|
||||
it also checks that no revoked frame or old source buffer is applied afterward.
|
||||
The real runtime is killed or suspended in test-owned processes to verify known
|
||||
progress, no implicit restart/replay, forced cleanup and explicit human retry.
|
||||
Compile errors and guest faults are corrected over HTTP within the same task.
|
||||
The normal desktop Debug process starts after release and blocks a new grant.
|
||||
The suspension/manual-Debug scenarios require a POSIX desktop and a free Debug
|
||||
port 7777; the gate never attaches to an existing user's Debug process.
|
||||
|
||||
The automated client is not an external coding agent. Separate acceptance on
|
||||
2026-09-29 used Codex CLI 0.158.0 against the packaged Studio and runtime 0.1.0
|
||||
on macOS ARM64. The agent consulted references/LSP, edited saved PBS source,
|
||||
built/packed, consumed native MCP PNGs, tested 1,110 frames of directional input,
|
||||
and explicitly released authority. The developer confirmed DEV and then ran the
|
||||
edited game through manual Debug Play. This establishes compatibility for that
|
||||
client/platform, not uniform compatibility across providers or operating systems.
|
||||
|
||||
Full regression and distribution gates also passed: installed offline references,
|
||||
real runtime protocol tests, architecture/Modulith, and two isolated startup/stop
|
||||
cycles using the extracted Studio ZIP. The latter verified listener closure and
|
||||
old-credential rejection after restart. API/Core and JavaFX MUST NOT import
|
||||
MCP/HTTP implementations; architecture tests enforce it. Consolidated acceptance
|
||||
evidence and deferred findings live in the DSC-0068 lesson, not in temporary logs.
|
||||
|
||||
### Integrated Connection Acceptance (DEC-0061)
|
||||
|
||||
Prior DSC-0068 native-client evidence covers the original HTTP flow only. The
|
||||
integrated flow additionally requires a real native Codex session initialized
|
||||
before grant, unchanged configuration through desktop restart/new grant, native
|
||||
images/build/release, scaffold and existing-project preparation, installation
|
||||
update and graphical launch, plus IntelliJ connector attachment. Automated
|
||||
fixtures cannot substitute for these gates. PLN-0140 completed automated validation
|
||||
and the user confirmed all outstanding manual gates on 2026-09-29. The manual
|
||||
confirmation is user-reported acceptance, not an independently observed test run.
|
||||
[LSN-0077](../../../discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md)
|
||||
preserves the result and evidence provenance after workflow housekeeping.
|
||||
|
||||
### Automatic preparation when opening a project
|
||||
|
||||
Opening a project MUST prepare its enabled MCP integration using the same neutral
|
||||
port as scaffold and DEV retry. Desktop composition MUST start the shared loopback
|
||||
server before project sessions become available; no external command or separate
|
||||
per-project desktop Run is required. Explicitly disabled integration MUST remain
|
||||
disabled. Preparation failure MUST remain visible in DEV readiness without blocking
|
||||
project use. Opening MUST NOT publish credentials or grant/acquire agent control.
|
||||
The coding client continues to own its configured stdio process and initial trust.
|
||||
@@ -73,13 +73,14 @@ Propagation rules:
|
||||
- propagation is workspace to global;
|
||||
- global-to-workspace rebroadcast is not baseline behavior.
|
||||
|
||||
The global Studio bus is backed by a typed event bus reference owned by the Studio application container.
|
||||
The global Studio bus is a JavaFX-adapter facility created by the application composition root and injected into the UI factory.
|
||||
|
||||
Container rules:
|
||||
Composition rules:
|
||||
|
||||
- the Studio `Container` owns the global typed event bus reference used by `StudioEventBus`;
|
||||
- host-integrated services that need shared Studio operational visibility should receive that container-owned typed event bus reference during bootstrap instead of allocating disconnected local buses;
|
||||
- the `Container` must be initialized during Studio boot before packer-backed integration services, workspaces, or adapters begin use.
|
||||
- `prometeu-app` owns construction and lifecycle of the shared UI bus;
|
||||
- UI composition roots receive the bus explicitly and workspace buses derive from that injected instance;
|
||||
- host integrations publish neutral application facts through their owning API boundary and may be adapted to UI events at the JavaFX edge;
|
||||
- `p.studio.Container`, Spring context lookup, or another static service locator must not participate in event access.
|
||||
|
||||
This topology exists so callers do not need to duplicate publication decisions manually.
|
||||
|
||||
@@ -98,6 +99,8 @@ Illustrative baseline categories include:
|
||||
- diagnostics update events;
|
||||
- asset selection events.
|
||||
|
||||
Selection, navigation, attach/detach, edit scope, and presentation refresh are UI-local event categories. Application facts such as execution state, build results, runtime state, and asset operation results belong to neutral API contracts owned by their functional module and must not be defined only as JavaFX events.
|
||||
|
||||
For project bootstrap and splash/loading integration, the Studio event catalog should reserve typed events for:
|
||||
|
||||
- project loading started;
|
||||
|
||||
@@ -1,169 +1,66 @@
|
||||
# Studio Components Module Specification
|
||||
# Studio JavaFX Components Boundary Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
|
||||
Purpose: Define the authoritative visual control layer for the Studio.
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-studio-ui-javafx`
|
||||
- shared Studio controls and workspace-framework primitives
|
||||
- JavaFX controls actively used by the Studio
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the visual component boundary inside the JavaFX adapter without creating a second application or domain layer.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio components module decision into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- `prometeu-studio-components`
|
||||
- Studio shell and workspace UI needs
|
||||
- JavaFX controls actively used by the Studio
|
||||
This specification is subordinate to [`9. Studio Core and Adapter Architecture Specification.md`](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md).
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. `prometeu-studio-components` is the official visual control module for Studio UI.
|
||||
2. Studio UI should normally consume visual controls from `prometeu-studio-components`, not directly from raw JavaFX.
|
||||
3. A control enters the module when it is needed by the current Studio UI wave.
|
||||
4. Controls in the module wrap and shape the JavaFX controls the Studio actively uses, but do not clone the full JavaFX API.
|
||||
5. Every admitted control must preserve theme and i18n compatibility.
|
||||
6. Reusable event-driven workspace controls should be admitted when they are part of the active Studio workspace framework.
|
||||
1. Reusable Studio visual controls belong to `prometeu-studio-ui-javafx`.
|
||||
2. The JavaFX adapter may organize reusable controls by shell, forms, banks, lifecycle, navigation, feedback, and inspection roles.
|
||||
3. A control is admitted when it has an immediate Studio consumer; speculative mirroring of JavaFX is forbidden.
|
||||
4. Shared controls must preserve theme, localization, and explicit visual-state behavior.
|
||||
5. Controls that observe UI events must expose predictable attach/detach or subscribe/unsubscribe lifecycle behavior.
|
||||
6. Visual controls must depend on neutral Studio API contracts, not core or provider implementations.
|
||||
7. Domain rules, application orchestration, filesystem workflows, compiler/Packer/LSP/runtime calls, and Spring composition do not belong in the visual component layer.
|
||||
|
||||
## Module Role
|
||||
## JavaFX Wrapping Boundary
|
||||
|
||||
`prometeu-studio-components` is:
|
||||
The Studio may use raw JavaFX for trivial local composition. A reusable control should expose the Studio-facing API actually needed instead of cloning the complete upstream JavaFX surface.
|
||||
|
||||
- the authoritative Studio control layer;
|
||||
- the home of the Studio visual dialect;
|
||||
- the place where Studio-facing controls are shaped for Studio use;
|
||||
- the preferred home for reusable lifecycle-aware workspace controls when those controls are part of the visible Studio UI dialect.
|
||||
Shared controls may include:
|
||||
|
||||
`prometeu-studio-components` is not:
|
||||
- shell and action controls;
|
||||
- workspace rails and hosts;
|
||||
- form sections and action bars;
|
||||
- list, tree, inspector, and dual-list surfaces;
|
||||
- activity, progress, badges, headers, and feedback controls;
|
||||
- lifecycle-managed visual primitives.
|
||||
|
||||
- a speculative generic framework;
|
||||
- a full reimplementation of JavaFX;
|
||||
- a dumping ground for unrelated non-visual infrastructure.
|
||||
## Construction and Lifecycle
|
||||
|
||||
## Admission Policy
|
||||
Controls, rows, dialogs, and views MUST NOT be Spring singletons by default. A Spring-managed JavaFX composition factory may create them with explicit constructor dependencies.
|
||||
|
||||
A control is admissible when it is needed by the current Studio UI work.
|
||||
Controls that attach event subscriptions MUST release them when detached. UI-local events may coordinate selection, navigation, editing scope, attach/detach, and presentation refresh. Request/response application behavior MUST use injected Studio API services directly.
|
||||
|
||||
Rules:
|
||||
## State Boundary
|
||||
|
||||
- immediate current Studio use is sufficient justification;
|
||||
- a second use is not required when the control is clearly part of the shell or the current workspace surface;
|
||||
- no control should be added without an immediate Studio consumer.
|
||||
- a control needed first by one workspace may still be admitted when it is clearly intended as a reusable Studio workspace primitive.
|
||||
Presentation-only view models, form drafts, selection state, and formatting helpers may live beside JavaFX controls when they do not determine domain outcomes.
|
||||
|
||||
## Studio Usage Rule
|
||||
|
||||
The baseline Studio UI should not rely on raw JavaFX controls as its normal visual surface.
|
||||
|
||||
Rules:
|
||||
|
||||
- a visual control used by Studio should normally come from `prometeu-studio-components`;
|
||||
- extremely trivial local composition may stay in `prometeu-studio`;
|
||||
- local exceptions must remain exceptional rather than becoming the default path.
|
||||
|
||||
## Wrapping Boundary
|
||||
|
||||
Controls in `prometeu-studio-components` must wrap the JavaFX controls the Studio actively uses.
|
||||
|
||||
Rules:
|
||||
|
||||
- the Studio-layer control should expose the Studio-facing API actually needed;
|
||||
- exhaustive mirroring of upstream JavaFX APIs is not required;
|
||||
- the goal is consistency and clarity, not a perfect one-to-one mirror of every JavaFX type.
|
||||
|
||||
## Control Lifecycle Hooks
|
||||
|
||||
Studio controls may need to observe event buses or other external state.
|
||||
|
||||
Rules:
|
||||
|
||||
- the control layer must provide explicit subscribe and unsubscribe lifecycle methods that can be overridden when needed;
|
||||
- the control layer should also provide `onAttached()` and `onDetached()` lifecycle hooks;
|
||||
- `onAttached()` should call `subscribe()`;
|
||||
- `onDetached()` should call `unsubscribe()`;
|
||||
- controls that attach subscriptions must also define how those subscriptions are released;
|
||||
- event-driven controls must not hide subscription lifecycle completely inside ad hoc local wiring.
|
||||
|
||||
These hooks exist so event-driven controls remain predictable and safe to embed in shell and workspace UI.
|
||||
|
||||
## Reusable Workspace Primitives
|
||||
|
||||
Some reusable controls are not shell-only and are not domain-specific either.
|
||||
|
||||
They may still belong in `prometeu-studio-components` when they are part of the visible Studio workspace framework.
|
||||
|
||||
Illustrative admissible examples include:
|
||||
|
||||
- projection hosts for list/tree/detail surfaces;
|
||||
- lifecycle-managed row or item controls;
|
||||
- reusable section or inspector surfaces;
|
||||
- visible controls that encode local-patch versus structural-sync interaction patterns.
|
||||
|
||||
What does not belong here:
|
||||
|
||||
- workspace-specific orchestration logic;
|
||||
- domain-specific service calls;
|
||||
- hidden coordination code with no visible control responsibility.
|
||||
|
||||
## Typical Control Scope
|
||||
|
||||
Typical controls that belong in the module include:
|
||||
|
||||
- shell controls;
|
||||
- action controls and buttons;
|
||||
- tab systems;
|
||||
- tree and list controls;
|
||||
- inspector and panel surfaces;
|
||||
- activity and feedback surfaces;
|
||||
- badges, headers, and related Studio primitives.
|
||||
|
||||
What stays outside the module:
|
||||
|
||||
- workspace-specific composition logic;
|
||||
- non-visual domain behavior;
|
||||
- speculative controls with no immediate Studio consumer.
|
||||
|
||||
## Theme and i18n
|
||||
|
||||
Every admitted control must support:
|
||||
|
||||
- CSS-based theming;
|
||||
- safe locale-aware text behavior when text is exposed;
|
||||
- no hardcoded user-facing text;
|
||||
- explicit visual states where state matters.
|
||||
|
||||
## Organization Guidance
|
||||
|
||||
The module should be organized by Studio role rather than vague technical buckets.
|
||||
|
||||
Illustrative areas include:
|
||||
|
||||
- shell;
|
||||
- actions;
|
||||
- navigation;
|
||||
- feedback;
|
||||
- inspection;
|
||||
- trees.
|
||||
|
||||
## Anti-Bloat Rule
|
||||
|
||||
The module must remain:
|
||||
|
||||
- intentional;
|
||||
- Studio-driven;
|
||||
- small enough to reason about;
|
||||
- broad enough to prevent UI entropy in the application.
|
||||
Non-visual policies and workflows that determine asset validity, capacity, metadata, build, runtime, project, or semantic results MUST live behind `prometeu-studio-api` and be implemented by `prometeu-studio-core` or an explicit infrastructure adapter.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- defining the first concrete component set in full detail
|
||||
- defining final package layout exhaustively
|
||||
- mirroring the entire JavaFX control hierarchy
|
||||
- storing domain-specific workspace orchestration code in the components module
|
||||
- creating a standalone `prometeu-studio-components` Gradle module;
|
||||
- wrapping the full JavaFX API;
|
||||
- storing workspace business logic in controls;
|
||||
- using Spring as a registry for each visual object;
|
||||
- defining components for a future web UI.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- the module role is unambiguous;
|
||||
- admission rules are stable enough to guide implementation;
|
||||
- reusable workspace-control admission is clear enough to prevent local reimplementation drift;
|
||||
- the JavaFX wrapping boundary is clear enough to prevent drift.
|
||||
This specification is satisfied when reusable JavaFX controls have clear visual ownership, explicit lifecycle behavior, neutral injected dependencies, and no application or provider implementation responsibilities.
|
||||
|
||||
@@ -6,7 +6,10 @@ Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-studio`
|
||||
- `prometeu-studio-api`
|
||||
- `prometeu-studio-core`
|
||||
- `prometeu-studio-ui-javafx`
|
||||
- `prometeu-app`
|
||||
- the Studio `Assets` workspace
|
||||
- packer-facing Studio service integration for asset browsing, inspection, diagnostics, and staged mutations
|
||||
|
||||
@@ -29,6 +32,7 @@ This specification extends:
|
||||
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
|
||||
- [`9. Studio Core and Adapter Architecture Specification.md`](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md)
|
||||
|
||||
For packer-facing semantics, this specification must align with:
|
||||
|
||||
@@ -52,7 +56,7 @@ The workspace must assume:
|
||||
- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services;
|
||||
- packer-facing operational freshness may surface states such as `healthy`, `stale`, `diverged`, `reconciling`, or `failed`.
|
||||
|
||||
Packer-backed operational events consumed by this workspace are expected to enter Studio through the container-owned typed event bus path rather than through workspace-local ad hoc bus creation.
|
||||
The JavaFX workspace must consume neutral Studio asset contracts. Stable public Packer APIs are consumed by Studio Core where appropriate; Packer bootstrap and concrete integration remain in `prometeu-app`. Packer-backed application facts may be projected into UI-local events at the JavaFX edge, but the workspace must not call Packer directly or create an ad hoc provider integration.
|
||||
|
||||
## Workspace Model
|
||||
|
||||
@@ -100,6 +104,7 @@ The `Assets` workspace must be implemented as a composition root plus lifecycle-
|
||||
Rules:
|
||||
|
||||
- the workspace root should coordinate service calls, workspace state, and structural synchronization;
|
||||
- service calls must target injected `prometeu-studio-api` contracts; domain workflows and filesystem orchestration must not be implemented by the workspace root;
|
||||
- the workspace root should not own the render and update path of every navigator row, details section, and form control directly;
|
||||
- the navigator host, asset rows, selected-asset details host, and details-internal sections/forms should subscribe only to the events and state they consume;
|
||||
- event-consuming controls must subscribe only while mounted in the UI tree;
|
||||
|
||||
@@ -6,7 +6,10 @@ Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-studio`
|
||||
- `prometeu-studio-api`
|
||||
- `prometeu-studio-core`
|
||||
- `prometeu-studio-ui-javafx`
|
||||
- `prometeu-app`
|
||||
- Studio project-session persistence under `.studio/`
|
||||
- project-local Studio session restoration state
|
||||
- project-local Studio setup configuration
|
||||
@@ -26,7 +29,7 @@ It extends:
|
||||
## Core Rules
|
||||
|
||||
1. The canonical root for project-local Studio persistence MUST be `.studio/` in the project root.
|
||||
2. The main project-local Studio session-restoration store MUST be owned by `StudioProjectSession`, or by a service explicitly owned by `StudioProjectSession`.
|
||||
2. The main project-local Studio session-restoration store MUST be owned by the neutral project-session boundary, implemented in `p.studio.core.session` or by a project service explicitly composed into that session.
|
||||
3. The main session-restoration store MUST remain a single file at `.studio/state.json`.
|
||||
4. The main session-restoration store MUST be versioned.
|
||||
5. The main session-restoration store MUST load when the project session opens.
|
||||
@@ -76,6 +79,8 @@ The main session-restoration store MUST NOT include:
|
||||
- heavy operational output;
|
||||
- recomputable results that do not represent session restoration state.
|
||||
|
||||
Under DEC-0060, automation grants, task/control identities, active runtime sessions and the task-local operation/deduplication registry MUST NOT be persisted or restored through `.studio/state.json` or `.studio/setup.json`. Reopening a project MUST start under manual control. Restoring DEV as the selected workspace is presentation restoration, not permission to resume work. MCP connection credentials MUST NOT be stored in versioned files; they are regenerated for every project grant and never restored on restart. See the [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md).
|
||||
|
||||
`Project-local activity` and project-local setup may still live under `.studio/`, but they are separate persistence concerns and not part of the main session-restoration store defined here.
|
||||
|
||||
## Ownership Rules
|
||||
@@ -100,3 +105,36 @@ This specification is complete enough when:
|
||||
- accepted and excluded categories are explicit;
|
||||
- load, restore, save, and fallback timing are explicit;
|
||||
- and the ownership boundary with `StudioProjectSession` is normatively locked.
|
||||
|
||||
## Integrated MCP Discovery (DEC-0061)
|
||||
|
||||
`.studio/setup.json` MUST carry neutral `agentIntegration` intent with
|
||||
`schemaVersion:1`, `enabled` and `clientProfile`. Preserve runtime and editor
|
||||
fields. This intent is configuration, not readiness or authorization. Machine-local
|
||||
resolved client configuration is a separate preparation output.
|
||||
|
||||
The transient descriptor is `.studio/mcp/connection.json`, limited to 16 KiB.
|
||||
Schema v1 requires integral `schemaVersion:1` and nonempty string `instanceId`,
|
||||
`projectRoot`, `endpoint`, `credential`, `catalogFingerprint`. Root MUST match the
|
||||
connector's canonical root. Endpoint MUST be `http://127.0.0.1:<port>/mcp`, with
|
||||
no userinfo, query, fragment or redirect. Grant/task IDs and receipts are forbidden.
|
||||
|
||||
On macOS `.studio/mcp` MUST be owned by the current user with mode 0700;
|
||||
descriptor, lock and temporary files MUST be 0600 before secrets are written.
|
||||
Reject symlinked/unsafe paths and tracked descriptor targets. Add precise ignore
|
||||
rules idempotently without changing unrelated project permissions or files.
|
||||
|
||||
Ownership MUST use an OS-held lock on the stable `publication.lock` inode; do
|
||||
not delete the lock file on ordinary cleanup. A second live publisher fails. A
|
||||
crashed process releases its lock through the OS; a new owner may atomically
|
||||
replace stale content. Write a protected same-directory temporary file and
|
||||
atomically rename it. Cleanup checks both instance and publication generation
|
||||
so an old callback cannot remove newer discovery data.
|
||||
|
||||
Publication is a required grant lifecycle participant, not a swallowed observer.
|
||||
Prepare/publish occur outside the Core monitor; authority activation uses a
|
||||
generation fence. Acquisition cannot succeed until publication and grant both
|
||||
commit. Failure aborts credentials/files and reports a failed grant. Revoke/close
|
||||
invalidate credentials before asynchronous work cleanup, then remove owned
|
||||
publication and release ownership. File cleanup failure MUST NOT prevent runtime
|
||||
cancellation. An already-admitted release response MUST remain deliverable.
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user