feat(pbs): add array-backed Stack and circular Queue

This commit is contained in:
2026-10-27 09:37:10 +00:00
parent 01a1968689
commit 0016d92ac3
34 changed files with 5274 additions and 9 deletions
@@ -0,0 +1,106 @@
# Stack/Queue implementation and qualification evidence
Owner: `compiler/pbs`. Accepted DEC-0080 / completed PLN-0158 in DSC-0097, R1–R9.
Captured 2026-10-27 over Studio baseline `01a19686`. The provider remained clean at
`dcf6561ea73446e0a3e1cf1c73eda20923b38df0`; no runtime write or commit occurred.
## Reproduction and outcome
From the Studio root:
```sh
./gradlew test :prometeu-app:installedKnowledgeTest --console=plain
CARGO_TARGET_DIR=/tmp/studio-pbx-map-target python3 tools/pbx-conformance/run.py --runtime ../runtime
CARGO_TARGET_DIR=/tmp/studio-pbx-map-target python3 tools/pbx-conformance/run.py --runtime ../runtime --release
git diff --check
discussion validate
```
All returned zero. Temporary Cargo projects/targets stay outside the read-only
runtime checkout. Focused development runs used `--stack-queue-only`; retained
final VM evidence is from the two complete harness runs, including all existing
Registry, storage/copy, language and collection corpora.
Aggregated standard JUnit reports have 1,091 cases, zero failures/errors and 13
existing skips; 1,078 executed. The separate installed-knowledge task adds two
passing cases, compiling actual JAR resources in an isolated outside-checkout JVM.
The final Gradle run completed in 32 seconds with 15 executed and 79 up-to-date
tasks; unchanged suites retained valid passing results. See exact suites/skips in
[gradle-results.json](gradle-results.json). Existing skips remain BackendGateIIntegrationTest
(8), MainProjectPipelineIntegrationTest (4), ExternalSourceDevelopmentHostTest (1).
There are 106 mandatory new PBX files: 58 paired behavior/expected-fault cases,
34 paired operation-resource fixtures, four separate test-only injection files,
eight paired GC files and two import/installed examples. Each runtime profile
requires them all. The complete fixture directory contains 1,495 fingerprinted
PBX files; directory size is not itself a count of executed cases.
Each final profile observes 184 Stack + 180 Queue natural quota refusals, including
18 + 12 after visible writes (all during clear), four separate growth probes,
36 real GC observations and both distribution examples. Both ordinary and optimized
producer paths are mandatory in each profile. Missing fixtures fail qualification.
## Resources, phases and GC
[stack-queue-results.json](stack-queue-results.json) records all 34 operation/producer
peak vectors and refusal summaries per profile, natural counts, separate probes,
GC rounds and distribution results. Peak vector order is GuestBytes, HandleSlots,
AuxiliaryBytes, TemporaryBytes, StringBytes, StringAllocations, IndividualStringBytes,
CallDepth. These are whole-session/fixture peaks including setup and calls, not
standalone collection object sizes. Limits are lowered only where setup-to-operation
peaks increase, retaining the measured no-increase domains in the raw vectors.
Non-owning observations compare complete original collection/backing objects at
each instruction to the successful prefix. Before mutation, prior state survives;
afterward, earlier successful stores remain and no rollback is asserted. Clear
naturally demonstrates partial updates. Result preparation, typed empty returns,
copy/backing construction and snapshot-node refusals remain charged. Growing paths
observe at least two coexisting arrays; ordinary updates/capture retain one backing
and never reconstruct the whole collection.
The separate test-only growth probes fail after installing capacity three with
the new slot=42 and old size=2. The refused probe instruction preserves its own
entry storage/operands, retaining the earlier publication. These probes are only
in fixture-local SDK copies, never in production source, and are not counted as
natural refusal frequency.
Snapshot GC observes 1,200 → 1 → 1 → 0 nodes and Items, with no retained source
array. Collection GC observes 64 → 61 → 0 → 1 → 0 Items, one retained current/empty
backing through the first four rounds and zero afterward. Old growth backings are
not retained. Every observation asserts that the actual collection counter advanced.
Both producers and both runtime profiles pass. Final VM owner drop also releases
GuestBytes/HandleSlots/AuxiliaryBytes/TemporaryBytes/StringBytes/StringAllocations.
## Requirement coverage
| Requirement | Final evidence |
| --- | --- |
| R1 Types, identity, origin, construction | Frontend context/invariance/optional/privacy/homonym gates, SDK workspace gate, basic/capacity/references/snapshot/evaluation and alias imports |
| R2 Complete API and absence | basic/capacity, empty/single/multiple Cursor states, zero/false, evaluation, negative indexer/unsupported API cases |
| R3 Growth and bounds | exact 0→1→2→3→5→8, default/explicit capacities, arithmetic helper checks and negative/above-u32/required-size faults |
| R4 Dense/circular groups | wrap and wrapped-growth source cases, resource validation of every active/inactive slot and start/count/backing, tuple/native/reference execution |
| R5 Failure phases | 34 marked paired fixtures, successful-prefix comparisons, 364 natural refusals including 30 after writes, four separate post-write probes |
| R6 Lifetime and coexistence | array peak counts, no reconstruction on ordinary updates, actual removal/clear/reuse/old-backing GC, complete owner release |
| R7 Shared Cursor | both capture orders, sticky final/empty states, duplicates/shared mutation, mutation independence, both snapshot GC paths |
| R8 Frontend/editor/distribution | concrete public eight-method APIs/constructors/definitions, hidden fields, trusted aliases/reexports, isolated JAR compile and actual PBX execution |
| R9 Complete qualification | full regression, complete production debug/release corpora with both producers, reproducible fingerprints/raw logs and limits |
## Integrity and limits
- `source.sha256`: every changed/new code/spec/test surface, excluding discussion prose/evidence.
- `fixtures.sha256.gz`: all actual generated PBX fingerprints, including installed examples.
- `environment.json`: baseline/provider, host/tool versions, commands, mandatory fixture names,
uncompressed log digests and counts.
- `conformance-debug.log.gz`, `conformance-release.log.gz`, `regression.log.gz`:
lossless raw final outputs, compressed deterministically.
- `workflow.txt`: completion, CLI validation and housekeeping results.
- `SHA256SUMS`: integrity hashes of this evidence directory.
The standard existing skips and upstream headless-schema LifecycleRole/NonFiniteValue
gaps remain explicit. Original provider payloads remain in complete logs; those
cases are not called conformance to the unchanged schema. Qualification is local
macOS/arm64 without benchmark, cross-host or installed-game-readiness claims.
The CLI has no standalone lesson-ID query/creation. LSN-0095 was obtained through
the framework's read-only `DiscussionIndex.next_id` accessor; CLI housekeeping owns
lesson registration, counter advancement, index changes and workflow deletions.
@@ -0,0 +1,10 @@
1db55d241bb0f3088afefccf7596bf7a9014bc0dae54b80d54e15a3a47a91135 README.md
4e16e23cfc9d75228649d632f590183523fb6a854ac0f2d940eaffe021b6a70d conformance-debug.log.gz
c74d26c969512b48895178a7bdbc542c15c736b5f2a41b7b864bafb58dadc837 conformance-release.log.gz
c6d5b81a62d8e9a274615f2ca0aaf0b0f4a7159e57be8911f8f9926a507a5811 environment.json
31a231667d6dab2d50eac1814d12b9fe24deea737fd0933146a78ae3458138df fixtures.sha256.gz
0bc694f54f81807ed1d856d10e370eb652ca833ba9fc1f8a229feb8bdaee4f8c gradle-results.json
23844d7c633f5d92e3b0a0998582272383eeb1a293571553809b274303806d01 regression.log.gz
7f405c7a5cd9d47c6b46fe903e019fe4dfe8e189f9596b8133e9510ceb14a784 source.sha256
64272efe4bf46ab787455c5a82a20e5857f8ca72e39a2bdcfcde191221b0e63f stack-queue-results.json
2a42448fbc6324cc52b1840e6f337d92843a6d9209854307096916dbf8d3d6bb workflow.txt
@@ -0,0 +1,129 @@
{
"captured": "2026-10-27T08:57:39.430825+00:00",
"owner": "compiler/pbs",
"decision": "DEC-0080",
"plan": "PLN-0158",
"studio_baseline_head": "01a196868929fb87a4e3b326481e8818f77c597e",
"runtime_head": "dcf6561ea73446e0a3e1cf1c73eda20923b38df0",
"runtime_working_tree": "",
"host": "macOS-27.0.1-arm64-arm-64bit-Mach-O",
"rust": "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",
"stack_queue_fixture_count": 106,
"all_fixture_count": 1495,
"fixture_names": [
"pbs-queue-arithmetic-optimized.pbx",
"pbs-queue-arithmetic.pbx",
"pbs-queue-basic-optimized.pbx",
"pbs-queue-basic.pbx",
"pbs-queue-capacity-optimized.pbx",
"pbs-queue-capacity.pbx",
"pbs-queue-cursor-empty-optimized.pbx",
"pbs-queue-cursor-empty.pbx",
"pbs-queue-cursor-order-optimized.pbx",
"pbs-queue-cursor-order.pbx",
"pbs-queue-cursor-single-optimized.pbx",
"pbs-queue-cursor-single.pbx",
"pbs-queue-evaluation-optimized.pbx",
"pbs-queue-evaluation.pbx",
"pbs-queue-fault-negative-optimized.pbx",
"pbs-queue-fault-negative.pbx",
"pbs-queue-fault-required-optimized.pbx",
"pbs-queue-fault-required.pbx",
"pbs-queue-fault-too-large-optimized.pbx",
"pbs-queue-fault-too-large.pbx",
"pbs-queue-gc-collection-optimized.pbx",
"pbs-queue-gc-collection.pbx",
"pbs-queue-gc-snapshot-optimized.pbx",
"pbs-queue-gc-snapshot.pbx",
"pbs-queue-groups-optimized.pbx",
"pbs-queue-groups.pbx",
"pbs-queue-injected-growth-optimized.pbx",
"pbs-queue-injected-growth.pbx",
"pbs-queue-native-optimized.pbx",
"pbs-queue-native.pbx",
"pbs-queue-references-optimized.pbx",
"pbs-queue-references.pbx",
"pbs-queue-refusal-clear-optimized.pbx",
"pbs-queue-refusal-clear.pbx",
"pbs-queue-refusal-cursor-optimized.pbx",
"pbs-queue-refusal-cursor.pbx",
"pbs-queue-refusal-empty-optimized.pbx",
"pbs-queue-refusal-empty.pbx",
"pbs-queue-refusal-growth-optimized.pbx",
"pbs-queue-refusal-growth.pbx",
"pbs-queue-refusal-insert-optimized.pbx",
"pbs-queue-refusal-insert.pbx",
"pbs-queue-refusal-peek-optimized.pbx",
"pbs-queue-refusal-peek.pbx",
"pbs-queue-refusal-remove-optimized.pbx",
"pbs-queue-refusal-remove.pbx",
"pbs-queue-refusal-wrapped-optimized.pbx",
"pbs-queue-refusal-wrapped.pbx",
"pbs-queue-refusal-zero-optimized.pbx",
"pbs-queue-refusal-zero.pbx",
"pbs-queue-snapshot-optimized.pbx",
"pbs-queue-snapshot.pbx",
"pbs-queue-wrap-optimized.pbx",
"pbs-queue-wrap.pbx",
"pbs-stack-arithmetic-optimized.pbx",
"pbs-stack-arithmetic.pbx",
"pbs-stack-basic-optimized.pbx",
"pbs-stack-basic.pbx",
"pbs-stack-capacity-optimized.pbx",
"pbs-stack-capacity.pbx",
"pbs-stack-cursor-empty-optimized.pbx",
"pbs-stack-cursor-empty.pbx",
"pbs-stack-cursor-order-optimized.pbx",
"pbs-stack-cursor-order.pbx",
"pbs-stack-cursor-single-optimized.pbx",
"pbs-stack-cursor-single.pbx",
"pbs-stack-evaluation-optimized.pbx",
"pbs-stack-evaluation.pbx",
"pbs-stack-fault-negative-optimized.pbx",
"pbs-stack-fault-negative.pbx",
"pbs-stack-fault-required-optimized.pbx",
"pbs-stack-fault-required.pbx",
"pbs-stack-fault-too-large-optimized.pbx",
"pbs-stack-fault-too-large.pbx",
"pbs-stack-gc-collection-optimized.pbx",
"pbs-stack-gc-collection.pbx",
"pbs-stack-gc-snapshot-optimized.pbx",
"pbs-stack-gc-snapshot.pbx",
"pbs-stack-groups-optimized.pbx",
"pbs-stack-groups.pbx",
"pbs-stack-injected-growth-optimized.pbx",
"pbs-stack-injected-growth.pbx",
"pbs-stack-native-optimized.pbx",
"pbs-stack-native.pbx",
"pbs-stack-queue-imports.pbx",
"pbs-stack-queue-installed.pbx",
"pbs-stack-references-optimized.pbx",
"pbs-stack-references.pbx",
"pbs-stack-refusal-clear-optimized.pbx",
"pbs-stack-refusal-clear.pbx",
"pbs-stack-refusal-cursor-optimized.pbx",
"pbs-stack-refusal-cursor.pbx",
"pbs-stack-refusal-empty-optimized.pbx",
"pbs-stack-refusal-empty.pbx",
"pbs-stack-refusal-growth-optimized.pbx",
"pbs-stack-refusal-growth.pbx",
"pbs-stack-refusal-insert-optimized.pbx",
"pbs-stack-refusal-insert.pbx",
"pbs-stack-refusal-peek-optimized.pbx",
"pbs-stack-refusal-peek.pbx",
"pbs-stack-refusal-remove-optimized.pbx",
"pbs-stack-refusal-remove.pbx",
"pbs-stack-refusal-zero-optimized.pbx",
"pbs-stack-refusal-zero.pbx",
"pbs-stack-snapshot-optimized.pbx",
"pbs-stack-snapshot.pbx"
],
"commands": [
"./gradlew test :prometeu-app:installedKnowledgeTest --console=plain",
"CARGO_TARGET_DIR=/tmp/studio-pbx-map-target python3 tools/pbx-conformance/run.py --runtime ../runtime",
"CARGO_TARGET_DIR=/tmp/studio-pbx-map-target python3 tools/pbx-conformance/run.py --runtime ../runtime --release",
"git diff --check",
"discussion validate"
],
"regression_log_sha256": "8d7faf3e6164d929353fb6cfbba25d5abdbe5f12cc1e759cb41522b80ec9d1a1"
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,22 @@
7f46e87702529c8ea94660a644580c0c884bb27a965a2612d32a92bc31ff9b52 docs/compiler/pbs/specs/sdk-list-and-cursor.md
a47f6fc58068a333119e73201a1a04b5ba96c916ccf6c22a4a13161ee92e7629 docs/compiler/pbs/specs/sdk-stack-and-queue.md
d9e307588aa286a90a7b8906d50569d432ffa675c99d308e4f281833a8758524 prometeu-app/src/test/java/p/studio/app/compiler/CompilerProjectKnowledgeTest.java
cf4615c65aed22ccbfbb860c070b03dad1910c8dc48adc4fc03dca4d50ba91e7 prometeu-app/src/test/java/p/studio/app/compiler/InstalledKnowledgeProbe.java
e206ff3b35b3a0f1fd18946b0522ff7d36c94156121a31a9e3e45a897e4e2c39 prometeu-app/src/test/java/p/studio/app/compiler/InstalledKnowledgeTest.java
85d8f687a903862b4e7d5a5b8711cc9af720ec7f4d282bba77ddfaee93dff0a8 prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsListCursorTest.java
680402a55fe6b1d3cd41a44caa5ecdda58dbefc0854d3f3df0c25b522c435373 prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsStackQueueTest.java
d4bdf6179293b12af929369fd332a5e42143d042db64b2a248621a59a5d93a46 prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsGenericInstantiation.java
e4480f091cbd9d8ea92750f31cacc667d0b288ce82b810e0ba0d952abfe8d4f4 prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsSdkCollections.java
3cb79ef5f9a97dbfc48ec717de4b9f9f5624e50ce52833595851714908f78ae6 prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java
6d181bf1a77ef50d6e2f89962f04e1a04d56e56d44493a5af97c897a323bb33f prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsDeclarationParser.java
ac41b92f699aba21fc885b00e6ae59d313f24e084d5436655b493257430364db prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs
6567377cbb58c2e2332556fa759667e63923b7e1cfb44fe65e440c6db309d15c prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/mod.barrel
a00ed6bfa995119b339443a5fc36f420c6793d1ed2f06b1fa5fca9b3b536362b prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/mod.barrel
053b62206cb45a5c5736ef43b58c869031bd0524a06b29be1353bba25826abe2 prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/stack-queue.pbs
a9fdd1f53a9be0db51fdf141513c845aef39ee603c58717a177b098dcec9d986 prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java
4007df0d9e100df34d26fe4bee3e758fe7b5d75130d46d4428d9d0f5ae81cb30 prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsStackQueueTest.java
f25b614021eb6918e845d3e4b5076fc0a4dccc9b89a2c281cbb59cd0b4bb0385 prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsStackQueueEditorialTest.java
d7de3d9d235678b39cdfc8d626558e026d35352aa78f98e78bda8b13507fa8e3 tools/pbx-conformance/README.md
eef34cb97cd82e162e4be6f1c0caccd0058fc44721cd9dca6cf1b9fb6c2afd09 tools/pbx-conformance/main.rs
b9a8b4d1b31d327a1e42ec1d58bb38795a68b77a298f4d77ab34cb75f8658be1 tools/pbx-conformance/run.py
b36c3c8117722328dc136676542fbee675de5a4428aa74af6fc383df48f32326 tools/pbx-conformance/stack_queue.rs
@@ -0,0 +1,32 @@
LSN-0095 allocated via read-only DiscussionIndex.next_id; all state mutations use CLI.
discussion validate
validation passed
exit=0
discussion mark-plan PLN-0158 done --json
{
"discussion_id": "DSC-0097",
"plan_id": "PLN-0158",
"status": "done"
}
exit=0
discussion housekeep DSC-0097 --lesson discussion/lessons/DSC-0097-pbs-sdk-stack-queue/LSN-0095-private-array-stacks-and-circular-queues.md
housekept DSC-0097
removed workflow artifacts: 3
registered lesson: LSN-0095
exit=0
discussion validate
validation passed
exit=0
discussion inspect DSC-0097
DSC-0097 done pbs-sdk-stack-queue
PBS SDK Stack and Queue
tags: compiler-pbs, collections, umbrella-agd-0089
lessons:
- LSN-0095 done exists /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/discussion/lessons/DSC-0097-pbs-sdk-stack-queue/LSN-0095-private-array-stacks-and-circular-queues.md
exit=0