Compare commits

...
Author SHA1 Message Date
bquarkz 632ba6d0d6 refactor(compiler)!: migrate SDK to minimal storage ISA
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
Replace retired guards and publication opcodes with SDK checks, neutral TRAP and sequential List/Linked mutations with explicit failure phases. Preserve snapshot cursors and import schema 2 metadata with the delivered provider pin.

Include common/source/installed conformance, debug and release evidence, synchronized specs and the consolidated lesson. Runtime checkout remains unchanged.
2026-10-24 01:35:42 +01:00
bquarkz 77aada6259 feat(pbs): add linked collections and bidirectional snapshots
Implement SDK linked<T> with forward and reverse Cursor snapshots, trusted compiler integration, and neutral FIELDS_PUBLISH producer support. Pin the tested runtime revision and include specs, editor and installed knowledge coverage, conformance fixtures, and DSC-0091 lessons and evidence.
2026-10-23 10:28:44 +01:00
bquarkz c410e35001 feat(pbs): add mutable lists and stable snapshot cursors
Implement SDK list<T> and Cursor<T> with trusted compiler bindings and generic storage publication across IR and PBX. Pin the runtime provider and include specs, conformance coverage, installed examples, and DSC-0090 lessons.
2026-10-23 00:46:39 +01:00
bquarkz 76a8b074e8 feat(pbs): add concrete generic structs and free functions 2026-10-22 14:42:38 +01:00
bquarkz 240216170c feat(pbs): add parametric arrays and concrete generic contracts
Support explicit contract type parameters, canonical nominal applications,
recursive substitution, concrete implementations and instantiated editor views.
Complete parametric Array syntax and contextual construction integration.

Preserve type origins across imports and reexports, fix trait argument stack
order, and relocate global slots before lifecycle assembly. Publish specs,
installed examples and consolidated discussion lessons.

Validate frontend, common pipeline, architecture, LSP and installed knowledge
gates, plus the full production VM conformance corpus with 14 generic fixtures.
2026-10-20 11:30:00 +01:00
bquarkz b62db87245 feat(pbs): integrate explicit runtime Random handles 2026-10-17 13:51:12 +01:00
bquarkz d1e9259085 feat(pbs): add service constants and runtime math integration 2026-10-17 11:21:58 +01:00
bquarkz 2a418085d2 feat(pbs): implement first-class functions and explicit captures 2026-10-17 01:27:52 +01:00
bquarkz 39df63581c feat(pbs): implement typed arrays, optional binding and contract execution 2026-10-16 16:21:33 +01:00
bquarkz c4e1b9055d fix(compiler): isolate PBS conformance tests from common pipeline 2026-10-16 11:56:55 +01:00
bquarkz a04214a705 fix(mcp): allow runtime error details in tool output schemas 2026-10-16 11:51:55 +01:00
bquarkz 91eb86f317 test(packer): qualify asset contracts and improve Jenkins reporting 2026-10-16 11:47:58 +01:00
bquarkz 13c0ababbb feat(pbs): align typed values and Pad input facade
Test / Build occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
2026-10-15 15:48:50 +01:00
bquarkz 603ed01227 feat(compiler): port runtime catalogs and enforce target ABI (AGD77)
Import both runtime catalogs and provenance, port all intrinsic metadata and exact constants, and validate target signatures and carriers through the common pipeline. Package matching compiler/SDK resources and add active parity plus production runtime conformance checks.

Validation: 420 compiler/PBS tests passed, with 12 existing skips; provider export, runtime execution and installed catalog checks passed. The pre-existing Gfx.clear typed-metadata failure remains active and assigned to AGD78 under the explicitly accepted scope revision recorded in LSN-0080.
2026-10-15 13:07:49 +01:00
bquarkz bd5694dbdf feat(compiler): implement typed registry and production PBX conformance (AGD76) 2026-10-14 21:04:04 +01:00
bquarkz a9ede541af Merge pull request 'feat(pbs): resolve editorial chains and expose read-only external sources' (#35) from dev/pbs-editorial-chains-sdk-navigation into master
Test / Build skipped: 16, passed: 942
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 66.91% (23371/34928) * Branch Coverage: 56.47% (9948/17616) * Lines of Code: 34928 * Cyclomatic Complexity: 15041 #### Quality Gates Summary Output truncated.
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Reviewed-on: #35
2026-10-07 08:36:18 +00:00
bquarkz d71e46ade8 fix(ci): publish coverage separately from test checks
Test / Build skipped: 16, passed: 838
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 66.91% (23370/34928) * Branch Coverage: 56.47% (9947/17616) * Lines of Code: 34928 * Cyclomatic Complexity: 15041 #### Quality Gates Summary Output truncated.
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
2026-10-07 09:25:14 +01:00
bquarkz 8dff6d8d5f package testing
Test / Build skipped: 16, passed: 838
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
2026-10-07 09:09:31 +01:00
bquarkz 967b9ec598 feat(pbs): resolve editorial chains and expose read-only external sources
Intrepid/Prometeu/Studio/pipeline/head Build started...
Test / Build skipped: 16, passed: 838
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
2026-10-07 09:00:31 +01:00
290 changed files with 25375 additions and 2091 deletions
+16 -2
View File
@@ -66,6 +66,20 @@ configuration; old task identities and operation receipts are not restored.
DEV displays connection separately from project authority. No project-local DEV displays connection separately from project authority. No project-local
launcher, Python transport script or embedded chat is required. 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 ### Installation and IntelliJ development
Build and stage the complete distribution, including its Java runtime: Build and stage the complete distribution, including its Java runtime:
@@ -175,8 +189,8 @@ acknowledge completed cleanup; control stays locked until cleanup is confirmed.
The following findings are recorded for investigation after implementation; they The following findings are recorded for investigation after implementation; they
are not considered fixed by the passing integration tests: are not considered fixed by the passing integration tests:
- **PBS/LSP SDK navigation:** definition lookup for the bundled SDK's `Input.pad()` - **PBS/LSP SDK navigation:** the historical probe of the former `Input.pad()`
currently returns no location. Project-source navigation and indexed SDK reference 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 reads work. Investigate SDK symbol resolution separately; an empty definition
result is not evidence of missing runtime support or permission to edit the SDK. 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 - **Build tooling:** the validation environment's JDK 25 triggers Kotlin's target-24
@@ -8,6 +8,14 @@ tags: [studio, lsp, vscode, compiler-pbs, editor, definition]
# PBS go-to-definition uses editorial lookup and physical files # 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 ## 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`. 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`.
@@ -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.
@@ -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.
@@ -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.
@@ -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)
@@ -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).
@@ -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)
@@ -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).
@@ -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.
@@ -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"
}
}
@@ -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.
@@ -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.
@@ -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"
}
}
@@ -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
@@ -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."
]
}
@@ -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.
@@ -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"
}
@@ -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. - Runtime and bytecode authority override language preferences.
- Closed VM compatibility is mandatory. - 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. - Host API usage remains capability-gated and versioned.
- Canonical host primitive bindings remain reserved to SDK/toolchain-controlled `declare host` surfaces. - 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. - Struct values are reference-like and identity-bearing in v1 core.
- Service values are canonical module-owned singleton values 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. - `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. - Core PBS v1 does not expose explicit lifetime-control syntax in ordinary user code.
## 6. Runtime Memory Spaces ## 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. 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. 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).
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.
## 8. Identity, Aliasing, and Copy Behavior ## 8. Identity, Aliasing, and Copy Behavior
@@ -201,11 +194,11 @@ The language does not promise:
### 9.3 Safepoint relationship ### 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. 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 ### 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 crosses the host boundary,
- whether an operation may trap. - 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: 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.
- 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.
### 11.3 Non-allocation-bearing surfaces by themselves ### 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, 3. the VM heap versus host-memory boundary is normatively described,
4. memory-related cost facts are specified well enough for diagnostics/tooling hooks, 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. 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`, - `service`,
- `error`, - `error`,
- `enum`, - `enum`,
- `callback`, - structural `Fn` types and lambda expressions with explicit captures,
- `declare global`, - `declare global`,
- `declare const`, - `declare const`,
- and declaration nodes required by barrel/linking flow. - 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, 2. recovery/rejection invariants are explicit and test-backed,
3. attribution invariants are explicit and test-backed, 3. attribution invariants are explicit and test-backed,
4. lowering preconditions consumed by `13` are unambiguous. 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: 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, - observable copy-versus-alias semantics,
- and host-boundary crossings. - 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, 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, 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. 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, 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, 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. 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 | BarrelServiceItem
| BarrelGlobalItem | BarrelGlobalItem
| BarrelConstItem | BarrelConstItem
| BarrelCallbackItem
BarrelVisibility ::= 'mod' | 'pub' BarrelVisibility ::= 'mod' | 'pub'
BarrelFnItem ::= BarrelVisibility 'fn' Identifier ParamList ReturnAnn? ';' BarrelFnItem ::= BarrelVisibility 'fn' Identifier TypeParameters? ParamList ReturnAnn? ';'
BarrelStructItem ::= BarrelVisibility 'struct' Identifier ';' BarrelStructItem ::= BarrelVisibility 'struct' Identifier TypeParameters? ';'
BarrelContractItem ::= BarrelVisibility 'contract' Identifier ';' BarrelContractItem ::= BarrelVisibility 'contract' Identifier TypeParameters? ';'
BarrelHostItem ::= BarrelVisibility 'host' Identifier ';' BarrelHostItem ::= BarrelVisibility 'host' Identifier ';'
BarrelErrorItem ::= BarrelVisibility 'error' Identifier ';' BarrelErrorItem ::= BarrelVisibility 'error' Identifier ';'
BarrelEnumItem ::= BarrelVisibility 'enum' Identifier ';' BarrelEnumItem ::= BarrelVisibility 'enum' Identifier ';'
BarrelServiceItem ::= BarrelVisibility 'service' Identifier ';' BarrelServiceItem ::= BarrelVisibility 'service' Identifier ';'
BarrelGlobalItem ::= BarrelVisibility 'global' Identifier ';' BarrelGlobalItem ::= BarrelVisibility 'global' Identifier ';'
BarrelConstItem ::= BarrelVisibility 'const' Identifier ';' BarrelConstItem ::= BarrelVisibility 'const' Identifier ';'
BarrelCallbackItem ::= BarrelVisibility 'callback' Identifier ';'
``` ```
Rules: Rules:
@@ -191,11 +189,10 @@ Rules:
- Multiple `fn` barrel entries with the same identifier are allowed only when signatures differ (overload set). - Multiple `fn` barrel entries with the same identifier are allowed only when signatures differ (overload set).
- Barrel labels MAY differ from the implementation labels. - Barrel labels MAY differ from the implementation labels.
- A `fn` barrel entry must resolve to exactly one declaration in module scope. - 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 `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 `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 `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. - 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`. - 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 enum GameState;
pub service Physics; pub service Physics;
pub global Palette; pub global Palette;
pub callback TickCb;
``` ```
## 6. File grammar ## 6. File grammar
@@ -272,7 +268,7 @@ Rules:
### 6.2 Top-level declarations ### 6.2 Top-level declarations
```ebnf ```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. 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 ```ebnf
TypeDecl ::= StructDecl | ServiceDecl | ContractDecl | HostDecl | BuiltinTypeDecl | ErrorDecl | EnumDecl 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 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 HostDecl ::= 'declare' 'host' Identifier HostBody
BuiltinTypeDecl ::= AttrList? 'declare' 'builtin' 'type' Identifier '(' BuiltinFieldList? ')' BuiltinTypeBody BuiltinTypeDecl ::= AttrList? 'declare' 'builtin' 'type' Identifier '(' BuiltinFieldList? ')' BuiltinTypeBody
ErrorDecl ::= 'declare' 'error' Identifier ErrorBody 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. - 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. - Structs do not have static methods in v1 core.
### 7.2 Callbacks ### 7.2 First-class function values
```ebnf 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).
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.
### 7.3 Services ### 7.3 Services
```ebnf ```ebnf
ServiceDecl ::= 'declare' 'service' Identifier ServiceBody ServiceDecl ::= 'declare' 'service' Identifier ServiceBody
ServiceBody ::= '{' ServiceMember* '}' 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: Rules:
- `declare service Name { ... }` declares a nominal service type together with its canonical module-owned singleton value `Name`. - `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. - 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 fields.
- Services do not declare `ctor`. - Services do not declare `ctor`.
- Services are never constructed with `new`. - 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 ### 7.4 Functions
```ebnf ```ebnf
FunctionDecl ::= 'fn' Identifier ParamList ReturnAnn? Block FunctionDecl ::= 'fn' Identifier TypeParameters? ParamList ReturnAnn? Block
ParamList ::= '(' (Param (',' Param)*)? ')' ParamList ::= '(' (Param (',' Param)*)? ')'
Param ::= Identifier ':' TypeRef Param ::= Identifier ':' TypeRef
ReturnAnn ::= '->' ReturnSpec ReturnAnn ::= '->' ReturnSpec
@@ -464,9 +452,9 @@ Rules:
```ebnf ```ebnf
TypeRef ::= OptionalType | TypePrimary TypeRef ::= OptionalType | TypePrimary
TypePrimary ::= SelfType | SimpleType | NamedTupleType | GroupType | UnitType TypePrimary ::= FnType | SelfType | SimpleType | NamedTupleType | GroupType | UnitType
SelfType ::= 'Self' SelfType ::= 'Self'
SimpleType ::= Identifier SimpleType ::= Identifier TypeArguments?
NamedTupleType ::= '(' NamedTupleField (',' NamedTupleField){0,5} ')' NamedTupleType ::= '(' NamedTupleField (',' NamedTupleField){0,5} ')'
NamedTupleField ::= Identifier ':' TypeRef NamedTupleField ::= Identifier ':' TypeRef
GroupType ::= '(' TypeRef ')' GroupType ::= '(' TypeRef ')'
@@ -479,7 +467,7 @@ Rules:
- Named tuple arity is 1..6 in v1 core syntax. - Named tuple arity is 1..6 in v1 core syntax.
- Tuple types in PBS core are always named. - Tuple types in PBS core are always named.
- Single-slot tuple types are allowed only in type/signature surface, not as tuple literals. - 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. - `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`. - 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. - 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 Literal ::= IntLit | FloatLit | StringLit | BoolLit
BoolLit ::= 'true' | 'false' 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' ThisExpr ::= 'this'
NewExpr ::= 'new' NewTarget '(' ArgList? ')' NewExpr ::= 'new' NewTarget '(' ArgList? ')'
NewTarget ::= Identifier ('.' Identifier)? NewTarget ::= Identifier (TypeArguments | '<' '>')? ('.' Identifier)?
BindExpr ::= 'bind' '(' Expr ',' Identifier ')' LambdaExpr ::= 'fn' '[' CaptureNames? ']' ParamList '->' TypeRef Block
CaptureNames ::= Identifier (',' Identifier)*
FnType ::= 'Fn' '(' (TypeRef (',' TypeRef)*)? ')' '->' TypeRef
SomeExpr ::= 'some' '(' Expr ')' SomeExpr ::= 'some' '(' Expr ')'
NoneExpr ::= 'none' NoneExpr ::= 'none'
OkExpr ::= 'ok' '(' Expr ')' OkExpr ::= 'ok' '(' Expr ')'
@@ -622,7 +612,7 @@ Rules:
- `new Type.ctorName(args...)` is the canonical named-constructor surface. - `new Type.ctorName(args...)` is the canonical named-constructor surface.
- Struct construction arguments are positional and follow the declared struct field order. - 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. - `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. - `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. - `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)`. - `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)`). - 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. - Positional tuple expression sugar requires an expected named tuple shape supplied by context.
- No single-slot tuple literal exists in v1 core syntax. - 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. - 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. - 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 `ok(...)` construction form,
- invalid `err(...)` construction form, - invalid `err(...)` construction form,
- use of `ok(...)` or `err(...)` outside allowed result-flow positions, - use of `ok(...)` or `err(...)` outside allowed result-flow positions,
- invalid `bind(...)` construction form,
- invalid `else` extraction form, - invalid `else` extraction form,
- invalid `if` expression form, - invalid `if` expression form,
- invalid `switch` expression form, - invalid `switch` expression form,
- invalid `for` loop form, - invalid `for` loop form,
- invalid `new` construction form, - invalid `new` construction form,
- invalid enum case path, - invalid enum case path,
- invalid callback declaration shape,
- invalid struct field access modifier surface, - invalid struct field access modifier surface,
- invalid struct method declaration shape, - invalid struct method declaration shape,
- invalid service 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: It consolidates the primary surface forms used by tooling and conformance for:
- `apply` and call sugar, - `apply` and call sugar,
- `bind` and nominal callbacks,
- overloads that differ by return shape, - overloads that differ by return shape,
- `optional`, - `optional`,
- `result<Error>`, - `result<Error>`,
@@ -1019,45 +1003,21 @@ declare service Physics {
} }
``` ```
### 15.6 Nominal callback ### 15.6 Function values
```pbs ```pbs
declare callback TickCb(dt: int) -> void; fn twice(x: int) -> int { return x * 2; }
fn demo_function() -> int {
fn on_tick(dt: int) -> void { let f: Fn(int) -> int = twice;
let _ = dt; return f(21);
}
fn install(cb: TickCb) -> void {
cb apply 16;
cb(16);
}
fn demo_callback() -> void {
let cb: TickCb = on_tick;
install(cb);
} }
``` ```
### 15.7 Bound callback ### 15.7 Explicit captures
```pbs ```pbs
declare callback UpdateCb(dt: int) -> void; fn create_adder(n: int) -> Fn(int) -> int {
return fn [n](x: int) -> int { return n + x; };
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);
} }
``` ```
@@ -1236,3 +1196,25 @@ fn test(e: Enum) -> str {
return label; 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: 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. - `declare host` introduces names in the host-owner namespace.
- `let`, parameters, `declare const`, and `declare global` introduce names in the value 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. - `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. - 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. - Named top-level functions can form first-class Fn values with structural signatures.
- `bind(...)` is a callback-formation construct, not a general function-value construct. - 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 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. - `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. - 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. - Builtin simple types are resolved without import or declaration.
- User-authored type declarations must not reuse builtin simple type names. - 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. - 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. - `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. - `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. - 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. - `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. - `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. - 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 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 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 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 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 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 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. - 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. - 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. - 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: - A non-builtin `declare const` initializer must not use:
- callable application or call sugar, - callable application or call sugar,
- `new`, - `new`,
- `bind(...)`,
- `some(...)` or `none`, - `some(...)` or `none`,
- tuple expressions, - tuple expressions,
- block expressions, - block expressions,
@@ -350,6 +349,11 @@ Rules:
### 3.6 Structs, services, methods, and contracts ### 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: Rules:
- Struct values are heap-backed reference values in v1 core. - Struct values are heap-backed reference values in v1 core.
@@ -384,7 +388,7 @@ Rules:
- Services do not have fields. - Services do not have fields.
- Services do not declare named constructors and are never targets of `new`. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - `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. - 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 `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. - 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: [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.
- `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
}
```
### 3.8 Canonical application ### 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, - invalid contract coercion from concrete struct or service value,
- unresolved barrel function signature after label-insensitive matching, - unresolved barrel function signature after label-insensitive matching,
- unresolved host barrel entry, - unresolved host barrel entry,
- unresolved callback barrel entry,
- invalid enum case path, - invalid enum case path,
- invalid enum intrinsic member call, - invalid enum intrinsic member call,
- invalid named constructor target, - 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, - ambiguous overloaded top-level `fn` assignment to callback type,
- attempted assignment of service method to callback type, - attempted assignment of service method to callback type,
- attempted assignment of host 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, - `apply` on a non-callable target,
- arity mismatch in `apply`, - arity mismatch in `apply`,
- argument type 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 optional intrinsic member call,
- invalid builtin intrinsic member call, - invalid builtin intrinsic member call,
- member projection on a missing named output label. - 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).
@@ -537,3 +537,36 @@ The current PBS design direction is:
10. `declare host` remains reserved to stdlib/toolchain interface modules. 10. `declare host` remains reserved to stdlib/toolchain interface modules.
11. Reserved attributes such as `[Host(...)]` are compile-time metadata, not runtime objects. 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. 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).
@@ -263,13 +263,13 @@ Example:
```pbs ```pbs
[BuiltinType(name="color", version=1)] [BuiltinType(name="color", version=1)]
declare builtin type Color( declare builtin type Color(
pub raw: int, pub raw: long,
); );
[BuiltinType(name="pixel", version=1)] [BuiltinType(name="pixel", version=1)]
declare builtin type Pixel( declare builtin type Pixel(
pub x: int, pub x: long,
pub y: int, pub y: long,
pub color: Color, pub color: Color,
); );
``` ```
@@ -277,13 +277,13 @@ declare builtin type Pixel(
Canonical semantic layout: Canonical semantic layout:
```text ```text
Pixel -> [int, int, Color] Pixel -> [long, long, Color]
``` ```
Canonical flattened slot layout: Canonical flattened slot layout:
```text ```text
Pixel -> [int, int, int] Pixel -> [long, long, long]
``` ```
## 13. Member Categories ## 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. 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`. 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. 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.
@@ -356,3 +356,13 @@ Content hashes identify the packaged texts, not a semantic language release.
Conformance MUST include reading all indexed references from installed JARs outside Conformance MUST include reading all indexed references from installed JARs outside
the repository and compiling the shipped example against the installed SDK. No 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. 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: The following inputs are already fixed elsewhere and must not be contradicted here:
- PBS prioritizes determinism and compatibility over ergonomics when the two conflict. - 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. - 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`. - Function application is defined on the canonical `apply` surface, with call sugar desugaring to `apply`.
- `optional T` function fallthrough yields `none`. - `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. 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 ## 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 payload expression of `some(expr)`,
- the operand of `expr!`, - the operand of `expr!`,
- the operand of `handle 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. - call receivers, callees, and argument expressions as required by the call rule above.
## 8. Blocks and Abrupt Completion ## 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. `handle` does not intercept or convert traps.
## 11. `apply`, Call Sugar, and `bind` ## 11. Function application and closures
### 11.1 Canonical role of `apply` ### 11.1 Canonical role of `apply`
@@ -279,22 +279,9 @@ If a callable returns:
- `optional<P>`, extraction remains explicit through `else`, - `optional<P>`, extraction remains explicit through `else`,
- `result<E> P`, propagation or processing remains explicit through `!` or `handle`. - `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. 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).
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`.
## 12. Branch Selection ## 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, 3. host-call interaction rules are stated without relying on informal prose elsewhere,
4. the document can drive runtime conformance tests without decision backfill, 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. 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.
+12 -1
View File
@@ -54,7 +54,7 @@ for exact rules rather than inferring compatibility with another language.
`pbs:sdk:game:1:sdk/gfx/main.pbs` exposes the actual installed Gfx source, `pbs:sdk:game:1:sdk/gfx/main.pbs` exposes the actual installed Gfx source,
including documentation comments and signatures. Its `mod.barrel` reference including documentation comments and signatures. Its `mod.barrel` reference
defines exports. Equivalent references exist for `sdk/asset`, `sdk/composer`, defines exports. Equivalent references exist for `sdk/asset`, `sdk/composer`,
`sdk/input`, `sdk/log`, and `core/color`. Read those interfaces before calling `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. 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 Ordinary game source uses public services such as `Gfx`; it must not manufacture
@@ -135,3 +135,14 @@ That means:
- PBS semantic highlight resources belong to PBS rather than to Studio or LSP, - PBS semantic highlight resources belong to PBS rather than to Studio or LSP,
- PBS publishes that contract through `FrontendSpec`, - PBS publishes that contract through `FrontendSpec`,
- and Studio/LSP consume that contract without becoming owners of PBS semantic presentation assets. - 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 # 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) 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 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`, 3. `code`,
4. `exports`, 4. `exports`,
5. `syscalls`, 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 ### 6.2 Function ordering and IDs
@@ -168,7 +174,6 @@ At minimum, artifact conformance checks should assert:
The following remain deferred: The following remain deferred:
- richer optional debug/source-map formats, - 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. - and profile-specific binary compatibility policy details beyond current v1 baseline.
## 11. Non-Goals ## 11. Non-Goals
@@ -1,5 +1,10 @@
# Compiler Verification and Safety Checks Specification # 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) 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 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 # 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) Status: Draft v1 (Backend Baseline)
Applies to: executable-backend lowering from the common `IRBackend` handoff into `IRVM` Applies to: executable-backend lowering from the common `IRBackend` handoff into `IRVM`
@@ -1,5 +1,10 @@
# Backend Spec-to-Test Conformance Matrix # 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) Status: Draft v1 (Traceability Baseline)
Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts 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, - 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. - 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. - 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,7 +272,17 @@ Absent editor capabilities MUST have deterministic fallback behavior at tooling
3. host protocols that can represent unsupported operations SHOULD do so explicitly; 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. 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 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.
@@ -246,7 +246,7 @@ for one fixed port. The public LSP configuration default remains unchanged for
other hosts. A manifest language change requires reopening that project's server; 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. the adapter MUST NOT send queries to a server bound to another language/root.
Each query uses a short-lived client connection. For document requests, the 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 adapter opens exactly the saved UTF-8 text and waits for that connection's
published diagnostics before issuing the semantic query. Other dependency files published diagnostics before issuing the semantic query. Other dependency files
are read from disk by the existing compiler bridge. A fresh connection prevents are read from disk by the existing compiler bridge. A fresh connection prevents
@@ -266,14 +266,54 @@ Core bounds the request worker wait to 12 seconds. Documents are limited to 4 Mi
of UTF-8 and task-local hierarchy state to 1024 items. These are adapter resource 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. guards, unrelated to the runtime's deterministic frame/watchdog semantics.
Document URIs must resolve to known physical project/dependency source files. 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 Symlink targets are canonicalized before admission. External sources may be
queried, but edit-producing queries on read-only roots are rejected. Every URI in 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 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 scope; an unsafe proposal is rejected as a whole. File-operation edits and
executable commands are not offered; `workspace/applyEdit` is always refused. executable commands are not offered; `workspace/applyEdit` is always refused.
No query writes a file. Virtual SDK declarations may not have physical definition No query writes a file. `readExternalSource` reads the exact registered external
locations in the existing LSP; indexed SDK references remain available instead. 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 ## 4. Result, Error and Operation Contracts
@@ -519,8 +559,8 @@ are also checked. Rebuilding changes pixels/build identity and visibly marks the
old capture stale. Images remain in memory; window screenshots are not evidence. old capture stale. Images remain in memory; window screenshots are not evidence.
The fixture uses supported project-source LSP definition/symbol navigation and The fixture uses supported project-source LSP definition/symbol navigation and
indexed SDK reads. A probe of the installed SDK's `Input.pad()` definition returns indexed SDK reads. The historical probe of the former SDK `Input.pad()` definition returned
an empty result with the current language service; the gate does not claim SDK 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 symbol navigation where no location is returned. This is a language tooling
limitation, not a headless or MCP execution fallback. limitation, not a headless or MCP execution fallback.
+79 -47
View File
@@ -2,7 +2,7 @@ Prometeu VM Runtime — Canonical Architecture
Status: canonical Status: canonical
This document is the authoritative architectural reference for the Prometeu VM runtime. It reflects the implementation as it exists today and defines the invariants that govern architectural changes in the VM layer. This document is the authoritative architectural reference for the Prometeu VM runtime. It defines the invariants that govern architectural changes in the VM layer.
Scope boundary: Scope boundary:
@@ -14,8 +14,8 @@ Scope boundary:
Document roles: Document roles:
- This file is normative for VM/runtime architecture. - This file is normative for VM/runtime architecture.
- Detailed domain specifications may live under `docs/runtime/specs/`, but they must not contradict this document where VM/runtime invariants are concerned. - Detailed domain specifications may live under `docs/specs/runtime/`, but they must not contradict this document where VM/runtime invariants are concerned.
- Roadmaps, agendas, and PR proposals may discuss future changes, but they are not authoritative until this document is updated. - Future architectural changes become authoritative when this document is updated.
- The machine-wide fantasy console framing lives in the runtime specs manual and related domain specs; those documents are complementary, not competing VM architecture sources. - The machine-wide fantasy console framing lives in the runtime specs manual and related domain specs; those documents are complementary, not competing VM architecture sources.
Maintenance rule: Maintenance rule:
@@ -30,10 +30,10 @@ Maintenance rule:
- Operand stack + call frames; bytecode is fetched from a ROM/program image with a separate constant pool. - Operand stack + call frames; bytecode is fetched from a ROM/program image with a separate constant pool.
- GC‑managed heap - GC‑managed heap
- Non‑compacting mark–sweep collector; stable object handles (`HeapRef`) while live. Sweep invalidates unreachable handles; objects are never moved. - Non‑compacting mark–sweep collector; stable object handles (`HeapRef`) while live. Sweep invalidates unreachable handles; objects are never moved.
- Closures (Model B) - Typed first-class Fn
- First‑class closures with a heap‑allocated environment. The closure object is passed to the callee as a hidden `arg0` when invoking a closure. - Structural logical parameter/result signatures and heap Closure environments retained by CallFrames, without hidden arg0.
- Cooperative coroutines - Single execution context
- Deterministic, cooperative scheduling. Switching and GC occur only at explicit safepoints (`FRAME_SYNC`). - VM directly owns PC, stacks and globals; no heap Coroutine or guest scheduler. GC opportunities are FRAME_SYNC and successful last-root RET after result rooting.
- Unified syscall ABI - Unified syscall ABI
- PBX pre-load artifacts declare canonical host bindings in `SYSC` and encode call sites as `HOSTCALL <sysc_index>`. The loader resolves and patches them to numeric `SYSCALL <id>` before verification/execution. Capability gating is enforced at load and checked again defensively at runtime. Syscalls are not first‑class values. - PBX pre-load artifacts declare canonical host bindings in `SYSC` and encode call sites as `HOSTCALL <sysc_index>`. The loader resolves and patches them to numeric `SYSCALL <id>` before verification/execution. Capability gating is enforced at load and checked again defensively at runtime. Syscalls are not first‑class values.
@@ -48,29 +48,28 @@ Maintenance rule:
- The VM’s current operand stack and frames are GC roots. - The VM’s current operand stack and frames are GC roots.
- Heap - Heap
- The heap stores runtime objects that require identity and reachability tracking. Handles are `HeapRef` indices into an internal object store. - The heap stores runtime objects that require identity and reachability tracking. Handles are `HeapRef { index: u32, generation: u32 }` values into an internal object store. Every access checks the live generation; reclaimed maximum-generation slots are retired permanently.
- The collector is mark–sweep, non‑moving: it marks from roots, then reclaims unreachable objects without relocating survivors. Indices for live objects remain stable across collections. - The collector is mark–sweep, non‑moving: it marks from roots, then reclaims unreachable objects without relocating survivors. Indices for live objects remain stable across collections.
2.2 Heap Object Kinds (as used today) 2.2 Heap Object Kinds (as used today)
- Arrays of `Value` - Typed arrays
- Variable‑length arrays whose elements may contain further `HeapRef`s. - Variable-length arrays use the Registry element layout and defaults. Primitive/builtin values are stored directly; Struct/Array elements contain generational references. Native String/Dynamic slots retain their ownership rules. Stack/local execution continues to use `Value`.
- Closures - Closures
- Carry a function identifier and a captured environment (a slice/vector of `Value`s stored with the closure). Captured `HeapRef`s are traversed by the GC. - Carry a function identifier and a captured environment (a slice/vector of `Value`s stored with the closure). Captured `HeapRef`s are traversed by the GC.
- Coroutines - Structs and Dynamic boxes
- Heap‑resident coroutine records (state + wake time + suspended operand stack and call frames). These act as GC roots when suspended. - Typed payloads use resolved reference/ownership maps. Private Struct cells can share mutable captured bindings.
Notes: Notes:
- Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, coroutine records, and any future heap kinds). The constant pool never embeds raw `HeapRef`s. - Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, Structs and Dynamic boxes). The constant pool never embeds raw `HeapRef`s.
2.3 GC Roots 2.3 GC Roots
- VM roots - Roots comprise globals, all live operand values, Closure owners in every active
- Current operand stack and call frames of the running coroutine (or main context). CallFrame and legally retained native/host roots. Inspection snapshots are not
- Suspended coroutines guest roots. Tracing visits complete typed fields, arrays, captures and cells.
- All heap‑resident, suspended coroutine objects are treated as roots. Their saved stacks/frames are scanned during marking. - Root results are transferred/rooted before the last frame is removed or GC runs,
- Root traversal and remain owned until consumed/replaced/reset/unloaded. Unreachable cycles collect.
- The VM exposes a root‑visitor that walks the operand stack, frames, and coroutine records to feed the collector. The collector then follows children from each object kind (e.g., array elements, closure environments, coroutine stacks).
3. Execution Model 3. Execution Model
@@ -85,20 +84,22 @@ Notes:
3.2 Safepoints 3.2 Safepoints
- `FRAME_SYNC` is the only safepoint. - Threshold GC opportunities are FRAME_SYNC and successful RET of the last root,
- At `FRAME_SYNC`, the VM performs two actions in a well‑defined order: after result rooting. Ordinary callee RET, entry preparation, syscalls and
1) Garbage‑collection opportunity: root enumeration + mark–sweep. allocation/quota refusal do not collect. GC adds no guest callback, clock/frame
2) Scheduler handoff: the currently running coroutine may yield/sleep, and a next ready coroutine is selected deterministically. advance, budget grant or partial sweep on scratch failure.
- No other opcode constitutes a GC or scheduling safepoint. Syscalls do not implicitly trigger GC or rescheduling.
3.3 Scheduler Behavior (Cooperative Coroutines) 3.3 Single Context and Host Continuation
- Coroutines are cooperative and scheduled deterministically (FIFO among ready coroutines). - FRAME_SYNC may occur in any body, has no stack effect and resumes next PC with
- `YIELD` and `SLEEP` take effect at `FRAME_SYNC`: live frames/locals/environments. It closes the logical frame but does not restart
- `YIELD` places the current coroutine at the end of the ready queue. entry. Budget exhaustion/breakpoints preserve the same open logical frame.
- `SLEEP` parks the current coroutine until its exact `wake_tick`, after which it re‑enters the ready queue at the correct point. - Last-root RET completes entry. Recurring host prepares FunctionId 0 next frame,
- `SPAWN` creates a new coroutine with its own stack/frames recorded in the heap and enqueues it deterministically. preserving globals/init guard; preparation validates/reserves before replacing
- No preemption: the VM never interrupts a coroutine between safepoints. previous owners and allocates no Coroutine. HALT/trap/reset/unload retain their
contracts. Render/asset workers remain independent of guest execution.
- SPAWN/YIELD/SLEEP are retired: numbers 0x54–0x56 stay reserved and all uses reject
at load, including unreachable code. No compatibility scheduler remains.
4. Verification Model 4. Verification Model
@@ -119,25 +120,33 @@ The verifier statically checks bytecode for structural safety and stack‑shape
- Syscalls - Syscalls
- The verifier runs only on the patched executable image. `HOSTCALL` is invalid at verification time. Final `SYSCALL` IDs must exist per `SyscallMeta`, and arity/declared return slot counts must match metadata. - The verifier runs only on the patched executable image. `HOSTCALL` is invalid at verification time. Final `SYSCALL` IDs must exist per `SyscallMeta`, and arity/declared return slot counts must match metadata.
- Closures - Closures
- `CALL_CLOSURE` is only allowed on closure values; the callee function must be known; argument counts for closure calls must match. - Expected FnTypeId determines complete parameter/result groups even when the concrete FunctionId is unknown. Known mismatch rejects; Unknown retains runtime checks. Capture indices and target metadata are checked, and direct entry into capturing bodies rejects.
- Coroutines - Trait calls
- `YIELD` context must be valid; `SPAWN` argument counts are validated. - Exact method signatures and complete views resolve through immutable tables; concrete receiver is the first callee parameter, with no capture environment.
4.2 Runtime vs Verifier Guarantees 4.2 Runtime vs Verifier Guarantees
- The verifier guarantees structural correctness and stack‑shape invariants. It does not perform full type checking of value contents; dynamic checks (e.g., numeric domain checks, polymorphic comparisons, concrete syscall argument validation) occur at runtime and may trap. - The Registry verifier checks structure and stack shape and conservatively tracks known types through control flow. It rejects proved incompatibilities; Unknown values retain runtime checks at typed boundaries. Numeric domain checks, polymorphic comparisons and concrete syscall argument validation may still trap at runtime.
- Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface. - Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface.
5. Closures (Model B) — Calling Convention 5. Typed Fn and Environments
------------------------------------------- ----------------------------
- Creation - Fn identity is ordered logical parameter/result TypeIds; names, target and captures
- `MAKE_CLOSURE` captures N values from the operand stack into a heap‑allocated environment alongside a function identifier. The opcode _pushes a `HeapRef` to the new closure. are metadata. Pure Array/Fn structural cycles reject; nominal anchors stop expansion.
- Call - MAKE_CLOSURE takes FunctionId/FnTypeId, captures full declared groups and pushes a
- `CALL_CLOSURE` invokes a closure. The closure object itself is supplied to the callee as a hidden `arg0`. User‑visible arguments follow the function’s declared arity. distinct one-slot instance. Immutable bindings copy values; mutable bindings can
- Access to captures share private typed Struct cells. Metadata lives in required PBX section 8.
- The callee can access captured values via the closure’s environment. Captured `HeapRef`s are traced by the GC. - CALL_CLOSURE takes expected FnTypeId and retains the Closure in CallFrame, without
public arg0. GET_CAPTURE takes an index and copies a complete group. Direct calls
to capturing bodies reject; bound receivers use explicit adapter bodies.
- Fn is valid in Struct/Array/Dynamic, defaults Null and compares instance identity.
It gains no REF_* casts, Trait implementations, fault isolation or separate budget.
- Validate/reserve before consume/publication; faults preserve input owners and expose
no partial frame/object. Costs are 8+C / 6 / 2+W including traps, charged once.
- CALL_TRAIT takes TraitTypeId/method index, consumes explicit args and a complete
view, then passes concrete receiver first. Exact immutable-table dispatch costs 6.
6. Unified Syscall ABI 6. Unified Syscall ABI
@@ -160,11 +169,11 @@ The verifier statically checks bytecode for structural safety and stack‑shape
- Collector - Collector
- Non‑moving mark–sweep. - Non‑moving mark–sweep.
- Triggers - Triggers
- GC runs only at `FRAME_SYNC` safepoints. - Threshold GC runs at FRAME_SYNC and successful last-root RET after result rooting.
- Liveness - Liveness
- Roots comprise: the live VM stack/frames and all suspended coroutines. The collector traverses object‑specific children (array elements, closure environments, coroutine stacks). - Globals, live operand values and active-frame Closures root complete typed object graphs, including cells and legally retained host/native owners.
- Determinism - Determinism
- GC opportunities and scheduling order are tied to `FRAME_SYNC`, ensuring repeatable execution traces across runs with the same inputs. - Opportunities depend on execution boundaries and thresholds, preserving deterministic guest execution with the same inputs.
8. Non‑Goals 8. Non‑Goals
@@ -180,6 +189,29 @@ The verifier statically checks bytecode for structural safety and stack‑shape
-------------------------- --------------------------
- Keep the public surface minimal and metadata‑driven (e.g., syscalls via `SyscallMeta`). - Keep the public surface minimal and metadata‑driven (e.g., syscalls via `SyscallMeta`).
- Do not assume implicit safepoints; schedule and GC only at `FRAME_SYNC`. - Preserve explicit GC opportunities and root results before root-return collection.
- When adding new opcodes or object kinds, extend the verifier and GC traversal accordingly (children enumeration, environment scanning, root sets). - When adding new opcodes or object kinds, extend the verifier and GC traversal accordingly (children enumeration, environment scanning, root sets).
- Update this document alongside any architectural change that affects runtime invariants. - Update this document alongside any architectural change that affects runtime invariants.
## Program Registry
The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v0.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v0 is the sole target format; publication requires full bounded validation. Fn tag 4 and mandatory captures section 8 extend the Registry; no old-schema fallback is permitted.
`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production and internal generators must use this sole sealed-v1 path. Typed Fn integration and legacy removal are implemented together; publication alone is not proof that every consumer has migrated. [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary.
## VM-owned random core
See the [random contract](../specs/runtime/02e-vm-owned-random-core.md) for Random BuiltinId 0x0016, ObjectKind tag 9, intrinsics 0x4000–0x4003, atomic state mutation, bounded 4+8*N costs and rejection-limit trap 0x00000015. Random is managed by the VM heap and existing GC, without host entropy or PBX changes.
## Typed array range copy
ARRAY_COPY (0xA9) copies complete groups between exact typed arrays with strict
physical ranges and pre-attempt overlap semantics. Preparation reserves scratch
before infallible commit; failures preserve operands/destinations and retain
charged work. No callbacks, GC or scheduling occur inside the instruction.
The [instruction contract](../specs/runtime/02-vm-instruction-set.md#typed-array-range-copy)
defines encoding, fault order and early cost selection. ARRAY_LEN remains the
physical query; producer algorithms own logical limits and multi-owner invariants.
There is no transactional sequence of stores. Encodings 0xA7/0xA8/0xAA/0xAB are
unsupported, including in dead code.
+17
View File
@@ -0,0 +1,17 @@
target,name,version,slot,carrier,bits_or_value
color,black,1,0,Int64,255
color,blue,1,0,Int64,65535
color,cyan,1,0,Int64,16777215
color,gray,1,0,Int64,2155905279
color,green,1,0,Int64,16711935
color,indigo,1,0,Int64,1258324735
color,magenta,1,0,Int64,4278255615
color,orange,1,0,Int64,4286578943
color,red,1,0,Int64,4278190335
color,transparent,1,0,Int64,0
color,white,1,0,Int64,4294967295
color,yellow,1,0,Int64,4294902015
mathf,pi,1,0,Float,0x400921FB54442D18
mathf,tau,1,0,Float,0x401921FB54442D18
vec2,zero,1,0,Float,0x0000000000000000
vec2,zero,1,1,Float,0x0000000000000000
1 target name version slot carrier bits_or_value
2 color black 1 0 Int64 255
3 color blue 1 0 Int64 65535
4 color cyan 1 0 Int64 16777215
5 color gray 1 0 Int64 2155905279
6 color green 1 0 Int64 16711935
7 color indigo 1 0 Int64 1258324735
8 color magenta 1 0 Int64 4278255615
9 color orange 1 0 Int64 4286578943
10 color red 1 0 Int64 4278190335
11 color transparent 1 0 Int64 0
12 color white 1 0 Int64 4294967295
13 color yellow 1 0 Int64 4294902015
14 mathf pi 1 0 Float 0x400921FB54442D18
15 mathf tau 1 0 Float 0x401921FB54442D18
16 vec2 zero 1 0 Float 0x0000000000000000
17 vec2 zero 1 1 Float 0x0000000000000000
+109 -43
View File
@@ -1,43 +1,109 @@
final_id_hex,final_id_dec,canonical_name,canonical_version,owner,name,arg_slots,ret_slots,arg_layout,ret_layout,deterministic,may_allocate final_id_hex,final_id_dec,canonical_name,canonical_version,owner,name,arg_slots,ret_slots,arg_layout,ret_layout,deterministic,may_allocate,parameter_names,cost_cycles,mutates_guest_state,cost_model,attempt_cost_cycles,max_attempts,schema_version,arg_nullable,invocation_model,scratch_model,context_access,cost_arg_index,cost_per_byte
0x1000,4096,vec2.dot,1,vec2,dot,4,1,float|float|float|float,float,true,false 0x1000,4096,vec2.dot,1,vec2,dot,4,1,Float|Float|Float|Float,Float,true,false,ax|ay|bx|by,10,false,fixed,0,0,2,false|false|false|false,host_buffered_v1,existing_contract_v1,host,,0
0x1001,4097,vec2.length,1,vec2,length,2,1,float|float,float,true,false 0x1001,4097,vec2.length,1,vec2,length,2,1,Float|Float,Float,true,false,x|y,40,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x1100,4352,color.from_raw,1,color,from_raw,1,1,int,builtin:color,true,false 0x1100,4352,color.from_raw,1,color,from_raw,1,1,Int64,builtin:color,true,false,raw,1,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x1101,4353,color.rgb,1,color,rgb,3,1,int|int|int,builtin:color,true,false 0x1101,4353,color.rgb,1,color,rgb,3,1,Int64|Int64|Int64,builtin:color,true,false,r|g|b,1,false,fixed,0,0,2,false|false|false,host_buffered_v1,existing_contract_v1,host,,0
0x1102,4354,color.rgba,1,color,rgba,4,1,int|int|int|int,builtin:color,true,false 0x1102,4354,color.rgba,1,color,rgba,4,1,Int64|Int64|Int64|Int64,builtin:color,true,false,r|g|b|a,1,false,fixed,0,0,2,false|false|false|false,host_buffered_v1,existing_contract_v1,host,,0
0x1103,4355,color.html_rgba,1,color,html_rgba,1,1,str,builtin:color,true,false 0x1103,4355,color.html_rgba,1,color,html_rgba,1,1,String,builtin:color,true,false,value,1,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x1104,4356,color.gray_scale,1,color,gray_scale,1,1,int,builtin:color,true,false 0x1104,4356,color.gray_scale,1,color,gray_scale,1,1,Int64,builtin:color,true,false,value,1,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x1105,4357,color.hex,1,color,hex,1,1,builtin:color,int,true,false 0x1105,4357,color.hex,1,color,hex,1,1,builtin:color,Int64,true,false,color,1,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x1106,4358,color.alpha,1,color,alpha,1,1,builtin:color,int,true,false 0x1106,4358,color.alpha,1,color,alpha,1,1,builtin:color,Int64,true,false,color,1,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x1120,4384,color.black,1,color,black,0,1,,builtin:color,true,false 0x1120,4384,color.black,1,color,black,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1121,4385,color.white,1,color,white,0,1,,builtin:color,true,false 0x1121,4385,color.white,1,color,white,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1122,4386,color.red,1,color,red,0,1,,builtin:color,true,false 0x1122,4386,color.red,1,color,red,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1123,4387,color.green,1,color,green,0,1,,builtin:color,true,false 0x1123,4387,color.green,1,color,green,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1124,4388,color.blue,1,color,blue,0,1,,builtin:color,true,false 0x1124,4388,color.blue,1,color,blue,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1125,4389,color.yellow,1,color,yellow,0,1,,builtin:color,true,false 0x1125,4389,color.yellow,1,color,yellow,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1126,4390,color.orange,1,color,orange,0,1,,builtin:color,true,false 0x1126,4390,color.orange,1,color,orange,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1127,4391,color.indigo,1,color,indigo,0,1,,builtin:color,true,false 0x1127,4391,color.indigo,1,color,indigo,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1128,4392,color.gray,1,color,gray,0,1,,builtin:color,true,false 0x1128,4392,color.gray,1,color,gray,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x1129,4393,color.cyan,1,color,cyan,0,1,,builtin:color,true,false 0x1129,4393,color.cyan,1,color,cyan,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x112A,4394,color.magenta,1,color,magenta,0,1,,builtin:color,true,false 0x112A,4394,color.magenta,1,color,magenta,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x112B,4395,color.transparent,1,color,transparent,0,1,,builtin:color,true,false 0x112B,4395,color.transparent,1,color,transparent,0,1,,builtin:color,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2000,8192,input.pad,1,input,pad,0,1,,builtin:input.pad,true,false 0x2100,8448,input.pad.up.pressed,1,input.pad.up,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2001,8193,input.touch,1,input,touch,0,1,,builtin:input.touch,true,false 0x2101,8449,input.pad.up.released,1,input.pad.up,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2010,8208,input.pad.up,1,input.pad,up,1,1,builtin:input.pad,builtin:input.button,true,false 0x2102,8450,input.pad.up.down,1,input.pad.up,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2011,8209,input.pad.down,1,input.pad,down,1,1,builtin:input.pad,builtin:input.button,true,false 0x2103,8451,input.pad.up.hold,1,input.pad.up,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2012,8210,input.pad.left,1,input.pad,left,1,1,builtin:input.pad,builtin:input.button,true,false 0x2104,8452,input.pad.down.pressed,1,input.pad.down,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2013,8211,input.pad.right,1,input.pad,right,1,1,builtin:input.pad,builtin:input.button,true,false 0x2105,8453,input.pad.down.released,1,input.pad.down,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2014,8212,input.pad.a,1,input.pad,a,1,1,builtin:input.pad,builtin:input.button,true,false 0x2106,8454,input.pad.down.down,1,input.pad.down,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2015,8213,input.pad.b,1,input.pad,b,1,1,builtin:input.pad,builtin:input.button,true,false 0x2107,8455,input.pad.down.hold,1,input.pad.down,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2016,8214,input.pad.x,1,input.pad,x,1,1,builtin:input.pad,builtin:input.button,true,false 0x2108,8456,input.pad.left.pressed,1,input.pad.left,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2017,8215,input.pad.y,1,input.pad,y,1,1,builtin:input.pad,builtin:input.button,true,false 0x2109,8457,input.pad.left.released,1,input.pad.left,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2018,8216,input.pad.l,1,input.pad,l,1,1,builtin:input.pad,builtin:input.button,true,false 0x210A,8458,input.pad.left.down,1,input.pad.left,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2019,8217,input.pad.r,1,input.pad,r,1,1,builtin:input.pad,builtin:input.button,true,false 0x210B,8459,input.pad.left.hold,1,input.pad.left,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x201A,8218,input.pad.start,1,input.pad,start,1,1,builtin:input.pad,builtin:input.button,true,false 0x210C,8460,input.pad.right.pressed,1,input.pad.right,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x201B,8219,input.pad.select,1,input.pad,select,1,1,builtin:input.pad,builtin:input.button,true,false 0x210D,8461,input.pad.right.released,1,input.pad.right,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2020,8224,input.touch.button,1,input.touch,button,1,1,builtin:input.touch,builtin:input.button,true,false 0x210E,8462,input.pad.right.down,1,input.pad.right,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2021,8225,input.touch.x,1,input.touch,x,1,1,builtin:input.touch,int,true,false 0x210F,8463,input.pad.right.hold,1,input.pad.right,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2022,8226,input.touch.y,1,input.touch,y,1,1,builtin:input.touch,int,true,false 0x2110,8464,input.pad.a.pressed,1,input.pad.a,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2030,8240,input.button.pressed,1,input.button,pressed,1,1,builtin:input.button,bool,true,false 0x2111,8465,input.pad.a.released,1,input.pad.a,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2031,8241,input.button.released,1,input.button,released,1,1,builtin:input.button,bool,true,false 0x2112,8466,input.pad.a.down,1,input.pad.a,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2032,8242,input.button.down,1,input.button,down,1,1,builtin:input.button,bool,true,false 0x2113,8467,input.pad.a.hold,1,input.pad.a,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2033,8243,input.button.hold,1,input.button,hold,1,1,builtin:input.button,int,true,false 0x2114,8468,input.pad.b.pressed,1,input.pad.b,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2115,8469,input.pad.b.released,1,input.pad.b,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2116,8470,input.pad.b.down,1,input.pad.b,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2117,8471,input.pad.b.hold,1,input.pad.b,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2118,8472,input.pad.x.pressed,1,input.pad.x,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2119,8473,input.pad.x.released,1,input.pad.x,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x211A,8474,input.pad.x.down,1,input.pad.x,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x211B,8475,input.pad.x.hold,1,input.pad.x,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x211C,8476,input.pad.y.pressed,1,input.pad.y,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x211D,8477,input.pad.y.released,1,input.pad.y,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x211E,8478,input.pad.y.down,1,input.pad.y,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x211F,8479,input.pad.y.hold,1,input.pad.y,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2120,8480,input.pad.l.pressed,1,input.pad.l,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2121,8481,input.pad.l.released,1,input.pad.l,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2122,8482,input.pad.l.down,1,input.pad.l,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2123,8483,input.pad.l.hold,1,input.pad.l,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2124,8484,input.pad.r.pressed,1,input.pad.r,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2125,8485,input.pad.r.released,1,input.pad.r,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2126,8486,input.pad.r.down,1,input.pad.r,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2127,8487,input.pad.r.hold,1,input.pad.r,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2128,8488,input.pad.start.pressed,1,input.pad.start,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2129,8489,input.pad.start.released,1,input.pad.start,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x212A,8490,input.pad.start.down,1,input.pad.start,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x212B,8491,input.pad.start.hold,1,input.pad.start,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x212C,8492,input.pad.select.pressed,1,input.pad.select,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x212D,8493,input.pad.select.released,1,input.pad.select,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x212E,8494,input.pad.select.down,1,input.pad.select,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x212F,8495,input.pad.select.hold,1,input.pad.select,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2130,8496,input.touch.button.pressed,1,input.touch.button,pressed,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2131,8497,input.touch.button.released,1,input.touch.button,released,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2132,8498,input.touch.button.down,1,input.touch.button,down,0,1,,Bool,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2133,8499,input.touch.button.hold,1,input.touch.button,hold,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2134,8500,input.touch.x,1,input.touch,x,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x2135,8501,input.touch.y,1,input.touch,y,0,1,,Int64,true,false,,1,false,fixed,0,0,2,,host_buffered_v1,existing_contract_v1,host,,0
0x3000,12288,math.i32.min,1,math.i32,min,2,1,Int32|Int32,Int32,true,false,a|b,2,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3001,12289,math.i32.max,1,math.i32,max,2,1,Int32|Int32,Int32,true,false,a|b,2,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3002,12290,math.i32.clamp,1,math.i32,clamp,3,1,Int32|Int32|Int32,Int32,true,false,value|min|max,4,false,fixed,0,0,2,false|false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3003,12291,math.i32.abs,1,math.i32,abs,1,1,Int32,Int32,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3004,12292,math.i64.min,1,math.i64,min,2,1,Int64|Int64,Int64,true,false,a|b,2,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3005,12293,math.i64.max,1,math.i64,max,2,1,Int64|Int64,Int64,true,false,a|b,2,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3006,12294,math.i64.clamp,1,math.i64,clamp,3,1,Int64|Int64|Int64,Int64,true,false,value|min|max,4,false,fixed,0,0,2,false|false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3007,12295,math.i64.abs,1,math.i64,abs,1,1,Int64,Int64,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3008,12296,mathf.min,1,mathf,min,2,1,Float|Float,Float,true,false,a|b,2,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3009,12297,mathf.max,1,mathf,max,2,1,Float|Float,Float,true,false,a|b,2,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x300A,12298,mathf.clamp,1,mathf,clamp,3,1,Float|Float|Float,Float,true,false,value|min|max,4,false,fixed,0,0,2,false|false|false,host_buffered_v1,existing_contract_v1,host,,0
0x300B,12299,mathf.abs,1,mathf,abs,1,1,Float,Float,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x300C,12300,mathf.floor,1,mathf,floor,1,1,Float,Float,true,false,value,4,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x300D,12301,mathf.ceil,1,mathf,ceil,1,1,Float,Float,true,false,value,4,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x300E,12302,mathf.trunc,1,mathf,trunc,1,1,Float,Float,true,false,value,4,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x300F,12303,mathf.round,1,mathf,round,1,1,Float,Float,true,false,value,4,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3010,12304,mathf.sqrt,1,mathf,sqrt,1,1,Float,Float,true,false,value,16,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3011,12305,mathf.sin,1,mathf,sin,1,1,Float,Float,true,false,angle,32,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3012,12306,mathf.cos,1,mathf,cos,1,1,Float,Float,true,false,angle,32,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3013,12307,mathf.atan2,1,mathf,atan2,2,1,Float|Float,Float,true,false,y|x,48,false,fixed,0,0,2,false|false,host_buffered_v1,existing_contract_v1,host,,0
0x3014,12308,math.i32.to_i64,1,math.i32,to_i64,1,1,Int32,Int64,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3015,12309,math.i64.to_i32,1,math.i64,to_i32,1,1,Int64,Int32,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3016,12310,math.i32.to_float,1,math.i32,to_float,1,1,Int32,Float,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3017,12311,math.i64.to_float,1,math.i64,to_float,1,1,Int64,Float,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3018,12312,mathf.to_i32,1,mathf,to_i32,1,1,Float,Int32,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x3019,12313,mathf.to_i64,1,mathf,to_i64,1,1,Float,Int64,true,false,value,2,false,fixed,0,0,2,false,host_buffered_v1,existing_contract_v1,host,,0
0x4000,16384,random.new,1,random,new,1,1,Int64,builtin:Random,true,true,seed,32,true,fixed,0,0,2,false,vm_owned_v1,existing_contract_v1,vm_state,,0
0x4001,16385,random.next,1,random,next,1,1,builtin:Random,Int64,true,false,rng,8,true,fixed,0,0,2,true,vm_owned_v1,existing_contract_v1,vm_state,,0
0x4002,16386,random.nextf,1,random,nextf,1,1,builtin:Random,Float,true,false,rng,12,true,fixed,0,0,2,true,vm_owned_v1,existing_contract_v1,vm_state,,0
0x4003,16387,random.range,1,random,range,3,1,builtin:Random|Int64|Int64,Int64,true,false,rng|min|max,4,true,random_rejection_v1,8,64,2,true|false|false,vm_owned_v1,existing_contract_v1,vm_state,,0
0x4100,16640,hash.i64,1,hash,i64,1,1,Int64,Int64,true,false,value,8,false,fixed,0,0,2,false,borrowed_inline_v1,none,none,,0
0x4101,16641,hash.float,1,hash,float,1,1,Float,Int64,true,false,value,8,false,fixed,0,0,2,false,borrowed_inline_v1,none,none,,0
0x4102,16642,hash.string,1,hash,string,1,1,String,Int64,true,false,value,8,false,argument_utf8_bytes_v1,0,0,2,true,borrowed_inline_v1,none,none,0,1
1 final_id_hex final_id_dec canonical_name canonical_version owner name arg_slots ret_slots arg_layout ret_layout deterministic may_allocate parameter_names cost_cycles mutates_guest_state cost_model attempt_cost_cycles max_attempts schema_version arg_nullable invocation_model scratch_model context_access cost_arg_index cost_per_byte
2 0x1000 4096 vec2.dot 1 vec2 dot 4 1 float|float|float|float Float|Float|Float|Float float Float true false ax|ay|bx|by 10 false fixed 0 0 2 false|false|false|false host_buffered_v1 existing_contract_v1 host 0
3 0x1001 4097 vec2.length 1 vec2 length 2 1 float|float Float|Float float Float true false x|y 40 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
4 0x1100 4352 color.from_raw 1 color from_raw 1 1 int Int64 builtin:color true false raw 1 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
5 0x1101 4353 color.rgb 1 color rgb 3 1 int|int|int Int64|Int64|Int64 builtin:color true false r|g|b 1 false fixed 0 0 2 false|false|false host_buffered_v1 existing_contract_v1 host 0
6 0x1102 4354 color.rgba 1 color rgba 4 1 int|int|int|int Int64|Int64|Int64|Int64 builtin:color true false r|g|b|a 1 false fixed 0 0 2 false|false|false|false host_buffered_v1 existing_contract_v1 host 0
7 0x1103 4355 color.html_rgba 1 color html_rgba 1 1 str String builtin:color true false value 1 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
8 0x1104 4356 color.gray_scale 1 color gray_scale 1 1 int Int64 builtin:color true false value 1 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
9 0x1105 4357 color.hex 1 color hex 1 1 builtin:color int Int64 true false color 1 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
10 0x1106 4358 color.alpha 1 color alpha 1 1 builtin:color int Int64 true false color 1 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
11 0x1120 4384 color.black 1 color black 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
12 0x1121 4385 color.white 1 color white 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
13 0x1122 4386 color.red 1 color red 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
14 0x1123 4387 color.green 1 color green 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
15 0x1124 4388 color.blue 1 color blue 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
16 0x1125 4389 color.yellow 1 color yellow 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
17 0x1126 4390 color.orange 1 color orange 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
18 0x1127 4391 color.indigo 1 color indigo 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
19 0x1128 4392 color.gray 1 color gray 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
20 0x1129 4393 color.cyan 1 color cyan 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
21 0x112A 4394 color.magenta 1 color magenta 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
22 0x112B 4395 color.transparent 1 color transparent 0 1 builtin:color true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
23 0x2000 0x2100 8192 8448 input.pad input.pad.up.pressed 1 input input.pad.up pad pressed 0 1 builtin:input.pad Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
24 0x2001 0x2101 8193 8449 input.touch input.pad.up.released 1 input input.pad.up touch released 0 1 builtin:input.touch Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
25 0x2010 0x2102 8208 8450 input.pad.up input.pad.up.down 1 input.pad input.pad.up up down 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
26 0x2011 0x2103 8209 8451 input.pad.down input.pad.up.hold 1 input.pad input.pad.up down hold 1 0 1 builtin:input.pad builtin:input.button Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
27 0x2012 0x2104 8210 8452 input.pad.left input.pad.down.pressed 1 input.pad input.pad.down left pressed 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
28 0x2013 0x2105 8211 8453 input.pad.right input.pad.down.released 1 input.pad input.pad.down right released 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
29 0x2014 0x2106 8212 8454 input.pad.a input.pad.down.down 1 input.pad input.pad.down a down 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
30 0x2015 0x2107 8213 8455 input.pad.b input.pad.down.hold 1 input.pad input.pad.down b hold 1 0 1 builtin:input.pad builtin:input.button Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
31 0x2016 0x2108 8214 8456 input.pad.x input.pad.left.pressed 1 input.pad input.pad.left x pressed 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
32 0x2017 0x2109 8215 8457 input.pad.y input.pad.left.released 1 input.pad input.pad.left y released 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
33 0x2018 0x210A 8216 8458 input.pad.l input.pad.left.down 1 input.pad input.pad.left l down 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
34 0x2019 0x210B 8217 8459 input.pad.r input.pad.left.hold 1 input.pad input.pad.left r hold 1 0 1 builtin:input.pad builtin:input.button Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
35 0x201A 0x210C 8218 8460 input.pad.start input.pad.right.pressed 1 input.pad input.pad.right start pressed 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
36 0x201B 0x210D 8219 8461 input.pad.select input.pad.right.released 1 input.pad input.pad.right select released 1 0 1 builtin:input.pad builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
37 0x2020 0x210E 8224 8462 input.touch.button input.pad.right.down 1 input.touch input.pad.right button down 1 0 1 builtin:input.touch builtin:input.button Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
38 0x2021 0x210F 8225 8463 input.touch.x input.pad.right.hold 1 input.touch input.pad.right x hold 1 0 1 builtin:input.touch int Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
39 0x2022 0x2110 8226 8464 input.touch.y input.pad.a.pressed 1 input.touch input.pad.a y pressed 1 0 1 builtin:input.touch int Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
40 0x2030 0x2111 8240 8465 input.button.pressed input.pad.a.released 1 input.button input.pad.a pressed released 1 0 1 builtin:input.button bool Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
41 0x2031 0x2112 8241 8466 input.button.released input.pad.a.down 1 input.button input.pad.a released down 1 0 1 builtin:input.button bool Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
42 0x2032 0x2113 8242 8467 input.button.down input.pad.a.hold 1 input.button input.pad.a down hold 1 0 1 builtin:input.button bool Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
43 0x2033 0x2114 8243 8468 input.button.hold input.pad.b.pressed 1 input.button input.pad.b hold pressed 1 0 1 builtin:input.button int Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
44 0x2115 8469 input.pad.b.released 1 input.pad.b released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
45 0x2116 8470 input.pad.b.down 1 input.pad.b down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
46 0x2117 8471 input.pad.b.hold 1 input.pad.b hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
47 0x2118 8472 input.pad.x.pressed 1 input.pad.x pressed 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
48 0x2119 8473 input.pad.x.released 1 input.pad.x released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
49 0x211A 8474 input.pad.x.down 1 input.pad.x down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
50 0x211B 8475 input.pad.x.hold 1 input.pad.x hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
51 0x211C 8476 input.pad.y.pressed 1 input.pad.y pressed 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
52 0x211D 8477 input.pad.y.released 1 input.pad.y released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
53 0x211E 8478 input.pad.y.down 1 input.pad.y down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
54 0x211F 8479 input.pad.y.hold 1 input.pad.y hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
55 0x2120 8480 input.pad.l.pressed 1 input.pad.l pressed 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
56 0x2121 8481 input.pad.l.released 1 input.pad.l released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
57 0x2122 8482 input.pad.l.down 1 input.pad.l down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
58 0x2123 8483 input.pad.l.hold 1 input.pad.l hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
59 0x2124 8484 input.pad.r.pressed 1 input.pad.r pressed 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
60 0x2125 8485 input.pad.r.released 1 input.pad.r released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
61 0x2126 8486 input.pad.r.down 1 input.pad.r down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
62 0x2127 8487 input.pad.r.hold 1 input.pad.r hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
63 0x2128 8488 input.pad.start.pressed 1 input.pad.start pressed 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
64 0x2129 8489 input.pad.start.released 1 input.pad.start released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
65 0x212A 8490 input.pad.start.down 1 input.pad.start down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
66 0x212B 8491 input.pad.start.hold 1 input.pad.start hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
67 0x212C 8492 input.pad.select.pressed 1 input.pad.select pressed 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
68 0x212D 8493 input.pad.select.released 1 input.pad.select released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
69 0x212E 8494 input.pad.select.down 1 input.pad.select down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
70 0x212F 8495 input.pad.select.hold 1 input.pad.select hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
71 0x2130 8496 input.touch.button.pressed 1 input.touch.button pressed 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
72 0x2131 8497 input.touch.button.released 1 input.touch.button released 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
73 0x2132 8498 input.touch.button.down 1 input.touch.button down 0 1 Bool true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
74 0x2133 8499 input.touch.button.hold 1 input.touch.button hold 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
75 0x2134 8500 input.touch.x 1 input.touch x 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
76 0x2135 8501 input.touch.y 1 input.touch y 0 1 Int64 true false 1 false fixed 0 0 2 host_buffered_v1 existing_contract_v1 host 0
77 0x3000 12288 math.i32.min 1 math.i32 min 2 1 Int32|Int32 Int32 true false a|b 2 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
78 0x3001 12289 math.i32.max 1 math.i32 max 2 1 Int32|Int32 Int32 true false a|b 2 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
79 0x3002 12290 math.i32.clamp 1 math.i32 clamp 3 1 Int32|Int32|Int32 Int32 true false value|min|max 4 false fixed 0 0 2 false|false|false host_buffered_v1 existing_contract_v1 host 0
80 0x3003 12291 math.i32.abs 1 math.i32 abs 1 1 Int32 Int32 true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
81 0x3004 12292 math.i64.min 1 math.i64 min 2 1 Int64|Int64 Int64 true false a|b 2 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
82 0x3005 12293 math.i64.max 1 math.i64 max 2 1 Int64|Int64 Int64 true false a|b 2 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
83 0x3006 12294 math.i64.clamp 1 math.i64 clamp 3 1 Int64|Int64|Int64 Int64 true false value|min|max 4 false fixed 0 0 2 false|false|false host_buffered_v1 existing_contract_v1 host 0
84 0x3007 12295 math.i64.abs 1 math.i64 abs 1 1 Int64 Int64 true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
85 0x3008 12296 mathf.min 1 mathf min 2 1 Float|Float Float true false a|b 2 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
86 0x3009 12297 mathf.max 1 mathf max 2 1 Float|Float Float true false a|b 2 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
87 0x300A 12298 mathf.clamp 1 mathf clamp 3 1 Float|Float|Float Float true false value|min|max 4 false fixed 0 0 2 false|false|false host_buffered_v1 existing_contract_v1 host 0
88 0x300B 12299 mathf.abs 1 mathf abs 1 1 Float Float true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
89 0x300C 12300 mathf.floor 1 mathf floor 1 1 Float Float true false value 4 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
90 0x300D 12301 mathf.ceil 1 mathf ceil 1 1 Float Float true false value 4 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
91 0x300E 12302 mathf.trunc 1 mathf trunc 1 1 Float Float true false value 4 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
92 0x300F 12303 mathf.round 1 mathf round 1 1 Float Float true false value 4 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
93 0x3010 12304 mathf.sqrt 1 mathf sqrt 1 1 Float Float true false value 16 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
94 0x3011 12305 mathf.sin 1 mathf sin 1 1 Float Float true false angle 32 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
95 0x3012 12306 mathf.cos 1 mathf cos 1 1 Float Float true false angle 32 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
96 0x3013 12307 mathf.atan2 1 mathf atan2 2 1 Float|Float Float true false y|x 48 false fixed 0 0 2 false|false host_buffered_v1 existing_contract_v1 host 0
97 0x3014 12308 math.i32.to_i64 1 math.i32 to_i64 1 1 Int32 Int64 true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
98 0x3015 12309 math.i64.to_i32 1 math.i64 to_i32 1 1 Int64 Int32 true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
99 0x3016 12310 math.i32.to_float 1 math.i32 to_float 1 1 Int32 Float true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
100 0x3017 12311 math.i64.to_float 1 math.i64 to_float 1 1 Int64 Float true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
101 0x3018 12312 mathf.to_i32 1 mathf to_i32 1 1 Float Int32 true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
102 0x3019 12313 mathf.to_i64 1 mathf to_i64 1 1 Float Int64 true false value 2 false fixed 0 0 2 false host_buffered_v1 existing_contract_v1 host 0
103 0x4000 16384 random.new 1 random new 1 1 Int64 builtin:Random true true seed 32 true fixed 0 0 2 false vm_owned_v1 existing_contract_v1 vm_state 0
104 0x4001 16385 random.next 1 random next 1 1 builtin:Random Int64 true false rng 8 true fixed 0 0 2 true vm_owned_v1 existing_contract_v1 vm_state 0
105 0x4002 16386 random.nextf 1 random nextf 1 1 builtin:Random Float true false rng 12 true fixed 0 0 2 true vm_owned_v1 existing_contract_v1 vm_state 0
106 0x4003 16387 random.range 1 random range 3 1 builtin:Random|Int64|Int64 Int64 true false rng|min|max 4 true random_rejection_v1 8 64 2 true|false|false vm_owned_v1 existing_contract_v1 vm_state 0
107 0x4100 16640 hash.i64 1 hash i64 1 1 Int64 Int64 true false value 8 false fixed 0 0 2 false borrowed_inline_v1 none none 0
108 0x4101 16641 hash.float 1 hash float 1 1 Float Int64 true false value 8 false fixed 0 0 2 false borrowed_inline_v1 none none 0
109 0x4102 16642 hash.string 1 hash string 1 1 String Int64 true false value 8 false argument_utf8_bytes_v1 0 0 2 true borrowed_inline_v1 none none 0 1
+90 -16
View File
@@ -12,7 +12,7 @@ Machine boundary:
Authority rule: Authority rule:
- This document is normative for bytecode-level encoding and opcode surface. - This document is normative for bytecode-level encoding and opcode surface.
- Runtime-wide invariants still live in [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md). - Runtime-wide invariants still live in [`ARCHITECTURE.md`](ARCHITECTURE.md).
- If a bytecode-level rule here conflicts with runtime architecture, the conflict must be resolved explicitly in both documents; neither should drift silently. - If a bytecode-level rule here conflicts with runtime architecture, the conflict must be resolved explicitly in both documents; neither should drift silently.
#### Encoding Rules #### Encoding Rules
@@ -51,6 +51,7 @@ Authority rule:
- Arithmetic: - Arithmetic:
- `ADD`, `SUB`, `MUL`, `DIV`, `MOD` — binary numeric ops. - `ADD`, `SUB`, `MUL`, `DIV`, `MOD` — binary numeric ops.
- `NEG` — unary numeric negation. - `NEG` — unary numeric negation.
- Integer arithmetic wraps at the resulting carrier width. For `DIV`, the signed minimum divided by `-1` returns that minimum; for `MOD`, the same operands return zero. Division or modulo by zero still traps. Mixed Int32/Int64 division promotes to Int64 before the operation.
- Comparison and logic: - Comparison and logic:
- `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE` — comparisons → `[bool]`. - `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE` — comparisons → `[bool]`.
@@ -64,13 +65,13 @@ Authority rule:
- Functions and scopes: - Functions and scopes:
- `CALL u32` — call by function index; argument/result arity per function metadata. - `CALL u32` — call by function index; argument/result arity per function metadata.
- `RET` — return from current function (block terminator). - `RET` — return from current function (block terminator).
- `MAKE_CLOSURE u32,u32` — create closure from `(fn_id, capture_count)`. - `MAKE_CLOSURE u32,u32` — create typed closure from `(FunctionId, FnTypeId)`; cost 8+C.
- `CALL_CLOSURE u32` — invoke closure with `arg_count` user arguments. - `CALL_CLOSURE u32` — invoke against expected FnTypeId; cost 6.
- `GET_CAPTURE u32` (0x57) — copy indexed complete capture group from current frame; cost 2+W.
- `CALL_TRAIT u32,u32` (0x58) — invoke TraitTypeId/method index through complete view; cost 6.
- Concurrency: - Retired execution operations:
- `SPAWN u32,u32` — create coroutine for `(fn_id, arg_count)`. - 0x54–0x56 (SPAWN/YIELD/SLEEP) remain reserved and reject at load, including unreachable code. Diagnostic decoding may identify them; no execution or assembler emission is permitted.
- `YIELD` — request cooperative yield at the next safepoint.
- `SLEEP u32` — request suspension for a logical tick duration.
- System/Timing: - System/Timing:
- `HOSTCALL u32` — PBX pre-load host binding call by `SYSC` table index; the loader must resolve and rewrite it before verification or execution. - `HOSTCALL u32` — PBX pre-load host binding call by `SYSC` table index; the loader must resolve and rewrite it before verification or execution.
@@ -97,12 +98,29 @@ Example:
- `canonical_name` is the fully qualified intrinsic identity seen by compiler-side intrinsic pools. - `canonical_name` is the fully qualified intrinsic identity seen by compiler-side intrinsic pools.
- `arg_slots` and `ret_slots` are the real stack effect contract for verifier/lowering consumers. - `arg_slots` and `ret_slots` are the real stack effect contract for verifier/lowering consumers.
- `arg_layout` and `ret_layout` use `|`-separated ABI atoms: - `arg_layout` and `ret_layout` use `|`-separated ABI atoms:
- `int` - `Int32`
- `float` - `Int64`
- `bool` - `Float`
- `Bool`
- `String`
- `builtin:<builtin_name>` - `builtin:<builtin_name>`
- Rows must remain unique by both `(canonical_name, canonical_version)` and `final_id_hex` / `final_id_dec`. - Rows must remain unique by both `(canonical_name, canonical_version)` and `final_id_hex` / `final_id_dec`.
- Rows must remain deterministically ordered by final ID. - Rows must remain deterministically ordered by final ID.
- parameter_names uses ordered | separated names for flattened argument slots.
- cost_model is fixed, random_rejection_v1, or argument_utf8_bytes_v1. cost_cycles is the full fixed
cost or the variable base. attempt_cost_cycles/max_attempts are zero for
fixed and String byte-cost entries; random.range publishes base 4, attempt 8, maximum 64.
hash.string publishes base 8, argument index 0 and one cycle per UTF-8 byte.
- Mathematical and random attempts charge upfront, including failure, without
an additional generic INTRINSIC cycle. Random draws retain attempt costs.
- mutates_guest_state distinguishes reproducible stateful calls from pure
computation. It is true for all random entries; may_allocate is true only
for random.new. Consumers must preserve stateful calls and source order.
- Both [INTRINSICS.csv](INTRINSICS.csv) and
[BUILTIN_CONSTANTS.csv](BUILTIN_CONSTANTS.csv) are generated from runtime
descriptors. Float constants publish bits rather than decimal approximations.
- See [numeric semantics and consumer examples](../specs/runtime/02d-gameplay-math-and-numeric-semantics.md)
for math/mathf, scalar IDs 0x3000–0x3019, numeric traps and the revised vec2 v1 contract.
For exact immediates and stack effects, see `CoreOpCode::spec()` which is the single source of truth used by the decoder, disassembler, and verifier. For exact immediates and stack effects, see `CoreOpCode::spec()` which is the single source of truth used by the decoder, disassembler, and verifier.
@@ -110,7 +128,7 @@ For exact immediates and stack effects, see `CoreOpCode::spec()` which is the si
- The canonical decoder is `prometeu_bytecode::decode_next(pc, bytes)`. - The canonical decoder is `prometeu_bytecode::decode_next(pc, bytes)`.
- It uses the Core ISA spec to determine immediate size and the canonical `next_pc`. - It uses the Core ISA spec to determine immediate size and the canonical `next_pc`.
- Unknown or legacy opcodes must produce a deterministic `UnknownOpcode` error. - Unknown opcodes produce deterministic UnknownOpcode errors; recognized retired opcodes produce structured load rejection before execution.
#### Module Boundary #### Module Boundary
@@ -122,24 +140,80 @@ For exact immediates and stack effects, see `CoreOpCode::spec()` which is the si
#### Scope Notes #### Scope Notes
- "Core ISA" in the current repository means the canonical opcode surface implemented by the runtime today. - "Core ISA" in the current repository means the canonical opcode surface implemented by the runtime today.
- It includes closures, coroutines, `HOSTCALL` patching semantics, `INTRINSIC`, and `FRAME_SYNC`. - It includes typed closures, trait calls, `HOSTCALL` patching semantics, `INTRINSIC`, and `FRAME_SYNC`.
- It does not, by itself, define higher-level runtime policy such as crash taxonomy, firmware behavior, cartridge lifecycle, or host service organization. Those belong to the canonical runtime architecture and related specs. - It does not, by itself, define higher-level runtime policy such as crash taxonomy, firmware behavior, cartridge lifecycle, or host service organization. Those belong to the canonical runtime architecture and related specs.
#### FRAME_SYNC — Semantics and Placement (Bytecode Level) #### FRAME_SYNC — Semantics and Placement (Bytecode Level)
- Semantics: - Semantics:
- `FRAME_SYNC` is a zero-operand instruction and does not modify the operand stack. - `FRAME_SYNC` is a zero-operand instruction and does not modify the operand stack.
- It marks a VM safepoint for GC and the cooperative scheduler. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`. - It marks a VM safepoint for threshold GC. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`.
- On execution, the VM may suspend the current coroutine until the next frame boundary and/or perform GC. After resuming, execution continues at the next instruction. - Execution returns to the host at the logical frame boundary, preserving the single context. Resumption continues at the next instruction with live frames/locals/environments. Successful last-root RET is a separate GC opportunity after result rooting and completes that entry.
- Placement rules (representable and checkable): - Placement rules (representable and checkable):
- `FRAME_SYNC` may appear anywhere inside a function body where normal instructions can appear. It is NOT a block terminator (`spec.is_terminator == false`). - `FRAME_SYNC` may appear anywhere inside a function body where normal instructions can appear. It is NOT a block terminator (`spec.is_terminator == false`).
- Instruction boundaries are canonical: encoders/emitters must only place `FRAME_SYNC` at valid instruction PCs. The verifier already enforces “jump-to-boundary” and end-exclusive `[start, end)` function ranges using the canonical layout routine. - Instruction boundaries are canonical: encoders/emitters must only place `FRAME_SYNC` at valid instruction PCs. The verifier already enforces “jump-to-boundary” and end-exclusive `[start, end)` function ranges using the canonical layout routine.
- Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/scheduling. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers. - Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/frame handoff. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers.
- Disassembly: - Disassembly:
- Disassemblers must print the mnemonic `FRAME_SYNC` verbatim for this opcode. - Disassemblers must print the mnemonic `FRAME_SYNC` verbatim for this opcode.
- Tools MAY optionally annotate it as a safepoint in comments, e.g., `FRAME_SYNC ; safepoint`. - Tools MAY optionally annotate it as a safepoint in comments, e.g., `FRAME_SYNC ; safepoint`.
- Verification notes: - Verification notes:
- The bytecode verifier treats `FRAME_SYNC` as a normal instruction with no stack effect and no control-flow targets. It is permitted before `RET`, between basic blocks, and as the last instruction of a function. Jumps targeting the function end (`pc == end`) remain valid under the end-exclusive rule. - The bytecode verifier treats `FRAME_SYNC` as a normal instruction with no stack effect and no control-flow targets. It is permitted before `RET` and between basic blocks; a reachable path must still terminate explicitly rather than fall through the function range. Jumps targeting the function end (`pc == end`) remain valid under the end-exclusive rule. A taken end branch completes the current call with the same result-height/type checks, frame release and root-return safepoint as `RET`. It consumes only the decoded branch's cycles, without an additional implicit `RET` charge, and never executes the neighboring function or range gap.
## Registry instruction encodings
The [Registry contract](../specs/runtime/02c-program-registry-and-pbx-v0.md#dynamic-and-reference-instructions)
defines opcodes 0x0090–0x0096. Tooling recognizes their u32 TypeId immediates:
```text
DYN_PACK 0
DYN_UNPACK 0
DYN_CAN_UNPACK 0
REF_IS_EXACT source=4, target=5
REF_IMPLEMENTS source=4, target=6
REF_TO_TRAIT source=4, target=6
REF_CAST source=6, target=4
```
Dynamic instructions occupy six bytes; reference instructions occupy ten bytes.
Static opcode metadata must represent Registry-dependent slot effects as unresolved,
never as zero. Resolve the semantic widths and immediate categories from the validated
Registry. Encoding/decoding support alone does not authorize execution: a slot-only
image/verifier must reject these instructions until typed-image integration is present.
#### Registry-backed collections
STRUCT_NEW (0x00A0), STRUCT_GET (0x00A1), STRUCT_SET (0x00A2), ARRAY_NEW (0x00A3), ARRAY_LEN (0x00A4), ARRAY_GET (0x00A5) and ARRAY_SET (0x00A6) require a validated Registry. Their exact immediates, full group effects, attempt costs and failure ordering are normative in the [typed collection instruction table](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions). These operations have no implicit conversion or safepoint. See the [producer handoff](collection-producer-handoff.md) for emission oracles.
## VM-owned random core
See the [random contract](../specs/runtime/02e-vm-owned-random-core.md) for Random BuiltinId 0x0016, ObjectKind tag 9, intrinsics 0x4000–0x4003, atomic state mutation, bounded 4+8*N costs and rejection-limit trap 0x00000015. Random is managed by the VM heap and existing GC, without host entropy or PBX changes.
## Typed array range copy
ARRAY_COPY (0xA9, Array TypeId u32) consumes source, sourceStart, target,
targetStart, count without a result. Complete groups and owners survive overlap
and failed preparation. Charge 4+2*N*W before ordinary validation for available
Int64 count in 0..u32::MAX; other counts/underflow charge base 4. Checked cost
overflow charges base and traps SizeOverflow. The
[canonical contract](../specs/runtime/02-vm-instruction-set.md#typed-array-range-copy)
defines fault precedence, scratch and commit. ARRAY_LEN (0xA4) and physical array
checks remain. Encodings 0xA7/0xA8/0xAA/0xAB reject at load even in dead code;
no replacement publication/guard or transaction is provided.
## Identity/hash and catalog schema 2
The [identity/hash specification](../specs/runtime/02f-vm-identity-and-value-hashing.md)
defines opcodes 0x0097/0x0098, intrinsics 0x4100–0x4102, XXH64 hash-v1 and
borrowed_inline_v1. INTRINSICS.csv schema 2 retains its original eighteen columns
and appends schema_version, arg_nullable, invocation_model, scratch_model,
context_access, cost_arg_index and cost_per_byte. Descriptors remain authoritative;
unknown or inconsistent schemas/profiles/models must fail explicitly. Existing
canonical versions, signatures, effects and costs remain unchanged.
See the [identity/hash producer handoff](identity-hashing-producer-handoff.md) and
[qualification record](IDENTITY_HASHING_QUALIFICATION.md) for emitted PBX, catalog
provenance and consumer acceptance evidence.
+32 -2
View File
@@ -10,6 +10,7 @@ Canonical runtime sources:
- `../runtime/docs/vm-arch/ARCHITECTURE.md` - `../runtime/docs/vm-arch/ARCHITECTURE.md`
- `../runtime/docs/vm-arch/ISA_CORE.md` - `../runtime/docs/vm-arch/ISA_CORE.md`
- `../runtime/docs/vm-arch/INTRINSICS.csv` - `../runtime/docs/vm-arch/INTRINSICS.csv`
- `../runtime/docs/vm-arch/BUILTIN_CONSTANTS.csv`
When these mirrors are retained, an integration change that updates a canonical When these mirrors are retained, an integration change that updates a canonical
runtime source MUST update the corresponding Studio mirror in the same logical runtime source MUST update the corresponding Studio mirror in the same logical
@@ -19,14 +20,43 @@ change. Verify synchronization from the Studio repository root with:
diff -u docs/vm-arch/ARCHITECTURE.md ../runtime/docs/vm-arch/ARCHITECTURE.md diff -u docs/vm-arch/ARCHITECTURE.md ../runtime/docs/vm-arch/ARCHITECTURE.md
diff -u docs/vm-arch/ISA_CORE.md ../runtime/docs/vm-arch/ISA_CORE.md diff -u docs/vm-arch/ISA_CORE.md ../runtime/docs/vm-arch/ISA_CORE.md
diff -u docs/vm-arch/INTRINSICS.csv ../runtime/docs/vm-arch/INTRINSICS.csv diff -u docs/vm-arch/INTRINSICS.csv ../runtime/docs/vm-arch/INTRINSICS.csv
diff -u docs/vm-arch/BUILTIN_CONSTANTS.csv ../runtime/docs/vm-arch/BUILTIN_CONSTANTS.csv
``` ```
All three commands MUST exit successfully with no output before a change claims All four commands MUST exit successfully with no output before a change claims
that the mirrors are synchronized. If the runtime repository is not available that the mirrors are synchronized. If the runtime repository is not available
in the same checkout, synchronization evidence must be produced against the in the same checkout, synchronization evidence must be produced against the
canonical runtime revision before merging. canonical runtime revision before merging.
Compiler-owned transformation contracts remain under `docs/specs/compiler`. Compiler-owned transformation contracts remain under `docs/compiler/general/specs`.
Those specifications define `IRBackend -> IRVM -> PBX` emission, but they MUST Those specifications define `IRBackend -> IRVM -> PBX` emission, but they MUST
conform to the runtime-owned PBX and ISA contracts and MUST NOT redefine runtime conform to the runtime-owned PBX and ISA contracts and MUST NOT redefine runtime
execution semantics. execution semantics.
## Catalog provenance
`runtime-catalog.properties` identifies the selected provider revision and hashes
of both CSVs. The compiler and PBS SDK package these artifacts with their own
resource namespaces. Catalog synchronization alone does not claim the other
architecture mirrors are synchronized or that all PBS facades are implemented.
Run the explicit source/exporter verification from the Studio root:
```sh
python3 tools/runtime-catalog/verify.py --runtime ../runtime
```
This command requires a clean checkout of the recorded provider revision, compares
committed bytes and hashes, and runs its real catalog exporter parity test with
build output in a temporary directory. Missing or different evidence sources fail
explicitly. Ordinary builds and local catalog tests never invoke this command.
The manual port and consumer requirements are defined in
[Runtime catalog support](../compiler/general/specs/runtime-catalog-support.md).
The selected provider publishes intrinsic schema 2 (25 columns). Manual compiler
metadata must retain every nullable bit, invocation/scratch/context profile and
cost parameter, including entries without PBS source facades. Storage producer
qualification uses the minimal ISA: ARRAY_LEN and ARRAY_COPY remain; 0xA7, 0xA8,
0xAA and 0xAB are unsupported. Compiler/SDK conformance must be regenerated for
the selected revision rather than reusing evidence from earlier providers.
+3
View File
@@ -0,0 +1,3 @@
runtime.revision=dcf6561ea73446e0a3e1cf1c73eda20923b38df0
INTRINSICS.csv.sha256=7c1c363f5f0f941b3ab27cfc72af41e13e44cd4371c687db8300721288f47e63
BUILTIN_CONSTANTS.csv.sha256=e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039
+75 -46
View File
@@ -1,63 +1,92 @@
pipeline { pipeline {
agent any agent any
tools {
gradle 'gradle-9.3.1'
}
environment { environment {
GRADLE_USER_HOME = '/var/jenkins_home/.gradle' GRADLE_USER_HOME = '/var/jenkins_home/.gradle'
GRADLE_OPTS = '-Dorg.gradle.parallel=true -Dorg.gradle.caching=true' GRADLE_OPTS = '-Dorg.gradle.parallel=true -Dorg.gradle.caching=true'
JAVA_TOOL_OPTIONS = '-Djava.awt.headless=true'
JAVA_OPTS = '-Xmx2g' JAVA_OPTS = '-Xmx2g'
TESTS_STARTED = 'false'
VERIFICATION_SUCCEEDED = 'false'
} }
stages { stages {
stage('Build') { stage('Clean') {
steps { steps {
// A separate successful clean prevents publishing a previous build's reports.
withGradle {
sh './gradlew clean --no-daemon --console=plain'
}
}
}
stage('Tests and coverage') {
steps {
script { env.TESTS_STARTED = 'true' }
withChecks(name: 'Test', includeStage: true) { withChecks(name: 'Test', includeStage: true) {
withGradle { withGradle {
sh """ // --continue finishes independent tests/reports but retains a nonzero exit on failure.
gradle \ sh './gradlew test jacocoTestReport --continue --parallel --max-workers=2 --build-cache --no-daemon --console=plain'
clean \
test \
jacocoTestReport \
--parallel \
--max-workers=2 \
--build-cache \
--no-daemon
"""
} }
recordCoverage(tools: [[parser: 'JACOCO', pattern: "build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml"]],
id: 'jacoco',
name: 'JaCoCo Coverage',
sourceCodeRetention: 'EVERY_BUILD',
qualityGates: [
[threshold: 50.0, metric: 'CLASS', baseline: 'PROJECT', unstable: true],
[threshold: 50.0, metric: 'METHOD', baseline: 'PROJECT', unstable: true],
[threshold: 50.0, metric: 'LINE', baseline: 'PROJECT', unstable: true],
[threshold: 50.0, metric: 'INSTRUCTION', baseline: 'PROJECT', unstable: true],
[threshold: 40.0, metric: 'BRANCH', baseline: 'PROJECT', unstable: true]])
junit testResults: '**/build/test-results/test/TEST-*.xml'
} }
script { env.VERIFICATION_SUCCEEDED = 'true' }
} }
} // Test }
stage('Reports') {
steps {
script {
// archiveArtifacts artifacts: '**/coverage-sources.zip', allowEmptyArchive: false, fingerprint: false, onlyIfSuccessful: false
publishHTML (target: [
allowMissing: true,
alwaysLinkToLastBuild: false,
keepAll: true,
reportDir: "build/reports/jacoco/jacocoTestReport/html",
reportFiles: 'index.html',
reportName: 'Coverage Report'
])
// def pmd = scanForIssues tool: [$class: 'Pmd'], pattern: 'lib/build/reports/pmd/*.xml'
// publishIssues issues: [pmd]
}
}
} // Reports
} }
}
post {
always {
script {
if (env.TESTS_STARTED == 'true') {
// Isolate publishers so a failed publisher does not suppress the other diagnostics.
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
junit testResults: '**/build/test-results/test/TEST-*.xml',
allowEmptyResults: env.VERIFICATION_SUCCEEDED != 'true'
if (env.VERIFICATION_SUCCEEDED == 'true' && !fileExists('prometeu-packer/prometeu-packer-v1/build/test-results/test/TEST-p.packer.services.PackerAssetContractTest.xml')) {
error 'Successful verification is missing the packer contract test report.'
}
}
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
if (fileExists('build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml')) {
withChecks(name: 'JaCoCo Coverage', includeStage: false) {
recordCoverage(tools: [[parser: 'JACOCO', pattern: 'build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml']],
id: 'jacoco',
name: 'JaCoCo Coverage',
checksName: 'JaCoCo Coverage',
sourceDirectories: [[path: 'glob:**/src/main/java']],
sourceCodeEncoding: 'UTF-8',
sourceCodeRetention: 'EVERY_BUILD',
qualityGates: [
[threshold: 50.0, metric: 'CLASS', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'METHOD', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'LINE', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'INSTRUCTION', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 40.0, metric: 'BRANCH', baseline: 'PROJECT', criticality: 'UNSTABLE']])
}
} else if (env.VERIFICATION_SUCCEEDED == 'true') {
error 'Successful verification is missing the consolidated JaCoCo XML report.'
} else {
echo 'Verification failed before consolidated coverage was available; preserving available test reports.'
}
}
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
publishHTML(target: [
allowMissing: env.VERIFICATION_SUCCEEDED != 'true',
alwaysLinkToLastBuild: false,
keepAll: true,
reportDir: 'build/reports/jacoco/jacocoTestReport/html',
reportFiles: 'index.html',
reportName: 'Coverage Report'
])
}
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
archiveArtifacts artifacts: '**/build/test-results/test/**, **/build/reports/tests/test/**, **/build/reports/jacoco/**',
allowEmptyArchive: env.VERIFICATION_SUCCEEDED != 'true',
onlyIfSuccessful: false
}
} else {
echo 'Preparation did not complete; no current test run to publish. See the build console for diagnostics.'
}
}
}
}
}
+57
View File
@@ -0,0 +1,57 @@
# Studio Jenkins verification
`Jenkinsfile` uses the checked-in Gradle wrapper (currently 9.3.1). A compatible
Java installation must be available to launch Gradle; project conventions select
Java 21 for compilation/tests. The pipeline retains its existing Gradle cache
location, worker limit and installed Jenkins report plugins. It does not require
a named Jenkins Gradle installation.
The build runs on a Unix agent with Java and dependency/cache access. It sets
`JAVA_TOOL_OPTIONS=-Djava.awt.headless=true` for Gradle and test JVMs. No display,
runtime binary, sibling runtime checkout, runtime download/build, or new Jenkins
plugin is required by the packer contract suite.
## Commands
```sh
export JAVA_TOOL_OPTIONS=-Djava.awt.headless=true
./gradlew clean --no-daemon --console=plain
./gradlew test jacocoTestReport --continue --parallel --max-workers=2 --build-cache --no-daemon --console=plain
```
Clean is a separate stage: when it fails, old reports must not be published as a
new test run. Gradle `--continue` lets independent tasks and reports finish after
a test failure; it does not turn a failing command into success. Runtime/desktop
opt-in test tasks are not invoked. The ordinary packer `test` task includes
`PackerAssetContractTest` without skips or a runtime fallback.
## Failure reporting
The unconditional post block publishes available JUnit, consolidated JaCoCo XML,
HTML and archived test/coverage reports after a failed verification command.
Each publisher is isolated so one publisher error does not prevent the others
from being attempted. The build console retains compilation/setup diagnostics.
An otherwise successful verification must produce JUnit results, the packer
contract suite report, consolidated JaCoCo XML and HTML. Missing successful-build
evidence fails publication. A failed compilation may have no reports: the
original build failure remains authoritative and available diagnostics are still
preserved. A failed clean does not publish potentially stale artifacts.
Coverage thresholds are unchanged: CLASS/METHOD/LINE/INSTRUCTION 50%, BRANCH
40%, PROJECT baseline and UNSTABLE criticality. Reports from partially failed
test runs are useful diagnostics, not a passing quality gate.
## Contract and manual verification boundary
See the packer fixture [provenance and coverage](../../prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md).
The automated suite checks producer bytes and metadata against independent
expectations. Runtime gameplay remains manual with existing games, not a local
or CI automated test. Record manual outcomes only after execution.
Local Gradle checks and Groovy parsing cannot certify controller plugin behavior.
A Jenkins run is needed to observe actual report publication and coverage checks;
report any unavailable controller validation explicitly.
Jenkins behavior references: [post conditions](https://www.jenkins.io/doc/book/pipeline/syntax/#post)
and [catchError](https://www.jenkins.io/doc/pipeline/steps/workflow-basic-steps/#catcherror-catch-error-and-set-build-result-to-failure).
+2
View File
@@ -85,6 +85,8 @@ tasks.register<Test>("installedKnowledgeTest") {
val distribution = layout.buildDirectory.dir("install/prometeu-app") val distribution = layout.buildDirectory.dir("install/prometeu-app")
inputs.dir(distribution) inputs.dir(distribution)
systemProperty("studio.test.distribution", distribution.get().asFile.absolutePath) systemProperty("studio.test.distribution", distribution.get().asFile.absolutePath)
systemProperty("pbs.registryConformanceDirectory",
project(":prometeu-compiler:prometeu-build-pipeline").layout.buildDirectory.dir("registry-conformance").get().asFile.absolutePath)
} }
tasks.register<Test>("headlessProcessTest") { tasks.register<Test>("headlessProcessTest") {
@@ -10,6 +10,8 @@ import p.studio.api.automation.*;
import p.studio.api.project.ProjectCatalog; import p.studio.api.project.ProjectCatalog;
import p.studio.core.language.LanguageQueryPort; import p.studio.core.language.LanguageQueryPort;
import p.studio.lsp.api.LspServerLifecycle; import p.studio.lsp.api.LspServerLifecycle;
import p.studio.lsp.services.protocol.ExternalSourceLanguageServer;
import org.eclipse.lsp4j.jsonrpc.Launcher;
import java.net.*; import java.net.*;
import java.nio.file.*; import java.nio.file.*;
@@ -24,7 +26,7 @@ public final class AutomationLspQueries implements LanguageQueryPort {
private final ObjectMapper mapper; private final ObjectMapper mapper;
private final com.google.gson.Gson gson = new MessageJsonHandler(Map.of()).getGson(); private final com.google.gson.Gson gson = new MessageJsonHandler(Map.of()).getGson();
private final Map<TaskIdentity, Map<String, CallHierarchyItem>> items = new ConcurrentHashMap<>(); private final Map<TaskIdentity, Map<String, CallHierarchyItem>> items = new ConcurrentHashMap<>();
private static final Set<String> OPERATIONS = Set.of("diagnostics", "completion", "hover", "signatureHelp", "definition", private static final Set<String> OPERATIONS = Set.of("readExternalSource", "diagnostics", "completion", "hover", "signatureHelp", "definition",
"references", "documentSymbols", "workspaceSymbols", "prepareRename", "rename", "codeActions", "formatting", "references", "documentSymbols", "workspaceSymbols", "prepareRename", "rename", "codeActions", "formatting",
"documentLinks", "foldingRanges", "selectionRanges", "prepareCallHierarchy", "incomingCalls", "outgoingCalls", "semanticTokens"); "documentLinks", "foldingRanges", "selectionRanges", "prepareCallHierarchy", "incomingCalls", "outgoingCalls", "semanticTokens");
private static final Set<String> EDITS = Set.of("completion", "prepareRename", "rename", "codeActions", "formatting"); private static final Set<String> EDITS = Set.of("completion", "prepareRename", "rename", "codeActions", "formatting");
@@ -33,7 +35,47 @@ public final class AutomationLspQueries implements LanguageQueryPort {
this.lifecycle = lifecycle; this.projects = projects; this.knowledge = knowledge; this.mapper = mapper; this.lifecycle = lifecycle; this.projects = projects; this.knowledge = knowledge; this.mapper = mapper;
} }
@Override public void endTask(TaskIdentity task) { items.remove(task); } private record ExternalTask(String consumer, p.studio.lsp.messages.LspServerEndpoint endpoint,
p.studio.lsp.messages.LspProjectContext binding, Set<String> uris) {}
private final Map<TaskIdentity, ExternalTask> externalTasks = new ConcurrentHashMap<>();
@Override public void endTask(TaskIdentity task) {
items.remove(task);
final var state = externalTasks.remove(task);
if (state == null) return;
final var workers = Executors.newCachedThreadPool();
try (var socket = new Socket()) {
socket.connect(new InetSocketAddress(state.endpoint().host(), state.endpoint().port()), 2000);
final var client = new QuietClient();
final var launcher = new Launcher.Builder<ExternalSourceLanguageServer>().setLocalService(client)
.setRemoteInterface(ExternalSourceLanguageServer.class).setInput(socket.getInputStream())
.setOutput(socket.getOutputStream()).setExecutorService(workers).create();
final var listening = launcher.startListening();
try {
final var server = launcher.getRemoteProxy();
final var init = new InitializeParams();
init.setRootUri(state.binding().projectRoot().toUri().toString());
init.setCapabilities(new ClientCapabilities());
init.getCapabilities().setExperimental(Map.of("prometeuExternalSources", true));
init.setInitializationOptions(Map.of("prometeuExternalConsumerId", state.consumer()));
server.initialize(init).get(2, TimeUnit.SECONDS);
server.releaseExternalSource(new ExternalSourceLanguageServer.Request(state.consumer(), null)).get(2, TimeUnit.SECONDS);
} finally { listening.cancel(true); }
} catch (Exception failure) {
// A closed project host has already released its registry. Other cleanup
// failures are surfaced instead of silently reporting a successful task end.
if (lifecycle.endpoint(state.binding()).isPresent())
throw new IllegalStateException("Could not release task external sources", failure);
} finally { workers.shutdownNow(); }
}
private static class QuietClient implements LanguageClient {
public void telemetryEvent(Object event) {}
public void publishDiagnostics(PublishDiagnosticsParams event) {}
public void showMessage(MessageParams message) {}
public CompletableFuture<MessageActionItem> showMessageRequest(ShowMessageRequestParams request) { return CompletableFuture.completedFuture(null); }
public void logMessage(MessageParams message) {}
}
@Override public Map<String, Object> query(TaskIdentity task, String operation, Map<String, Object> parameters) throws Exception { @Override public Map<String, Object> query(TaskIdentity task, String operation, Map<String, Object> parameters) throws Exception {
if (!OPERATIONS.contains(operation)) throw failure(AutomationFailure.Code.UNSUPPORTED_CAPABILITY, "Unsupported language operation: " + operation); if (!OPERATIONS.contains(operation)) throw failure(AutomationFailure.Code.UNSUPPORTED_CAPABILITY, "Unsupported language operation: " + operation);
@@ -55,7 +97,15 @@ public final class AutomationLspQueries implements LanguageQueryPort {
uri = params.path("uri").asText(null); uri = params.path("uri").asText(null);
if (uri == null) throw new IllegalArgumentException("uri is required"); if (uri == null) throw new IllegalArgumentException("uri is required");
} }
Path document = uri == null ? null : sourcePath(context, uri); final boolean external = uri != null && uri.startsWith("prometeu-source:");
if (external) {
final var state = externalTasks.get(task);
if (state == null || !state.uris().contains(uri)) throw failure(AutomationFailure.Code.OUTSIDE_PROJECT_SCOPE, "Unknown task-owned external source");
if (EDITS.contains(operation)) throw failure(AutomationFailure.Code.READ_ONLY_SCOPE, "External sources are read-only");
if (!Set.of("readExternalSource", "hover", "definition").contains(operation))
throw failure(AutomationFailure.Code.UNSUPPORTED_CAPABILITY, "Operation is unavailable for external documents");
} else if (operation.equals("readExternalSource")) throw new IllegalArgumentException("An external source URI is required");
Path document = uri == null || external ? null : sourcePath(context, uri);
if (document != null && EDITS.contains(operation)) requireEditable(context, document.toUri().toString()); if (document != null && EDITS.contains(operation)) requireEditable(context, document.toUri().toString());
String source = null; String source = null;
if (document != null) { if (document != null) {
@@ -83,14 +133,28 @@ public final class AutomationLspQueries implements LanguageQueryPort {
return CompletableFuture.completedFuture(new ApplyWorkspaceEditResponse(false)); return CompletableFuture.completedFuture(new ApplyWorkspaceEditResponse(false));
} }
}; };
var launcher = LSPLauncher.createClientLauncher(client, socket.getInputStream(), socket.getOutputStream(), workers, consumer -> consumer); var launcher = new Launcher.Builder<ExternalSourceLanguageServer>().setLocalService(client)
.setRemoteInterface(ExternalSourceLanguageServer.class).setInput(socket.getInputStream())
.setOutput(socket.getOutputStream()).setExecutorService(workers).create();
var listening = launcher.startListening(); var listening = launcher.startListening();
final var server = launcher.getRemoteProxy();
final var acquired = new HashSet<String>();
boolean succeeded = false;
try { try {
var server = launcher.getRemoteProxy();
var initialize = new InitializeParams(); var initialize = new InitializeParams();
initialize.setRootUri(binding.projectRoot().toUri().toString()); initialize.setRootUri(binding.projectRoot().toUri().toString());
initialize.setCapabilities(new ClientCapabilities()); initialize.setCapabilities(new ClientCapabilities());
initialize.getCapabilities().setExperimental(Map.of("prometeuExternalSources", true));
final var previous = externalTasks.get(task);
initialize.setInitializationOptions(previous == null
? Map.of("prometeuExternalPersistentConsumer", true)
: Map.of("prometeuExternalConsumerId", previous.consumer(), "prometeuExternalPersistentConsumer", true));
var capabilities = await(server.initialize(initialize), deadline).getCapabilities(); var capabilities = await(server.initialize(initialize), deadline).getCapabilities();
final var experimental = gson.toJsonTree(capabilities.getExperimental());
if (experimental.isJsonObject() && experimental.getAsJsonObject().has("prometeuExternalConsumerId")) {
final String consumer = experimental.getAsJsonObject().get("prometeuExternalConsumerId").getAsString();
externalTasks.putIfAbsent(task, new ExternalTask(consumer, endpoint, binding, ConcurrentHashMap.newKeySet()));
}
server.initialized(new InitializedParams()); server.initialized(new InitializedParams());
requireCapability(operation, capabilities); requireCapability(operation, capabilities);
List<Diagnostic> currentDiagnostics = List.of(); List<Diagnostic> currentDiagnostics = List.of();
@@ -99,9 +163,17 @@ public final class AutomationLspQueries implements LanguageQueryPort {
server.getTextDocumentService().didOpen(new DidOpenTextDocumentParams(new TextDocumentItem(uri, primary.id(), 1, source))); server.getTextDocumentService().didOpen(new DidOpenTextDocumentParams(new TextDocumentItem(uri, primary.id(), 1, source)));
currentDiagnostics = await(diagnostics, deadline); currentDiagnostics = await(diagnostics, deadline);
} }
if (external) {
final var request = new ExternalSourceLanguageServer.Request(externalTasks.get(task).consumer(), uri);
source = await(server.revalidateExternalSource(request), deadline).text();
if (source.getBytes(java.nio.charset.StandardCharsets.UTF_8).length > 4 * 1024 * 1024)
throw failure(AutomationFailure.Code.LIMIT_EXCEEDED, "External source exceeds 4 MiB");
}
var text = server.getTextDocumentService(); var text = server.getTextDocumentService();
var id = uri == null ? null : new TextDocumentIdentifier(uri); var id = uri == null ? null : new TextDocumentIdentifier(uri);
Object result = switch (operation) { Object result = switch (operation) {
case "readExternalSource" -> await(server.readExternalSource(
new ExternalSourceLanguageServer.Request(externalTasks.get(task).consumer(), uri)), deadline);
case "diagnostics" -> currentDiagnostics; case "diagnostics" -> currentDiagnostics;
case "hover" -> await(text.hover(new HoverParams(id, position(params.path("position"), source))), deadline); case "hover" -> await(text.hover(new HoverParams(id, position(params.path("position"), source))), deadline);
case "completion" -> await(text.completion(new CompletionParams(id, position(params.path("position"), source))), deadline); case "completion" -> await(text.completion(new CompletionParams(id, position(params.path("position"), source))), deadline);
@@ -136,6 +208,17 @@ public final class AutomationLspQueries implements LanguageQueryPort {
}; };
var wire = mapper.readTree(gson.toJson(result)); var wire = mapper.readTree(gson.toJson(result));
validateEdits(context, wire); validateEdits(context, wire);
if (operation.equals("definition") && externalTasks.containsKey(task)) {
final var returned = new HashSet<String>();
rememberExternalUris(returned, wire);
acquired.addAll(returned);
acquired.removeAll(externalTasks.get(task).uris());
for (String externalUri : returned) {
await(server.retainExternalSource(new ExternalSourceLanguageServer.Request(
externalTasks.get(task).consumer(), externalUri)), deadline);
externalTasks.get(task).uris().add(externalUri);
}
}
var limitations = new ArrayList<String>(); var limitations = new ArrayList<String>();
if (operation.equals("codeActions") && wire.isArray()) { if (operation.equals("codeActions") && wire.isArray()) {
for (var action : wire) if (action.has("command")) { for (var action : wire) if (action.has("command")) {
@@ -147,11 +230,30 @@ public final class AutomationLspQueries implements LanguageQueryPort {
var output = new LinkedHashMap<String, Object>(); var output = new LinkedHashMap<String, Object>();
output.put("operation", operation); output.put("result", mapper.convertValue(wire, Object.class)); output.put("operation", operation); output.put("result", mapper.convertValue(wire, Object.class));
output.put("limitations", limitations); output.put("limitations", limitations);
succeeded = true;
return Collections.unmodifiableMap(output); return Collections.unmodifiableMap(output);
} finally { listening.cancel(true); } } finally {
if (!succeeded && !acquired.isEmpty() && externalTasks.containsKey(task)) {
final var state = externalTasks.get(task);
final boolean interrupted = Thread.interrupted();
try {
for (String acquiredUri : acquired) {
state.uris().remove(acquiredUri);
server.releaseExternalSource(new ExternalSourceLanguageServer.Request(state.consumer(), acquiredUri))
.get(500, TimeUnit.MILLISECONDS);
}
} finally { if (interrupted) Thread.currentThread().interrupt(); }
}
listening.cancel(true);
}
} finally { workers.shutdownNow(); } } finally { workers.shutdownNow(); }
} }
private void rememberExternalUris(Set<String> uris, com.fasterxml.jackson.databind.JsonNode node) {
if (node.isObject() && node.path("uri").asText().startsWith("prometeu-source:")) uris.add(node.path("uri").asText());
if (node.isContainerNode()) node.forEach(child -> rememberExternalUris(uris, child));
}
private void addItemIds(TaskIdentity task, com.fasterxml.jackson.databind.JsonNode node) { private void addItemIds(TaskIdentity task, com.fasterxml.jackson.databind.JsonNode node) {
if (node.isObject() && node.has("uri") && node.has("selectionRange") && node.has("name") && node.has("kind")) { if (node.isObject() && node.has("uri") && node.has("selectionRange") && node.has("name") && node.has("kind")) {
var stored = items.computeIfAbsent(task, ignored -> new ConcurrentHashMap<>()); var stored = items.computeIfAbsent(task, ignored -> new ConcurrentHashMap<>());
@@ -163,6 +265,12 @@ public final class AutomationLspQueries implements LanguageQueryPort {
} }
private static void requireCapability(String operation, ServerCapabilities caps) { private static void requireCapability(String operation, ServerCapabilities caps) {
if (operation.equals("readExternalSource")) {
final var raw = new com.google.gson.Gson().toJsonTree(caps.getExperimental());
if (!raw.isJsonObject() || !raw.getAsJsonObject().has("prometeuExternalSources"))
throw failure(AutomationFailure.Code.UNSUPPORTED_CAPABILITY, "LSP does not advertise external sources");
return;
}
Object capability = switch (operation) { Object capability = switch (operation) {
case "diagnostics" -> caps.getTextDocumentSync(); case "diagnostics" -> caps.getTextDocumentSync();
case "hover" -> caps.getHoverProvider(); case "completion" -> caps.getCompletionProvider(); case "hover" -> caps.getHoverProvider(); case "completion" -> caps.getCompletionProvider();
@@ -233,6 +341,7 @@ public final class AutomationLspQueries implements LanguageQueryPort {
catch (ExecutionException failure) { catch (ExecutionException failure) {
if (failure.getCause() instanceof org.eclipse.lsp4j.jsonrpc.ResponseErrorException response) { if (failure.getCause() instanceof org.eclipse.lsp4j.jsonrpc.ResponseErrorException response) {
int code = response.getResponseError().getCode(); int code = response.getResponseError().getCode();
if (code == -32010) throw failure(AutomationFailure.Code.READ_ONLY_SCOPE, response.getResponseError().getMessage());
if (code == -32602) throw new IllegalArgumentException("LSP rejected query parameters"); if (code == -32602) throw new IllegalArgumentException("LSP rejected query parameters");
if (code == -32601 || code == -32600) if (code == -32601 || code == -32600)
throw failure(AutomationFailure.Code.UNSUPPORTED_CAPABILITY, response.getResponseError().getMessage()); throw failure(AutomationFailure.Code.UNSUPPORTED_CAPABILITY, response.getResponseError().getMessage());
@@ -245,7 +245,9 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
default -> AutomationFailure.Code.INFRASTRUCTURE_FAILURE; default -> AutomationFailure.Code.INFRASTRUCTURE_FAILURE;
}; };
pending.remove(item.id); pending.remove(item.id);
item.result.completeExceptionally(new AutomationException(code, "Runtime " + error.path("code").asText() + ": " + error.path("message").asText())); Map<String, Object> runtimeError = mapper.convertValue(error, new com.fasterxml.jackson.core.type.TypeReference<>() {});
item.result.completeExceptionally(new AutomationException(new AutomationFailure(code,
"Runtime " + error.path("code").asText() + ": " + error.path("message").asText(), runtimeError)));
} else { } else {
var result = message.get("result"); var result = message.get("result");
if (item.command.equals("cancel") && (!result.path("requested").isBoolean() || !result.path("requested").booleanValue() if (item.command.equals("cancel") && (!result.path("requested").isBoolean() || !result.path("requested").booleanValue()
@@ -53,6 +53,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -161,6 +165,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -248,6 +256,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -335,6 +347,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -367,7 +383,7 @@
{ {
"name": "studio_language_query", "name": "studio_language_query",
"authority": "task", "authority": "task",
"description": "Query supported project LSP capabilities after synchronizing saved files. Returns refactoring proposals, never applies edits.", "description": "Query project LSP capabilities using saved project files or task-owned read-only external sources. readExternalSource reads an external URI returned by definition; hover and definition can continue inside it. Returns refactoring proposals, never applies edits.",
"inputSchema": { "inputSchema": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -538,6 +554,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -640,6 +660,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -735,6 +759,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -824,6 +852,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -911,6 +943,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -998,6 +1034,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -1094,6 +1134,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -1181,6 +1225,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -1268,6 +1316,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -1427,6 +1479,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -1529,6 +1585,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -1650,6 +1710,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -1750,6 +1814,10 @@
}, },
"message": { "message": {
"type": "string" "type": "string"
},
"runtimeError": {
"type": "object",
"additionalProperties": true
} }
}, },
"required": [ "required": [
@@ -47,6 +47,10 @@ class CompilerProjectKnowledgeTest {
assertTrue(result.libraries().getFirst().id().startsWith("sdk:pbs:")); assertTrue(result.libraries().getFirst().id().startsWith("sdk:pbs:"));
assertFalse(result.references().isEmpty()); assertFalse(result.references().isEmpty());
assertTrue(result.references().stream().anyMatch(value -> value.id().equals("pbs:quickstart"))); assertTrue(result.references().stream().anyMatch(value -> value.id().equals("pbs:quickstart")));
assertTrue(result.references().stream().anyMatch(value -> value.id().equals("pbs:spec:sdk-list-and-cursor.md")));
assertTrue(result.references().stream().anyMatch(value -> value.id().equals("pbs:example:game:1:src/collections.pbs")));
assertTrue(result.references().stream().anyMatch(value -> value.id().equals("pbs:spec:sdk-linked-and-cursor.md")));
assertTrue(result.references().stream().anyMatch(value -> value.id().equals("pbs:example:game:1:src/linked.pbs")));
assertTrue(language.referenceIds().contains("pbs:quickstart")); assertTrue(language.referenceIds().contains("pbs:quickstart"));
assertFalse(result.limitations().stream().anyMatch(value -> value.contains("DOCUMENTATION_UNAVAILABLE"))); assertFalse(result.limitations().stream().anyMatch(value -> value.contains("DOCUMENTATION_UNAVAILABLE")));
assertFalse(Files.exists(root.resolve(".workspace"))); assertFalse(Files.exists(root.resolve(".workspace")));
@@ -19,8 +19,18 @@ public final class InstalledKnowledgeProbe {
check(provider.getClass().getProtectionDomain().getCodeSource().getLocation().getPath().endsWith(".jar"), "Frontend must come from installed JAR"); check(provider.getClass().getProtectionDomain().getCodeSource().getLocation().getPath().endsWith(".jar"), "Frontend must come from installed JAR");
check(CompilerProjectKnowledge.class.getProtectionDomain().getCodeSource().getLocation().getPath().endsWith(".jar"), "App must come from installed JAR"); check(CompilerProjectKnowledge.class.getProtectionDomain().getCodeSource().getLocation().getPath().endsWith(".jar"), "App must come from installed JAR");
check(!Files.exists(Path.of("settings.gradle.kts")) && !Files.exists(Path.of("docs")), "No repository in working directory"); check(!Files.exists(Path.of("settings.gradle.kts")) && !Files.exists(Path.of("docs")), "No repository in working directory");
verifyRuntimeCatalogs(provider.getClass().getClassLoader());
if (arguments.length == 1 && arguments[0].equals("--catalog-only")) return;
Path root = Files.createDirectory(Path.of("example")).toRealPath(); Path root = Files.createDirectory(Path.of("example")).toRealPath();
var docs = provider.documentation().orElseThrow().references(1, p.studio.AppMode.Game); var docs = provider.documentation().orElseThrow().references(1, p.studio.AppMode.Game);
check(docs.stream().anyMatch(r -> r.id().equals("pbs:spec:generic-contracts.md")), "Missing installed generic-contract specification");
check(docs.stream().anyMatch(r -> r.id().equals("pbs:example:game:1:src/contracts.pbs")), "Missing installed generic-contract example");
check(docs.stream().anyMatch(r -> r.id().equals("pbs:spec:generic-structs-and-free-functions.md")), "Missing installed generic struct/function specification");
check(docs.stream().anyMatch(r -> r.id().equals("pbs:example:game:1:src/generics.pbs")), "Missing installed generic struct/function example");
check(docs.stream().anyMatch(r -> r.id().equals("pbs:spec:sdk-list-and-cursor.md")), "Missing installed List/Cursor specification");
check(docs.stream().anyMatch(r -> r.id().equals("pbs:example:game:1:src/collections.pbs")), "Missing installed List/Cursor example");
check(docs.stream().anyMatch(r -> r.id().equals("pbs:spec:sdk-linked-and-cursor.md")), "Missing installed Linked specification");
check(docs.stream().anyMatch(r -> r.id().equals("pbs:example:game:1:src/linked.pbs")), "Missing installed Linked example");
for (var reference : docs) { for (var reference : docs) {
if (reference.id().startsWith("pbs:example:game:1:")) { if (reference.id().startsWith("pbs:example:game:1:")) {
Path file = root.resolve(reference.id().substring("pbs:example:game:1:".length())); Path file = root.resolve(reference.id().substring("pbs:example:game:1:".length()));
@@ -49,9 +59,39 @@ public final class InstalledKnowledgeProbe {
check(actual.toString().equals(reference.text()), "Incorrect installed reference: " + reference.id()); check(actual.toString().equals(reference.text()), "Incorrect installed reference: " + reference.id());
} }
var result = BuilderPipelineService.INSTANCE.compile( var result = BuilderPipelineService.INSTANCE.compile(
BuilderPipelineContext.fromConfig(new BuilderPipelineConfig(false, root.toString())), LogAggregator.empty()); BuilderPipelineContext.fromConfig(new BuilderPipelineConfig(false, root.toString())), LogAggregator.stdout());
check(result.diagnostics().stream().noneMatch(issue -> issue.isError()), "Example must compile without errors"); check(result.diagnostics().stream().noneMatch(issue -> issue.isError()), "Example must compile without errors");
check(result.bytecodeBytes().length > 0, "Example must produce bytecode"); check(result.bytecodeBytes().length > 0, "Example must produce bytecode");
Path listRoot=Files.createDirectory(Path.of("list-example")).toRealPath();
Files.createDirectories(listRoot.resolve("src"));
Files.copy(root.resolve("prometeu.json"),listRoot.resolve("prometeu.json"));
Files.writeString(listRoot.resolve("src/mod.barrel"),"pub fn frame() -> void;");
Files.writeString(listRoot.resolve("src/main.pbs"),Files.readString(root.resolve("src/collections.pbs"))+"\n"+"""
[Frame] fn frame() -> void {
if collectionsExample()!=42 {let failure=1/0;}
}
""");
var listResult=BuilderPipelineService.INSTANCE.compile(
BuilderPipelineContext.fromConfig(new BuilderPipelineConfig(false,listRoot.toString())),LogAggregator.stdout());
check(listResult.diagnostics().stream().noneMatch(issue->issue.isError()),"Installed List/Cursor example must compile");
Path fixtures=Path.of(System.getProperty("pbs.registryConformanceDirectory"));
Files.createDirectories(fixtures);Files.write(fixtures.resolve("pbs-list-installed.pbx"),listResult.bytecodeBytes());
System.out.println("Installed List/Cursor execution fixture generated");
Path linkedRoot=Files.createDirectory(Path.of("linked-example")).toRealPath();
Files.createDirectories(linkedRoot.resolve("src"));
Files.copy(root.resolve("prometeu.json"),linkedRoot.resolve("prometeu.json"));
Files.writeString(linkedRoot.resolve("src/mod.barrel"),"pub fn frame() -> void;");
Files.writeString(linkedRoot.resolve("src/main.pbs"),Files.readString(root.resolve("src/linked.pbs"))+"\n"+"""
[Frame] fn frame() -> void {
if linkedExample()!=42 {let failure=1/0;}
}
""");
var linkedResult=BuilderPipelineService.INSTANCE.compile(
BuilderPipelineContext.fromConfig(new BuilderPipelineConfig(false,linkedRoot.toString())),LogAggregator.stdout());
check(linkedResult.diagnostics().stream().noneMatch(issue->issue.isError()),"Installed Linked example must compile");
Files.write(fixtures.resolve("pbs-linked-installed.pbx"),linkedResult.bytecodeBytes());
System.out.println("Installed Linked execution fixture generated");
verifyExternalSources(provider.getClass().getClassLoader());
registration.unsubscribe(); registration.unsubscribe();
System.out.println("Installed knowledge verified: " + docs.size() + " references; example compiled"); System.out.println("Installed knowledge verified: " + docs.size() + " references; example compiled");
} }
@@ -59,4 +99,88 @@ public final class InstalledKnowledgeProbe {
private static void check(boolean condition, String message) { private static void check(boolean condition, String message) {
if (!condition) throw new AssertionError(message); if (!condition) throw new AssertionError(message);
} }
private static void verifyRuntimeCatalogs(ClassLoader loader) throws Exception {
var names = java.util.List.of("INTRINSICS.csv", "BUILTIN_CONSTANTS.csv", "runtime-catalog.properties");
var compiler = new java.util.HashMap<String, byte[]>();
for (var name : names) {
for (var owner : java.util.List.of("compiler", "pbs-sdk")) {
var resource = loader.getResource("runtime-catalog/" + owner + "/" + name);
check(resource != null && resource.getProtocol().equals("jar"), "Missing installed catalog: " + owner + "/" + name);
try (var stream = resource.openStream()) {
var bytes = stream.readAllBytes();
if (owner.equals("compiler")) compiler.put(name, bytes);
else check(java.util.Arrays.equals(compiler.get(name), bytes), "Compiler/SDK contract mismatch: " + name);
}
}
}
var properties = new java.util.Properties();
properties.load(new java.io.ByteArrayInputStream(compiler.get("runtime-catalog.properties")));
check(properties.getProperty("runtime.revision").matches("[0-9a-f]{40}"), "Missing target revision");
for (var name : names.subList(0, 2)) {
var digest = java.util.HexFormat.of().formatHex(java.security.MessageDigest.getInstance("SHA-256").digest(compiler.get(name)));
check(digest.equals(properties.getProperty(name + ".sha256")), "Packaged catalog hash mismatch: " + name);
}
System.out.println("Installed compiler/SDK catalog identity verified: " + properties.getProperty("runtime.revision"));
}
private static void verifyExternalSources(ClassLoader loader) throws Exception {
var resource = loader.getResource("game/stdlib/1/sdk/gfx/main.pbs");
check(resource != null && resource.getProtocol().equals("jar"), "SDK must be read from a JAR URL");
check(p.studio.lsp.services.compiler.CompilerLanguageServiceBridge.class.getProtectionDomain()
.getCodeSource().getLocation().getPath().endsWith(".jar"), "LSP bridge must come from installed JAR");
Path root = Files.createDirectory(Path.of("external-sources")).toRealPath();
Files.createDirectories(root.resolve("src"));
Files.writeString(root.resolve("prometeu.json"), """
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
String source = "import { Gfx } from @sdk:gfx;\nfn main() -> void { Gfx.clear(0); }\n";
Path file = Files.writeString(root.resolve("src/main.pbs"), source);
Files.writeString(root.resolve("src/mod.barrel"), "pub fn main() -> void;\n");
var context = new p.studio.lsp.messages.LspProjectContext("installed", "pbs", root);
var bridge = new p.studio.lsp.services.compiler.CompilerLanguageServiceBridge();
try (var registry = new p.studio.lsp.services.compiler.ExternalSourceRegistry()) {
String consumer = registry.connect(null, false);
int[] sdkUse = position(source, "Gfx.clear", "Gfx.".length());
var targets = bridge.navigation(context, file.toUri().toString(), source, sdkUse[0], sdkUse[1], registry, consumer).locations();
check(targets.size() == 1, "Packaged SDK definition must resolve");
String uri = targets.getFirst().uri();
check(uri.startsWith("prometeu-source:"), "SDK must use a virtual URI");
var content = registry.read(consumer, uri);
check(content.descriptor().readOnly() && content.descriptor().origin().equals("bundled"), "Bundled SDK must be read-only");
try (var stream = resource.openStream()) {
check(content.text().equals(new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8)), "SDK text must exactly match JAR bytes");
}
int[] hostUse = position(content.text(), "LowGfx.clear", "LowGfx.".length());
check(bridge.externalHover(context, uri, hostUse[0], hostUse[1], registry, consumer).markdown().contains("clear"), "SDK hover must work");
var host = bridge.navigation(context, uri, null, hostUse[0], hostUse[1], registry, consumer).locations().getFirst();
check(registry.read(consumer, host.uri()).text().split("\n")[host.startLine()].contains("clear"), "SDK to host definition range must match");
check(!bridge.externalSemanticTokens(context, uri, registry, consumer).tokens().isEmpty(), "SDK semantic highlighting must work");
int[] colorUse = position(content.text(), "color: Color", 7);
var core = bridge.navigation(context, uri, null, colorUse[0], colorUse[1], registry, consumer).locations().getFirst();
var coreContent = registry.read(consumer, core.uri());
check(coreContent.descriptor().readOnly() && coreContent.descriptor().name().replace('\\', '/').contains("core/color"), "SDK to core definition must resolve");
var coreResource = loader.getResource("game/stdlib/1/core/color/main.pbs");
check(coreResource != null && coreResource.getProtocol().equals("jar"), "Core must be read from a JAR URL");
try (var stream = coreResource.openStream()) {
check(coreContent.text().equals(new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8)), "Core text must exactly match JAR bytes");
}
check(coreContent.text().split("\n")[core.startLine()].contains("Color"), "Core definition range must match");
registry.disconnect(consumer);
registry.connect(consumer, false);
check(registry.revalidate(consumer, uri, path -> bridge.currentSource(context, path)).text().equals(content.text()), "Bundled source must revalidate after reconnect");
}
try (var files = Files.walk(root)) {
check(files.filter(Files::isRegularFile).map(root::relativize).map(Path::toString).collect(java.util.stream.Collectors.toSet())
.equals(java.util.Set.of("prometeu.json", "src/main.pbs", "src/mod.barrel")), "Navigation must not extract bundled sources into the project");
}
System.out.println("Packaged external sources verified: JAR bytes, SDK/host/core navigation, hover, tokens, read-only, reconnect, no extraction");
}
private static int[] position(String text, String needle, int offset) {
int index = text.indexOf(needle);
check(index >= 0, "Missing source fragment: " + needle);
String prefix = text.substring(0, index + offset);
return new int[] {(int) prefix.chars().filter(c -> c == '\n').count(), prefix.length() - prefix.lastIndexOf('\n') - 1};
}
} }
@@ -12,6 +12,19 @@ class InstalledKnowledgeTest {
@TempDir Path outsideRepository; @TempDir Path outsideRepository;
@Test void installedJarsProvideAllReferencesAndCompileTheExampleOutsideTheCheckout() throws Exception { @Test void installedJarsProvideAllReferencesAndCompileTheExampleOutsideTheCheckout() throws Exception {
String log = runProbe();
assertTrue(log.contains("references; example compiled"), log);
assertTrue(log.contains("Packaged external sources verified"), log);
assertTrue(log.contains("Installed List/Cursor execution fixture generated"), log);
assertTrue(log.contains("Installed Linked execution fixture generated"), log);
}
@Test void installedCompilerAndSdkCarryTheSameVerifiedCatalog() throws Exception {
String log = runProbe("--catalog-only");
assertTrue(log.contains("Installed compiler/SDK catalog identity verified"), log);
}
private String runProbe(String... arguments) throws Exception {
Path distribution = Path.of(System.getProperty("studio.test.distribution")); Path distribution = Path.of(System.getProperty("studio.test.distribution"));
String jars; String jars;
try (var files = Files.list(distribution.resolve("lib"))) { try (var files = Files.list(distribution.resolve("lib"))) {
@@ -20,14 +33,17 @@ class InstalledKnowledgeTest {
} }
String probeClasses = Path.of(InstalledKnowledgeProbe.class.getProtectionDomain().getCodeSource().getLocation().toURI()).toString(); String probeClasses = Path.of(InstalledKnowledgeProbe.class.getProtectionDomain().getCodeSource().getLocation().toURI()).toString();
Path output = outsideRepository.resolve("probe.log"); Path output = outsideRepository.resolve("probe.log");
var process = new ProcessBuilder(Path.of(System.getProperty("java.home"), "bin", "java").toString(), var command = new java.util.ArrayList<>(java.util.List.of(distribution.resolve("runtime/bin/java").toString(),
"-cp", jars + java.io.File.pathSeparator + probeClasses, InstalledKnowledgeProbe.class.getName()) "-Dpbs.registryConformanceDirectory=" + System.getProperty("pbs.registryConformanceDirectory"),
"-cp", jars + java.io.File.pathSeparator + probeClasses, InstalledKnowledgeProbe.class.getName()));
command.addAll(java.util.List.of(arguments));
var process = new ProcessBuilder(command)
.directory(outsideRepository.toFile()).redirectErrorStream(true).redirectOutput(output.toFile()).start(); .directory(outsideRepository.toFile()).redirectErrorStream(true).redirectOutput(output.toFile()).start();
try { try {
assertTrue(process.waitFor(45, TimeUnit.SECONDS), "Installed knowledge probe timed out"); assertTrue(process.waitFor(45, TimeUnit.SECONDS), "Installed knowledge probe timed out");
String log = Files.readString(output); String log = Files.readString(output);
assertEquals(0, process.exitValue(), log); assertEquals(0, process.exitValue(), log);
assertTrue(log.contains("references; example compiled"), log); return log;
} finally { if (process.isAlive()) process.destroyForcibly().waitFor(); } } finally { if (process.isAlive()) process.destroyForcibly().waitFor(); }
} }
} }
@@ -54,6 +54,36 @@ class AutomationLspQueriesTest {
Map<String, Object> at(int line, int character) { Map<String, Object> at(int line, int character) {
return Map.of("uri", source.toUri().toString(), "position", Map.of("line", line, "character", character)); return Map.of("uri", source.toUri().toString(), "position", Map.of("line", line, "character", character));
} }
@Test void bundledSourcesAreReadableAcrossConnectionsAndOwnedByTheTask() throws Exception {
Files.writeString(source, "import { Gfx } from @sdk:gfx;\nfn main() -> void { Gfx.clear(0); }\n");
Files.writeString(source.resolveSibling("mod.barrel"), "pub fn main() -> void;\n");
acquire();
final var definition = query("definition", at(1, 24)).path("result");
assertFalse(definition.isEmpty(), definition.toString());
final String uri = definition.get(0).path("uri").asText();
assertTrue(uri.startsWith("prometeu-source:"), uri);
final var content = query("readExternalSource", Map.of("uri", uri)).path("result");
assertTrue(content.path("descriptor").path("readOnly").asBoolean());
assertEquals("bundled", content.path("descriptor").path("origin").asText());
final String text = content.path("text").asText();
final int offset = text.indexOf("LowGfx.clear") + "LowGfx.".length();
assertTrue(offset > "LowGfx.".length());
final String prefix = text.substring(0, offset);
final var position = Map.of("line", (int) prefix.chars().filter(c -> c == '\n').count(),
"character", offset - prefix.lastIndexOf('\n') - 1);
final var request = Map.<String, Object>of("uri", uri, "position", position);
assertTrue(query("hover", request).path("result").toString().contains("clear"));
final var host = query("definition", request).path("result");
assertFalse(host.isEmpty());
assertTrue(query("readExternalSource", Map.of("uri", host.get(0).path("uri").asText()))
.path("result").path("text").asText().contains("declare host LowGfx"));
assertEquals(AutomationFailure.Code.READ_ONLY_SCOPE, assertThrows(AutomationException.class,
() -> query("formatting", request)).failure().code());
session.automation().reclaim().toCompletableFuture().join();
acquire();
assertEquals(AutomationFailure.Code.OUTSIDE_PROJECT_SCOPE, assertThrows(AutomationException.class,
() -> query("readExternalSource", Map.of("uri", uri))).failure().code());
}
@Test void diagnosticsAndNavigationSeeSavedChangesOverTheActualServer() throws Exception { @Test void diagnosticsAndNavigationSeeSavedChangesOverTheActualServer() throws Exception {
acquire(); acquire();
assertTrue(query("diagnostics", at(0, 0)).path("result").isArray()); assertTrue(query("diagnostics", at(0, 0)).path("result").isArray());
@@ -186,26 +216,43 @@ class AutomationLspQueriesTest {
assertTrue(cleaned.get()); assertTrue(cleaned.get());
assertEquals(ControlState.MANUAL, session.automation().snapshot().state()); assertEquals(ControlState.MANUAL, session.automation().snapshot().state());
} }
@Test void externalDependencyNavigationIsReadableButRefactoringIsReadOnly() throws Exception { @org.junit.jupiter.params.ParameterizedTest
Path lib = Files.createDirectories(temporary.resolve("lib")).toRealPath(); @org.junit.jupiter.params.provider.ValueSource(booleans = {false, true})
void externalDependencyNavigationIsReadableButRefactoringIsReadOnly(boolean inWorkspace) throws Exception {
Path lib = Files.createDirectories(inWorkspace ? root.resolve(".workspace/repos/lib") : temporary.resolve("lib")).toRealPath();
manifest(lib, "lib", List.of()); manifest(lib, "lib", List.of());
Path module = Files.createDirectories(lib.resolve("src/shared")); Path module = Files.createDirectories(lib.resolve("src/shared"));
Path declaration = module.resolve("main.pbs"); Path declaration = module.resolve("main.pbs");
Files.writeString(declaration, "fn answer() -> int { return 42; }\n"); Files.writeString(declaration, "// á 😀\r\nfn answer() -> int { return helper(); }\r\nfn helper() -> int { return 42; }\r\n");
Files.writeString(module.resolve("mod.barrel"), "pub fn answer() -> int;\n"); Files.writeString(module.resolve("mod.barrel"), "pub fn answer() -> int;\n");
manifest(root, "app", List.of(Map.of("path", "../lib"))); manifest(root, "app", List.of(Map.of("path", inWorkspace ? ".workspace/repos/lib" : "../lib")));
Files.createDirectories(root.resolve(".workspace/repos")); Files.writeString(root.resolve(".workspace/repos/registry.json"), "{}"); Files.createDirectories(root.resolve(".workspace/repos")); Files.writeString(root.resolve(".workspace/repos/registry.json"), "{}");
Files.writeString(source, "import { answer } from @lib:shared;\nfn main() -> int { return answer(); }\n"); Files.writeString(source, "import { answer } from @lib:shared;\nfn main() -> int { return answer(); }\n");
Files.writeString(source.resolveSibling("mod.barrel"), "pub fn main() -> int;\n"); Files.writeString(source.resolveSibling("mod.barrel"), "pub fn main() -> int;\n");
acquire(); acquire();
var locations = query("definition", at(1, 26)).path("result"); var locations = query("definition", at(1, 26)).path("result");
assertFalse(locations.isEmpty(), locations.toString()); assertFalse(locations.isEmpty(), locations.toString());
assertEquals(declaration.toUri().toString(), locations.get(0).path("uri").asText()); assertTrue(locations.get(0).path("uri").asText().startsWith("prometeu-source:"));
assertEquals(Files.readString(declaration), query("readExternalSource", Map.of("uri", locations.get(0).path("uri").asText())).path("result").path("text").asText());
final String externalUri = locations.get(0).path("uri").asText();
assertEquals(1, locations.get(0).path("range").path("start").path("line").asInt());
final var nested = query("definition", Map.of("uri", externalUri, "position", Map.of("line", 1, "character", 28))).path("result");
assertFalse(nested.isEmpty(), nested.toString());
assertEquals(2, nested.get(0).path("range").path("start").path("line").asInt());
assertEquals("documentSymbols", query("documentSymbols", Map.of("uri", declaration.toUri().toString())).path("operation").asText()); assertEquals("documentSymbols", query("documentSymbols", Map.of("uri", declaration.toUri().toString())).path("operation").asText());
assertEquals(AutomationFailure.Code.READ_ONLY_SCOPE, assertThrows(AutomationException.class, assertEquals(AutomationFailure.Code.READ_ONLY_SCOPE, assertThrows(AutomationException.class,
() -> query("formatting", Map.of("uri", declaration.toUri().toString()))).failure().code()); () -> query("formatting", Map.of("uri", declaration.toUri().toString()))).failure().code());
final Path alias = Files.createSymbolicLink(root.resolve("src/dependency-alias.pbs"), declaration);
assertEquals(AutomationFailure.Code.READ_ONLY_SCOPE, assertThrows(AutomationException.class,
() -> query("formatting", Map.of("uri", alias.toUri().toString()))).failure().code());
var rename = new HashMap<>(at(1, 26)); rename.put("newName", "renamed"); var rename = new HashMap<>(at(1, 26)); rename.put("newName", "renamed");
assertEquals(AutomationFailure.Code.READ_ONLY_SCOPE, assertThrows(AutomationException.class, () -> query("rename", rename)).failure().code()); assertEquals(AutomationFailure.Code.READ_ONLY_SCOPE, assertThrows(AutomationException.class, () -> query("rename", rename)).failure().code());
final String oldText = Files.readString(declaration);
Files.writeString(declaration, "// changed revision\n" + oldText);
assertThrows(AutomationException.class, () -> query("readExternalSource", Map.of("uri", externalUri)));
final var renewed = query("definition", at(1, 26)).path("result");
assertNotEquals(externalUri, renewed.get(0).path("uri").asText());
assertEquals(2, renewed.get(0).path("range").path("start").path("line").asInt());
} }
private void manifest(Path path, String name, List<?> dependencies) throws Exception { private void manifest(Path path, String name, List<?> dependencies) throws Exception {
mapper.writeValue(path.resolve("prometeu.json").toFile(), Map.of("name", name, "version", "1.0.0", "language", "pbs", "stdlib", "1", "target", "Game", "dependencies", dependencies)); mapper.writeValue(path.resolve("prometeu.json").toFile(), Map.of("name", name, "version", "1.0.0", "language", "pbs", "stdlib", "1", "target", "Game", "dependencies", dependencies));
@@ -15,16 +15,42 @@ class McpContractTest {
assertEquals(17, catalog.names().size()); assertEquals(17, catalog.names().size());
for (var name : catalog.names()) { for (var name : catalog.names()) {
var definition = catalog.definition(name); var definition = catalog.definition(name);
catalog.validateArguments(name, definition.get("exampleArguments")); assertDoesNotThrow(() -> catalog.validateArguments(name, definition.get("exampleArguments")), name + " arguments");
var result = McpToolResult.success(mapper, (ObjectNode) definition.get("exampleValue")); var result = McpToolResult.success(mapper, (ObjectNode) definition.get("exampleValue"));
ContractSchema.validate(definition.get("outputSchema"), result.wire().get("structuredContent")); assertDoesNotThrow(() -> ContractSchema.validate(definition.get("outputSchema"), result.wire().get("structuredContent")), name + " success envelope");
var failure = McpToolResult.failure(mapper, new AutomationFailure(AutomationFailure.Code.INVALID_TASK, "Revoked")); var failure = McpToolResult.failure(mapper, new AutomationFailure(AutomationFailure.Code.INVALID_TASK, "Revoked"));
ContractSchema.validate(definition.get("outputSchema"), failure.wire().get("structuredContent")); assertDoesNotThrow(() -> ContractSchema.validate(definition.get("outputSchema"), failure.wire().get("structuredContent")), name + " failure envelope");
assertTrue(Set.of("authenticated", "granted", "task").contains(definition.get("authority").asText())); assertTrue(Set.of("authenticated", "granted", "task").contains(definition.get("authority").asText()));
assertEquals(definition.get("authority").asText().equals("task"), definition.get("inputSchema").get("properties").has("taskId")); assertEquals(definition.get("authority").asText().equals("task"), definition.get("inputSchema").get("properties").has("taskId"));
assertFalse(catalog.descriptor(name).has("exampleArguments")); assertFalse(catalog.descriptor(name).has("exampleArguments"));
} }
} }
@Test void failureSchemasPreserveRuntimeDetailsWithoutAllowingUnknownEnvelopeFields() {
var details = Map.<String, Object>of(
"code", "InvalidProgram",
"details", Map.of("reason", "LifecycleSignature", "offset", 123,
"context", List.of("boot", "verification")));
var failure = new AutomationFailure(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Rejected", details);
for (var name : catalog.names()) {
var wire = McpToolResult.failure(mapper, failure).wire();
ObjectNode envelope = (ObjectNode) wire.get("structuredContent");
var schema = catalog.definition(name).get("outputSchema");
assertDoesNotThrow(() -> ContractSchema.validate(schema, envelope), name + " runtime details");
assertEquals(mapper.valueToTree(details), envelope.path("error").path("runtimeError"), name);
assertEquals(envelope.toString(), wire.path("content").get(0).path("text").asText(), name);
assertTrue(wire.path("isError").asBoolean(), name);
ObjectNode error = (ObjectNode) envelope.get("error");
error.put("runtimeError", "invalid");
assertThrows(IllegalArgumentException.class, () -> ContractSchema.validate(schema, envelope), name);
error.set("runtimeError", mapper.createObjectNode());
error.put("unexpected", true);
assertThrows(IllegalArgumentException.class, () -> ContractSchema.validate(schema, envelope), name);
error.remove("unexpected");
envelope.put("unexpected", true);
assertThrows(IllegalArgumentException.class, () -> ContractSchema.validate(schema, envelope), name);
}
}
@Test void missingRootTaskUnexpectedFieldsAndWrongTypesAreRejected() { @Test void missingRootTaskUnexpectedFieldsAndWrongTypesAreRejected() {
for (var name : catalog.names()) { for (var name : catalog.names()) {
ObjectNode sample = catalog.definition(name).get("exampleArguments").deepCopy(); ObjectNode sample = catalog.definition(name).get("exampleArguments").deepCopy();
@@ -50,7 +50,15 @@ public final class HeadlessFixture {
var request = MAPPER.readTree(line); String id = request.path("requestId").asText(), command = request.path("command").asText(); var request = MAPPER.readTree(line); String id = request.path("requestId").asText(), command = request.path("command").asText();
switch (command) { switch (command) {
case "initialize" -> response(id, MAPPER.createObjectNode().setAll(Map.of("protocolVersion", hello.path("protocolVersion"), "capabilities", hello.path("capabilities")))); case "initialize" -> response(id, MAPPER.createObjectNode().setAll(Map.of("protocolVersion", hello.path("protocolVersion"), "capabilities", hello.path("capabilities"))));
case "boot", "reset" -> response(id, state()); case "boot", "reset" -> {
if (mode.startsWith("load-fault-")) {
var resource = "/runtime/fault-" + mode.substring("load-fault-".length()) + ".json";
var fault = MAPPER.readTree(HeadlessFixture.class.getResourceAsStream(resource));
var error = MAPPER.createObjectNode().put("code", "boot_failed").put("message", "Runtime rejected cartridge");
error.putObject("details").set("fault", fault);
emit(MAPPER.createObjectNode().put("type", "response").put("sessionId", "fixture").put("requestId", id).set("error", error));
} else response(id, state());
}
case "get_state" -> { if (!mode.equals("hang-call")) response(id, state()); } case "get_state" -> { if (!mode.equals("hang-call")) response(id, state()); }
case "get_fault" -> response(id, MAPPER.nullNode()); case "get_fault" -> response(id, MAPPER.nullNode());
case "advance" -> { case "advance" -> {
@@ -284,14 +284,14 @@ class HeadlessMcpDesktopTest {
assertTrue(value(call("studio_project_context", args())).path("languages").toString().contains("pbs")); assertTrue(value(call("studio_project_context", args())).path("languages").toString().contains("pbs"));
value(call("studio_reference_read", args().put("referenceId", "pbs:quickstart").put("limit", 100))); value(call("studio_reference_read", args().put("referenceId", "pbs:quickstart").put("limit", 100)));
var sdk = value(call("studio_reference_read", args().put("referenceId", "pbs:sdk:game:1:sdk/input/main.pbs").put("limit", 1000))); var sdk = value(call("studio_reference_read", args().put("referenceId", "pbs:sdk:game:1:sdk/input/main.pbs").put("limit", 1000)));
assertTrue(sdk.toString().contains("InputPad"), "Consult installed SDK source through the indexed read-only reference"); assertTrue(sdk.toString().contains("LowPad"), "Consult installed SDK source through the indexed read-only reference");
assertEquals(ControlState.WAITING_FOR_AGENT, project.automation().snapshot().state()); assertEquals(ControlState.WAITING_FOR_AGENT, project.automation().snapshot().state());
task = value(call("studio_control_acquire", args())).path("taskId").asText(); task = value(call("studio_control_acquire", args())).path("taskId").asText();
assertFalse(task.isBlank()); assertFalse(task.isBlank());
// Agent-native edit of the installed example; SDK remains unchanged. // Agent-native edit of the installed example; SDK remains unchanged.
String edited = Files.readString(source).replace("import { Gfx } from @sdk:gfx;", String edited = Files.readString(source).replace("import { Gfx } from @sdk:gfx;",
"import { Gfx } from @sdk:gfx;\nimport { Input } from @sdk:input;") "import { Gfx } from @sdk:gfx;\nimport { Pad, Button, Touch } from @sdk:input;")
.replace("x = x + 1;", "if (Input.pad().right().down()) { x = x + 3; } else { x = x + 1; }"); .replace("x = x + 1;", "if (Pad.down(Button.Right)) { x = x + 3; } else { x = x + 1; }");
Files.writeString(source, edited); Files.writeString(source, edited);
var query = args().put("operation", "diagnostics"); query.putObject("parameters").put("uri", source.toUri().toString()); var query = args().put("operation", "diagnostics"); query.putObject("parameters").put("uri", source.toUri().toString());
assertTrue(value(call("studio_language_query", query)).path("result").isEmpty()); assertTrue(value(call("studio_language_query", query)).path("result").isEmpty());
@@ -18,6 +18,20 @@ class HeadlessProcessSessionTest {
var session = new HeadlessProcessSession(process, new ObjectMapper(), HeadlessFixture.limits(mode), "build"); sessions.add(session); return session; var session = new HeadlessProcessSession(process, new ObjectMapper(), HeadlessFixture.limits(mode), "build"); sessions.add(session); return session;
} }
@AfterEach void cleanup() { sessions.forEach(session -> session.abort("test cleanup")); } @AfterEach void cleanup() { sessions.forEach(session -> session.abort("test cleanup")); }
@Test void productionLoadDiagnosticsSurviveBootFailureAndMcpSerialization() throws Exception {
var mapper = new ObjectMapper();
for (String fixture : List.of("resource", "invalid-role", "retired-opcode", "native", "native-abi", "unknown-native")) {
var session = start("load-fault-" + fixture);
var failure = assertThrows(AutomationException.class, () -> session.initializeAndBoot(root)).failure();
var fault = mapper.readTree(getClass().getResourceAsStream("/runtime/fault-" + fixture + ".json"));
var error = mapper.valueToTree(failure.runtimeError());
assertEquals(fault, error.path("details").path("fault"));
assertTrue(error.path("details").path("fault").path("pc").isNull());
var wire = p.studio.app.mcp.McpToolResult.failure(mapper, failure).wire();
assertEquals(fault, wire.path("structuredContent").path("error").path("runtimeError").path("details").path("fault"));
assertThrows(UnsupportedOperationException.class, () -> failure.runtimeError().put("code", "changed"));
}
}
@Test void fragmentedProtocolPreservesUnsignedFrameIdentityLayoutAndSeparateStderr() throws Exception { @Test void fragmentedProtocolPreservesUnsignedFrameIdentityLayoutAndSeparateStderr() throws Exception {
var session = start("normal"); session.initializeAndBoot(root); var session = start("normal"); session.initializeAndBoot(root);
var outcome = session.advance(3, ignored -> {}); var outcome = session.advance(3, ignored -> {});
@@ -0,0 +1,24 @@
{
"initError": {
"code": "registry_load_failed",
"load": {
"code": "LOAD_INVALID_REGISTRY",
"function": 0,
"id_domain": null,
"limit": null,
"member": null,
"offset": 136,
"pc": null,
"reason": "LifecycleRole",
"record": 0,
"referenced_id": null,
"requested": null,
"resource": null,
"section": 1
},
"message": "RegistryLoadFailed(LoadFailure { code: InvalidRegistry, reason: LifecycleRole, section: Some(1), offset: Some(136), record: Some(0), member: None, id_domain: None, referenced_id: None, function: Some(0), pc: None, resource: None, requested: None, limit: None })"
},
"kind": "vm_init",
"pc": null,
"summary": "Conformance fixture"
}
@@ -0,0 +1,19 @@
{
"initError": {
"binding": {
"declared_arg_slots": 1,
"declared_ret_slots": 1,
"expected_arg_slots": 0,
"expected_ret_slots": 1,
"module": "system",
"name": "has_cart",
"reason": "abi_mismatch",
"version": 1
},
"code": "loader_patch_failed",
"message": "LoaderPatchFailed(ResolveFailed(AbiMismatch { module: \"system\", name: \"has_cart\", version: 1, declared_arg_slots: 1, declared_ret_slots: 1, expected_arg_slots: 0, expected_ret_slots: 1 }))"
},
"kind": "vm_init",
"pc": null,
"summary": "Conformance fixture"
}
@@ -0,0 +1,17 @@
{
"initError": {
"binding": {
"module": "system",
"name": "has_cart",
"provided": 0,
"reason": "missing_capability",
"required": 1,
"version": 1
},
"code": "loader_patch_failed",
"message": "LoaderPatchFailed(ResolveFailed(MissingCapability { required: 1, provided: 0, module: \"system\", name: \"has_cart\", version: 1 }))"
},
"kind": "vm_init",
"pc": null,
"summary": "Conformance fixture"
}
@@ -0,0 +1,24 @@
{
"initError": {
"code": "registry_load_failed",
"load": {
"code": "LOAD_RESOURCE_LIMIT",
"function": null,
"id_domain": null,
"limit": 0,
"member": null,
"offset": null,
"pc": null,
"reason": "Limit",
"record": null,
"referenced_id": null,
"requested": 32,
"resource": "Work",
"section": null
},
"message": "RegistryLoadFailed(LoadFailure { code: ResourceLimit, reason: Limit, section: None, offset: None, record: None, member: None, id_domain: None, referenced_id: None, function: None, pc: None, resource: Some(Work), requested: Some(32), limit: Some(0) })"
},
"kind": "vm_init",
"pc": null,
"summary": "Conformance fixture"
}
@@ -0,0 +1,24 @@
{
"initError": {
"code": "registry_load_failed",
"load": {
"code": "LOAD_INVALID_CODE",
"function": 0,
"id_domain": null,
"limit": null,
"member": null,
"offset": null,
"pc": 0,
"reason": "Truncated",
"record": null,
"referenced_id": null,
"requested": null,
"resource": null,
"section": 2
},
"message": "RegistryLoadFailed(LoadFailure { code: InvalidCode, reason: Truncated, section: Some(2), offset: None, record: None, member: None, id_domain: None, referenced_id: None, function: Some(0), pc: Some(0), resource: None, requested: None, limit: None })"
},
"kind": "vm_init",
"pc": null,
"summary": "Conformance fixture"
}
@@ -0,0 +1,15 @@
{
"initError": {
"binding": {
"module": "system",
"name": "missing",
"reason": "unknown_syscall",
"version": 1
},
"code": "loader_patch_failed",
"message": "LoaderPatchFailed(ResolveFailed(UnknownSyscall { module: \"system\", name: \"missing\", version: 1 }))"
},
"kind": "vm_init",
"pc": null,
"summary": "Conformance fixture"
}
@@ -25,3 +25,9 @@ dependencies {
tasks.named<JacocoReport>("jacocoTestReport") { tasks.named<JacocoReport>("jacocoTestReport") {
enabled = false enabled = false
} }
// Keep PBS conformance fixtures beside the common pipeline fixtures for the runtime harness.
tasks.named<Test>("test") {
systemProperty("pbs.registryConformanceDirectory",
project(":prometeu-compiler:prometeu-build-pipeline").layout.buildDirectory.dir("registry-conformance").get().asFile.absolutePath)
}
@@ -0,0 +1,238 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.pbs.PbsFrontendCompiler;
import p.studio.compiler.source.diagnostics.DiagnosticSink;
import p.studio.compiler.source.identifiers.FileId;
import static org.junit.jupiter.api.Assertions.*;
class PbsClosuresTest {
@Test void namedAndAnonymousFunctionsShareSignature() throws Exception {
PbsStructuredValuesTest.compile("closure-functions", """
fn twice(x: int) -> int { return x * 2; }
fn invoke(x: int, f: Fn(int) -> int) -> int { return f(x); }
declare service Probe {
fn main() -> int {
let f: Fn(int) -> int = twice;
let g = fn [](x: int) -> int { return x + 2; };
return invoke(20, f) + g(0);
}
}
""");
}
@Test void capturesSnapshotAndEscape() throws Exception {
PbsStructuredValuesTest.compile("closure-snapshot", """
fn create(n: int) -> Fn(int) -> int {
let factor = n;
let f = fn [factor](x: int) -> int { return x * factor; };
factor = 100;
return f;
}
declare service Probe {
fn main() -> int { let f = create(3); return f(14); }
}
""");
}
@Test void closuresShareObjectsAndTravelThroughArrays() throws Exception {
PbsStructuredValuesTest.compile("closure-objects", """
declare struct Counter(pub mut value: int);
declare service Probe {
fn main() -> int {
let counter = new Counter(40);
let increment = fn [counter]() -> void { counter.value += 1; };
let read = fn [counter]() -> int { return counter.value; };
let reads: array<(Fn() -> int)> = [read];
increment(); increment();
if let f = reads[0] { return f(); }
return 999;
}
}
""");
}
@Test void nestedClosuresCaptureFunctions() throws Exception {
PbsStructuredValuesTest.compile("closure-nested", """
fn create(n: int) -> Fn() -> Fn(int) -> int {
let add = fn [n](x: int) -> int { return n + x; };
return fn [add]() -> Fn(int) -> int { return add; };
}
declare service Probe {
fn main() -> int { let factory = create(20); let f = factory(); return f(22); }
}
""");
}
@Test void capturedGroupsAndContractReceiverPreserveTheirLayouts() throws Exception {
PbsStructuredValuesTest.compile("closure-groups", """
declare contract Answer { fn get() -> int; }
declare struct Box(pub value: int) { fn get() -> int { return this.value; } }
implements Answer for Box using box { fn get() -> int { return box.get(); } }
declare service Probe {
fn main() -> int {
let pair: (left: int, right: int) = (20, 21);
let target: Answer = new Box(1);
let f = fn [pair, target]() -> (left: int, right: int) {
return (pair.left, pair.right + target.get());
};
let value = f();
return value.left + value.right;
}
}
""");
}
@Test void separateFactoriesKeepIndependentState() throws Exception {
PbsStructuredValuesTest.compile("closure-isolation", """
declare struct Counter(pub mut n: int);
fn create(start: int) -> Fn() -> int {
let state = new Counter(start);
return fn [state]() -> int { state.n += 1; return state.n; };
}
declare service Probe {
fn main() -> int {
let a = create(10);
let b = create(18);
let first = a();
let second = a();
return first + second + b();
}
}
""");
}
@Test void functionFieldsAndOverloadsUseExpectedSignature() throws Exception {
PbsStructuredValuesTest.compile("closure-fields", """
fn value(x: int) -> int { return x + 2; }
fn value(x: bool) -> int { return 999; }
declare struct Behavior(pub run: Fn(int) -> int);
declare service Probe {
fn main() -> int {
let behavior = new Behavior(value);
return behavior.run(40);
}
}
""");
}
@Test void importedFunctionValuesLinkToProvider() throws Exception {
var diagnostics = DiagnosticSink.empty();
var compiler = new PbsFrontendCompiler();
var names = new p.studio.compiler.source.tables.NameTable();
var host = p.studio.compiler.messages.HostAdmissionContext.permissiveDefault();
var surface = p.studio.compiler.messages.FESurfaceContext.empty();
var modules = p.studio.utilities.structures.ReadOnlyList.from(
new p.studio.compiler.source.tables.ModuleReference("test",p.studio.utilities.structures.ReadOnlyList.from("provider")),
new p.studio.compiler.source.tables.ModuleReference("test",p.studio.utilities.structures.ReadOnlyList.from("client")));
var providerId = new FileId(10);
var providerAst = p.studio.compiler.pbs.parser.PbsParser.parse(p.studio.compiler.pbs.lexer.PbsLexer.lex(
"fn twice(x: int) -> int { return x * 2; }",providerId,diagnostics),providerId,diagnostics);
var provider = compiler.compileParsedFile(providerId,providerAst,diagnostics,p.studio.compiler.models.SourceKind.PROJECT,
new p.studio.compiler.source.identifiers.ModuleId(0),modules,host,surface,names);
var function = providerAst.functions().getFirst();
var signature = provider.callableSignatures().getFirst();
var imported = new PbsFrontendCompiler.ImportedCallableSurface(new p.studio.compiler.source.identifiers.ModuleId(0),
signature.callableName(),signature.arity(),1,function.returnKind(),function.returnType(),signature.typeShape());
var clientId = new FileId(11);
var source = "declare service Probe { fn main() -> int { let f: Fn(int) -> int = twice; return f(21); } }";
var ast = p.studio.compiler.pbs.parser.PbsParser.parse(p.studio.compiler.pbs.lexer.PbsLexer.lex(source,clientId,diagnostics),clientId,diagnostics);
var client = compiler.compileParsedFile(clientId,ast,diagnostics,p.studio.compiler.models.SourceKind.PROJECT,
new p.studio.compiler.source.identifiers.ModuleId(1),modules,host,surface,names,providerAst.topDecls(),
p.studio.utilities.structures.ReadOnlyList.from(imported),p.studio.utilities.structures.ReadOnlyList.empty(),
p.studio.compiler.models.IRReservedMetadata.empty(),java.util.Map.of());
assertFalse(diagnostics.hasErrors(), () -> diagnostics.stream().map(d -> d.getCode()+":"+d.getMessage()).toList().toString());
var aggregator = p.studio.compiler.models.IRBackend.aggregator();
aggregator.merge(provider); aggregator.merge(client);
var backend = aggregator.entryPointCallableName("Probe.main").entryPointModuleId(new p.studio.compiler.source.identifiers.ModuleId(1)).emit();
var program = new LowerToIRVMService().lower(backend);
var output = new p.studio.compiler.backend.bytecode.BytecodeEmitter().emit(program.coherentEmissionPlan());
new p.studio.compiler.backend.bytecode.BytecodePreloadVerifierService().verify(output);
java.nio.file.Files.write(java.nio.file.Path.of(System.getProperty("pbs.registryConformanceDirectory"),"pbs-structured-closure-import.pbx"),output.serialize());
}
@Test void installedExampleProducesExecutableClosures() throws Exception {
try(var resource = PbsFrontendCompiler.class.getResourceAsStream("/pbs-knowledge/examples/game/1/src/closures.pbs")) {
assertNotNull(resource);
var source = new String(resource.readAllBytes(),java.nio.charset.StandardCharsets.UTF_8);
PbsStructuredValuesTest.compile("closure-installed", source + "\ndeclare service Probe { fn main() -> int { return closureExample(); } }");
}
}
@Test void closuresSurviveExistingFrameLifecycleAndAreCollectible() throws Exception {
var source = """
declare struct Counter(pub mut value: int);
declare global callbacks: array<(Fn() -> int)> = new array(1);
declare global frames: int = 0;
[Frame]
fn frame() -> void {
if frames == 0 {
let counter = new Counter(40);
callbacks[0] = fn [counter]() -> int {
counter.value += 1;
return counter.value;
};
} else {
if let action = callbacks[0] {
let first = action();
let second = action();
if first != 41 { callbacks[-1] = action; }
if second != 42 { callbacks[-1] = action; }
callbacks.clear(0);
}
}
for i: int from 0 until 1200 {
let discarded = fn [i]() -> int { return i; };
}
frames += 1;
}
""";
var diagnostics = DiagnosticSink.empty();
var id = new FileId(0);
var moduleId = new p.studio.compiler.source.identifiers.ModuleId(0);
var ast = p.studio.compiler.pbs.parser.PbsParser.parse(p.studio.compiler.pbs.lexer.PbsLexer.lex(source,id,diagnostics),id,diagnostics);
var modules = p.studio.utilities.structures.ReadOnlyList.from(new p.studio.compiler.source.tables.ModuleReference("test",
p.studio.utilities.structures.ReadOnlyList.from("main")));
var file = new PbsFrontendCompiler().compileParsedFile(id,ast,diagnostics,p.studio.compiler.models.SourceKind.PROJECT,
moduleId,modules,p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),
p.studio.compiler.messages.FESurfaceContext.empty(),new p.studio.compiler.source.tables.NameTable());
assertFalse(diagnostics.hasErrors(), () -> diagnostics.stream().map(d -> d.getCode()+":"+d.getMessage()).toList().toString());
var aggregator = p.studio.compiler.models.IRBackend.aggregator();
aggregator.merge(file);
var backend = aggregator.lifecycleModuleOrder(p.studio.utilities.structures.ReadOnlyList.from(moduleId)).emit();
var issues = p.studio.compiler.messages.BuildingIssueSink.empty();
var assembled = new p.studio.compiler.lifecycle.LifecycleAssemblerService().assemble(backend,issues);
assertFalse(issues.hasErrors(), issues.asCollection().toString());
var program = new LowerToIRVMService().lower(assembled);
var output = new p.studio.compiler.backend.bytecode.BytecodeEmitter().emit(program.coherentEmissionPlan());
new p.studio.compiler.backend.bytecode.BytecodePreloadVerifierService().verify(output);
java.nio.file.Files.write(java.nio.file.Path.of(System.getProperty("pbs.registryConformanceDirectory"),"closure-frame-lifecycle.pbx"),output.serialize());
}
@Test void retiredCallbackDeclarationsAndExportsReject() {
var source = "declare callback Tick(x: int) -> int; fn probe() -> void {}";
var diagnostics = DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0),source,diagnostics);
assertTrue(diagnostics.hasErrors());
var barrelDiagnostics = DiagnosticSink.empty();
var id = new FileId(0);
p.studio.compiler.pbs.parser.PbsBarrelParser.parse(
p.studio.compiler.pbs.lexer.PbsLexer.lex("pub callback Tick;",id,barrelDiagnostics),id,barrelDiagnostics);
assertTrue(barrelDiagnostics.hasErrors());
}
@Test void invalidCapturesAndSignaturesReject() {
for (var body : new String[] {
"declare callback Old() -> void;",
"let x = bind(ctx, handler);",
"let n = 1; let f = fn []() -> int { return n; };",
"let n = 1; let f = fn [n]() -> void { n = 2; };",
"let f = fn [missing]() -> int { return missing; };",
"let n = 1; let f = fn [n,n]() -> int { return n; };",
"let f: Fn(int) -> bool = fn [](x: int) -> int { return x; };",
"let f = fn (x: int) -> int { return x; };",
"let f = fn [](x: int) { return x; };",
"let f = fn [](x) -> int { return x; };",
"let f = fn [](x: int) -> int { x };",
"let f = fn [](x: int) -> int { return x; }; let x = f(true);"
}) {
var diagnostics = DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0), "fn probe() { " + body + " }", diagnostics);
assertTrue(diagnostics.hasErrors(), body);
}
}
}
@@ -0,0 +1,234 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.backend.bytecode.*;
import p.studio.compiler.models.*;
import p.studio.compiler.pbs.*;
import p.studio.compiler.pbs.ast.PbsAst;
import p.studio.compiler.pbs.lexer.PbsLexer;
import p.studio.compiler.pbs.parser.PbsParser;
import p.studio.compiler.source.diagnostics.DiagnosticSink;
import p.studio.compiler.source.identifiers.*;
import p.studio.utilities.structures.ReadOnlyList;
import java.nio.file.*;
import static org.junit.jupiter.api.Assertions.*;
class PbsGenericContractsTest {
private static final String ECHO = "declare contract Echo<T> { fn echo(value: T) -> T; } declare service Strategy {}\n";
static BytecodeModule compile(String name, String source) throws Exception {
var diagnostics = DiagnosticSink.empty();
var id = new FileId(0);
var ast = PbsParser.parse(PbsLexer.lex(source, id, diagnostics), id, diagnostics, PbsParser.ParseMode.ORDINARY);
var supplemental = ReadOnlyList.<PbsAst.TopDecl>empty();
var reserved = IRReservedMetadata.empty();
if (name.equals("native")) {
var nativeId = new FileId(100);
var nativeSource = "[BuiltinType(name = \"vec2\", version = 1)] declare builtin type Vector(pub x: float, pub y: float) {}";
var nativeAst = PbsParser.parse(PbsLexer.lex(nativeSource, nativeId, diagnostics), nativeId, diagnostics, PbsParser.ParseMode.INTERFACE_MODULE);
supplemental = nativeAst.topDecls();
reserved = new PbsReservedMetadataExtractor().extract(nativeAst, SourceKind.SDK_INTERFACE);
}
var file = new PbsFrontendCompiler().compileParsedFile(id, ast, diagnostics, SourceKind.PROJECT, new ModuleId(0),
ReadOnlyList.empty(), p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),
p.studio.compiler.messages.FESurfaceContext.empty(), new p.studio.compiler.source.tables.NameTable(),
supplemental, ReadOnlyList.empty(), ReadOnlyList.empty(), reserved, java.util.Map.of());
assertFalse(diagnostics.hasErrors(), () -> name + ": " + diagnostics.stream().map(d -> d.getCode()+":"+d.getMessage()).toList().toString());
var backend = IRBackend.builder().entryPointCallableName("Probe.main").entryPointModuleId(new ModuleId(0))
.executableFunctions(file.executableFunctions()).globals(file.globals()).registry(file.registry())
.intrinsicPool(file.intrinsicPool()).callableSignatures(file.callableSignatures()).build();
var program = new LowerToIRVMService().lower(backend);
var module = new BytecodeEmitter().emit(program.coherentEmissionPlan());
if (name.equals("gc")) module = PbsStructuredValuesTest.withTestSafepoint(module);
var directory = Path.of(System.getProperty("pbs.registryConformanceDirectory"));
Files.createDirectories(directory);
Files.writeString(directory.resolve("pbs-generic-contract-"+name+".ir.txt"), file.executableFunctions().stream()
.map(f -> f.callableName()+" "+f.metadata()+"\n"+f.instructions().stream().map(Object::toString).collect(java.util.stream.Collectors.joining("\n")))
.collect(java.util.stream.Collectors.joining("\n\n")));
new BytecodePreloadVerifierService().verify(module);
Files.write(directory.resolve("pbs-generic-contract-"+name+".pbx"), module.serialize());
return module;
}
@Test void concreteAndGenericContractsHaveTheSameBehavior() throws Exception {
for (var generic : new boolean[]{true, false}) {
var declaration = generic ? "declare contract Identity<T> { fn hash(e: T) -> int; fn equals(a: T, b: T) -> bool; }" :
"declare contract IntContract { fn hash(e: int) -> int; fn equals(a: int, b: int) -> bool; }";
var application = generic ? "Identity<int>" : "IntContract";
compile(generic ? "identity" : "manual", declaration + "declare service Strategy {} implements " + application + " for Strategy using s {" +
"fn hash(e: int) -> int { return e; } fn equals(a: int, b: int) -> bool { return a == b; } } " +
"declare service Probe { fn main() -> int { let identity: " + application + " = Strategy; if identity.equals(7, 7) { return identity.hash(42); } return 0; } }");
}
}
@Test void oneOwnerDispatchesIndependentApplicationsAndExplicitViews() throws Exception {
compile("multiple", ECHO + """
implements Echo<int> for Strategy using s { fn echo(value: int) -> int { return value; } }
implements Echo<bool> for Strategy using s { fn echo(value: bool) -> bool { return value; } }
declare service Probe { fn main() -> int {
let ints: Echo<int> = Strategy;
let flags = ints as Echo<bool>;
if flags.echo(true) { return ints.echo(42); }
return 0;
} }
""");
}
@Test void composedArgumentsPreserveCompleteGroups() throws Exception {
compile("tuple", """
declare contract Convert<A, B> { fn convert(value: A) -> B; }
declare service Strategy {}
implements Convert<array<int>, (left: int, right: int)> for Strategy using s {
fn convert(value: array<int>) -> (left: int, right: int) { return (left: value[0] else 0, right: 2); }
}
declare service Probe { fn main() -> int {
let c: Convert<array<int>, (left: int, right: int)> = Strategy;
let pair = c.convert([40]); return pair.left + pair.right;
} }
""");
compile("optional", ECHO + """
implements Echo<optional int> for Strategy using s { fn echo(value: optional int) -> optional int { return value; } }
declare service Probe { fn main() -> int {
let c: Echo<optional int> = Strategy;
if let wrong = c.echo(none) { return 0; }
return c.echo(some(42)) else 0;
} }
""");
compile("function", ECHO + """
implements Echo<Fn(int) -> int> for Strategy using s { fn echo(value: Fn(int) -> int) -> Fn(int) -> int { return value; } }
fn add(value: int) -> int { return value + 2; }
declare service Probe { fn main() -> int {
let c: Echo<Fn(int) -> int> = Strategy;
let f = c.echo(add); return f(40);
} }
""");
compile("contract", ECHO + """
declare contract Read<T> { fn read() -> T; }
implements Read<int> for Strategy using s { fn read() -> int { return 42; } }
implements Echo<Read<int>> for Strategy using s { fn echo(value: Read<int>) -> Read<int> { return value; } }
declare service Probe { fn main() -> int {
let reader: Read<int> = Strategy;
let c: Echo<Read<int>> = Strategy;
return c.echo(reader).read();
} }
""");
compile("native", ECHO + """
implements Echo<Vector> for Strategy using s { fn echo(value: Vector) -> Vector { return value; } }
declare service Probe { fn main() -> int {
let c: Echo<Vector> = Strategy;
let value = c.echo(new Vector(20.0, 22.0));
return (value.x + value.y) as int;
} }
""");
}
@Test void finiteRecursionPhantomArgumentsAndReceiverIdentityExecute() throws Exception {
compile("recursive", """
declare contract Node<T> { fn next() -> Node<T>; fn value() -> T; }
declare service Strategy {}
implements Node<int> for Strategy using s {
fn next() -> Node<int> { return Strategy; }
fn value() -> int { return 42; }
}
declare service Probe { fn main() -> int { let node: Node<int> = Strategy; return node.next().value(); } }
""");
compile("phantom", """
declare contract Marker<T> { fn answer() -> int; }
declare service Strategy {}
implements Marker<array<int>> for Strategy using s { fn answer() -> int { return 42; } }
implements Marker<array<bool>> for Strategy using s { fn answer() -> int { return 42; } }
declare service Probe { fn main() -> int {
let first: Marker<array<int>> = Strategy;
let second: Marker<array<bool>> = Strategy;
return first.answer() + second.answer() - 42;
} }
""");
compile("receiver", """
declare contract Read<T> { fn read() -> T; }
declare struct Counter(pub mut value: int) { fn increment() { this.value += 1; } }
implements Read<int> for Counter using counter { fn read() -> int { return counter.value; } }
declare service Probe { fn main() -> int {
let counter = new Counter(41);
let reader: Read<int> = counter;
counter.increment(); return reader.read();
} }
""");
}
@Test void contractCaptureSurvivesARealGcSafepoint() throws Exception {
compile("gc", """
declare contract Read<T> { fn read() -> T; }
declare struct Counter(pub value: int);
implements Read<int> for Counter using counter { fn read() -> int { return counter.value; } }
fn capture() -> Fn() -> int {
let reader: Read<int> = new Counter(42);
return fn [reader]() -> int { return reader.read(); };
}
declare service Probe {
fn garbage() { let discarded: array<int> = new array(1); }
fn collect() { let marker = 314159; }
fn main() -> int {
let read = capture();
for i: int from 0 until 1100 { Probe.garbage(); }
Probe.collect(); return read();
}
}
""");
}
@Test void installedContractExampleExecutes() throws Exception {
try (var stream = PbsFrontendCompiler.class.getResourceAsStream("/pbs-knowledge/examples/game/1/src/contracts.pbs")) {
assertNotNull(stream);
compile("installed", new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8)
+ "\ndeclare service Probe { fn main() -> int { return contractExample(); } }");
}
}
@Test void moduleOriginsAliasesAndExportedStrategiesExecute(@org.junit.jupiter.api.io.TempDir Path root) throws Exception {
Files.createDirectories(root.resolve("src/policy"));
Files.createDirectories(root.resolve("src/facade"));
Files.createDirectories(root.resolve("src/left"));
Files.createDirectories(root.resolve("src/right"));
Files.writeString(root.resolve("prometeu.json"), """
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
Files.writeString(root.resolve("src/mod.barrel"), "pub fn frame() -> void;");
for (var name : new String[]{"left", "right"}) {
Files.writeString(root.resolve("src/"+name+"/mod.barrel"), "pub struct Enemy;");
Files.writeString(root.resolve("src/"+name+"/main.pbs"), "declare struct Enemy(pub hp: int);");
}
Files.writeString(root.resolve("src/policy/mod.barrel"), "pub contract Identity<T>; pub contract Marker<T>; pub service Strategy;");
Files.writeString(root.resolve("src/facade/mod.barrel"), "pub contract Identity<T>; pub contract Marker<T>;");
Files.writeString(root.resolve("src/facade/main.pbs"), "import { Identity, Marker } from @app:policy;");
Files.writeString(root.resolve("src/policy/main.pbs"), """
import { Enemy as A } from @app:left;
import { Enemy as B } from @app:right;
declare contract Identity<T> { fn hash(value: T) -> int; }
declare contract Marker<T> { fn tag() -> int; }
declare service Strategy {}
implements Identity<int> for Strategy using s { fn hash(value: int) -> int { return value; } }
implements Marker<A> for Strategy using s { fn tag() -> int { return 20; } }
implements Marker<B> for Strategy using s { fn tag() -> int { return 22; } }
""");
Files.writeString(root.resolve("src/main.pbs"), """
import { Identity as Policy, Marker as Tag } from @app:facade;
import { Strategy as Selected } from @app:policy;
import { Enemy as Left } from @app:left;
import { Enemy as Right } from @app:right;
[Frame]
fn frame() -> void {
let identity: Policy<int> = Selected;
let left: Tag<Left> = Selected;
let right: Tag<Right> = Selected;
if identity.hash(42) != 42 { let fail = 1 / 0; }
if left.tag() + right.tag() != 42 { let fail = 1 / 0; }
}
""");
var result = p.studio.compiler.workspaces.BuilderPipelineService.INSTANCE.compile(
p.studio.compiler.models.BuilderPipelineContext.fromConfig(new p.studio.compiler.messages.BuilderPipelineConfig(false, root.toString())),
p.studio.utilities.logs.LogAggregator.stdout());
assertFalse(result.diagnostics().stream().anyMatch(d -> d.isError()), result.diagnostics().toString());
assertTrue(result.bytecodeBytes().length > 0);
Files.write(Path.of(System.getProperty("pbs.registryConformanceDirectory"), "pbs-generic-contract-imports.pbx"), result.bytecodeBytes());
}
}
@@ -0,0 +1,211 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.backend.bytecode.*;
import p.studio.compiler.models.*;
import p.studio.compiler.pbs.*;
import p.studio.compiler.pbs.lexer.PbsLexer;
import p.studio.compiler.pbs.parser.PbsParser;
import p.studio.compiler.source.diagnostics.DiagnosticSink;
import p.studio.compiler.source.identifiers.*;
import p.studio.utilities.structures.ReadOnlyList;
import java.nio.file.*;
import static org.junit.jupiter.api.Assertions.*;
class PbsGenericStructsTest {
private static final String BOX = """
declare struct Box<T>(value: T) {
fn get() -> T { return this.value; }
fn set(value: T) { this.value = value; }
}
""";
private static Path directory() { return Path.of(System.getProperty("pbs.registryConformanceDirectory")); }
private static BytecodeModule compile(String name, String source) throws Exception {
var diagnostics = DiagnosticSink.empty(); var id = new FileId(0);
var ast = PbsParser.parse(PbsLexer.lex(source, id, diagnostics), id, diagnostics, PbsParser.ParseMode.ORDINARY);
var file = new PbsFrontendCompiler().compileParsedFile(id, ast, diagnostics, SourceKind.PROJECT, new ModuleId(0),
ReadOnlyList.empty(), p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),
p.studio.compiler.messages.FESurfaceContext.empty(), new p.studio.compiler.source.tables.NameTable());
assertFalse(diagnostics.hasErrors(), () -> name+": "+diagnostics.stream().map(d -> d.getCode()+":"+d.getMessage()).toList());
var backend = IRBackend.builder().entryPointCallableName("Probe.main").entryPointModuleId(new ModuleId(0))
.executableFunctions(file.executableFunctions()).globals(file.globals()).registry(file.registry())
.intrinsicPool(file.intrinsicPool()).callableSignatures(file.callableSignatures()).build();
var program = new LowerToIRVMService().lower(backend);
var module = new BytecodeEmitter().emit(program.coherentEmissionPlan());
if (name.equals("gc")) module = PbsStructuredValuesTest.withTestSafepoint(module);
new BytecodePreloadVerifierService().verify(module);
Files.createDirectories(directory());
Files.write(directory().resolve("pbs-generic-struct-"+name+".pbx"), module.serialize());
return module;
}
@Test void genericAndHandwrittenObjectsPreserveReferenceIdentity() throws Exception {
compile("basic", BOX+"""
declare service Probe { fn main() -> int {
let box = new Box<int>(40); let alias = box;
alias.set(42); return box.get();
} }
""");
compile("manual", """
declare struct IntBox(value: int) {
fn get() -> int { return this.value; }
fn set(value: int) { this.value = value; }
}
declare service Probe { fn main() -> int {
let box = new IntBox(40); let alias = box;
alias.set(42); return box.get();
} }
""");
}
@Test void constructorsSelfAndPhantomApplicationsAreConcrete() throws Exception {
compile("constructor", """
declare struct Box<T>(value: T) {
ctor make(value: T) { this.value = value; }
fn same() -> Self { return this; }
fn get() -> T { return this.value; }
}
declare service Probe { fn main() -> int {
let box = new Box<int>.make(42); return box.same().get();
} }
""");
compile("phantom", """
declare struct Marker<T>() { fn answer() -> int { return 21; } }
declare service Probe { fn main() -> int {
let a = new Marker<int>(); let b = new Marker<long>(); return a.answer() + b.answer();
} }
""");
}
@Test void composedStorageAndCompleteGroupsExecute() throws Exception {
compile("multiple", """
declare struct Pair<K, V>(key: K, value: V) {
fn first() -> K { return this.key; }
fn second() -> V { return this.value; }
}
declare service Probe { fn main() -> int {
let pair = new Pair<int, int>(20, 22); return pair.first() + pair.second();
} }
""");
compile("tuple", BOX+"""
declare service Probe { fn main() -> int {
let box = new Box<(left: int, right: int)>((left: 20, right: 22));
let pair = box.get(); return pair.left + pair.right;
} }
""");
compile("optional", BOX+"""
declare service Probe { fn main() -> int {
let box = new Box<optional int>(none); box.set(some(42)); return box.get() else 0;
} }
""");
compile("array", BOX+"""
declare service Probe { fn main() -> int {
let box = new Box<array<int>>([42]); return box.get()[0] else 0;
} }
""");
compile("recursive", """
declare struct Node<T>(value: T, next: optional Node<T>) { fn get() -> T { return this.value; } }
declare service Probe { fn main() -> int { let node = new Node<int>(42, none); return node.get(); } }
""");
}
@Test void freeFunctionsFnAndOwnerBoundDispatchInteract() throws Exception {
compile("combined", BOX+"""
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(); }
declare service Probe { fn main() -> int {
let box = new Box<int>(42); let reader: Reader<int> = box;
let invoke: Fn(Reader<int>) -> int = read<int>; return invoke(reader);
} }
""");
compile("function", """
fn identity<T>(value: T) -> T { return value; }
declare service Probe { fn main() -> int { let f: Fn(int) -> int = identity<int>; return f(42); } }
""");
compile("function-manual", """
fn identity(value: int) -> int { return value; }
declare service Probe { fn main() -> int { let f: Fn(int) -> int = identity; return f(42); } }
""");
}
@Test void specializedCapturesRemainRootedAcrossCollection() throws Exception {
compile("gc", BOX+"""
fn capture<T>(value: T) -> Fn() -> T {
let box = new Box<T>(value); return fn [box]() -> T { return box.get(); };
}
declare service Probe {
fn garbage() { let discarded: array<int> = new array(1); }
fn collect() { let marker = 314159; }
fn main() -> int {
let read = capture<int>(42);
for i: int from 0 until 1100 { Probe.garbage(); }
Probe.collect(); return read();
}
}
""");
}
@Test void installedGenericExampleUsesTheSameProductionPipeline() throws Exception {
try (var stream = PbsFrontendCompiler.class.getResourceAsStream("/pbs-knowledge/examples/game/1/src/generics.pbs")) {
assertNotNull(stream);
compile("installed", new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8)
+ "\ndeclare service Probe { fn main() -> int { return genericsExample(); } }");
}
}
@Test void importsAliasesReexportsAndDefinitionScopedHelpersExecute(@org.junit.jupiter.api.io.TempDir Path root) throws Exception {
Files.createDirectories(root.resolve("src/policy")); Files.createDirectories(root.resolve("src/facade"));
Files.writeString(root.resolve("prometeu.json"), """
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
Files.writeString(root.resolve("src/mod.barrel"), "pub fn frame() -> void;");
var exports = "pub struct Box<T>; pub contract Reader<T>; pub fn read<T>(reader: Reader<T>) -> T; pub fn wrap<U>(value: U) -> Box<U>;";
Files.writeString(root.resolve("src/policy/mod.barrel"), exports);
Files.writeString(root.resolve("src/facade/mod.barrel"), exports);
Files.writeString(root.resolve("src/facade/main.pbs"), "import { Box, Reader, read, wrap } from @app:policy;");
Files.writeString(root.resolve("src/policy/main.pbs"), BOX+"""
declare contract Reader<T> { fn read() -> T; }
implements<T> Reader<T> for Box<T> using box { fn read() -> T { return box.get(); } }
fn helper<T>(value: T) -> T { return value; }
fn wrap<U>(value: U) -> Box<U> { return new Box<U>(helper<U>(value)); }
fn read<T>(reader: Reader<T>) -> T { return reader.read(); }
""");
Files.writeString(root.resolve("src/main.pbs"), """
import { Box as B, Reader as R, read as invoke, wrap as make } from @app:facade;
fn helper(value: int) -> int { return 0; }
[Frame] fn frame() -> void {
let box: B<int> = make<int>(42); let reader: R<int> = box;
let f: Fn(R<int>) -> int = invoke<int>;
if f(reader) != 42 { let fail = 1 / 0; }
}
""");
var result = p.studio.compiler.workspaces.BuilderPipelineService.INSTANCE.compile(
p.studio.compiler.models.BuilderPipelineContext.fromConfig(new p.studio.compiler.messages.BuilderPipelineConfig(false, root.toString())),
p.studio.utilities.logs.LogAggregator.stdout());
assertFalse(result.diagnostics().stream().anyMatch(d -> d.isError()), result.diagnostics().toString());
assertTrue(result.bytecodeBytes().length > 0);
Files.createDirectories(directory()); Files.write(directory().resolve("pbs-generic-struct-imports.pbx"), result.bytecodeBytes());
}
@Test void homonymousArgumentsFromDifferentModulesRemainNominallyDistinct(@org.junit.jupiter.api.io.TempDir Path root) throws Exception {
for (var module : new String[]{"policy", "left", "right"}) Files.createDirectories(root.resolve("src/"+module));
Files.writeString(root.resolve("prometeu.json"), """
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
Files.writeString(root.resolve("src/mod.barrel"), "pub fn frame() -> void;");
Files.writeString(root.resolve("src/policy/mod.barrel"), "pub struct Box<T>;");
Files.writeString(root.resolve("src/policy/main.pbs"), BOX);
for (var module : new String[]{"left", "right"}) {
Files.writeString(root.resolve("src/"+module+"/mod.barrel"), "pub struct Enemy;");
Files.writeString(root.resolve("src/"+module+"/main.pbs"), "declare struct Enemy(pub hp: int);");
}
Files.writeString(root.resolve("src/main.pbs"), """
import { Box } from @app:policy;
import { Enemy as Left } from @app:left;
import { Enemy as Right } from @app:right;
[Frame] fn frame() -> void {
let a = new Box<Left>(new Left(20));
let b = new Box<Right>(new Right(22));
if a.get().hp + b.get().hp != 42 { let fail = 1 / 0; }
}
""");
var result = p.studio.compiler.workspaces.BuilderPipelineService.INSTANCE.compile(
p.studio.compiler.models.BuilderPipelineContext.fromConfig(new p.studio.compiler.messages.BuilderPipelineConfig(false, root.toString())),
p.studio.utilities.logs.LogAggregator.stdout());
assertFalse(result.diagnostics().stream().anyMatch(d -> d.isError()), result.diagnostics().toString());
Files.createDirectories(directory()); Files.write(directory().resolve("pbs-generic-struct-origins.pbx"), result.bytecodeBytes());
}
}
@@ -0,0 +1,274 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.*;
import java.nio.charset.StandardCharsets;
import static org.junit.jupiter.api.Assertions.*;
class PbsLinkedTest {
static void compile(String name, String source) throws Exception {
PbsListCursorTest.compileCollection("linked", name, source);
}
static void probe(String name, String body) throws Exception {
compile(name,"declare service Probe {fn main()->int {"+body+"}}");
}
@Test void allOperationsPreserveBothDirectionsAndLogicalSize() throws Exception {
probe("basic","""
let values:linked<int>=new linked();let alias=values;
if values.first().hasSome() or values.last().hasSome() {return 0;}
if values.removeFirst().hasSome() or values.removeLast().hasSome() {return 0;}
values.clear();values.add(20);values.addFirst(1);values.insert(1,2);
values.insert(3,22);values[1]=42;
if (alias.size() as int)!=4 {return 0;}
if (values.first() else 0)!=1 or (values.last() else 0)!=22 {return 0;}
if (values.removeAt(1) else 0)!=42 {return 0;}
if (values.removeFirst() else 0)!=1 {return 0;}
if (values.removeLast() else 0)!=22 {return 0;}
if (values.first() else 0)!=20 or (values.last() else 0)!=20 {return 0;}
if (values.removeLast() else 0)!=20 {return 0;}
if (values.size() as int)!=0 or values.first().hasSome() {return 0;}
values.addFirst(42);if (values.removeFirst() else 0)!=42 {return 0;}
values.add(7);values.clear();values.add(42);return alias[0] else 0;
""");
probe("links","""
let values=new linked<int>();
for i:int from 0 until 16 {values.add(i);}
values.insert(8,90);values.insert(0,91);values.insert(18,92);
values.removeAt(9);values.removeFirst();values.removeLast();
let forward=values.cursor();let backward=values.reverseCursor();
for i:int from 0 until 16 {
if (values[i] else -1)!=i {return 0;}
if (forward.current() else -1)!=i {return 0;}
if (backward.current() else -1)!=(15-i) {return 0;}
forward.next();backward.next();
}
if forward.hasNext() or backward.hasNext() {return 0;}
if (values.size() as int)!=16 {return 0;}return 42;
""");
probe("construction","""
let values:linked<int>=new linked();
let diamond:linked<int>=new linked<>();
let maybe:optional (linked<int>)=some(new linked());
if let owner=maybe {if (owner.size() as int)!=0 {return 0;}} else {return 0;}
let index:int=0;values.insert(index,42);let at:long=0;return values[at] else 0;
""");
probe("long-size","""
let maximum:long=9223372036854775807;
if _linkedNextSize(maximum-1)!=maximum {return 0;}
let beyondArray:long=4294967296;
if _linkedNextSize(beyondArray-1)!=beyondArray {return 0;}
return 42;
""");
}
@Test void snapshotsHaveTheSharedStatesAndStayIndependentInBothOrders() throws Exception {
for (var method:new String[]{"cursor","reverseCursor"}) {
probe("empty-"+method,"let values=new linked<int>();let cursor=values."+method+"();values.add(42);cursor.next();cursor.next();if cursor.hasNext() or cursor.current().hasSome() {return 0;}return 42;");
probe("single-"+method,"let values=new linked<int>();values.add(42);let cursor=values."+method+"();values.clear();cursor.next();cursor.next();if cursor.hasNext() {return 0;}return cursor.current() else 0;");
}
probe("snapshot","""
let values=new linked<int>();values.add(20);values.add(22);values.add(20);
let forward=values.cursor();let reverse=values.reverseCursor();
values[0]=99;values.insert(1,7);values.removeAt(2);values.addFirst(3);
values.removeFirst();values.removeLast();values.clear();values.add(100);
if (forward.current() else 0)!=20 or (reverse.current() else 0)!=20 {return 0;}
if forward.hasNext()==false or reverse.hasNext()==false {return 0;}
forward.next();reverse.next();
if (forward.current() else 0)!=22 or (reverse.current() else 0)!=22 {return 0;}
forward.next();reverse.next();forward.next();reverse.next();
if forward.hasNext() or reverse.hasNext() {return 0;}
return (forward.current() else 0)+(reverse.current() else 0)+2;
""");
probe("false-present","""
let values=new linked<bool>();values.add(false);
let cursor=values.reverseCursor();values.clear();
if let value=cursor.current() {if value==false {return 42;}}return 0;
""");
}
@Test void identityAndFullGroupsSurviveAllMutations() throws Exception {
compile("optional-field","""
declare struct Payload(pub value:optional int);
declare service Probe {fn main()->int {
let values=new linked<Payload>();values.add(new Payload(some(42)));
let cursor=values.cursor();values.clear();
if let item=cursor.current() {return item.value else 0;}return 0;
}}
""");
compile("identity","""
declare struct Item(pub mut value:int);
declare service Probe {fn main()->int {
let item=new Item(20);let other=new Item(20);let values=new linked<Item>();
values.add(item);values.add(other);values.add(item);
let cursor=values.reverseCursor();values.removeAt(1);values.clear();item.value=22;
if let first=cursor.current() {if first!=item {return 0;}} else {return 0;}
cursor.next();if let middle=cursor.current() {if middle==item {return 0;}} else {return 0;}
cursor.next();if let last=cursor.current() {return last.value+other.value;}return 0;
}}
""");
probe("tuple","""
let values=new linked<(left:int,right:int)>();
values.add((left:1,right:2));values.addFirst((left:3,right:4));
values[1]=(left:20,right:22);values.removeFirst();
let cursor=values.reverseCursor();values.clear();
if let value=cursor.current() {return value.left+value.right;}return 0;
""");
probe("nested-array","""
let payload:array<int>=[20];let values=new linked<array<int>>();
values.add(payload);values.insert(0,payload);values.removeAt(1);
let cursor=values.cursor();values.clear();payload[0]=42;
if let value=cursor.current() {return value[0] else 0;}return 0;
""");
compile("function","""
fn answer()->int {return 42;}
declare service Probe {fn main()->int {
let values=new linked<Fn()->int>();values.add(answer);values.addFirst(answer);
values.removeLast();let cursor=values.reverseCursor();values.clear();
if let call=cursor.current() {return call();}return 0;
}}
""");
compile("contract","""
declare contract Reader {fn read()->int;}
declare struct Item(pub value:int);
implements Reader for Item using item {fn read()->int {return item.value;}}
declare service Probe {fn main()->int {
let item=new Item(42);let values=new linked<Reader>();values.add(item as Reader);
values.addFirst(item as Reader);values.removeAt(1);
let cursor=values.reverseCursor();values.clear();
if let value=cursor.current() {return value.read();}return 0;
}}
""");
compile("vec2","""
[BuiltinType(name="vec2",version=1)] declare builtin type Vector(pub x:float,pub y:float) {}
fn nativeProbe()->int {
let values=new linked<Vector>();values.add(new Vector(1.0,2.0));
values.addFirst(new Vector(20.0,22.0));values.removeLast();
let cursor=values.cursor();values.clear();
if let value=cursor.current() {return (value.x+value.y) as int;}return 0;
}
declare service Probe {fn main()->int {return nativeProbe();}}
""");
String color;
try(var stream=getClass().getResourceAsStream("/game/stdlib/1/core/color/main.pbs")) {
assertNotNull(stream);color=new String(stream.readAllBytes(),StandardCharsets.UTF_8);
}
compile("pixel",color+"""
[BuiltinType(name="pixel",version=1)] declare builtin type Pixel(pub x:long,pub y:long,pub color:Color) {}
fn nativeProbe()->int {
let values=new linked<Pixel>();values.add(new Pixel(1,2,BLUE));
values.insert(0,new Pixel(20,22,RED));values.removeAt(1);
let cursor=values.reverseCursor();values.clear();
if let value=cursor.current() {if value.color!=RED {return 0;}return (value.x+value.y) as int;}return 0;
}
declare service Probe {fn main()->int {return nativeProbe();}}
""");
}
@Test void evaluationAndNamedApplicationPreserveSourceOrder() throws Exception {
compile("evaluation","""
declare struct Effects(pub mut count:int,pub values:linked<int>) {
fn receiver()->linked<int> {this.count=this.count*10+1;return this.values;}
fn index()->int {this.count=this.count*10+2;return 0;}
fn value()->int {this.count=this.count*10+3;return 42;}
}
declare service Probe {fn main()->int {
let values=new linked<int>();values.add(0);let effects=new Effects(0,values);
effects.receiver()[effects.index()]=effects.value();if effects.count!=123 {return 0;}
effects.count=0;effects.receiver().insert apply (value:effects.value(),index:effects.index());
if effects.count!=132 {return 0;}
let index:int=1;values.removeAt apply index;return values[0] else 0;
}}
""");
}
@Test void invalidIndicesAndGrowthCannotTruncateOrWrap() throws Exception {
var cases=java.util.Map.of(
"fault-read","let values=new linked<int>();return values[0] else 0;",
"fault-write","let values=new linked<int>();values[0]=42;return 0;",
"fault-remove","let values=new linked<int>();values.removeAt(0);return 0;",
"fault-negative","let values=new linked<int>();values.add(1);return values[-1] else 0;",
"fault-insert","let values=new linked<int>();values.insert(1,42);return 0;",
"fault-long-index","let values=new linked<int>();values.add(42);let index:long=4294967296;return values[index] else 0;",
"fault-overflow","_linkedNextSize(9223372036854775807);return 0;");
for(var item:cases.entrySet())probe(item.getKey(),item.getValue());
}
@Test void resourceFixturesExposeEveryMutationBoundary() throws Exception {
var operations=java.util.Map.of("insert","values.insert(12,42);","add","values.add(42);",
"addFirst","values.addFirst(42);","remove","let previous=values.removeAt(12);",
"removeFirst","let previous=values.removeFirst();","removeLast","let previous=values.removeLast();",
"replace","values[12]=42;","clear","values.clear();",
"cursor","let snapshot=values.cursor();","reverseCursor","let snapshot=values.reverseCursor();");
for(var operation:operations.entrySet())compile("refusal-"+operation.getKey(),"""
fn mutationMarker() {let marker:int=314160;}
fn completedMarker() {let marker:int=314161;}
fn performSecond(values:linked<int>) {OPERATION}
fn descend(values:linked<int>,depth:int) {if depth>0 {descend(values,depth-1);} else {performSecond(values);}}
fn perform(values:linked<int>) {descend(values,24);}
declare service Probe {fn main()->int {
let values=new linked<int>();for i:int from 0 until 32 {values.add(i);}
mutationMarker();perform(values);completedMarker();return 42;
}}
""".replace("OPERATION",operation.getValue()));
}
@Test void snapshotsReleaseOriginalNodesAndConsumedPrefixesAtNormalSafepoints() throws Exception {
compile("gc","""
declare struct Item(pub value:int);declare struct Garbage();
fn collect() {let marker:int=314159;}
fn makeCursor()->Cursor<Item> {
let values=new linked<Item>();for i:int from 0 until 1200 {values.add(new Item(i));}
let cursor=values.cursor();values.removeAt(600);values.removeFirst();values.removeLast();values.clear();
return cursor;
}
fn useCursor() {
let cursor=makeCursor();collect();
for i:int from 0 until 1199 {cursor.next();}collect();
for i:int from 0 until 1200 {cursor.next();}collect();
if let item=cursor.current() {if item.value!=1199 {let failure=1/0;}} else {let failure=1/0;}
}
declare service Probe {fn main()->int {
useCursor();for i:int from 0 until 1200 {let discarded=new Garbage();}collect();return 42;
}}
""");
}
@Test void removedPayloadsAndDoubleLinkedCyclesBecomeCollectible() throws Exception {
compile("gc-collection","""
declare struct Item(pub value:int);declare struct Garbage();
fn collect() {let marker:int=314159;}
fn pressure() {for i:int from 0 until 1200 {let garbage=new Garbage();}}
fn create()->linked<Item> {
let values=new linked<Item>();for i:int from 0 until 1200 {values.add(new Item(i));}return values;
}
fn discard(values:linked<Item>) {values.removeAt(600);values.removeFirst();values.removeLast();}
fn useCollection() {
let values=create();collect();discard(values);pressure();collect();values.clear();pressure();collect();
if (values.size() as int)!=0 {let failure=1/0;}
}
declare service Probe {fn main()->int {useCollection();pressure();collect();return 42;}}
""");
}
@Test void realSdkImportsAndReexportsCompile(@TempDir Path root) throws Exception {
Files.createDirectories(root.resolve("src/facade"));
Files.writeString(root.resolve("prometeu.json"),"""
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
Files.writeString(root.resolve("src/mod.barrel"),"pub fn frame() -> void;");
Files.writeString(root.resolve("src/facade/mod.barrel"),"pub struct Items<T>;pub contract Walk<T>;");
Files.writeString(root.resolve("src/facade/main.pbs"),"import {linked as Items,Cursor as Walk} from @sdk:collections;");
Files.writeString(root.resolve("src/main.pbs"),"""
import {Items,Walk} from @app:facade;
[Frame] fn frame() -> void {
let values:Items<int>=new Items();values.add(20);values.add(22);
let cursor:Walk<int>=values.reverseCursor();values.clear();
let total:int=0;
while true {
if let value=cursor.current() {total=total+value;} else {break;}
if cursor.hasNext() {cursor.next();} else {break;}
}
if total!=42 {let failure=1/0;}
}
""");
var compiled=p.studio.compiler.workspaces.BuilderPipelineService.INSTANCE.compile(
p.studio.compiler.models.BuilderPipelineContext.fromConfig(new p.studio.compiler.messages.BuilderPipelineConfig(false,root.toString())),
p.studio.utilities.logs.LogAggregator.stdout());
assertFalse(compiled.diagnostics().stream().anyMatch(d->d.isError()),compiled.diagnostics().toString());
assertTrue(compiled.bytecodeBytes().length>0);
Files.write(Path.of(System.getProperty("pbs.registryConformanceDirectory")).resolve("pbs-linked-imports.pbx"),compiled.bytecodeBytes());
}
}
@@ -0,0 +1,379 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.backend.bytecode.*;
import p.studio.compiler.models.*;
import p.studio.compiler.pbs.*;
import p.studio.compiler.pbs.ast.PbsAst;
import p.studio.compiler.pbs.lexer.PbsLexer;
import p.studio.compiler.pbs.parser.PbsParser;
import p.studio.compiler.source.diagnostics.DiagnosticSink;
import p.studio.compiler.source.identifiers.*;
import p.studio.utilities.structures.ReadOnlyList;
import java.nio.file.*;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import static org.junit.jupiter.api.Assertions.*;
class PbsListCursorTest {
private static Path directory() { return Path.of(System.getProperty("pbs.registryConformanceDirectory")); }
static BytecodeModule compile(String name,String source) throws Exception {
return compileCollection("list", name, source);
}
static BytecodeModule compileCollection(String collection,String name,String source) throws Exception {
var diagnostics=DiagnosticSink.empty();var id=new FileId(0);var sdkId=new FileId(1);
String sdk;
try(var stream=PbsListCursorTest.class.getResourceAsStream("/game/stdlib/1/sdk/collections/main.pbs")) {
assertNotNull(stream);sdk=new String(stream.readAllBytes(),StandardCharsets.UTF_8);
}
var ast=PbsParser.parse(PbsLexer.lex(sdk+"\n"+source,id,diagnostics),id,diagnostics,PbsParser.ParseMode.INTERFACE_MODULE);
var file=new PbsFrontendCompiler().compileParsedFile(id,ast,diagnostics,source.contains("[BuiltinType")?SourceKind.SDK_INTERFACE:SourceKind.PROJECT,new ModuleId(0),
ReadOnlyList.empty(),p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),
p.studio.compiler.messages.FESurfaceContext.empty(),new p.studio.compiler.source.tables.NameTable());
assertFalse(diagnostics.hasErrors(),()->name+": "+diagnostics.stream().map(d->d.getCode()+":"+d.getMessage()+" at "+d.getSpan().getStart()+":"+d.getSpan().getEnd()).toList());
var backend=IRBackend.builder().entryPointCallableName("Probe.main").entryPointModuleId(new ModuleId(0))
.executableFunctions(file.executableFunctions()).globals(file.globals()).registry(file.registry())
.intrinsicPool(file.intrinsicPool()).callableSignatures(file.callableSignatures()).build();
var program=new LowerToIRVMService().lower(backend);
var module=new BytecodeEmitter().emit(program.coherentEmissionPlan());
if(name.startsWith("gc"))module=PbsStructuredValuesTest.withTestSafepoint(module);
new BytecodePreloadVerifierService().verify(module);
Files.createDirectories(directory());Files.write(directory().resolve("pbs-"+collection+"-"+name+".pbx"),module.serialize());
if(!name.startsWith("gc")) {
var optimized=new OptimizeIRVMService().optimize(new LowerToIRVMService().lower(backend));
var optimizedModule=new BytecodeEmitter().emit(optimized.coherentEmissionPlan());
new BytecodePreloadVerifierService().verify(optimizedModule);
Files.write(directory().resolve("pbs-"+collection+"-"+name+"-optimized.pbx"),optimizedModule.serialize());
}
return module;
}
@Test void defaultConstructionAndSourceAlgorithmsCompile() throws Exception {
compile("basic","""
declare service Probe { fn main() -> int {
let values = new list<int>();
values.add(20); values.add(22);
return (values[0] else 0) + (values[1] else 0);
} }
""");
}
private static void probe(String name,String body) throws Exception {
compile(name,"declare service Probe { fn main() -> int { "+body+" } }");
}
@Test void capacityPoliciesAndLogicalCleanup() throws Exception {
probe("construction","""
let values: list<int> = new list();
if (values.size() as int) != 0 { return 0; }
if (values.capacity() as int) != 16 { return 0; }
let maybe:optional (list<int>)=some(new list());
if let owner=maybe {if (owner.size() as int)!=0 {return 0;}} else {return 0;}
let capacity: int = 0;
let empty: list<int> = new list(capacity);
if (empty.capacity() as int) != 0 { return 0; }
empty.add(42);let first:long=0;return empty[first] else 0;
""");
probe("capacity","""
let values = new list<int>(0);
values.add(1); if (values.capacity() as int) != 1 { return 0; }
values.add(2); if (values.capacity() as int) != 2 { return 0; }
values.add(3); if (values.capacity() as int) != 3 { return 0; }
values.add(4); if (values.capacity() as int) != 5 { return 0; }
values.add(5); values.add(6);
if (values.capacity() as int) != 8 { return 0; }
values.reserve(9); if (values.capacity() as int) != 9 { return 0; }
values.reserve(0); if (values.capacity() as int) != 9 { return 0; }
values.resize(20); if (values.capacity() as int) != 20 { return 0; }
values.resize(2); values.trim();
if (values.capacity() as int) != 2 { return 0; }
values.clear(); if (values.capacity() as int) != 2 { return 0; }
values.trim(); if (values.capacity() as int) != 0 { return 0; }
return 42;
""");
probe("holes","""
let values = new list<int>(0);
values.resize(3); values[0] = 0; values[2] = 7;
if values[0].hasNone() { return 0; }
if values[1].hasSome() { return 0; }
values.add(9); values.insert(1, 42);
if (values.size() as int) != 5 { return 0; }
if values[2].hasSome() { return 0; }
if (values[3] else 0) != 7 { return 0; }
if values.removeAt(2).hasSome() { return 0; }
if (values[2] else 0) != 7 { return 0; }
let previous = values.removeAt(1);
values.clearAt(0); if values[0].hasSome() { return 0; }
if (values.size() as int) != 3 { return 0; }
values.resize(1); values.resize(3);
if values[1].hasSome() or values[2].hasSome() { return 0; }
values.clear(); values.resize(3);
if values[0].hasSome() or values[2].hasSome() { return 0; }
return previous else 0;
""");
probe("structural-growth","""
let maximum: long = 4294967295;
if _grownCapacity(maximum - 1, maximum) != maximum { return 0; }
if (_grownCapacity(0, 42) as int) != 42 { return 0; }
return 42;
""");
}
@Test void cursorStatesAndSnapshots() throws Exception {
probe("cursor-empty","""
let values = new list<int>(); values.resize(3);
let cursor: Cursor<int> = values.cursor();
values.add(42);
cursor.next(); cursor.next();
if cursor.hasNext() or cursor.current().hasSome() { return 0; }
return 42;
""");
probe("cursor-single","""
let values = new list<int>(); values.add(42);
let cursor = values.cursor();
if cursor.hasNext() { return 0; }
cursor.next(); cursor.next(); cursor.next();
if cursor.hasNext() { return 0; }
return cursor.current() else 0;
""");
probe("cursor-many","""
let values = new list<int>();
values.add(20); values.add(22);
let cursor = values.cursor();
if (cursor.current() else 0) != 20 { return 0; }
if (cursor.current() else 0) != 20 { return 0; }
if cursor.hasNext() == false { return 0; }
if cursor.hasNext() == false { return 0; }
cursor.next();
if cursor.hasNext() { return 0; }
if (cursor.current() else 0) != 22 { return 0; }
cursor.next(); cursor.next();
if (cursor.current() else 0) != 22 { return 0; }
return 42;
""");
probe("snapshot","""
let values = new list<int>(0); values.resize(4);
values[0]=0; values[2]=20; values[3]=22;
let cursor=values.cursor();
values[0]=9; values.insert(0,9); values.removeAt(1);
values.add(99); values.resize(1); values.clear(); values.trim();
let total:int=0; let count:int=0;
while true {
if let value=cursor.current() { total=total+value; count=count+1; }
else { break; }
if cursor.hasNext() {cursor.next();} else {break;}
}
if count!=3 {return 0;}
return total;
""");
probe("false-present","""
let values=new list<bool>();values.resize(2);values[1]=false;
let cursor=values.cursor();
if cursor.hasNext() {return 0;}
if let value=cursor.current() {if value==false {return 42;}}
return 0;
""");
probe("shared-optional","""
let empty:Cursor<optional int>=new _SnapshotCursor<optional int>(none);
if empty.current().hasSome() {return 0;}
let node=new _SnapshotNode<optional int>(none,none);
let cursor:Cursor<optional int>=new _SnapshotCursor<optional int>(some(node));
if cursor.current().hasNone() {return 0;}
if let payload=cursor.current() {if payload.hasSome() {return 0;}}
else {return 0;}
cursor.next();if cursor.current().hasNone() {return 0;}
return 42;
""");
}
@Test void aliasesAndCompletePayloads() throws Exception {
compile("identity","""
declare struct Item(pub mut value:int);
declare service Probe {fn main()->int {
let values=new list<Item>(0);let alias=values;
let item=new Item(20);let other=new Item(20);
values.add(item);alias.add(other);values.add(item);
if (alias.size() as int)!=3 {return 0;}
let cursor=values.cursor();values.clear();values.trim();item.value=22;
if let first=cursor.current() {if first!=item {return 0;}}
else {return 0;}
cursor.next();if let middle=cursor.current() {if middle==item {return 0;}}
else {return 0;}
cursor.next();if let last=cursor.current() {return last.value+other.value;}
return 0;
}}
""");
probe("tuple","""
let values=new list<(left:int,right:int)>(0);
values.add((left:20,right:22));values.insert(0,(left:1,right:2));
values.removeAt(0);let cursor=values.cursor();values.clear();
if let value=cursor.current() {return value.left+value.right;}
return 0;
""");
probe("nested-array","""
let payload:array<int>=[20];let values=new list<array<int>>();
values.add(payload);values.insert(0,payload);values.removeAt(0);
let cursor=values.cursor();values.clear();payload[0]=42;
if let value=cursor.current() {return value[0] else 0;}
return 0;
""");
compile("function","""
fn answer()->int {return 42;}
declare service Probe {fn main()->int {
let values=new list<Fn()->int>(0);values.add(answer);
values.insert(0,answer);values.removeAt(1);
let cursor=values.cursor();values.clear();
if let call=cursor.current() {return call();}return 0;
}}
""");
compile("evaluation","""
declare struct Effects(pub mut count:int,pub values:list<int>) {
fn receiver()->list<int> {this.count=this.count*10+1;return this.values;}
fn index()->int {this.count=this.count*10+2;return 0;}
fn value()->int {this.count=this.count*10+3;return 42;}
}
declare service Probe {fn main()->int {
let values=new list<int>();values.resize(1);
let effects=new Effects(0,values);
effects.receiver()[effects.index()]=effects.value();
if effects.count!=123 {return 0;}
effects.count=0;
effects.receiver().insert apply (value:effects.value(),index:effects.index());
if effects.count!=132 {return 0;}
let length:int=3;values.resize apply length;
let index:int=2;values.insert apply (index,1);
if (values.size() as int)!=4 {return 0;}
return values[0] else 0;
}}
""");
}
@Test void nativeAndContractGroupsSurviveTransfersAndCapture() throws Exception {
compile("vec2","""
[BuiltinType(name="vec2",version=1)]
declare builtin type Vector(pub x:float,pub y:float) {}
fn nativeProbe()->int {
let values=new list<Vector>(0);values.add(new Vector(20.0,22.0));
values.insert(0,new Vector(1.0,2.0));values.removeAt(0);
let cursor=values.cursor();values.clear();
if let value=cursor.current() {
let projected=(cursor.current() else new Vector(0.0,0.0)).x;
return (projected+value.y) as int;
}
return 0;
}
declare service Probe {fn main()->int {return nativeProbe();}}
""");
String color;
try(var stream=getClass().getResourceAsStream("/game/stdlib/1/core/color/main.pbs")) {
assertNotNull(stream);color=new String(stream.readAllBytes(),StandardCharsets.UTF_8);
}
compile("pixel",color+"""
[BuiltinType(name="pixel",version=1)]
declare builtin type Pixel(pub x:long,pub y:long,pub color:Color) {}
fn nativeProbe()->int {
let values=new list<Pixel>(0);values.add(new Pixel(20,22,RED));
values.insert(0,new Pixel(1,2,BLUE));values.removeAt(0);
let cursor=values.cursor();values.clear();
if let value=cursor.current() {
if value.color!=RED {return 0;}
return (value.x+value.y) as int;
}return 0;
}
declare service Probe {fn main()->int {return nativeProbe();}}
""");
compile("contract","""
declare contract Reader {fn read()->int;}
declare struct Item(pub value:int);
implements Reader for Item using item {fn read()->int {return item.value;}}
declare service Probe {fn main()->int {
let item=new Item(42);let values=new list<Reader>(0);
values.add(item as Reader);values.insert(0,item as Reader);values.removeAt(0);
let cursor=values.cursor();values.clear();
if let value=cursor.current() {return value.read();}return 0;
}}
""");
}
@Test void faultsPreserveProviderClassification() throws Exception {
probe("fault-read","let values=new list<int>(4);return values[0] else 0;");
probe("fault-write","let values=new list<int>(4);values[0]=42;return 0;");
probe("fault-negative","let values=new list<int>();values.add(1);return values[-1] else 0;");
probe("fault-insert","let values=new list<int>();values.insert(1,42);return 0;");
probe("fault-length","let values=new list<int>();values.resize(-1);return 0;");
probe("fault-overflow","let values=new list<int>();let length:long=4294967296;values.reserve(length);return 0;");
probe("fault-long-index","let values=new list<int>();values.add(42);let index:long=4294967296;return values[index] else 0;");
probe("fault-constructor","let values=new list<int>(-1);return 0;");
}
@Test void resourceRefusalFixturesExposeIndependentMutationBoundaries() throws Exception {
for(var operation:java.util.Map.of(
"insert","values.insert(12,42);",
"remove","let previous=values.removeAt(12);",
"growth","values.add(42);",
"cursor","let snapshot=values.cursor();").entrySet()) {
int capacity=operation.getKey().equals("growth")?128:256;
compile("refusal-"+operation.getKey(),"""
fn mutationMarker() {let marker:int=314160;}
fn completedMarker() {let marker:int=314161;}
fn performSecond(values:list<int>) {OPERATION}
fn perform(values:list<int>) {performSecond(values);}
declare service Probe {fn main()->int {
let values=new list<int>(CAPACITY);
values.resize(128);
for i:int from 0 until 128 {values[i]=i;}
mutationMarker();
perform(values);
completedMarker();return 42;
}}
""".replace("CAPACITY",Integer.toString(capacity)).replace("OPERATION",operation.getValue()));
}
}
@Test void snapshotPrefixAndStickyLastUseNormalSafepoints() throws Exception {
compile("gc","""
declare struct Item(pub value:int);
declare struct Garbage();
fn collect() {let marker:int=314159;}
fn makeCursor()->Cursor<Item> {
let values=new list<Item>(1200);
for i:int from 0 until 1200 {values.add(new Item(i));}
return values.cursor();
}
fn useCursor() {
let cursor=makeCursor();collect();
for i:int from 0 until 1199 {cursor.next();}
collect();
for i:int from 0 until 1200 {cursor.next();}
collect();
if let item=cursor.current() {
if item.value!=1199 {let failure=1/0;}
} else {let failure=1/0;}
}
declare service Probe {fn main()->int {
useCursor();
for i:int from 0 until 1200 {let discarded=new Garbage();}
collect();return 42;
}}
""");
}
@Test void sdkAliasesAndReexportsExecuteThroughTheWorkspace(@org.junit.jupiter.api.io.TempDir Path root) throws Exception {
Files.createDirectories(root.resolve("src/facade"));
Files.writeString(root.resolve("prometeu.json"),"""
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
Files.writeString(root.resolve("src/mod.barrel"),"pub fn frame() -> void;");
Files.writeString(root.resolve("src/facade/mod.barrel"),"pub struct Items<T>; pub contract Walk<T>;");
Files.writeString(root.resolve("src/facade/main.pbs"),"import {list as Items,Cursor as Walk} from @sdk:collections;");
Files.writeString(root.resolve("src/main.pbs"),"""
import {Items,Walk} from @app:facade;
[Frame] fn frame() -> void {
let values:Items<int>=new Items(0);values.add(20);values.add(22);
let cursor:Walk<int>=values.cursor();values.clear();
let total:int=0;
while true {
if let value=cursor.current() {total=total+value;} else {break;}
if cursor.hasNext() {cursor.next();} else {break;}
}
if total!=42 {let failure=1/0;}
}
""");
var result=p.studio.compiler.workspaces.BuilderPipelineService.INSTANCE.compile(
p.studio.compiler.models.BuilderPipelineContext.fromConfig(new p.studio.compiler.messages.BuilderPipelineConfig(false,root.toString())),
p.studio.utilities.logs.LogAggregator.stdout());
assertFalse(result.diagnostics().stream().anyMatch(d->d.isError()),result.diagnostics().toString());
assertTrue(result.bytecodeBytes().length>0);
Files.createDirectories(directory());Files.write(directory().resolve("pbs-list-imports.pbx"),result.bytecodeBytes());
}
}
@@ -0,0 +1,128 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.pbs.PbsFrontendCompiler;
import p.studio.compiler.models.IRBackend;
import p.studio.compiler.backend.bytecode.*;
import p.studio.compiler.source.diagnostics.DiagnosticSink;
import p.studio.compiler.source.identifiers.FileId;
import p.studio.compiler.models.SourceKind;
import java.nio.file.*;
import static org.junit.jupiter.api.Assertions.*;
class PbsRuntimeAlignmentTest {
private static String sdk(String path) throws Exception {
try(var stream = PbsFrontendCompiler.class.getResourceAsStream("/game/stdlib/1/"+path+"/main.pbs")) {
assertNotNull(stream); return new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);
}
}
static BytecodeModule compile(String name,String source) throws Exception {
return compile(name, source, SourceKind.SDK_INTERFACE);
}
static BytecodeModule compile(String name,String source,SourceKind sourceKind) throws Exception {
var diagnostics=DiagnosticSink.empty();
var fileId = new FileId(0);
var ast = p.studio.compiler.pbs.parser.PbsParser.parse(p.studio.compiler.pbs.lexer.PbsLexer.lex(source,fileId,diagnostics),fileId,diagnostics,p.studio.compiler.pbs.parser.PbsParser.ParseMode.INTERFACE_MODULE);
var file=new PbsFrontendCompiler().compileParsedFile(fileId,ast,diagnostics,sourceKind,
new p.studio.compiler.source.identifiers.ModuleId(0),p.studio.utilities.structures.ReadOnlyList.empty(),
p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),p.studio.compiler.messages.FESurfaceContext.empty(),new p.studio.compiler.source.tables.NameTable());
assertFalse(diagnostics.hasErrors(), ()->diagnostics.stream().map(d->d.getCode()+":"+d.getMessage()).toList().toString());
var backend=IRBackend.builder().entryPointCallableName("Probe.main").entryPointModuleId(new p.studio.compiler.source.identifiers.ModuleId(0)).executableFunctions(file.executableFunctions())
.globals(file.globals()).registry(file.registry()).intrinsicPool(file.intrinsicPool()).callableSignatures(file.callableSignatures()).build();
var program=new LowerToIRVMService().lower(backend);
if (name.endsWith("-optimized")) program = new OptimizeIRVMService().optimize(program);
var module=new BytecodeEmitter().emit(program.coherentEmissionPlan());
new BytecodePreloadVerifierService().verify(module);
var directory=Path.of(System.getProperty("pbs.registryConformanceDirectory"));Files.createDirectories(directory);
Files.write(directory.resolve("pbs-"+name+".pbx"),module.serialize());
return module;
}
@Test void numericValuesAndExplicitConversionsReachProductionPbx() throws Exception {
compile("numeric", """
declare service Probe {
fn widen(value: int) -> long { return value as long; }
fn contextual() -> long { return 1; }
fn receive(value: long) -> long { return value; }
fn main() -> long {
let large: long = 2147483648;
let maximum: long = 9223372036854775807;
Probe.contextual();
Probe.receive(2147483648);
return large + Probe.widen(7);
}
}
""");
compile("narrow", "declare service Probe { fn main() -> int { let value: long = 2147483648; return value as int; } }");
compile("float", "declare service Probe { fn main() -> float { return 1.5 + 2.25; } }");
compile("overflow", "declare service Probe { fn main() -> int { return 2147483647 + 1; } }");
}
@Test void allInputQueriesCompileFromThePublishedFacade() throws Exception {
var input=sdk("sdk/input");
for (var button : new String[]{"Up","Down","Left","Right","A","B","X","Y","L","R","Start","Select"}) {
for(var query:new String[]{"pressed","released","down","hold"}) {
var type=query.equals("hold")?"long":"bool";
compile("pad-"+button.toLowerCase()+"-"+query,input+"\ndeclare service Probe { fn select(button: Button) -> Button { return button; } fn main() -> "+type+" { let button = Probe.select(Button."+button+"); return Pad."+query+"(button); } }");
compile("pad-"+button.toLowerCase()+"-"+query+"-constant", input+"\ndeclare service Probe { fn main() -> "+type+" { return Pad."+query+"(Button."+button+"); } }");
}
}
for(var query:new String[]{"pressed","released","down","hold","x","y"}) {
var type=java.util.Set.of("hold","x","y").contains(query)?"long":"bool";
compile("touch-"+query,input+"\ndeclare service Probe { fn main() -> "+type+" { return Touch."+query+"(); } }");
}
}
@Test void completeBuiltinAndTupleGroupsReachProductionPbx() throws Exception {
compile("vec2", """
[BuiltinType(name = "vec2", version = 1)]
declare builtin type Vector(pub x: float, pub y: float) {}
[BuiltinConst(target = "vec2", name = "zero", version = 1)]
declare const ZERO: Vector;
declare service Probe {
fn echo(value: Vector) -> Vector { return value; }
fn main() -> Vector { let vector = Probe.echo(ZERO); return vector; }
}
""");
compile("tuple", """
declare service Probe {
fn pair() -> (x: int, y: long) { return (x: 7, y: 8 as long); }
fn main() -> (x: int, y: long) { let pair = Probe.pair(); return pair; }
}
""");
compile("named", """
declare global trace: int = 0;
declare service Probe {
fn x() -> int { trace = trace * 10 + 1; return 10; }
fn y() -> int { trace = trace * 10 + 2; return 20; }
fn combine(x: int, y: int) -> int { return x * 100 + y; }
fn main() -> int {
trace = 0;
let value = Probe.combine apply (y: Probe.y(), x: Probe.x());
return trace * 10000 + value;
}
}
""");
compile("color", sdk("core/color") + "declare service Probe { fn echo(value: Color) -> Color { return value; } fn main() -> Color { return Probe.echo(RED); } }");
compile("pixel", sdk("core/color") + """
[BuiltinType(name = "pixel", version = 1)]
declare builtin type Pixel(pub x: long, pub y: long, pub color: Color) {}
declare service Probe {
fn echo(value: Pixel) -> Pixel { return value; }
fn main() -> Pixel { let value = new Pixel(12, -34, RED); return Probe.echo(value); }
}
""");
compile("string", "declare service Probe { fn echo(value: str) -> str { return value; } fn main() -> str { return Probe.echo(\"hello\"); } }");
compile("division", "declare service Probe { fn main() -> int { return 1 / 0; } }");
compile("minimum", "declare service Probe { fn main() -> long { return -9223372036854775808; } }");
}
@Test void wrongNumericAndButtonTypesAreRejected() throws Exception {
for(var expression:new String[]{"1","1 as long","true","Other.A","\"A\""}) {
var diagnostics=DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0),sdk("sdk/input")+"\ndeclare enum Other(A); declare service Probe { fn main() -> bool { return Pad.pressed("+expression+"); } }",diagnostics,SourceKind.SDK_INTERFACE);
assertTrue(diagnostics.hasErrors());
}
for(var source:new String[]{"fn main() -> long { let x: long = 1; let y: int = 1; return x + y; }", "fn main() -> int { return 2147483648; }", "fn main() -> long { return 9223372036854775808; }"}) {
var diagnostics=DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0),source,diagnostics);
assertTrue(diagnostics.hasErrors());
}
}
}
@@ -0,0 +1,129 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.pbs.PbsFrontendCompiler;
import p.studio.compiler.source.diagnostics.DiagnosticSink;
import p.studio.compiler.source.identifiers.FileId;
import p.studio.compiler.models.SourceKind;
import static org.junit.jupiter.api.Assertions.*;
class PbsRuntimeMathTest {
static String sdk() throws Exception {
var result = new StringBuilder();
for (var name : new String[]{"math", "mathf"}) {
try (var stream = PbsFrontendCompiler.class.getResourceAsStream("/game/stdlib/1/sdk/"+name+"/main.pbs")) {
assertNotNull(stream);
result.append(new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8));
}
}
return result.toString();
}
@Test void constantsAndOverloadsCompile() throws Exception {
PbsRuntimeAlignmentTest.compile("math-pi", sdk()+"declare service Probe { fn main() -> float { return mathf.pi; } }");
PbsRuntimeAlignmentTest.compile("math-tau", sdk()+"declare service Probe { fn main() -> float { return mathf.tau; } }");
PbsRuntimeAlignmentTest.compile("math-literal", sdk()+"declare service Probe { fn main() -> float { return mathf.sin(-0.0); } }");
PbsRuntimeAlignmentTest.compile("math-long", "declare service Settings { declare const limit: long = 2147483648; } declare service Probe { fn main() -> long { return Settings.limit; } }");
PbsRuntimeAlignmentTest.compile("math-min", sdk()+"declare service Probe { fn main() -> long { let a: long = 42; let b: long = 55; return math.min(a,b); } }");
PbsRuntimeAlignmentTest.compile("math-service", "declare service Settings { declare const answer: int = 42; } declare service Probe { fn main() -> int { return Settings.answer; } }");
}
@Test void invalidMembersAndMixedCarriersReject() throws Exception {
for (var body : new String[]{"return math.min(1, 2 as long);", "return mathf.sin(1);", "mathf.pi = 3.0; return 0;"}) {
var diagnostics = DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0),sdk()+"declare service Probe { fn main() -> int { "+body+" } }",diagnostics,SourceKind.SDK_INTERFACE);
assertTrue(diagnostics.hasErrors(), body);
}
}
@Test void providerCorpusCompilesEverySignatureFromSource() throws Exception {
var directory = java.nio.file.Path.of(System.getProperty("pbs.registryConformanceDirectory"));
String corpus;
try (var stream = getClass().getResourceAsStream("/math/numeric-source.tsv")) {
assertNotNull(stream);
corpus = new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);
}
var manifest = new StringBuilder();
var covered = new java.util.HashSet<Integer>();
int index = 0;
for (var row : corpus.lines().toList()) {
var parts = row.split(" ");
int id = Integer.parseInt(parts[0], 16);
var definition = java.util.Arrays.stream(IRVMIntrinsicDefinition.values()).filter(d -> d.finalId() == id).findFirst().orElseThrow();
var source = new StringBuilder(sdk()).append("declare service Probe { fn main() -> ")
.append(sourceType(definition.retLayout())).append(" {");
var arguments = new java.util.ArrayList<String>();
var types = definition.argLayout().split("\\|");
for (int i = 0; i < types.length; i++) {
source.append("let a").append(i).append(": ").append(sourceType(types[i])).append(" = ")
.append(literal(parts[i+1])).append(";");
arguments.add("a"+i);
}
var name = definition.canonicalName().replace(".i32.", ".").replace(".i64.", ".");
source.append("return ").append(name).append("(").append(String.join(",",arguments)).append("); } }");
var fixture = "math-vector-" + index++;
PbsRuntimeAlignmentTest.compile(fixture, source.toString());
manifest.append("pbs-").append(fixture).append(" ").append(row).append("\n");
PbsRuntimeAlignmentTest.compile(fixture+"-optimized", source.toString());
manifest.append("pbs-").append(fixture).append("-optimized ").append(row).append("\n");
covered.add(id);
}
assertEquals(26, covered.size());
java.nio.file.Files.writeString(directory.resolve("math-vectors.tsv"), manifest);
}
private static String sourceType(String type) {
return switch(type) { case "Int32" -> "int"; case "Int64" -> "long"; case "Float" -> "float"; default -> throw new IllegalArgumentException(type); };
}
private static String literal(String token) {
if (!token.startsWith("f:")) return token.substring(2);
long bits = Long.parseUnsignedLong(token.substring(2),16);
if (bits == Long.MIN_VALUE) return "-0.0";
var result = java.math.BigDecimal.valueOf(Double.longBitsToDouble(bits)).toPlainString();
return result.contains(".") ? result : result + ".0";
}
@Test void qualifiedConstantDependenciesAndFailures() throws Exception {
PbsRuntimeAlignmentTest.compile("math-dependency", "declare global answer: int = 999; declare service Settings { declare const base: int = 40; declare const answer: int = base + 2; fn read() -> int { return answer; } } declare service Probe { fn main() -> int { answer = 999; return Settings.read(); } }", SourceKind.PROJECT);
for (var members : new String[]{
"declare const a: int = 1; declare const a: int = 2;",
"declare const a: int = Settings.b; declare const b: int = Settings.a;",
"declare const a: int = missing;",
"declare const a: int = 1; fn a() -> int { return 2; }",
"declare const a: int = true;"}) {
var diagnostics = DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0), "declare service Settings { "+members+" }", diagnostics);
assertTrue(diagnostics.hasErrors(), members);
}
for (var expression : new String[]{"math.min(1, 2 as long)", "mathf.sin(1)", "math.to_i64(1 as long)"}) {
var diagnostics = DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0),sdk()+"declare service Probe { fn main() { "+expression+"; } }",diagnostics,SourceKind.SDK_INTERFACE);
assertTrue(diagnostics.stream().anyMatch(d -> d.getMessage().contains("explicit conversion")), expression);
}
}
@Test void realModuleImportsAndAliasesProducePbx(@org.junit.jupiter.api.io.TempDir java.nio.file.Path root) throws Exception {
java.nio.file.Files.createDirectories(root.resolve("src/config"));
java.nio.file.Files.writeString(root.resolve("prometeu.json"), """
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
java.nio.file.Files.writeString(root.resolve("src/config/main.pbs"), "declare service Settings { declare const answer: int = 42; }");
java.nio.file.Files.writeString(root.resolve("src/config/mod.barrel"), "pub service Settings;");
java.nio.file.Files.writeString(root.resolve("src/mod.barrel"), "pub fn frame() -> void;");
java.nio.file.Files.writeString(root.resolve("src/main.pbs"), """
import { math } from @sdk:math;
import { mathf as numbers } from @sdk:mathf;
import { Settings as config } from @app:config;
[Frame]
fn frame() -> void {
if config.answer != 42 { let fail = 1 / 0; }
if numbers.pi != 3.141592653589793 { let fail = 1 / 0; }
if numbers.sin(0.0) != 0.0 { let fail = 1 / 0; }
let value: long = 42;
if math.min(value, 55 as long) != value { let fail = 1 / 0; }
}
""");
var result = p.studio.compiler.workspaces.BuilderPipelineService.INSTANCE.compile(
p.studio.compiler.models.BuilderPipelineContext.fromConfig(new p.studio.compiler.messages.BuilderPipelineConfig(false, root.toString())),
p.studio.utilities.logs.LogAggregator.stdout());
assertFalse(result.diagnostics().stream().anyMatch(d -> d.isError()), result.diagnostics().toString());
assertTrue(result.bytecodeBytes().length > 0);
java.nio.file.Files.write(java.nio.file.Path.of(System.getProperty("pbs.registryConformanceDirectory"),"pbs-math-import.pbx"),result.bytecodeBytes());
}
}
@@ -0,0 +1,294 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.pbs.PbsFrontendCompiler;
import static org.junit.jupiter.api.Assertions.*;
class PbsRuntimeRandomTest {
static String sdk() throws Exception {
try (var stream = PbsFrontendCompiler.class.getResourceAsStream("/game/stdlib/1/sdk/random/main.pbs")) {
assertNotNull(stream);
return new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);
}
}
@Test void mixedCallsPreserveAliasing() throws Exception {
for (var suffix : new String[]{"", "-optimized"}) {
PbsRuntimeAlignmentTest.compile("random-mixed"+suffix, sdk()+"""
declare service Probe {
fn main() -> (a: float, b: long, c: long) {
let rng = random.new(42 as long);
let alias = rng;
random.next(rng);
let a = random.nextf(alias);
let b = random.range(rng, -7 as long, -6 as long);
let c = random.next(alias);
return (a: a, b: b, c: c);
}
}
""");
}
}
private static void pair(String name, String source) throws Exception {
for (var suffix : new String[]{"", "-optimized"})
compile("random-"+name+suffix, source);
}
static void compile(String name, String source) throws Exception {
var diagnostics = p.studio.compiler.source.diagnostics.DiagnosticSink.empty();
var sdkId = new p.studio.compiler.source.identifiers.FileId(1);
var fileId = new p.studio.compiler.source.identifiers.FileId(0);
var names = new p.studio.compiler.source.tables.NameTable();
var modules = p.studio.utilities.structures.ReadOnlyList.from(
new p.studio.compiler.source.tables.ModuleReference("test",p.studio.utilities.structures.ReadOnlyList.from("client")),
new p.studio.compiler.source.tables.ModuleReference("sdk",p.studio.utilities.structures.ReadOnlyList.from("random")));
var sdkAst = p.studio.compiler.pbs.parser.PbsParser.parse(p.studio.compiler.pbs.lexer.PbsLexer.lex(sdk(),sdkId,diagnostics), sdkId,diagnostics,p.studio.compiler.pbs.parser.PbsParser.ParseMode.INTERFACE_MODULE);
var provider = new PbsFrontendCompiler().compileParsedFile(sdkId,sdkAst,diagnostics,p.studio.compiler.models.SourceKind.SDK_INTERFACE,
new p.studio.compiler.source.identifiers.ModuleId(1),modules,
p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),p.studio.compiler.messages.FESurfaceContext.empty(),names);
var imported = new java.util.ArrayList<PbsFrontendCompiler.ImportedCallableSurface>();
for (var signature : provider.callableSignatures()) {
var executable = provider.executableFunctions().stream().filter(f -> f.callableName().equals(signature.callableName())).findFirst().orElseThrow();
var method = signature.callableName().substring(signature.callableName().lastIndexOf('.')+1);
String type = switch(method) { case "new" -> "Random"; case "nextf" -> "float"; case "$instance" -> "random"; default -> "long"; };
imported.add(new PbsFrontendCompiler.ImportedCallableSurface(new p.studio.compiler.source.identifiers.ModuleId(1), signature.callableName(), signature.arity(), executable.returnSlots(),
p.studio.compiler.pbs.ast.PbsAst.ReturnKind.PLAIN, p.studio.compiler.pbs.ast.PbsAst.TypeRef.simple(type,sdkAst.span()),signature.typeShape()));
}
var ast = p.studio.compiler.pbs.parser.PbsParser.parse(p.studio.compiler.pbs.lexer.PbsLexer.lex(source,fileId,diagnostics),fileId,diagnostics,p.studio.compiler.pbs.parser.PbsParser.ParseMode.INTERFACE_MODULE);
var file = new PbsFrontendCompiler().compileParsedFile(fileId,ast,diagnostics,p.studio.compiler.models.SourceKind.PROJECT,
new p.studio.compiler.source.identifiers.ModuleId(0),modules,
p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),p.studio.compiler.messages.FESurfaceContext.empty(),names,
sdkAst.topDecls(),p.studio.utilities.structures.ReadOnlyList.wrap(imported),p.studio.utilities.structures.ReadOnlyList.empty(),provider.reservedMetadata(),java.util.Map.of());
assertFalse(diagnostics.hasErrors(), () -> name+": "+diagnostics.stream().map(d->d.getCode()+":"+d.getMessage()).toList());
var functions = new java.util.ArrayList<>(file.executableFunctions().asList());
var signatures = new java.util.ArrayList<>(file.callableSignatures().asList());
String entry = "Probe.main";
var initializer = functions.stream().filter(f -> f.callableName().startsWith("__pbs.file_init$")).findFirst();
if (initializer.isPresent()) {
var main = functions.stream().filter(f->f.callableName().equals("Probe.main")).findFirst().orElseThrow();
var init = initializer.get();
var id = new p.studio.compiler.source.identifiers.CallableId(signatures.size());
entry = "$test.entry";
int returns = main.returnSlots();
signatures.add(new p.studio.compiler.source.tables.CallableSignatureRef(new p.studio.compiler.source.identifiers.ModuleId(0),entry,0,"test"));
var instructions = p.studio.utilities.structures.ReadOnlyList.from(
new p.studio.compiler.models.IRBackendExecutableFunction.Instruction(p.studio.compiler.models.IRBackendExecutableFunction.InstructionKind.CALL_FUNC,
new p.studio.compiler.source.identifiers.ModuleId(0),init.callableName(),init.callableId(),null,null,0,0,init.span()),
new p.studio.compiler.models.IRBackendExecutableFunction.Instruction(p.studio.compiler.models.IRBackendExecutableFunction.InstructionKind.CALL_FUNC,
new p.studio.compiler.source.identifiers.ModuleId(0),main.callableName(),main.callableId(),null,null,0,returns,main.span()),
new p.studio.compiler.models.IRBackendExecutableFunction.Instruction(p.studio.compiler.models.IRBackendExecutableFunction.InstructionKind.RET,"",null,null,main.span()));
functions.add(new p.studio.compiler.models.IRBackendExecutableFunction(fileId,new p.studio.compiler.source.identifiers.ModuleId(0),entry,id,0,0,0,0,returns,returns,instructions,main.span(),main.metadata()));
}
var client = new p.studio.compiler.models.IRBackendFile(file.fileId(),file.functions(),file.syntheticFunctions(),file.globals(),
p.studio.utilities.structures.ReadOnlyList.wrap(functions),file.reservedMetadata(),file.modulePool(),
p.studio.utilities.structures.ReadOnlyList.wrap(signatures),file.intrinsicPool(),null,file.registry());
var aggregator = p.studio.compiler.models.IRBackend.aggregator();
aggregator.merge(provider); aggregator.merge(client);
var backend = aggregator.entryPointCallableName(entry).entryPointModuleId(new p.studio.compiler.source.identifiers.ModuleId(0)).emit();
var program = new LowerToIRVMService().lower(backend);
if(name.endsWith("-optimized")) program = new OptimizeIRVMService().optimize(program);
var module = new p.studio.compiler.backend.bytecode.BytecodeEmitter().emit(program.coherentEmissionPlan());
if (name.startsWith("random-null") || name.startsWith("random-typed-null")) module = withInjectedNull(module);
if (name.startsWith("random-gc")) module = PbsStructuredValuesTest.withTestSafepoint(module);
new p.studio.compiler.backend.bytecode.BytecodePreloadVerifierService().verify(module);
java.nio.file.Files.write(java.nio.file.Path.of(System.getProperty("pbs.registryConformanceDirectory"),"pbs-"+name+".pbx"),module.serialize());
}
// Controlled provider fixture: compile valid, fully initialized source, then
// suppress its unique one-slot field store. Allocation, field defaults, typed
// Array access and Random consumption still use the production provider.
private static p.studio.compiler.backend.bytecode.BytecodeModule withInjectedNull(
p.studio.compiler.backend.bytecode.BytecodeModule module) {
byte[] code = module.code().clone();
var entry = module.debugInfo().functionNames().stream().filter(f -> f.name().contains("Empty.$ctor.create")).findFirst().orElseThrow();
var function = module.functions().get(entry.funcIdx());
int replaced = 0;
for (int pc = function.codeOffset(); pc + 10 <= function.codeOffset() + function.codeLen(); pc += 2) {
if (code[pc] == (byte) 0xa2 && code[pc + 1] == 0
&& java.nio.ByteBuffer.wrap(code, pc + 6, 4).order(java.nio.ByteOrder.LITTLE_ENDIAN).getInt() == 0) {
java.util.Arrays.fill(code, pc, pc + 10, (byte) 0);
code[pc] = 0x11; code[pc + 2] = 0x11; // discard field value and receiver
replaced++;
}
}
assertEquals(1, replaced, "unique controlled provider field store");
return new p.studio.compiler.backend.bytecode.BytecodeModule(module.version(), module.constPool(),
module.functions(), code, module.debugInfo(), module.exports(), module.syscalls(),
module.registry(), module.intrinsicSignatures());
}
@Test void providerSeedVectors() throws Exception {
String corpus;
try (var stream = PbsRuntimeRandomTest.class.getResourceAsStream("/random/random-conformance.tsv")) {
assertNotNull(stream);
corpus = new String(stream.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);
}
var manifest = new StringBuilder();
int index = 0;
for (var row : corpus.lines().skip(1).toList()) {
var parts = row.split("\\s+");
for (var kind : new String[]{"next", "nextf"}) {
String type = kind.equals("next") ? "long" : "float";
int draw = Integer.parseInt(parts[1]);
String name = "vector-"+index++;
pair(name, "declare service Probe { fn main() -> "+type+" { let seed: long = "+parts[0]+"; let rng = random.new(seed); "
+ "random.next(rng);".repeat(draw-1)+"return random."+kind+"(rng); } }");
for (var suffix : new String[]{"", "-optimized"})
manifest.append("pbs-random-").append(name).append(suffix).append(" ")
.append(kind.equals("next") ? "l:"+parts[3] : "f:"+parts[4].toLowerCase())
.append(" ").append(draw).append("\n");
}
}
assertEquals(96, index);
java.nio.file.Files.writeString(java.nio.file.Path.of(System.getProperty("pbs.registryConformanceDirectory"), "random-vectors.tsv"), manifest);
}
@Test void storageAndIndependentStreams() throws Exception {
pair("storage", """
declare struct Empty(pub value: Random) { ctor create() { this.value = random.new(9223372036854775807); } } declare global saved: Random = new Empty.create().value;
declare struct Box(pub value: Random);
fn echo(rng: Random) -> Random { return rng; }
fn capture(rng: Random) -> Fn() -> long { return fn [rng]() -> long { return random.next(rng); }; }
declare service Probe {
fn main() -> (a: long, b: long, c: long, d: long, e: long) {
let rng = random.new(42 as long);
saved = echo(rng);
let box = new Box(saved);
let values: array<Random> = [box.value];
let draw = capture(rng);
let a = random.next(saved);
let b = random.next(box.value);
if let value = values[0] {
let c = random.next(value);
let d = draw();
let other = random.new(42 as long);
let e = random.next(other);
return (a: a, b: b, c: c, d: d, e: e);
}
return (0 as long, 0 as long, 0 as long, 0 as long, 0 as long);
}
}
""");
pair("named", """
declare global trace: int = 0;
declare struct Empty(pub value: Random) { ctor create() { this.value = random.new(9223372036854775807); } } declare global rng: Random = new Empty.create().value;
declare service Probe {
fn receiver() -> Random { trace = trace * 10 + 1; return rng; }
fn low() -> long { trace = trace * 10 + 2; random.next(rng); return -7; }
fn high() -> long { trace = trace * 10 + 3; random.next(rng); return -6; }
fn main() -> (trace: int, value: long, next: long) {
rng = random.new(42 as long); trace = 0;
let value = random.range apply (max: Probe.high(), rng: Probe.receiver(), min: Probe.low());
return (trace: trace, value: value, next: random.next(rng));
}
}
""");
pair("positional", """
declare global trace: int = 0;
declare struct Empty(pub value: Random) { ctor create() { this.value = random.new(9223372036854775807); } } declare global rng: Random = new Empty.create().value;
declare service Probe {
fn receiver() -> Random { trace = trace * 10 + 1; return rng; }
fn low() -> long { trace = trace * 10 + 2; random.next(rng); return -7; }
fn high() -> long { trace = trace * 10 + 3; random.next(rng); return -6; }
fn main() -> (trace: int, value: long, next: long) {
rng = random.new(42 as long); trace = 0;
let value = random.range(Probe.receiver(), Probe.low(), Probe.high());
return (trace: trace, value: value, next: random.next(rng));
}
}
""");
}
@Test void rangeBoundsAndControlledProviderNulls() throws Exception {
String[][] bounds = {{"0","1"},{"-10","-3"},{"-10","10"},{"0","16"},
{"-9223372036854775808","0"},{"-1","9223372036854775807"},{"-9223372036854775808","9223372036854775807"},
{"5","5"},{"6","5"}};
for (int i=0; i<bounds.length; i++)
pair("range-"+i, "declare service Probe { fn main() -> long { let rng = random.new(42 as long); let low: long = "+bounds[i][0]+"; let high: long = "+bounds[i][1]+"; return random.range(rng, low, high); } }");
pair("rejection", """
declare service Probe { fn main() -> (value: long, next: long) {
let rng = random.new(42 as long); random.next(rng);
let low: long = -9223372036854775808; let value = random.range(rng, low, 1 as long);
return (value: value, next: random.next(rng));
} }
""");
pair("null", "declare struct Empty(pub value: Random) { ctor create() { this.value = random.new(9223372036854775807); } } declare global empty: Random = new Empty.create().value; declare service Probe { fn main() -> long { return random.next(empty); } }");
pair("typed-null", """
declare struct Empty(pub value: Random) { ctor create() { this.value = random.new(9223372036854775807); } } declare global empty: Random = new Empty.create().value;
declare service Probe { fn main() -> long {
let values: array<Random> = [empty];
if let value = values[0] { return random.next(value); }
return 99;
} }
""");
}
@Test void incompatibleSourceCannotConstructOrAdaptRandom() throws Exception {
for (var body : new String[]{"new Random();", "random.new(true);", "let seed: int = 42; random.new(seed);",
"random.next(42);", "random.nextf(1.0);", "let rng = random.new(42 as long); random.range(rng, true, 2 as long);"}) {
var diagnostics = p.studio.compiler.source.diagnostics.DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new p.studio.compiler.source.identifiers.FileId(0),
sdk()+"declare service Probe { fn main() { "+body+" } }", diagnostics, p.studio.compiler.models.SourceKind.SDK_INTERFACE);
assertTrue(diagnostics.hasErrors(), body);
}
}
@Test void installedSdkImportsAndAliases(@org.junit.jupiter.api.io.TempDir java.nio.file.Path root) throws Exception {
java.nio.file.Files.createDirectories(root.resolve("src"));
java.nio.file.Files.writeString(root.resolve("prometeu.json"), """
{"name":"app","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
java.nio.file.Files.writeString(root.resolve("src/mod.barrel"), "pub fn frame() -> void;");
java.nio.file.Files.writeString(root.resolve("src/main.pbs"), """
import { Random as Generator, random as rng } from @sdk:random;
fn echo(value: Generator) -> Generator { return value; }
[Frame]
fn frame() -> void {
let generator: Generator = rng.new(42 as long);
let expected: long = -8740965581747508376;
if rng.next(echo(generator)) != expected { let fail = 1 / 0; }
if rng.range(generator, -7 as long, -6 as long) != -7 as long { let fail = 1 / 0; }
}
""");
var result = p.studio.compiler.workspaces.BuilderPipelineService.INSTANCE.compile(
p.studio.compiler.models.BuilderPipelineContext.fromConfig(new p.studio.compiler.messages.BuilderPipelineConfig(false,root.toString())),
p.studio.utilities.logs.LogAggregator.stdout());
assertFalse(result.diagnostics().stream().anyMatch(d->d.isError()),result.diagnostics().toString());
assertTrue(result.bytecodeBytes().length>0);
java.nio.file.Files.write(java.nio.file.Path.of(System.getProperty("pbs.registryConformanceDirectory"),"pbs-random-import.pbx"),result.bytecodeBytes());
}
@Test void referencesSurviveCollection() throws Exception {
pair("gc", """
declare struct Box(pub value: Random);
fn make() -> (items: array<Random>, draw: Fn() -> long, box: Box) {
let rng = random.new(42 as long);
let items: array<Random> = [rng];
let draw = fn [rng]() -> long { return random.next(rng); };
return (items: items, draw: draw, box: new Box(rng));
}
declare service Probe {
fn garbage() { random.new(1 as long); }
fn collect() { let marker = 314159; }
fn main() -> (a: long, b: long, c: long) {
let roots = make();
for i: int from 0 until 1100 { Probe.garbage(); }
Probe.collect();
if let rng = roots.items[0] {
let a = random.next(rng);
let draw = roots.draw;
let b = draw();
let c = random.next(roots.box.value);
return (a: a, b: b, c: c);
}
return (0 as long, 0 as long, 0 as long);
}
}
""");
}
@Test void opaqueValuesRejectFieldsAndStructuralAdaptation() throws Exception {
for (var source : new String[]{
"declare service Probe { fn main() -> long { let rng = random.new(42 as long); return rng.state; } }",
"declare struct Box(pub n: long); declare service Probe { fn main() -> Box { return random.new(42 as long); } }",
"declare contract Draw { fn draw() -> long; } declare service Probe { fn main() -> Draw { return random.new(42 as long); } }",
"declare contract Draw { fn draw() -> long; } declare service Probe { fn main() -> Draw { let rng = random.new(42 as long); return rng as Draw; } }"}) {
var failure = assertThrows(org.opentest4j.AssertionFailedError.class, () -> compile("invalid", source), source);
assertTrue(failure.getMessage().contains("E_SEM_"), failure.getMessage());
}
}
}
@@ -0,0 +1,507 @@
package p.studio.compiler.backend.irvm;
import org.junit.jupiter.api.Test;
import p.studio.compiler.pbs.PbsFrontendCompiler;
import p.studio.compiler.models.IRBackend;
import p.studio.compiler.models.IRBackendExecutableFunction;
import p.studio.compiler.backend.bytecode.*;
import p.studio.compiler.source.diagnostics.DiagnosticSink;
import p.studio.compiler.source.identifiers.FileId;
import p.studio.compiler.models.SourceKind;
import java.nio.file.*;
import p.studio.compiler.pbs.ast.PbsAst;
import p.studio.utilities.structures.ReadOnlyList;
import p.studio.compiler.source.identifiers.ModuleId;
import static org.junit.jupiter.api.Assertions.*;
class PbsStructuredValuesTest {
static BytecodeModule compile(String name,String source) throws Exception {
var diagnostics=DiagnosticSink.empty();
var fileId = new FileId(0);
var ast = p.studio.compiler.pbs.parser.PbsParser.parse(p.studio.compiler.pbs.lexer.PbsLexer.lex(source,fileId,diagnostics),fileId,diagnostics,p.studio.compiler.pbs.parser.PbsParser.ParseMode.INTERFACE_MODULE);
var file=new PbsFrontendCompiler().compileParsedFile(fileId,ast,diagnostics,source.contains("[BuiltinType") ? SourceKind.SDK_INTERFACE : SourceKind.PROJECT,
new p.studio.compiler.source.identifiers.ModuleId(0),p.studio.utilities.structures.ReadOnlyList.empty(),
p.studio.compiler.messages.HostAdmissionContext.permissiveDefault(),p.studio.compiler.messages.FESurfaceContext.empty(),new p.studio.compiler.source.tables.NameTable());
assertFalse(diagnostics.hasErrors(), ()->diagnostics.stream().map(d->d.getCode()+":"+d.getMessage()).toList().toString());
var functions = new java.util.ArrayList<>(file.executableFunctions().asList());
var signatures = new java.util.ArrayList<>(file.callableSignatures().asList());
String entry = "Probe.main";
var initializer = functions.stream().filter(f -> f.callableName().startsWith("__pbs.file_init$")).findFirst();
if (initializer.isPresent()) {
// The fixture driver performs the same ordered file-init call as the production lifecycle wrapper.
var main = functions.stream().filter(f -> f.callableName().equals("Probe.main")).findFirst().orElseThrow();
var init = initializer.get();
var id = new p.studio.compiler.source.identifiers.CallableId(signatures.size());
entry = "$test.entry";
signatures.add(new p.studio.compiler.source.tables.CallableSignatureRef(new ModuleId(0),entry,0,"()->simple:int"));
var kind = IRBackendExecutableFunction.InstructionKind.RET;
var instructions = ReadOnlyList.from(
new IRBackendExecutableFunction.Instruction(IRBackendExecutableFunction.InstructionKind.CALL_FUNC,
new ModuleId(0),init.callableName(),init.callableId(),null,null,0,0,init.span()),
new IRBackendExecutableFunction.Instruction(IRBackendExecutableFunction.InstructionKind.CALL_FUNC,
new ModuleId(0),main.callableName(),main.callableId(),null,null,0,1,main.span()),
new IRBackendExecutableFunction.Instruction(kind,"",null,null,main.span()));
functions.add(new IRBackendExecutableFunction(fileId,new ModuleId(0),entry,id,0,0,0,0,1,1,instructions,main.span(),main.metadata()));
}
var backend=IRBackend.builder().entryPointCallableName(entry).entryPointModuleId(new ModuleId(0)).executableFunctions(ReadOnlyList.wrap(functions))
.globals(file.globals()).registry(file.registry()).intrinsicPool(file.intrinsicPool()).callableSignatures(ReadOnlyList.wrap(signatures)).build();
var program=new LowerToIRVMService().lower(backend);
var module=new BytecodeEmitter().emit(program.coherentEmissionPlan());
if (name.equals("gc-roots")) module = withTestSafepoint(module);
new BytecodePreloadVerifierService().verify(module);
var directory=Path.of(System.getProperty("pbs.registryConformanceDirectory"));Files.createDirectories(directory);
Files.write(directory.resolve("pbs-structured-"+name+".pbx"),module.serialize());
return module;
}
// PBS sync/closure syntax belongs to AGD82. This test-only driver hook replaces
// an isolated marker assignment with FRAME_SYNC + NOPs, preserving every offset.
// All allocations, roots, field/array access and post-GC assertions are compiled PBS.
static BytecodeModule withTestSafepoint(BytecodeModule module) {
byte[] code = module.code().clone();
var marker = java.nio.ByteBuffer.allocate(6).order(java.nio.ByteOrder.LITTLE_ENDIAN)
.putShort((short) 0x17).putInt(314159).array();
int found = 0;
for (int offset = 0; offset + 12 <= code.length; offset++) {
if (!java.util.Arrays.equals(marker, java.util.Arrays.copyOfRange(code, offset, offset + 6))) continue;
assertEquals(0x43, code[offset + 6]);
assertEquals(0, code[offset + 7]);
java.util.Arrays.fill(code, offset, offset + 12, (byte) 0);
code[offset] = (byte) 0x80;
found++;
}
assertEquals(1, found, "exactly one test safepoint marker");
return new BytecodeModule(module.version(), module.constPool(), module.functions(), code,
module.debugInfo(), module.exports(), module.syscalls(), module.registry(), module.intrinsicSignatures());
}
@Test void arraysAndOptionalReachProductionPbx() throws Exception {
compile("array-cycle", """
declare service Probe {
fn main() -> int {
let count: int = 3;
let values: array<int> = new array(count);
let index: int = 1;
values[index] = 42;
let answer = values[index] else 0;
values.clear(index);
if let absent = values[index] { return 999; }
return answer;
}
}
""");
}
@Test void literalsAndNestingReachProductionPbx() throws Exception {
compile("array-nested", """
declare service Probe {
fn main() -> int {
let groups: array<array<int>> = new array(3);
groups[0] = [10, 42];
if let group = groups[0] {
if let value = group[1] { return value; }
}
return 0;
}
}
""");
}
@Test void optionalFunctionAndLazyFallbackReachProductionPbx() throws Exception {
compile("optional-flow", """
declare service Probe {
fn present() -> optional int { return some(42); }
fn absent() -> optional int { return none; }
fn main() -> int {
let value: optional int = Probe.present();
if let answer = value { return answer; }
return Probe.absent() else 0;
}
}
""");
}
@Test void structsConstructorsAndContractsReachProductionPbx() throws Exception {
compile("struct-contract", """
declare contract Target { fn health() -> int; }
declare struct Enemy(pub mut hp: int) {
ctor create(hp: int) { this.hp = hp; }
fn damage(amount: int) { this.hp -= amount; }
fn health() -> int { return this.hp; }
}
implements Target for Enemy using enemy { fn health() -> int { return enemy.health(); } }
declare service Probe {
fn main() -> int {
let enemies: array<Enemy> = new array(2);
let enemy = new Enemy.create(50);
enemies[0] = enemy;
if let selected = enemies[0] { selected.damage(8); }
let target: Target = enemy;
return target.health();
}
}
""");
}
@Test void serviceContractAndOptionalGroupsReachProductionPbx() throws Exception {
compile("service-contract", """
declare contract Answer { fn value() -> int; }
declare service Source { fn value() -> int { return 42; } }
implements Answer for Source using source { fn value() -> int { return source.value(); } }
declare service Probe {
fn main() -> int {
let first: Answer = Source;
let second: Answer = Source;
return first.value();
}
}
""");
compile("optional-tuple", """
declare service Probe {
fn pair() -> optional (left: int, right: int) { return some((left: 20, right: 22)); }
fn main() -> int {
if let pair = Probe.pair() { return pair.left + pair.right; }
return 0;
}
}
""");
}
@Test void tupleStorageAndOptionalIntrinsicsReachProductionPbx() throws Exception {
compile("tuple-storage", """
declare struct Pair(pub mut value: (left: int, right: int)) {}
declare service Probe {
fn main() -> int {
let values: array<(left: int, right: int)> = [(left: 20, right: 22)];
if let pair = values[0] {
let holder = new Pair(pair);
holder.value = (left: 21, right: 21);
return holder.value.left + holder.value.right;
}
return 0;
}
}
""");
compile("optional-intrinsics", """
declare service Probe {
fn absent() -> optional int {}
fn main() -> int {
let values: array<int> = [0];
if values[0].hasSome() {
if Probe.absent().hasNone() { return 42; }
}
return 0;
}
}
""");
compile("optional-lazy", """
declare service Probe {
fn forbidden() -> int {
let empty: array<int> = [];
return empty[0] else 999;
}
fn main() -> int {
let value: optional int = some(42);
return value else Probe.forbidden();
}
}
""");
}
@Test void contextualArraysAndAliasReachProductionPbx() throws Exception {
compile("array-context", """
declare service Probe {
fn make() -> array<int> { return [20, 22]; }
fn sum(values: array<int>) -> int { return (values[0] else 0) + (values[1] else 0); }
fn main() -> int {
let values: array<int> = { [1, 2] };
let alias = values;
alias[0] = 20;
alias[1] = 22;
let answer = Probe.sum(values);
if answer != Probe.sum([20, 22]) { return 999; }
if answer != Probe.sum(Probe.make()) { return 998; }
return answer;
}
}
""");
compile("binding-scope", """
declare service Probe {
fn main() -> int {
let answer = 42;
let value: optional int = some(8);
if let answer = value { let ignored = answer; }
return answer;
}
}
""");
}
@Test void overloadsAndEvaluationOrderReachProductionPbx() throws Exception {
compile("overloads", """
declare struct Enemy(pub hp: int) {
ctor create(value: int) { this.hp = value; }
ctor create(value: bool) { this.hp = 999; }
fn add(value: int) -> int { return this.hp + value; }
fn add(value: bool) -> int { return 999; }
}
declare service Probe {
fn main() -> int { return new Enemy.create(40).add(2); }
}
""");
compile("single-evaluation", """
declare struct Counter(pub mut count: int) {
fn next() -> int { this.count += 1; return this.count - 1; }
fn present() -> optional int { this.count += 1; return some(42); }
}
declare service Probe {
fn main() -> int {
let counter = new Counter(0);
let values: array<int> = new array(2);
values[counter.next()] = counter.next();
if counter.count != 2 { return 999; }
if (values[0] else 99) != 1 { return 998; }
if let value = counter.present() {
if counter.count == 3 { return value; }
}
return 997;
}
}
""");
}
@Test void boundsFixturesReachProductionPbx() throws Exception {
for (var entry : java.util.Map.of(
"negative-index", "let a: array<int> = new array(1); return a[-1] else 42;",
"past-end", "let a: array<int> = new array(1); return a[1] else 42;",
"negative-length", "let size: int = -1; let a: array<int> = new array(size); return 42;",
"large-length", "let size: long = 4294967296; let a: array<int> = new array(size); return 42;"
).entrySet()) compile(entry.getKey(), "declare service Probe { fn main() -> int { " + entry.getValue() + " } }");
compile("long-boundaries", """
declare service Probe {
fn main() -> int {
let size: long = 2;
let a: array<int> = new array(size);
let first: long = 0;
let last: int = 1;
a[first] = 20;
a[last] = 22;
if a.length != size { return 999; }
return (a[first] else 0) + (a[last] else 0);
}
}
""");
}
@Test void sourceOwnedGroupsSurviveRuntimeSafepoint() throws Exception {
compile("gc-roots", """
declare struct Enemy(pub hp: int) {}
declare service Probe {
fn garbage() { let discarded: array<int> = new array(1); }
fn gcCollect() { let marker = 314159; }
fn main() -> int {
let keep: array<Enemy> = [new Enemy(42)];
let tuples: array<(left: int, right: int)> = [(left: 20, right: 22)];
let names: array<str> = new array(2);
names[0] = "enemy";
for i: int from 0 until 1100 { Probe.garbage(); }
Probe.gcCollect();
if let unexpected = names[1] { return 997; }
if (names[0] else "missing") != "enemy" { return 996; }
if let enemy = keep[0] {
if let pair = tuples[0] {
if pair.left + pair.right == enemy.hp { return enemy.hp; }
}
}
return 999;
}
}
""");
}
@Test void nativeGroupsAndContractElementsReachProductionPbx() throws Exception {
compile("native-groups", """
[BuiltinType(name = "vec2", version = 1)]
declare builtin type Vector(pub x: float, pub y: float) {}
declare service Probe {
fn main() -> int {
let vectors: array<Vector> = [new Vector(20.0, 22.0)];
let vector = vectors[0] else new Vector(0.0, 0.0);
return (vector.x + vector.y) as int;
}
}
""");
compile("contract-elements", """
declare contract Target { fn health() -> int; }
declare struct Enemy(pub hp: int) { fn same() -> Self { return this; } }
implements Target for Enemy using enemy { fn health() -> int { return enemy.hp; } }
declare service Probe {
fn main() -> int {
let enemy = new Enemy(42);
let targets: array<Target> = [enemy as Target];
if let target = targets[0] { return target.health(); }
return 999;
}
}
""");
}
@Test void importedStructAndServiceUseProviderIdentity() throws Exception {
var diagnostics = DiagnosticSink.empty();
String providerSource = """
declare contract Answer { fn answer() -> int; }
declare struct Enemy(pub hp: int) {
ctor create(hp: int) { this.hp = hp; }
fn health() -> int { return this.hp; }
}
implements Answer for Enemy using enemy { fn answer() -> int { return enemy.hp; } }
declare service Source { fn value() -> int { return 42; } }
""";
String clientSource = """
declare service Probe {
fn main() -> int {
let values: array<Enemy> = [new Enemy.create(42)];
let first = Source;
let second = Source;
if first != second { return 999; }
if let enemy = values[0] {
let target: Answer = enemy as Answer;
if enemy.health() == first.value() { return target.answer(); }
}
return 998;
}
}
""";
var compiler = new PbsFrontendCompiler();
var host = p.studio.compiler.messages.HostAdmissionContext.permissiveDefault();
var surface = p.studio.compiler.messages.FESurfaceContext.empty();
var names = new p.studio.compiler.source.tables.NameTable();
var providerId = new FileId(10);
var providerAst = p.studio.compiler.pbs.parser.PbsParser.parse(
p.studio.compiler.pbs.lexer.PbsLexer.lex(providerSource, providerId, diagnostics), providerId, diagnostics,
p.studio.compiler.pbs.parser.PbsParser.ParseMode.INTERFACE_MODULE);
var modules = ReadOnlyList.from(new p.studio.compiler.source.tables.ModuleReference("test",ReadOnlyList.from("provider")),
new p.studio.compiler.source.tables.ModuleReference("test",ReadOnlyList.from("client")));
var provider = compiler.compileParsedFile(providerId, providerAst, diagnostics, SourceKind.PROJECT,
new ModuleId(0), modules, host, surface, names);
var imported = new java.util.ArrayList<PbsFrontendCompiler.ImportedCallableSurface>();
for (var signature : provider.callableSignatures()) {
var executable = provider.executableFunctions().stream().filter(f -> f.callableName().equals(signature.callableName())).findFirst().orElseThrow();
var type = signature.callableName().endsWith("$instance") ? PbsAst.TypeRef.simple("Source",providerAst.span())
: executable.returnSlots() == 0 ? PbsAst.TypeRef.unit(providerAst.span()) : PbsAst.TypeRef.simple("int",providerAst.span());
imported.add(new PbsFrontendCompiler.ImportedCallableSurface(new ModuleId(0),signature.callableName(), signature.arity(),
executable.returnSlots(), executable.returnSlots()==0?PbsAst.ReturnKind.EXPLICIT_UNIT:PbsAst.ReturnKind.PLAIN, type, signature.typeShape()));
}
var clientId = new FileId(11);
var clientAst = p.studio.compiler.pbs.parser.PbsParser.parse(
p.studio.compiler.pbs.lexer.PbsLexer.lex(clientSource, clientId, diagnostics), clientId, diagnostics,
p.studio.compiler.pbs.parser.PbsParser.ParseMode.INTERFACE_MODULE);
var client = compiler.compileParsedFile(clientId, clientAst, diagnostics, SourceKind.PROJECT, new ModuleId(1),modules,
host,surface,names,providerAst.topDecls(),ReadOnlyList.wrap(imported),ReadOnlyList.empty(),
p.studio.compiler.models.IRReservedMetadata.empty(),java.util.Map.of());
assertFalse(diagnostics.hasErrors(), () -> diagnostics.stream().map(d -> d.getCode()+":"+d.getMessage()).toList().toString());
var aggregator = IRBackend.aggregator();
aggregator.merge(provider); aggregator.merge(client);
var backend = aggregator.entryPointCallableName("Probe.main").entryPointModuleId(new ModuleId(1)).emit();
var program = new LowerToIRVMService().lower(backend);
var module = new BytecodeEmitter().emit(program.coherentEmissionPlan());
new BytecodePreloadVerifierService().verify(module);
Files.write(Path.of(System.getProperty("pbs.registryConformanceDirectory"),"pbs-structured-imports.pbx"),module.serialize());
}
@Test void globalArraysAreInitializedBeforeUse() throws Exception {
compile("global-array", """
declare global values: array<int> = [20, 22];
declare global empty: array<int> = new array(3);
declare service Probe {
fn main() -> int {
if empty.length != 3 as long { return 999; }
if let unexpected = empty[0] { return 998; }
return (values[0] else 0) + (values[1] else 0);
}
}
""");
}
@Test void installedArrayExampleExecutes() throws Exception {
try (var stream = PbsFrontendCompiler.class.getResourceAsStream("/pbs-knowledge/examples/game/1/src/arrays.pbs")) {
assertNotNull(stream);
var source = new String(stream.readAllBytes(),java.nio.charset.StandardCharsets.UTF_8);
compile("installed-example",source+"\ndeclare service Probe { fn main() -> int { return arrayExample(); } }");
}
}
@Test void returnOverloadsAndInferredOptionalGroupsExecute() throws Exception {
compile("return-overloads", """
declare struct Box(pub n: int) {
fn get() -> int { return this.n; }
fn get() -> long { return 999; }
fn same() -> Self { return this; }
}
declare service Probe {
fn main() -> int {
let box = new Box(42);
let answer: int = box.same().get();
return answer;
}
}
""");
compile("inferred-optional-tuple", """
declare service Probe {
fn main() -> int {
let value = some((left: 20, right: 22));
if let pair = value { return pair.left + pair.right; }
return 999;
}
}
""");
}
@Test void integerStorageNeedsOnlyTheArrayHandle() throws Exception {
compile("inline-integers", """
declare service Probe {
fn main() -> int {
let values: array<int> = [10, 20, 30];
return (values.length as int) + 39;
}
}
""");
}
@Test void parametricConstructorsReachProductionPbx() throws Exception {
compile("array-parametric", """
declare global saved: array<int>=new array<>(1);
declare service Probe {
fn make() -> array<int> { return new array<>(1); }
fn size(values: array<int>) -> int { return values.length as int; }
fn main() -> int {
let inferred = new array<int>(2);
let alias = inferred;
alias[0] = 20;
let nested: array<array<int>>=new array<>(2);
if let unexpected = nested[0] { return 999; }
nested[0] = inferred;
let explicitNested = new array<array<int>>(1);
explicitNested[0] = new array<int>(1);
saved = new array<>(1);
saved[0] = 18;
let fromReturn = Probe.make();
let count = Probe.size(new array<>(1)) + Probe.size(new array(1));
if 2 >= 1 {
return (inferred[0] else 0) + (saved[0] else 0) + count
+ (fromReturn.length as int) + (explicitNested.length as int);
}
return 999;
}
}
""");
}
@Test void invalidArraySurfacesAreRejected() {
for(var body : new String[] {
"let values = new array<>(3);",
"let values = new array<Missing>(3);",
"let values = new array<optional int>(3);",
"let values = new array<void>(3);",
"let values: array<int> = new array<bool>(3);",
"let values: array int = new array(3);", // removed syntax
"let values: array<int>[2] = new array(3);", // removed depth notation
"let values = [1, 2];", "let values = [];", "let values = new array(3);",
"let values: array<(optional int)> = new array(3);",
"let values: array[2147483647] int = new array(3);", "let values: array[0] int = new array(3);", "let values: array[-1] int = new array(3);",
"let values: array<int> = new array(3); let x = values[true];",
"let values: array<int> = new array(3); values[0] = true;",
"if let value = 42 { let x = value; }",
"let value: optional int = some(1); if let found = value {} let bad = found;",
"let value: optional int = some(1); if let found = value {} else { let bad = found; }",
"let values: array<int> = new array(3); let wrong: array<bool> = values;"
}) {
var diagnostics=DiagnosticSink.empty();
new PbsFrontendCompiler().compileFile(new FileId(0),"fn main() { "+body+" }",diagnostics);
assertTrue(diagnostics.hasErrors(), body);
}
}
}
@@ -0,0 +1,261 @@
3000 i:7 i:3 i:3 2
3001 i:7 i:3 i:7 2
3002 i:9 i:0 i:5 i:5 4
3003 i:-7 i:7 2
3004 l:2147483648 l:2147483649 l:2147483648 2
3005 l:2147483648 l:2147483649 l:2147483649 2
3006 l:9 l:0 l:5 l:5 4
3007 l:-7 l:7 2
3008 f:8000000000000000 f:0000000000000000 f:8000000000000000 2
3009 f:8000000000000000 f:0000000000000000 f:0000000000000000 2
300a f:8000000000000000 f:0000000000000000 f:3ff0000000000000 f:0000000000000000 4
300b f:8000000000000000 f:0000000000000000 2
3013 f:3ff0000000000000 f:0000000000000000 f:3ff921fb54442d18 48
3014 i:-2147483648 l:-2147483648 2
3015 l:2147483647 i:2147483647 2
3016 i:2147483647 f:41dfffffffc00000 2
3017 l:9223372036854775807 f:43e0000000000000 2
3003 i:-2147483648 trap:13 2
3007 l:-9223372036854775808 trap:13 2
3002 i:0 i:2 i:1 trap:12 4
300a f:0000000000000000 f:4000000000000000 f:3ff0000000000000 trap:12 4
3010 f:bff0000000000000 trap:12 16
3013 f:0000000000000000 f:0000000000000000 trap:12 48
3013 f:8000000000000000 f:bff0000000000000 f:c00921fb54442d18 48
3013 f:0000000000000000 f:bff0000000000000 f:400921fb54442d18 48
300f f:4004000000000000 f:4000000000000000 4
300f f:400c000000000000 f:4010000000000000 4
3015 l:2147483648 trap:13 2
3018 f:41e0000000000000 trap:13 2
3019 f:43e0000000000000 trap:13 2
3019 f:c3e0000000000000 l:-9223372036854775808 2
3017 l:9007199254740993 f:4340000000000000 2
3010 f:0000000000000000 f:0000000000000000 16
300c f:0000000000000000 f:0000000000000000 4
300d f:0000000000000000 f:0000000000000000 4
300e f:0000000000000000 f:0000000000000000 4
300f f:0000000000000000 f:0000000000000000 4
3018 f:0000000000000000 i:0 2
3019 f:0000000000000000 l:0 2
3011 f:0000000000000000 f:0000000000000000 32
3012 f:0000000000000000 f:3ff0000000000000 32
3011 f:8000000000000000 f:8000000000000000 32
3012 f:8000000000000000 f:3ff0000000000000 32
3013 f:0000000000000000 f:54edb5f397cc207d f:0000000000000000 48
3010 f:0000000000000001 f:1e60000000000000 16
300c f:0000000000000001 f:0000000000000000 4
300d f:0000000000000001 f:3ff0000000000000 4
300e f:0000000000000001 f:0000000000000000 4
300f f:0000000000000001 f:0000000000000000 4
3018 f:0000000000000001 i:0 2
3019 f:0000000000000001 l:0 2
3011 f:0000000000000001 f:0000000000000001 32
3012 f:0000000000000001 f:3ff0000000000000 32
3011 f:8000000000000001 f:8000000000000001 32
3012 f:8000000000000001 f:3ff0000000000000 32
3013 f:0000000000000001 f:823a3f3c9decf2dd f:400921fb54442d18 48
3010 f:0000000000000002 f:1e66a09e667f3bcd 16
300c f:0000000000000002 f:0000000000000000 4
300d f:0000000000000002 f:3ff0000000000000 4
300e f:0000000000000002 f:0000000000000000 4
300f f:0000000000000002 f:0000000000000000 4
3018 f:0000000000000002 i:0 2
3019 f:0000000000000002 l:0 2
3011 f:0000000000000002 f:0000000000000002 32
3012 f:0000000000000002 f:3ff0000000000000 32
3011 f:8000000000000002 f:8000000000000002 32
3012 f:8000000000000002 f:3ff0000000000000 32
3013 f:0000000000000002 f:8c9f4dfeacaf0126 f:400921fb54442d18 48
3010 f:000fffffffffffff f:1fffffffffffffff 16
300c f:000fffffffffffff f:0000000000000000 4
300d f:000fffffffffffff f:3ff0000000000000 4
300e f:000fffffffffffff f:0000000000000000 4
300f f:000fffffffffffff f:0000000000000000 4
3018 f:000fffffffffffff i:0 2
3019 f:000fffffffffffff l:0 2
3011 f:000fffffffffffff f:000fffffffffffff 32
3012 f:000fffffffffffff f:3ff0000000000000 32
3011 f:800fffffffffffff f:800fffffffffffff 32
3012 f:800fffffffffffff f:3ff0000000000000 32
3013 f:000fffffffffffff f:09ed7f8a283eb81c f:36115b63b5562616 48
3010 f:0010000000000000 f:2000000000000000 16
300c f:0010000000000000 f:0000000000000000 4
300d f:0010000000000000 f:3ff0000000000000 4
300e f:0010000000000000 f:0000000000000000 4
300f f:0010000000000000 f:0000000000000000 4
3018 f:0010000000000000 i:0 2
3019 f:0010000000000000 l:0 2
3011 f:0010000000000000 f:0010000000000000 32
3012 f:0010000000000000 f:3ff0000000000000 32
3011 f:8010000000000000 f:8010000000000000 32
3012 f:8010000000000000 f:3ff0000000000000 32
3013 f:0010000000000000 f:3feffffffffffffe f:0010000000000001 48
3010 f:3fdfffffffffffff f:3fe6a09e667f3bcc 16
300c f:3fdfffffffffffff f:0000000000000000 4
300d f:3fdfffffffffffff f:3ff0000000000000 4
300e f:3fdfffffffffffff f:0000000000000000 4
300f f:3fdfffffffffffff f:0000000000000000 4
3018 f:3fdfffffffffffff i:0 2
3019 f:3fdfffffffffffff l:0 2
3011 f:3fdfffffffffffff f:3fdeaee8744b05ef 32
3012 f:3fdfffffffffffff f:3fec1528065b7d50 32
3011 f:bfdfffffffffffff f:bfdeaee8744b05ef 32
3012 f:bfdfffffffffffff f:3fec1528065b7d50 32
3013 f:3fdfffffffffffff f:07faa1d222d1148d f:3ff921fb54442d18 48
3010 f:3fe0000000000000 f:3fe6a09e667f3bcd 16
300c f:3fe0000000000000 f:0000000000000000 4
300d f:3fe0000000000000 f:3ff0000000000000 4
300e f:3fe0000000000000 f:0000000000000000 4
300f f:3fe0000000000000 f:0000000000000000 4
3018 f:3fe0000000000000 i:0 2
3019 f:3fe0000000000000 l:0 2
3011 f:3fe0000000000000 f:3fdeaee8744b05f0 32
3012 f:3fe0000000000000 f:3fec1528065b7d50 32
3011 f:bfe0000000000000 f:bfdeaee8744b05f0 32
3012 f:bfe0000000000000 f:3fec1528065b7d50 32
3013 f:3fe0000000000000 f:ad7bbd56db31c9ec f:3ff921fb54442d18 48
3010 f:3fe0000000000001 f:3fe6a09e667f3bcd 16
300c f:3fe0000000000001 f:0000000000000000 4
300d f:3fe0000000000001 f:3ff0000000000000 4
300e f:3fe0000000000001 f:0000000000000000 4
300f f:3fe0000000000001 f:3ff0000000000000 4
3018 f:3fe0000000000001 i:0 2
3019 f:3fe0000000000001 l:0 2
3011 f:3fe0000000000001 f:3fdeaee8744b05f2 32
3012 f:3fe0000000000001 f:3fec1528065b7d4f 32
3011 f:bfe0000000000001 f:bfdeaee8744b05f2 32
3012 f:bfe0000000000001 f:3fec1528065b7d4f 32
3013 f:3fe0000000000001 f:3ffffffffffffffe f:3fcf5b75f92c80e1 48
3010 f:3ff0000000000000 f:3ff0000000000000 16
300c f:3ff0000000000000 f:3ff0000000000000 4
300d f:3ff0000000000000 f:3ff0000000000000 4
300e f:3ff0000000000000 f:3ff0000000000000 4
300f f:3ff0000000000000 f:3ff0000000000000 4
3018 f:3ff0000000000000 i:1 2
3019 f:3ff0000000000000 l:1 2
3011 f:3ff0000000000000 f:3feaed548f090cee 32
3012 f:3ff0000000000000 f:3fe14a280fb5068c 32
3011 f:bff0000000000000 f:bfeaed548f090cee 32
3012 f:bff0000000000000 f:3fe14a280fb5068c 32
3013 f:3ff0000000000000 f:3fe0000000000002 f:3ff1b6e192ebbe44 48
3010 f:4000000000000000 f:3ff6a09e667f3bcd 16
300c f:4000000000000000 f:4000000000000000 4
300d f:4000000000000000 f:4000000000000000 4
300e f:4000000000000000 f:4000000000000000 4
300f f:4000000000000000 f:4000000000000000 4
3018 f:4000000000000000 i:2 2
3019 f:4000000000000000 l:2 2
3011 f:4000000000000000 f:3fed18f6ead1b446 32
3012 f:4000000000000000 f:bfdaa22657537205 32
3011 f:c000000000000000 f:bfed18f6ead1b446 32
3012 f:c000000000000000 f:bfdaa22657537205 32
3013 f:4000000000000000 f:3ff921fb54442d18 f:3fecf5f1e82b5390 48
3010 f:3ff921fb54442d18 f:3ff40d931ff62705 16
300c f:3ff921fb54442d18 f:3ff0000000000000 4
300d f:3ff921fb54442d18 f:4000000000000000 4
300e f:3ff921fb54442d18 f:3ff0000000000000 4
300f f:3ff921fb54442d18 f:4000000000000000 4
3018 f:3ff921fb54442d18 i:1 2
3019 f:3ff921fb54442d18 l:1 2
3011 f:3ff921fb54442d18 f:3ff0000000000000 32
3012 f:3ff921fb54442d18 f:3c91a62633145c07 32
3011 f:bff921fb54442d18 f:bff0000000000000 32
3012 f:bff921fb54442d18 f:3c91a62633145c07 32
3013 f:3ff921fb54442d18 f:ea3931a1dc0ba585 f:400921fb54442d18 48
3010 f:400921fb54442d18 f:3ffc5bf891b4ef6a 16
300c f:400921fb54442d18 f:4008000000000000 4
300d f:400921fb54442d18 f:4010000000000000 4
300e f:400921fb54442d18 f:4008000000000000 4
300f f:400921fb54442d18 f:4008000000000000 4
3018 f:400921fb54442d18 i:3 2
3019 f:400921fb54442d18 l:3 2
3011 f:400921fb54442d18 f:3ca1a62633145c07 32
3012 f:400921fb54442d18 f:bff0000000000000 32
3011 f:c00921fb54442d18 f:bca1a62633145c07 32
3012 f:c00921fb54442d18 f:bff0000000000000 32
3013 f:400921fb54442d18 f:7103ecf9a81fd654 f:0ef42e61ed6e3c59 48
3010 f:401921fb54442d18 f:40040d931ff62705 16
300c f:401921fb54442d18 f:4018000000000000 4
300d f:401921fb54442d18 f:401c000000000000 4
300e f:401921fb54442d18 f:4018000000000000 4
300f f:401921fb54442d18 f:4018000000000000 4
3018 f:401921fb54442d18 i:6 2
3019 f:401921fb54442d18 l:6 2
3011 f:401921fb54442d18 f:bcb1a62633145c07 32
3012 f:401921fb54442d18 f:3ff0000000000000 32
3011 f:c01921fb54442d18 f:3cb1a62633145c07 32
3012 f:c01921fb54442d18 f:3ff0000000000000 32
3013 f:401921fb54442d18 f:22f1a991580a3c2b f:3ff921fb54442d18 48
3010 f:7fefffffffffffff f:5fefffffffffffff 16
300c f:7fefffffffffffff f:7fefffffffffffff 4
300d f:7fefffffffffffff f:7fefffffffffffff 4
300e f:7fefffffffffffff f:7fefffffffffffff 4
300f f:7fefffffffffffff f:7fefffffffffffff 4
3018 f:7fefffffffffffff trap:13 2
3019 f:7fefffffffffffff trap:13 2
3011 f:7fefffffffffffff f:3f7452fc98b34e97 32
3012 f:7fefffffffffffff f:bfefffe62ecfab75 32
3011 f:ffefffffffffffff f:bf7452fc98b34e97 32
3012 f:ffefffffffffffff f:bfefffe62ecfab75 32
3013 f:7fefffffffffffff f:3ff921fb54442d19 f:3ff921fb54442d18 48
3010 f:000ffffffffffffe f:1ffffffffffffffe 16
300c f:000ffffffffffffe f:0000000000000000 4
300d f:000ffffffffffffe f:3ff0000000000000 4
300e f:000ffffffffffffe f:0000000000000000 4
300f f:000ffffffffffffe f:0000000000000000 4
3018 f:000ffffffffffffe i:0 2
3019 f:000ffffffffffffe l:0 2
3011 f:000ffffffffffffe f:000ffffffffffffe 32
3012 f:000ffffffffffffe f:3ff0000000000000 32
3011 f:800ffffffffffffe f:800ffffffffffffe 32
3012 f:800ffffffffffffe f:3ff0000000000000 32
3013 f:000ffffffffffffe f:074caaf9d0e6af80 f:38b1dc162179e06b 48
3013 f:000fffffffffffff f:272b6a7c6b3a7cd8 f:18d2acdd5ccefbb4 48
3010 f:0010000000000001 f:2000000000000000 16
300c f:0010000000000001 f:0000000000000000 4
300d f:0010000000000001 f:3ff0000000000000 4
300e f:0010000000000001 f:0000000000000000 4
300f f:0010000000000001 f:0000000000000000 4
3018 f:0010000000000001 i:0 2
3019 f:0010000000000001 l:0 2
3011 f:0010000000000001 f:0010000000000001 32
3012 f:0010000000000001 f:3ff0000000000000 32
3011 f:8010000000000001 f:8010000000000001 32
3012 f:8010000000000001 f:3ff0000000000000 32
3013 f:0010000000000001 f:3feffffffffffffe f:0010000000000002 48
3010 f:0010000000000002 f:2000000000000001 16
300c f:0010000000000002 f:0000000000000000 4
300d f:0010000000000002 f:3ff0000000000000 4
300e f:0010000000000002 f:0000000000000000 4
300f f:0010000000000002 f:0000000000000000 4
3018 f:0010000000000002 i:0 2
3019 f:0010000000000002 l:0 2
3011 f:0010000000000002 f:0010000000000002 32
3012 f:0010000000000002 f:3ff0000000000000 32
3011 f:8010000000000002 f:8010000000000002 32
3012 f:8010000000000002 f:3ff0000000000000 32
3013 f:0010000000000002 f:7721df366e8fb3fd f:0000000000000000 48
3010 f:3fdffffffffffffd f:3fe6a09e667f3bcc 16
300c f:3fdffffffffffffd f:0000000000000000 4
300d f:3fdffffffffffffd f:3ff0000000000000 4
300e f:3fdffffffffffffd f:0000000000000000 4
300f f:3fdffffffffffffd f:0000000000000000 4
3018 f:3fdffffffffffffd i:0 2
3019 f:3fdffffffffffffd l:0 2
3011 f:3fdffffffffffffd f:3fdeaee8744b05ed 32
3012 f:3fdffffffffffffd f:3fec1528065b7d50 32
3011 f:bfdffffffffffffd f:bfdeaee8744b05ed 32
3012 f:bfdffffffffffffd f:3fec1528065b7d50 32
3013 f:3fdffffffffffffd f:7feffffffffffffe f:0002000000000000 48
3010 f:3fdffffffffffffe f:3fe6a09e667f3bcc 16
300c f:3fdffffffffffffe f:0000000000000000 4
300d f:3fdffffffffffffe f:3ff0000000000000 4
300e f:3fdffffffffffffe f:0000000000000000 4
300f f:3fdffffffffffffe f:0000000000000000 4
3018 f:3fdffffffffffffe i:0 2
3019 f:3fdffffffffffffe l:0 2
3011 f:3fdffffffffffffe f:3fdeaee8744b05ee 32
3012 f:3fdffffffffffffe f:3fec1528065b7d50 32
3011 f:bfdffffffffffffe f:bfdeaee8744b05ee 32
3012 f:bfdffffffffffffe f:3fec1528065b7d50 32
3013 f:3fdffffffffffffe f:401921fb54442d17 f:3fb45438e80932c3 48
1 3000 i:7 i:3 i:3 2
2 3001 i:7 i:3 i:7 2
3 3002 i:9 i:0 i:5 i:5 4
4 3003 i:-7 i:7 2
5 3004 l:2147483648 l:2147483649 l:2147483648 2
6 3005 l:2147483648 l:2147483649 l:2147483649 2
7 3006 l:9 l:0 l:5 l:5 4
8 3007 l:-7 l:7 2
9 3008 f:8000000000000000 f:0000000000000000 f:8000000000000000 2
10 3009 f:8000000000000000 f:0000000000000000 f:0000000000000000 2
11 300a f:8000000000000000 f:0000000000000000 f:3ff0000000000000 f:0000000000000000 4
12 300b f:8000000000000000 f:0000000000000000 2
13 3013 f:3ff0000000000000 f:0000000000000000 f:3ff921fb54442d18 48
14 3014 i:-2147483648 l:-2147483648 2
15 3015 l:2147483647 i:2147483647 2
16 3016 i:2147483647 f:41dfffffffc00000 2
17 3017 l:9223372036854775807 f:43e0000000000000 2
18 3003 i:-2147483648 trap:13 2
19 3007 l:-9223372036854775808 trap:13 2
20 3002 i:0 i:2 i:1 trap:12 4
21 300a f:0000000000000000 f:4000000000000000 f:3ff0000000000000 trap:12 4
22 3010 f:bff0000000000000 trap:12 16
23 3013 f:0000000000000000 f:0000000000000000 trap:12 48
24 3013 f:8000000000000000 f:bff0000000000000 f:c00921fb54442d18 48
25 3013 f:0000000000000000 f:bff0000000000000 f:400921fb54442d18 48
26 300f f:4004000000000000 f:4000000000000000 4
27 300f f:400c000000000000 f:4010000000000000 4
28 3015 l:2147483648 trap:13 2
29 3018 f:41e0000000000000 trap:13 2
30 3019 f:43e0000000000000 trap:13 2
31 3019 f:c3e0000000000000 l:-9223372036854775808 2
32 3017 l:9007199254740993 f:4340000000000000 2
33 3010 f:0000000000000000 f:0000000000000000 16
34 300c f:0000000000000000 f:0000000000000000 4
35 300d f:0000000000000000 f:0000000000000000 4
36 300e f:0000000000000000 f:0000000000000000 4
37 300f f:0000000000000000 f:0000000000000000 4
38 3018 f:0000000000000000 i:0 2
39 3019 f:0000000000000000 l:0 2
40 3011 f:0000000000000000 f:0000000000000000 32
41 3012 f:0000000000000000 f:3ff0000000000000 32
42 3011 f:8000000000000000 f:8000000000000000 32
43 3012 f:8000000000000000 f:3ff0000000000000 32
44 3013 f:0000000000000000 f:54edb5f397cc207d f:0000000000000000 48
45 3010 f:0000000000000001 f:1e60000000000000 16
46 300c f:0000000000000001 f:0000000000000000 4
47 300d f:0000000000000001 f:3ff0000000000000 4
48 300e f:0000000000000001 f:0000000000000000 4
49 300f f:0000000000000001 f:0000000000000000 4
50 3018 f:0000000000000001 i:0 2
51 3019 f:0000000000000001 l:0 2
52 3011 f:0000000000000001 f:0000000000000001 32
53 3012 f:0000000000000001 f:3ff0000000000000 32
54 3011 f:8000000000000001 f:8000000000000001 32
55 3012 f:8000000000000001 f:3ff0000000000000 32
56 3013 f:0000000000000001 f:823a3f3c9decf2dd f:400921fb54442d18 48
57 3010 f:0000000000000002 f:1e66a09e667f3bcd 16
58 300c f:0000000000000002 f:0000000000000000 4
59 300d f:0000000000000002 f:3ff0000000000000 4
60 300e f:0000000000000002 f:0000000000000000 4
61 300f f:0000000000000002 f:0000000000000000 4
62 3018 f:0000000000000002 i:0 2
63 3019 f:0000000000000002 l:0 2
64 3011 f:0000000000000002 f:0000000000000002 32
65 3012 f:0000000000000002 f:3ff0000000000000 32
66 3011 f:8000000000000002 f:8000000000000002 32
67 3012 f:8000000000000002 f:3ff0000000000000 32
68 3013 f:0000000000000002 f:8c9f4dfeacaf0126 f:400921fb54442d18 48
69 3010 f:000fffffffffffff f:1fffffffffffffff 16
70 300c f:000fffffffffffff f:0000000000000000 4
71 300d f:000fffffffffffff f:3ff0000000000000 4
72 300e f:000fffffffffffff f:0000000000000000 4
73 300f f:000fffffffffffff f:0000000000000000 4
74 3018 f:000fffffffffffff i:0 2
75 3019 f:000fffffffffffff l:0 2
76 3011 f:000fffffffffffff f:000fffffffffffff 32
77 3012 f:000fffffffffffff f:3ff0000000000000 32
78 3011 f:800fffffffffffff f:800fffffffffffff 32
79 3012 f:800fffffffffffff f:3ff0000000000000 32
80 3013 f:000fffffffffffff f:09ed7f8a283eb81c f:36115b63b5562616 48
81 3010 f:0010000000000000 f:2000000000000000 16
82 300c f:0010000000000000 f:0000000000000000 4
83 300d f:0010000000000000 f:3ff0000000000000 4
84 300e f:0010000000000000 f:0000000000000000 4
85 300f f:0010000000000000 f:0000000000000000 4
86 3018 f:0010000000000000 i:0 2
87 3019 f:0010000000000000 l:0 2
88 3011 f:0010000000000000 f:0010000000000000 32
89 3012 f:0010000000000000 f:3ff0000000000000 32
90 3011 f:8010000000000000 f:8010000000000000 32
91 3012 f:8010000000000000 f:3ff0000000000000 32
92 3013 f:0010000000000000 f:3feffffffffffffe f:0010000000000001 48
93 3010 f:3fdfffffffffffff f:3fe6a09e667f3bcc 16
94 300c f:3fdfffffffffffff f:0000000000000000 4
95 300d f:3fdfffffffffffff f:3ff0000000000000 4
96 300e f:3fdfffffffffffff f:0000000000000000 4
97 300f f:3fdfffffffffffff f:0000000000000000 4
98 3018 f:3fdfffffffffffff i:0 2
99 3019 f:3fdfffffffffffff l:0 2
100 3011 f:3fdfffffffffffff f:3fdeaee8744b05ef 32
101 3012 f:3fdfffffffffffff f:3fec1528065b7d50 32
102 3011 f:bfdfffffffffffff f:bfdeaee8744b05ef 32
103 3012 f:bfdfffffffffffff f:3fec1528065b7d50 32
104 3013 f:3fdfffffffffffff f:07faa1d222d1148d f:3ff921fb54442d18 48
105 3010 f:3fe0000000000000 f:3fe6a09e667f3bcd 16
106 300c f:3fe0000000000000 f:0000000000000000 4
107 300d f:3fe0000000000000 f:3ff0000000000000 4
108 300e f:3fe0000000000000 f:0000000000000000 4
109 300f f:3fe0000000000000 f:0000000000000000 4
110 3018 f:3fe0000000000000 i:0 2
111 3019 f:3fe0000000000000 l:0 2
112 3011 f:3fe0000000000000 f:3fdeaee8744b05f0 32
113 3012 f:3fe0000000000000 f:3fec1528065b7d50 32
114 3011 f:bfe0000000000000 f:bfdeaee8744b05f0 32
115 3012 f:bfe0000000000000 f:3fec1528065b7d50 32
116 3013 f:3fe0000000000000 f:ad7bbd56db31c9ec f:3ff921fb54442d18 48
117 3010 f:3fe0000000000001 f:3fe6a09e667f3bcd 16
118 300c f:3fe0000000000001 f:0000000000000000 4
119 300d f:3fe0000000000001 f:3ff0000000000000 4
120 300e f:3fe0000000000001 f:0000000000000000 4
121 300f f:3fe0000000000001 f:3ff0000000000000 4
122 3018 f:3fe0000000000001 i:0 2
123 3019 f:3fe0000000000001 l:0 2
124 3011 f:3fe0000000000001 f:3fdeaee8744b05f2 32
125 3012 f:3fe0000000000001 f:3fec1528065b7d4f 32
126 3011 f:bfe0000000000001 f:bfdeaee8744b05f2 32
127 3012 f:bfe0000000000001 f:3fec1528065b7d4f 32
128 3013 f:3fe0000000000001 f:3ffffffffffffffe f:3fcf5b75f92c80e1 48
129 3010 f:3ff0000000000000 f:3ff0000000000000 16
130 300c f:3ff0000000000000 f:3ff0000000000000 4
131 300d f:3ff0000000000000 f:3ff0000000000000 4
132 300e f:3ff0000000000000 f:3ff0000000000000 4
133 300f f:3ff0000000000000 f:3ff0000000000000 4
134 3018 f:3ff0000000000000 i:1 2
135 3019 f:3ff0000000000000 l:1 2
136 3011 f:3ff0000000000000 f:3feaed548f090cee 32
137 3012 f:3ff0000000000000 f:3fe14a280fb5068c 32
138 3011 f:bff0000000000000 f:bfeaed548f090cee 32
139 3012 f:bff0000000000000 f:3fe14a280fb5068c 32
140 3013 f:3ff0000000000000 f:3fe0000000000002 f:3ff1b6e192ebbe44 48
141 3010 f:4000000000000000 f:3ff6a09e667f3bcd 16
142 300c f:4000000000000000 f:4000000000000000 4
143 300d f:4000000000000000 f:4000000000000000 4
144 300e f:4000000000000000 f:4000000000000000 4
145 300f f:4000000000000000 f:4000000000000000 4
146 3018 f:4000000000000000 i:2 2
147 3019 f:4000000000000000 l:2 2
148 3011 f:4000000000000000 f:3fed18f6ead1b446 32
149 3012 f:4000000000000000 f:bfdaa22657537205 32
150 3011 f:c000000000000000 f:bfed18f6ead1b446 32
151 3012 f:c000000000000000 f:bfdaa22657537205 32
152 3013 f:4000000000000000 f:3ff921fb54442d18 f:3fecf5f1e82b5390 48
153 3010 f:3ff921fb54442d18 f:3ff40d931ff62705 16
154 300c f:3ff921fb54442d18 f:3ff0000000000000 4
155 300d f:3ff921fb54442d18 f:4000000000000000 4
156 300e f:3ff921fb54442d18 f:3ff0000000000000 4
157 300f f:3ff921fb54442d18 f:4000000000000000 4
158 3018 f:3ff921fb54442d18 i:1 2
159 3019 f:3ff921fb54442d18 l:1 2
160 3011 f:3ff921fb54442d18 f:3ff0000000000000 32
161 3012 f:3ff921fb54442d18 f:3c91a62633145c07 32
162 3011 f:bff921fb54442d18 f:bff0000000000000 32
163 3012 f:bff921fb54442d18 f:3c91a62633145c07 32
164 3013 f:3ff921fb54442d18 f:ea3931a1dc0ba585 f:400921fb54442d18 48
165 3010 f:400921fb54442d18 f:3ffc5bf891b4ef6a 16
166 300c f:400921fb54442d18 f:4008000000000000 4
167 300d f:400921fb54442d18 f:4010000000000000 4
168 300e f:400921fb54442d18 f:4008000000000000 4
169 300f f:400921fb54442d18 f:4008000000000000 4
170 3018 f:400921fb54442d18 i:3 2
171 3019 f:400921fb54442d18 l:3 2
172 3011 f:400921fb54442d18 f:3ca1a62633145c07 32
173 3012 f:400921fb54442d18 f:bff0000000000000 32
174 3011 f:c00921fb54442d18 f:bca1a62633145c07 32
175 3012 f:c00921fb54442d18 f:bff0000000000000 32
176 3013 f:400921fb54442d18 f:7103ecf9a81fd654 f:0ef42e61ed6e3c59 48
177 3010 f:401921fb54442d18 f:40040d931ff62705 16
178 300c f:401921fb54442d18 f:4018000000000000 4
179 300d f:401921fb54442d18 f:401c000000000000 4
180 300e f:401921fb54442d18 f:4018000000000000 4
181 300f f:401921fb54442d18 f:4018000000000000 4
182 3018 f:401921fb54442d18 i:6 2
183 3019 f:401921fb54442d18 l:6 2
184 3011 f:401921fb54442d18 f:bcb1a62633145c07 32
185 3012 f:401921fb54442d18 f:3ff0000000000000 32
186 3011 f:c01921fb54442d18 f:3cb1a62633145c07 32
187 3012 f:c01921fb54442d18 f:3ff0000000000000 32
188 3013 f:401921fb54442d18 f:22f1a991580a3c2b f:3ff921fb54442d18 48
189 3010 f:7fefffffffffffff f:5fefffffffffffff 16
190 300c f:7fefffffffffffff f:7fefffffffffffff 4
191 300d f:7fefffffffffffff f:7fefffffffffffff 4
192 300e f:7fefffffffffffff f:7fefffffffffffff 4
193 300f f:7fefffffffffffff f:7fefffffffffffff 4
194 3018 f:7fefffffffffffff trap:13 2
195 3019 f:7fefffffffffffff trap:13 2
196 3011 f:7fefffffffffffff f:3f7452fc98b34e97 32
197 3012 f:7fefffffffffffff f:bfefffe62ecfab75 32
198 3011 f:ffefffffffffffff f:bf7452fc98b34e97 32
199 3012 f:ffefffffffffffff f:bfefffe62ecfab75 32
200 3013 f:7fefffffffffffff f:3ff921fb54442d19 f:3ff921fb54442d18 48
201 3010 f:000ffffffffffffe f:1ffffffffffffffe 16
202 300c f:000ffffffffffffe f:0000000000000000 4
203 300d f:000ffffffffffffe f:3ff0000000000000 4
204 300e f:000ffffffffffffe f:0000000000000000 4
205 300f f:000ffffffffffffe f:0000000000000000 4
206 3018 f:000ffffffffffffe i:0 2
207 3019 f:000ffffffffffffe l:0 2
208 3011 f:000ffffffffffffe f:000ffffffffffffe 32
209 3012 f:000ffffffffffffe f:3ff0000000000000 32
210 3011 f:800ffffffffffffe f:800ffffffffffffe 32
211 3012 f:800ffffffffffffe f:3ff0000000000000 32
212 3013 f:000ffffffffffffe f:074caaf9d0e6af80 f:38b1dc162179e06b 48
213 3013 f:000fffffffffffff f:272b6a7c6b3a7cd8 f:18d2acdd5ccefbb4 48
214 3010 f:0010000000000001 f:2000000000000000 16
215 300c f:0010000000000001 f:0000000000000000 4
216 300d f:0010000000000001 f:3ff0000000000000 4
217 300e f:0010000000000001 f:0000000000000000 4
218 300f f:0010000000000001 f:0000000000000000 4
219 3018 f:0010000000000001 i:0 2
220 3019 f:0010000000000001 l:0 2
221 3011 f:0010000000000001 f:0010000000000001 32
222 3012 f:0010000000000001 f:3ff0000000000000 32
223 3011 f:8010000000000001 f:8010000000000001 32
224 3012 f:8010000000000001 f:3ff0000000000000 32
225 3013 f:0010000000000001 f:3feffffffffffffe f:0010000000000002 48
226 3010 f:0010000000000002 f:2000000000000001 16
227 300c f:0010000000000002 f:0000000000000000 4
228 300d f:0010000000000002 f:3ff0000000000000 4
229 300e f:0010000000000002 f:0000000000000000 4
230 300f f:0010000000000002 f:0000000000000000 4
231 3018 f:0010000000000002 i:0 2
232 3019 f:0010000000000002 l:0 2
233 3011 f:0010000000000002 f:0010000000000002 32
234 3012 f:0010000000000002 f:3ff0000000000000 32
235 3011 f:8010000000000002 f:8010000000000002 32
236 3012 f:8010000000000002 f:3ff0000000000000 32
237 3013 f:0010000000000002 f:7721df366e8fb3fd f:0000000000000000 48
238 3010 f:3fdffffffffffffd f:3fe6a09e667f3bcc 16
239 300c f:3fdffffffffffffd f:0000000000000000 4
240 300d f:3fdffffffffffffd f:3ff0000000000000 4
241 300e f:3fdffffffffffffd f:0000000000000000 4
242 300f f:3fdffffffffffffd f:0000000000000000 4
243 3018 f:3fdffffffffffffd i:0 2
244 3019 f:3fdffffffffffffd l:0 2
245 3011 f:3fdffffffffffffd f:3fdeaee8744b05ed 32
246 3012 f:3fdffffffffffffd f:3fec1528065b7d50 32
247 3011 f:bfdffffffffffffd f:bfdeaee8744b05ed 32
248 3012 f:bfdffffffffffffd f:3fec1528065b7d50 32
249 3013 f:3fdffffffffffffd f:7feffffffffffffe f:0002000000000000 48
250 3010 f:3fdffffffffffffe f:3fe6a09e667f3bcc 16
251 300c f:3fdffffffffffffe f:0000000000000000 4
252 300d f:3fdffffffffffffe f:3ff0000000000000 4
253 300e f:3fdffffffffffffe f:0000000000000000 4
254 300f f:3fdffffffffffffe f:0000000000000000 4
255 3018 f:3fdffffffffffffe i:0 2
256 3019 f:3fdffffffffffffe l:0 2
257 3011 f:3fdffffffffffffe f:3fdeaee8744b05ee 32
258 3012 f:3fdffffffffffffe f:3fec1528065b7d50 32
259 3011 f:bfdffffffffffffe f:bfdeaee8744b05ee 32
260 3012 f:bfdffffffffffffe f:3fec1528065b7d50 32
261 3013 f:3fdffffffffffffe f:401921fb54442d17 f:3fb45438e80932c3 48
@@ -0,0 +1,3 @@
Runtime revision: f7d7c167531bb662a1af9d73fc326bb476bf8aa7
Provider fixture SHA-256: 5536ee18cadaf32e3719b0e8d541dfcf1a84a49ea978a702101547c5ccdee3fe
First 240 scalar rows of numeric-conformance.tsv plus exact examples from 02d-gameplay-math-and-numeric-semantics.md. No host math oracle.
@@ -0,0 +1,5 @@
Copied unchanged from runtime crates/console/prometeu-vm/tests/fixtures/random-conformance.tsv
Runtime revision: f7d7c167531bb662a1af9d73fc326bb476bf8aa7
Provenance: runtime crates/console/prometeu-vm/tests/fixtures/random-oracle.md
48 rows: six seeds x eight draws. PBS tests project both signed words and Float bits.
No generator implementation is copied into the compiler.
@@ -0,0 +1,49 @@
seed draw word_hex signed float_bits
0 1 9B3184D7EE6BACDB -7263878661019030309 3FE366309AFDCD75
0 2 8B7B271AA4769FD4 -8396074084920287276 3FE16F64E3548ED3
0 3 9B4DB63DFE544AAB -7255943047247803733 3FE369B6C7BFCA89
0 4 E714BA3532308667 -1795605613775911321 3FECE29746A64610
0 5 64EAF919A9A040E2 7271898436958437602 3FD93ABE466A6810
0 6 325BCFFB862545B0 3628722603971397040 3FC92DE7FDC312A0
0 7 70180161DC24B6EC 8077207451505833708 3FDC06005877092C
0 8 39257F36B038F771 4117837307161671537 3FCC92BF9B581C78
1 1 3150032F5C48AC0A 3553343607941934090 3FC8A80197AE2454
1 2 099B2F21D97DB047 692198790160822343 3FA3365E43B2FB60
1 3 7539BA4A2ED012EB 8446987403885810411 3FDD4E6E928BB404
1 4 C842BA297694C455 -4016443230415174571 3FE90857452ED298
1 5 C8AE2BB397CD3537 -3986200569830361801 3FE915C57672F9A6
1 6 C2F1AF39457336BA -4399542700451088710 3FE85E35E728AE66
1 7 8710A37C51FEC0AD -8714285524614987603 3FE0E2146F8A3FD8
1 8 A4C73DCA70459C07 -6573217191447651321 3FE498E7B94E08B3
42 1 86B1DA1D72062B68 -8740965581747508376 3FE0D63B43AE40C5
42 2 1304AA46C9853D39 1370407407632858425 3FB304AA46C98538
42 3 A3670E9E0DD50358 -6672348250926415016 3FE46CE1D3C1BAA0
42 4 F9090E529A7DAE00 -501854135533064704 3FEF2121CA534FB5
42 5 C85B9FD837996F2C -4009435292248740052 3FE90B73FB06F32D
42 6 606121F8E3919196 6944869453235589526 3FD818487E38E464
42 7 7CE1C7FF478354BA 8998693429693338810 3FDF3871FFD1E0D4
42 8 CBC4AC70E541310E -3763693787692322546 3FE978958E1CA826
-1 1 EE89537ECBD16900 -1258382816822859520 3FEDD12A6FD97A2D
-1 2 DCBE53D8A6C852E6 -2540500949814193434 3FEB97CA7B14D90A
-1 3 561BA13FFCFD5094 6204730207832461460 3FD586E84FFF3F54
-1 4 76962EA43FCF9400 8545068625962177536 3FDDA58BA90FF3E4
-1 5 A2BF24C068F28D0D -6719611710200443635 3FE457E4980D1E51
-1 6 3D575F16AA0C40D8 4420106110234280152 3FCEABAF8B550620
-1 7 032B99D40D100946 228445342143613254 3F895CCEA0688040
-1 8 7053160AB14A824F 8093837190494847567 3FDC14C582AC52A0
-9223372036854775808 1 1C08F9C51E05B9F1 2020139057883232753 3FBC08F9C51E05B8
-9223372036854775808 2 4CC379FA6A441AFF 5531398883772734207 3FD330DE7E9A9106
-9223372036854775808 3 1E9926CF448F8AA7 2204836164224912039 3FBE9926CF448F88
-9223372036854775808 4 18ADD82F6DA7760F 1778315126095967759 3FB8ADD82F6DA770
-9223372036854775808 5 77DFD36640320B00 8637855046437047040 3FDDF7F4D9900C82
-9223372036854775808 6 CE09AC671D48BD0F -3600156868233085681 3FE9C1358CE3A917
-9223372036854775808 7 B15DBA0399E9E3D1 -5666168231532305455 3FE62BB740733D3C
-9223372036854775808 8 E88252991CF3E42C -1692699692368665556 3FED104A53239E7C
9223372036854775807 1 77D44C809FDF62DB 8634610500897825499 3FDDF5132027F7D8
9223372036854775807 2 05BCF3AED615466A 413473198052820586 3F96F3CEBB585500
9223372036854775807 3 693ED392E1CE694A 7583731450345580874 3FDA4FB4E4B8739A
9223372036854775807 4 83D248E707AC837B -8948009352528362629 3FE07A491CE0F590
9223372036854775807 5 5DD1D07026E00956 6760413695766956374 3FD774741C09B802
9223372036854775807 6 5713B8336C9A861C 6274561236862141980 3FD5C4EE0CDB26A0
9223372036854775807 7 4F2E7352ED7CCE69 5705624577933889129 3FD3CB9CD4BB5F32
9223372036854775807 8 DB109447225C784B -2661464346535888821 3FEB621288E44B8F
1 seed draw word_hex signed float_bits
2 0 1 9B3184D7EE6BACDB -7263878661019030309 3FE366309AFDCD75
3 0 2 8B7B271AA4769FD4 -8396074084920287276 3FE16F64E3548ED3
4 0 3 9B4DB63DFE544AAB -7255943047247803733 3FE369B6C7BFCA89
5 0 4 E714BA3532308667 -1795605613775911321 3FECE29746A64610
6 0 5 64EAF919A9A040E2 7271898436958437602 3FD93ABE466A6810
7 0 6 325BCFFB862545B0 3628722603971397040 3FC92DE7FDC312A0
8 0 7 70180161DC24B6EC 8077207451505833708 3FDC06005877092C
9 0 8 39257F36B038F771 4117837307161671537 3FCC92BF9B581C78
10 1 1 3150032F5C48AC0A 3553343607941934090 3FC8A80197AE2454
11 1 2 099B2F21D97DB047 692198790160822343 3FA3365E43B2FB60
12 1 3 7539BA4A2ED012EB 8446987403885810411 3FDD4E6E928BB404
13 1 4 C842BA297694C455 -4016443230415174571 3FE90857452ED298
14 1 5 C8AE2BB397CD3537 -3986200569830361801 3FE915C57672F9A6
15 1 6 C2F1AF39457336BA -4399542700451088710 3FE85E35E728AE66
16 1 7 8710A37C51FEC0AD -8714285524614987603 3FE0E2146F8A3FD8
17 1 8 A4C73DCA70459C07 -6573217191447651321 3FE498E7B94E08B3
18 42 1 86B1DA1D72062B68 -8740965581747508376 3FE0D63B43AE40C5
19 42 2 1304AA46C9853D39 1370407407632858425 3FB304AA46C98538
20 42 3 A3670E9E0DD50358 -6672348250926415016 3FE46CE1D3C1BAA0
21 42 4 F9090E529A7DAE00 -501854135533064704 3FEF2121CA534FB5
22 42 5 C85B9FD837996F2C -4009435292248740052 3FE90B73FB06F32D
23 42 6 606121F8E3919196 6944869453235589526 3FD818487E38E464
24 42 7 7CE1C7FF478354BA 8998693429693338810 3FDF3871FFD1E0D4
25 42 8 CBC4AC70E541310E -3763693787692322546 3FE978958E1CA826
26 -1 1 EE89537ECBD16900 -1258382816822859520 3FEDD12A6FD97A2D
27 -1 2 DCBE53D8A6C852E6 -2540500949814193434 3FEB97CA7B14D90A
28 -1 3 561BA13FFCFD5094 6204730207832461460 3FD586E84FFF3F54
29 -1 4 76962EA43FCF9400 8545068625962177536 3FDDA58BA90FF3E4
30 -1 5 A2BF24C068F28D0D -6719611710200443635 3FE457E4980D1E51
31 -1 6 3D575F16AA0C40D8 4420106110234280152 3FCEABAF8B550620
32 -1 7 032B99D40D100946 228445342143613254 3F895CCEA0688040
33 -1 8 7053160AB14A824F 8093837190494847567 3FDC14C582AC52A0
34 -9223372036854775808 1 1C08F9C51E05B9F1 2020139057883232753 3FBC08F9C51E05B8
35 -9223372036854775808 2 4CC379FA6A441AFF 5531398883772734207 3FD330DE7E9A9106
36 -9223372036854775808 3 1E9926CF448F8AA7 2204836164224912039 3FBE9926CF448F88
37 -9223372036854775808 4 18ADD82F6DA7760F 1778315126095967759 3FB8ADD82F6DA770
38 -9223372036854775808 5 77DFD36640320B00 8637855046437047040 3FDDF7F4D9900C82
39 -9223372036854775808 6 CE09AC671D48BD0F -3600156868233085681 3FE9C1358CE3A917
40 -9223372036854775808 7 B15DBA0399E9E3D1 -5666168231532305455 3FE62BB740733D3C
41 -9223372036854775808 8 E88252991CF3E42C -1692699692368665556 3FED104A53239E7C
42 9223372036854775807 1 77D44C809FDF62DB 8634610500897825499 3FDDF5132027F7D8
43 9223372036854775807 2 05BCF3AED615466A 413473198052820586 3F96F3CEBB585500
44 9223372036854775807 3 693ED392E1CE694A 7583731450345580874 3FDA4FB4E4B8739A
45 9223372036854775807 4 83D248E707AC837B -8948009352528362629 3FE07A491CE0F590
46 9223372036854775807 5 5DD1D07026E00956 6760413695766956374 3FD774741C09B802
47 9223372036854775807 6 5713B8336C9A861C 6274561236862141980 3FD5C4EE0CDB26A0
48 9223372036854775807 7 4F2E7352ED7CCE69 5705624577933889129 3FD3CB9CD4BB5F32
49 9223372036854775807 8 DB109447225C784B -2661464346535888821 3FEB621288E44B8F
@@ -13,9 +13,11 @@ dependencies {
// Build-time projection of owner-maintained sources; no second normative copy is edited by Studio. // Build-time projection of owner-maintained sources; no second normative copy is edited by Studio.
val pbsSpecs = rootProject.layout.projectDirectory.dir("docs/specs/compiler-languages/pbs") val pbsSpecs = rootProject.layout.projectDirectory.dir("docs/specs/compiler-languages/pbs")
val pbsAlignmentSpecs = rootProject.layout.projectDirectory.dir("docs/compiler/pbs/specs")
val pbsResources = layout.projectDirectory.dir("src/main/resources") val pbsResources = layout.projectDirectory.dir("src/main/resources")
val generatePbsKnowledge by tasks.registering(Sync::class) { val generatePbsKnowledge by tasks.registering(Sync::class) {
from(pbsSpecs) { include("*.md"); into("pbs-knowledge/specs") } from(pbsSpecs) { include("*.md"); into("pbs-knowledge/specs") }
from(pbsAlignmentSpecs) { include("*.md"); into("pbs-knowledge/specs") }
into(layout.buildDirectory.dir("generated/pbsKnowledge")) into(layout.buildDirectory.dir("generated/pbsKnowledge"))
inputs.files(fileTree(pbsResources) { include("game/stdlib/**/*.pbs", "game/stdlib/**/*.barrel", "pbs-knowledge/examples/**") }) inputs.files(fileTree(pbsResources) { include("game/stdlib/**/*.pbs", "game/stdlib/**/*.barrel", "pbs-knowledge/examples/**") })
doLast { doLast {
@@ -27,7 +29,7 @@ val generatePbsKnowledge by tasks.registering(Sync::class) {
entries.add(linkedMapOf("id" to id, "title" to title, "kind" to kind, entries.add(linkedMapOf("id" to id, "title" to title, "kind" to kind,
"resource" to resource, "sha256" to digest, "sdkVersion" to sdk, "target" to target)) "resource" to resource, "sha256" to digest, "sdkVersion" to sdk, "target" to target))
} }
pbsSpecs.asFile.listFiles()!!.filter { it.extension == "md" }.sortedBy { it.name }.forEach { source -> (pbsSpecs.asFile.listFiles()!!.toList() + (pbsAlignmentSpecs.asFile.listFiles()?.toList() ?: emptyList())).filter { it.extension == "md" }.sortedBy { it.name }.forEach { source ->
val chapter = source.name.substringBefore(". ") val chapter = source.name.substringBefore(". ")
val quickstart = source.name == "README.md" val quickstart = source.name == "README.md"
entry(if (quickstart) "pbs:quickstart" else "pbs:spec:$chapter", entry(if (quickstart) "pbs:quickstart" else "pbs:spec:$chapter",
@@ -54,3 +56,10 @@ val generatePbsKnowledge by tasks.registering(Sync::class) {
} }
} }
sourceSets.main { resources.srcDir(generatePbsKnowledge) } sourceSets.main { resources.srcDir(generatePbsKnowledge) }
tasks.named<ProcessResources>("processResources") {
from(rootProject.layout.projectDirectory.dir("docs/vm-arch")) {
include("INTRINSICS.csv", "BUILTIN_CONSTANTS.csv", "runtime-catalog.properties")
into("runtime-catalog/pbs-sdk")
}
}
@@ -32,6 +32,7 @@ import p.studio.compiler.services.FrontendDocumentLink;
import p.studio.compiler.services.FrontendFoldingRange; import p.studio.compiler.services.FrontendFoldingRange;
import p.studio.compiler.services.FrontendSelectionRange; import p.studio.compiler.services.FrontendSelectionRange;
import p.studio.compiler.services.FrontendDefinitionLocation; import p.studio.compiler.services.FrontendDefinitionLocation;
import p.studio.compiler.services.FrontendSourceDocument;
import p.studio.compiler.services.FrontendDocumentRequest; import p.studio.compiler.services.FrontendDocumentRequest;
import p.studio.compiler.services.FrontendDocumentSymbol; import p.studio.compiler.services.FrontendDocumentSymbol;
import p.studio.compiler.services.FrontendRenameEdit; import p.studio.compiler.services.FrontendRenameEdit;
@@ -63,6 +64,38 @@ import java.util.Objects;
import java.util.Optional; import java.util.Optional;
public final class PBSFrontendLanguageService implements FrontendLanguageService { public final class PBSFrontendLanguageService implements FrontendLanguageService {
@Override
public boolean supportsExternalSources() { return true; }
@Override
public Optional<FrontendSourceDocument> sourceDocument(
final FrontendDocumentRequest request,
final FrontendEditorialContext context,
final Path path) {
if (!(context.projectSurface() instanceof PbsSemanticReadSurface surface)
|| !(context.sourceFiles() instanceof FileTableReader files)) return Optional.empty();
FrontendSourceDocument projectSource = null;
for (final var entry : surface.astByFile().entrySet()) {
final var handle = files.get(entry.getKey());
if (handle == null || !handle.getCanonPath().toAbsolutePath().normalize().equals(path.toAbsolutePath().normalize())) continue;
final var text = handle.readUtf8();
if (text.isEmpty()) return Optional.empty();
final boolean bundled = surface.sourceKindByFile().get(entry.getKey()) == SourceKind.SDK_INTERFACE;
final Path owner = surface.ownerRootByFile().get(entry.getKey());
final boolean external = bundled || owner == null || !owner.toAbsolutePath().normalize().equals(request.projectRoot().toAbsolutePath().normalize());
final var source = new FrontendSourceDocument(path, text.orElseThrow(),
bundled ? "bundled" : external ? "dependency" : "project",
handle.getRelativePath().toString(), "pbs", external,
new FrontendEditorialContext(entry.getValue(),
surface.supplementalTopDeclsByFile().getOrDefault(entry.getKey(), ReadOnlyList.empty()),
context.semanticContext(), files, surface));
// A dependency may physically overlap a project source root. External
// ownership wins even if another file-table entry treats it as local.
if (external) return Optional.of(source);
projectSource = source;
}
return Optional.ofNullable(projectSource);
}
private final PbsEditorialSupportService editorialSupportService; private final PbsEditorialSupportService editorialSupportService;
private final PBSSemanticTokenProvider semanticTokenProvider; private final PBSSemanticTokenProvider semanticTokenProvider;
@@ -257,7 +290,12 @@ public final class PBSFrontendLanguageService implements FrontendLanguageService
typedSupplementalTopDecls, typedSupplementalTopDecls,
feSurfaceContext, feSurfaceContext,
offset)) { offset)) {
toFrontendLocation(location, fileTable).ifPresent(locations::add); final var handle = fileTable.get(location.span().getFileId());
if (handle != null) {
sourceDocument(request, editorialContext, handle.getCanonPath()).ifPresent(source ->
locations.add(new FrontendDefinitionLocation(source.path(),
toOffset(location.span().getStart()), toOffset(location.span().getEnd()), source)));
}
} }
return List.copyOf(locations); return List.copyOf(locations);
} }
@@ -401,14 +439,16 @@ public final class PBSFrontendLanguageService implements FrontendLanguageService
} }
final LinkedHashMap<String, FrontendRenameEdit> edits = new LinkedHashMap<>(); final LinkedHashMap<String, FrontendRenameEdit> edits = new LinkedHashMap<>();
for (final PbsEditorialLocation site : planned.sites()) { for (final PbsEditorialLocation site : planned.sites()) {
toFrontendLocation(site, fileTable).ifPresent(location -> final var mapped = toFrontendLocation(site, fileTable);
edits.putIfAbsent( if (mapped.isEmpty()) return FrontendRenameResult.refused("rename requires a non-editable source");
final var location = mapped.orElseThrow();
edits.putIfAbsent(
frontendLocationKey(location), frontendLocationKey(location),
new FrontendRenameEdit( new FrontendRenameEdit(
location.path(), location.path(),
location.startOffset(), location.startOffset(),
location.endOffset(), location.endOffset(),
newName))); newName));
} }
if (edits.isEmpty()) { if (edits.isEmpty()) {
return FrontendRenameResult.refused("not renameable"); return FrontendRenameResult.refused("not renameable");

Some files were not shown because too many files have changed in this diff Show More