docs: consolidate canonical specs and preserve PBS reference IDs

This commit is contained in:
2026-10-28 15:11:00 +00:00
parent 9504f4694a
commit 3a3417eb44
74 changed files with 3231 additions and 270 deletions
+5 -2
View File
@@ -260,8 +260,11 @@ If you are new to the codebase, this order is usually the fastest path:
Important reference surfaces:
- `docs/specs/compiler/`: shared compiler specifications
- `docs/specs/packer/`: packer specifications
- [Specification guide](docs/specs/README.md): domain ownership and reading order
- [General compiler](docs/specs/compiler/README.md): shared compiler specifications
- [PBS](docs/specs/compiler-languages/pbs/README.md): language and SDK specifications
- [Studio](docs/specs/studio/README.md): shell, workspaces and integration contracts
- [Packer](docs/specs/packer/README.md): packer specifications
- `docs/vm-arch/`: VM and ISA architecture references
These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.
@@ -36,5 +36,5 @@ dependencies {
- **Naming Consistency**: Ensure library aliases in TOML follow a clear pattern (e.g., `slf4j-api` vs `slf4jApi`) to keep the build scripts readable.
## References
- [DEC-0023-gradle-version-catalog-adoption.md](../../workflow/decisions/DEC-0023-gradle-version-catalog-adoption.md)
- [PLN-0046-implement-gradle-version-catalog.md](../../workflow/plans/PLN-0046-implement-gradle-version-catalog.md)
- DEC-0023-gradle-version-catalog-adoption.md (`DEC-0023-gradle-version-catalog-adoption.md`, historical workflow artifact removed by housekeeping)
- PLN-0046-implement-gradle-version-catalog.md (`PLN-0046-implement-gradle-version-catalog.md`, historical workflow artifact removed by housekeeping)
@@ -138,7 +138,7 @@ 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)
- [Typed common Registry/PBX specification](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.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
@@ -169,8 +169,8 @@ 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)
- [Normative catalog support](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md)
- [Typed common Registry/PBX contract](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.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,
@@ -76,8 +76,8 @@ Frontend negatives cover invalid Button arguments, mixed int/long variables, lit
## 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)
- [Normative PBS input and existing-value contract](../../../docs/specs/compiler-languages/pbs/18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md)
- [Shared runtime catalog contract](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md)
- [Typed registry and PBX contract](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.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)
@@ -8,7 +8,7 @@ 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.
Owner: compiler/pbs. This lesson consolidates accepted DEC-0067 and completed PLN-0146 (DSC-0079). The [typed arrays specification](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) is the normative reference; the [implementation evidence](../../evidence/DSC-0079-implementation/README.md) records the tested tree and commands.
## The original problem
@@ -107,7 +107,7 @@ Common mistakes to avoid:
## References
- [Normative function and capture specification](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
- [Normative function and capture specification](../../../docs/specs/compiler-languages/pbs/15.%20First-Class%20Functions%20and%20Captures%20Specification.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).
@@ -150,8 +150,8 @@ explicitly reported by the full harness; original payloads are preserved.
## 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)
- [Service constants and runtime math specification](../../../docs/specs/compiler-languages/pbs/19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md)
- [Runtime catalog policy](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.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.
@@ -12,7 +12,7 @@ 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).
is [Runtime Random Integration](../../../docs/specs/compiler-languages/pbs/20.%20Runtime%20Random%20Integration%20Specification.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
@@ -151,9 +151,9 @@ SDK/spec/example delivery, not execution through an installed runtime process.
## 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).
- [PBS Random specification](../../../docs/specs/compiler-languages/pbs/20.%20Runtime%20Random%20Integration%20Specification.md).
- [Typed arrays and optional execution](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [Functions and captures](../../../docs/specs/compiler-languages/pbs/15.%20First-Class%20Functions%20and%20Captures%20Specification.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).
@@ -153,7 +153,7 @@ remains DSC-0085. Other platforms are not claimed by this evidence.
- [Static source contract](<../../../docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md>).
- [Dynamic execution contract](<../../../docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md>).
- [PBS lowering](<../../../docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md>).
- [Common typed Registry/PBX](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
- [Common typed Registry/PBX](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
- [Source-to-PBX corpus](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsGuestLifecycleTest.java).
- [Production VM/foreground harness](../../../tools/pbx-conformance/lifecycle.rs).
- [Installed lifecycle guide](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/LIFECYCLE.md).
@@ -38,14 +38,14 @@ are normative; lessons teach the choices and retain implementation/evidence cont
| Sequence / discussion | Durable lesson | Normative specification |
| --- | --- | --- |
| 1. Array, DSC-0088 | [LSN-0087: contextual parametric arrays](../DSC-0088-pbs-array-type-syntax/LSN-0087-parametric-arrays-and-contextual-construction.md) | [Array/optional](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md) |
| 2. Generic contracts, DSC-0089 | [LSN-0088: concrete contracts](../DSC-0089-pbs-generic-contracts/LSN-0088-concrete-generic-contracts-from-source-to-vm.md) | [Generic contracts](../../../docs/compiler/pbs/specs/generic-contracts.md) |
| 3. Generic structs/functions, DSC-0094 | [LSN-0089: concrete state/bodies](../DSC-0094-pbs-generic-structs/LSN-0089-concrete-generic-state-and-bodies.md) | [Generic structs/functions](../../../docs/compiler/pbs/specs/generic-structs-and-free-functions.md) |
| 4. List/Cursor, DSC-0090 | [LSN-0090: mutable positions/stable snapshots](../DSC-0090-pbs-sdk-list/LSN-0090-mutable-lists-and-stable-snapshot-cursors.md) | [List/shared Cursor](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md) |
| 5. Linked, DSC-0091 | [LSN-0091: private nodes/sequential phases](../DSC-0091-pbs-sdk-linked/LSN-0091-private-linked-nodes-and-atomic-publication.md) | [Linked](../../../docs/compiler/pbs/specs/sdk-linked-and-cursor.md) |
| 6. Set/Identity, DSC-0092 | [LSN-0093: reusable identity/buckets](../DSC-0092-pbs-sdk-set/LSN-0093-reusable-identity-and-source-set-buckets.md) | [Set/Identity](../../../docs/compiler/pbs/specs/sdk-set-and-identity.md) |
| 7. Map/Keyval, DSC-0093 | [LSN-0094: presence/representative keys](../DSC-0093-pbs-sdk-map-keyval/LSN-0094-map-presence-key-identity-and-captured-associations.md) | [Map/Keyval](../../../docs/compiler/pbs/specs/sdk-map-and-keyval.md) |
| 8. Stack/Queue, DSC-0097 | [LSN-0095: dense/circular arrays](../DSC-0097-pbs-sdk-stack-queue/LSN-0095-private-array-stacks-and-circular-queues.md) | [Stack/Queue](../../../docs/compiler/pbs/specs/sdk-stack-and-queue.md) |
| 1. Array, DSC-0088 | [LSN-0087: contextual parametric arrays](../DSC-0088-pbs-array-type-syntax/LSN-0087-parametric-arrays-and-contextual-construction.md) | [Array/optional](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) |
| 2. Generic contracts, DSC-0089 | [LSN-0088: concrete contracts](../DSC-0089-pbs-generic-contracts/LSN-0088-concrete-generic-contracts-from-source-to-vm.md) | [Generic contracts](../../../docs/specs/compiler-languages/pbs/16.%20Generic%20Contracts%20Specification.md) |
| 3. Generic structs/functions, DSC-0094 | [LSN-0089: concrete state/bodies](../DSC-0094-pbs-generic-structs/LSN-0089-concrete-generic-state-and-bodies.md) | [Generic structs/functions](../../../docs/specs/compiler-languages/pbs/17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) |
| 4. List/Cursor, DSC-0090 | [LSN-0090: mutable positions/stable snapshots](../DSC-0090-pbs-sdk-list/LSN-0090-mutable-lists-and-stable-snapshot-cursors.md) | [List/shared Cursor](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md) |
| 5. Linked, DSC-0091 | [LSN-0091: private nodes/sequential phases](../DSC-0091-pbs-sdk-linked/LSN-0091-private-linked-nodes-and-atomic-publication.md) | [Linked](../../../docs/specs/compiler-languages/pbs/22.%20SDK%20Linked%20and%20Cursor%20Specification.md) |
| 6. Set/Identity, DSC-0092 | [LSN-0093: reusable identity/buckets](../DSC-0092-pbs-sdk-set/LSN-0093-reusable-identity-and-source-set-buckets.md) | [Set/Identity](../../../docs/specs/compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md) |
| 7. Map/Keyval, DSC-0093 | [LSN-0094: presence/representative keys](../DSC-0093-pbs-sdk-map-keyval/LSN-0094-map-presence-key-identity-and-captured-associations.md) | [Map/Keyval](../../../docs/specs/compiler-languages/pbs/24.%20SDK%20Map%20and%20Keyval%20Specification.md) |
| 8. Stack/Queue, DSC-0097 | [LSN-0095: dense/circular arrays](../DSC-0097-pbs-sdk-stack-queue/LSN-0095-private-array-stacks-and-circular-queues.md) | [Stack/Queue](../../../docs/specs/compiler-languages/pbs/25.%20SDK%20Stack%20and%20Queue%20Specification.md) |
The supporting [LSN-0092 / DSC-0096](../DSC-0096-runtime-storage-isa-consumer-migration/LSN-0092-sequential-collection-mutations-need-explicit-failure-boundaries.md)
explains accepted DEC-0077 / PLN-0155: source checks, ordinary stores/ARRAY_COPY,
@@ -73,8 +73,8 @@ Local run logs were `/tmp/agd90-final-tests.log`, `/tmp/agd90-frontend-final.log
## 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).
- [Normative Array contract](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [Function values and captures](../../../docs/specs/compiler-languages/pbs/15.%20First-Class%20Functions%20and%20Captures%20Specification.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.
@@ -196,9 +196,9 @@ 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).
- [PBS generic contracts specification](../../../docs/specs/compiler-languages/pbs/16.%20Generic%20Contracts%20Specification.md).
- [Typed Registry/PBX and global relocation](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
- [Arrays, optional and contract execution](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [Functions and captures](../../../docs/specs/compiler-languages/pbs/15.%20First-Class%20Functions%20and%20Captures%20Specification.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.
@@ -12,7 +12,7 @@ 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)
[List/Cursor specification](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md)
is the durable normative reference.
PBS needed a resizable collection whose existing references remain valid, together
@@ -43,7 +43,7 @@ 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
[specification](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.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;
@@ -241,9 +241,9 @@ production corpus, full regressions and pinned provenance.
## 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),
- [List/Cursor specification](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md)
and [Array/optional foundation](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [Common Registry/PBX specification](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md),
[current provider copy code](../../../../runtime/crates/console/prometeu-vm/src/virtual_machine/array_copy.rs)
and [ordinary typed storage](../../../../runtime/crates/console/prometeu-vm/src/virtual_machine/collections.rs).
- [Source fixture generator](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsListCursorTest.java),
@@ -11,7 +11,7 @@ tags: [compiler-pbs, collections, snapshot-cursor, failure-phases, runtime-confo
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)
workflow control artifacts are disposable; the [Linked specification](../../../docs/specs/compiler-languages/pbs/22.%20SDK%20Linked%20and%20Cursor%20Specification.md)
is the durable normative reference.
PBS needed a dense sequence with private doubly linked nodes and useful end
@@ -224,10 +224,10 @@ NonFiniteValue, remain explicitly reported with original payloads.
## 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 storage](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
- [Linked specification](../../../docs/specs/compiler-languages/pbs/22.%20SDK%20Linked%20and%20Cursor%20Specification.md),
[List/shared Cursor](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md),
[generic structs](../../../docs/specs/compiler-languages/pbs/17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md)
and [generic Registry/PBX storage](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.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)
@@ -19,7 +19,7 @@ available to PBS consumers.
AGD-0094 converged into accepted DEC-0078 and implementation PLN-0156. The user
accepted the recommendations, authorized the decision and plan, and requested
implementation. These identifiers record provenance; normative behavior now lives
in the [Set/Identity specification](../../../docs/compiler/pbs/specs/sdk-set-and-identity.md).
in the [Set/Identity specification](../../../docs/specs/compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md).
Completed workflow scaffolding is removed by the discussion CLI.
The runtime provider is `dcf6561ea73446e0a3e1cf1c73eda20923b38df0`, consumed
@@ -132,7 +132,7 @@ guard; a callback fault may leave it installed.
Prepare checks, callbacks, next size, nodes/tables and complete values before
structural stores. Then apply ordinary sequential stores without user callbacks.
The [shared failure-phase contract](../../../docs/compiler/pbs/specs/sdk-set-and-identity.md#guard-mutation-phases-and-faults)
The [shared failure-phase contract](../../../docs/specs/compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md#guard-mutation-phases-and-faults)
is essential:
| Outcome | Meaning |
@@ -209,9 +209,9 @@ JUnit cases are listed separately from the mandatory runtime corpus.
## References
- [Set/Identity/hash specification](../../../docs/compiler/pbs/specs/sdk-set-and-identity.md).
- [Shared Cursor specification](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md).
- [Common Registry/PBX specification](../../../docs/compiler/general/specs/typed-registry-and-pbx-v0.md).
- [Set/Identity/hash specification](../../../docs/specs/compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md).
- [Shared Cursor specification](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md).
- [Common Registry/PBX specification](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
- [SDK collection source](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs).
- [Set source fixtures](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsSetTest.java).
- [Conformance tooling and reproduction](../../../tools/pbx-conformance/README.md).
@@ -10,7 +10,7 @@ tags: [compiler-pbs, collections, map, keyval, identity, optional, cursor]
**Worker:** Lesson Worker. **Owner domain:** `compiler/pbs`.
**Discussion:** DSC-0093, accepted DEC-0079 implemented by PLN-0157 (R1–R12).
The normative contract is [SDK Map and Keyval](../../../docs/compiler/pbs/specs/sdk-map-and-keyval.md).
The normative contract is [SDK Map and Keyval](../../../docs/specs/compiler-languages/pbs/24.%20SDK%20Map%20and%20Keyval%20Specification.md).
The [evidence record](evidence/README.md) preserves reproduction commands, source
and fixture fingerprints, raw logs and requirement coverage after housekeeping.
@@ -58,7 +58,7 @@ generic struct and can hold optional components. The restriction on
## Preserve the stored key representative
Default Identity follows the [Set policy](../../../docs/compiler/pbs/specs/sdk-set-and-identity.md):
Default Identity follows the [Set policy](../../../docs/specs/compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md):
scalar/String values use their specified value domains; eligible objects use
instance identity; contracts use their validated receiver. Unsupported defaults
require an explicit Identity<K>. V needs no equality/hash capability.
@@ -113,7 +113,7 @@ an immutable private snapshot node, plus applicable carriers. Capture takes
O(B+N) work and O(N) extra storage, returns only when complete, calls no strategies
and retains no editable Map node or bucket position.
The [shared Cursor table](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md#cursor-protocol)
The [shared Cursor table](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol)
is unchanged: current starts on the first captured entry; hasNext tests for a
successor; next without one retains the last entry. Only an empty-born Cursor has
absent current. Consume current before checking whether to advance.
@@ -185,7 +185,7 @@ threshold, other-host qualification or installed game readiness. Existing unrela
disabled JUnit cases and upstream headless-schema gaps remain explicit in the
evidence and are not counted as new Map conformance.
- [Normative Map/Keyval specification](../../../docs/compiler/pbs/specs/sdk-map-and-keyval.md).
- [Normative Map/Keyval specification](../../../docs/specs/compiler-languages/pbs/24.%20SDK%20Map%20and%20Keyval%20Specification.md).
- [Executable installed example](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/src/maps.pbs).
- [SDK algorithms](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs).
- [Source-to-PBX qualification](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsMapKeyvalTest.java).
@@ -193,10 +193,10 @@ 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).
- [Generic structs and free functions](../../../docs/specs/compiler-languages/pbs/17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
- [Generic contracts](../../../docs/specs/compiler-languages/pbs/16.%20Generic%20Contracts%20Specification.md).
- [Arrays and optional](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [Functions and captures](../../../docs/specs/compiler-languages/pbs/15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
- [Random integration](../../../docs/specs/compiler-languages/pbs/20.%20Runtime%20Random%20Integration%20Specification.md).
- [Concrete common Registry/PBX](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
- Historical execution plan: PLN-0152, completed and removed by discussion housekeeping.
@@ -0,0 +1,158 @@
---
id: LSN-0098
ticket: canonical-documentation-migration
title: One specification tree and stable installed reference IDs
created: 2026-10-28
tags: [compiler, compiler-pbs, packer, studio, documentation, migration]
---
# One specification tree and stable installed reference IDs
**Worker:** Lesson Worker. **Owner:** `compiler/general`.
Propagation: `compiler/pbs`, `packer`, `studio` and cross-domain navigation.
DSC-0095 executed accepted DEC-0082 through PLN-0160. These are historical
workflow identifiers; the durable entry point is the
[specification guide](../../../docs/specs/README.md).
## Original problem
Compiler contracts were split between `docs/specs` and `docs/compiler`.
The earlier generic-struct implementation exposed contradictory constructor
descriptions across those surfaces. That semantic choice had already been
settled explicitly, but separate document roots still encouraged competing
authority, incomplete navigation and filename-derived installed IDs.
The user explicitly chose consolidation **into `docs/specs`**, reversing the
initial migration proposal. Updating paths also required updating AGENTS.md
routing, the PBS knowledge build, consumers and historical navigation.
## Consolidated decision and final result
There is one specification tree with distinct owners:
| Owner | Canonical reading guide |
| --- | --- |
| `compiler/general` | [Shared compiler contracts](../../../docs/specs/compiler/README.md) |
| `compiler/pbs` | [PBS source, SDK and projections](../../../docs/specs/compiler-languages/pbs/README.md) |
| `packer` | [Packer contracts](../../../docs/specs/packer/README.md) |
| `studio` | [Studio contracts](../../../docs/specs/studio/README.md) |
All 14 specifications formerly under `docs/compiler` were incorporated as
numbered chapters. Existing chapter numbers remained unchanged. Packer and
Studio retained their established directories; their affected navigation was
corrected. The replaced source tree was removed, and the PBS build consumes
only `docs/specs/compiler-languages/pbs`.
General compiler additions are [24: Runtime Catalog Support](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md)
and [25: Typed Registry and PBX v0](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
PBS additions and their retained published aliases are:
| Filename part of the published `pbs:spec:<filename>` ID | Canonical chapter ID |
| --- | --- |
| `typed-arrays-and-optional-execution.md` | `pbs:spec:14` |
| `first-class-functions-and-captures.md` | `pbs:spec:15` |
| `generic-contracts.md` | `pbs:spec:16` |
| `generic-structs-and-free-functions.md` | `pbs:spec:17` |
| `input-and-existing-type-runtime-alignment.md` | `pbs:spec:18` |
| `service-constants-and-runtime-math.md` | `pbs:spec:19` |
| `runtime-random-integration.md` | `pbs:spec:20` |
| `sdk-list-and-cursor.md` | `pbs:spec:21` |
| `sdk-linked-and-cursor.md` | `pbs:spec:22` |
| `sdk-set-and-identity.md` | `pbs:spec:23` |
| `sdk-map-and-keyval.md` | `pbs:spec:24` |
| `sdk-stack-and-queue.md` | `pbs:spec:25` |
The [content verification map](evidence/content-verification.json) preserves
every exact source/destination path, original and final fingerprints, and the
result of comparing all 14 contract bodies while excluding changed link
destinations, owner/status/scope metadata, added authority sections and whitespace.
All 14 bodies matched under that normalization. No source contract was dropped.
## Preserve identity independently of editorial filenames
Previously, `substringBefore(". ")` produced chapter IDs for numbered files and
whole-filename IDs for unnumbered files. A rename could therefore change a
published reference without changing its actual contract.
The build now emits an explicit compatibility catalog. For example:
```text
pbs:spec:generic-contracts.md -> pbs-knowledge/specs/16. Generic Contracts Specification.md
pbs:spec:16 -> pbs-knowledge/specs/16. Generic Contracts Specification.md
```
Both entries use the same resource and SHA-256. The old ID still resolves,
while the editor can follow the existing numbered-document pattern. There is
one canonical resource, not two source documents. The former unnumbered resource
path is replaced; reference clients resolve IDs through the catalog instead of
constructing filenames. Duplicate IDs and missing alias targets fail generation.
`PbsDocumentationTest` checks all 12 published aliases against their numbered
counterparts, including text, kind, resource and hash. The installed probe repeats
the identity checks using actual installed JARs in a process outside the checkout.
The normal quickstart, previous chapter IDs, SDK and example IDs remain available.
## Consolidate authority without changing semantics
Thematic chapters own complete feature contracts. Base chapters retain distinct
syntax, AST, diagnostic and lowering requirements and refer to those owners for
shared detail. Static-semantics feature summaries were reduced to owner references;
unique spans, error codes, substitution and runtime-hook requirements were retained.
Editorial alignment also removed stale descriptions already superseded by
accepted contracts: nominal callback/bind forms are retired in favor of structural
Fn, numeric `as` conversions retain their value-alignment contract, and reserved
service constants retain their supported BuiltinConst form. The existing
[explicit constructor initialization rule](../../../docs/specs/compiler-languages/pbs/17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md#construction-and-expected-types)
continues to cover ordinary/generic constructors and opaque Random fields.
Runtime reference defaults do not exempt PBS source constructors.
The migration does not redesign APIs or infer a new solution to substantive
normative disagreement. A future unresolved conflict still requires an explicit
decision rather than an editorial compromise.
## Navigation and provenance need different treatment
Rebase a moved file's relative links from its **original** location and then map
the target to its new location. A global text replacement cannot distinguish
general compiler, language, packer and provider ownership or different path depths.
The migration also repaired Studio-to-packer links and links to completed workflow
artifacts, using completed lessons or explicit historical citations.
Obsolete local hardware/bytecode authority pointers were replaced with provider
references and the [mirror policy](../../../docs/vm-arch/README.md). Retired PBS
drafts are historical context, not a competing normative source.
Architecture/ISA mirrors retain byte-exact provider content. Their relative links
belong to the original runtime context; changing them inside the mirror would
invalidate byte identity. The navigation checker resolves those links against
that context when a runtime checkout is supplied. It performs no runtime writes.
The 65 pre-existing evidence/mirror files recorded in the verification map retained
their exact hashes. Updated lesson links do not imply that historical executions
were repeated or newly qualified.
## Validation and common pitfalls
The final normal Gradle suite and installed-knowledge gate passed: 1,099 normal
test cases, zero failures/errors, 13 skipped; two installed tests passed. The final
JAR contains 79 references, 12 compatibility aliases and 28 canonical spec
resources, each byte-identical to its final source. The installed examples compile
outside the checkout. No runtime repository changes were required.
Avoid these failure modes:
- Moving files without updating the generated knowledge index or root locators.
- Letting a filename rename silently break a public reference ID.
- Preserving compatibility with a second editable spec tree or source fallback.
- Replacing shared text with links while dropping unique AST/diagnostic requirements.
- Editing mirrored provider bytes just to repair provider-relative links.
- Rewriting historical fingerprints or linking to workflow artifacts already removed.
Run `python3 tools/documentation/verify.py` for local navigation. Add
`--runtime ../runtime` to verify provider references against a read-only checkout;
ordinary builds do not require it. Run the existing installed-knowledge gate after
source changes because a passing checkout read does not prove packaged delivery.
[Validation evidence](evidence/README.md) records commands, results, fingerprints
and the complete migration map. Completed workflow artifacts are disposed of
through the local discussion CLI.
@@ -0,0 +1,38 @@
# Canonical documentation migration evidence
Owner: `compiler/general`. Discussion: DSC-0095; accepted decision DEC-0082;
implementation plan PLN-0160. Recorded on 2026-10-28, macOS ARM64.
## Commands and results
- `./gradlew test :prometeu-app:installedKnowledgeTest --console=plain` passed
against the final corpus. The normal suite reports 1,099 cases, zero failures
and errors, and 13 skipped. The installed suite reports two passing tests.
- `python3 tools/documentation/verify.py --runtime ../runtime` checks local paths,
encoded spaces and anchors, and provider-context mirror links. Final navigation
output is retained in `navigation.log`.
- `git diff --check` and `discussion validate` pass; the workflow is finalized
through CLI housekeeping rather than manual index edits.
- The installed probe runs the real JAR distribution outside the checkout. All
12 old filename IDs share canonical resources/hashes with numbered IDs. Existing
SDK and example reads, example compilation and packaged LSP checks also pass.
## Retained artifacts
- `regression.log.gz`: final Gradle command output.
- `results.json`: baseline revision, platform, normal/installed suite counts,
installed JAR fingerprint and packaged-corpus results.
- `content-verification.json`: exact 14-file source/destination map, original and
final source hashes, body-preservation results and 65 unchanged evidence/mirror
fingerprints. Body normalization excludes changed Markdown link destinations,
status/owner/scope metadata, the added authority section and whitespace.
- `installed-reference-index.json`: actual index extracted from the final installed
PBS JAR. There are 79 references, 12 aliases and 28 distinct specification resources.
- `navigation.log`: final documentation navigation verification.
- `SHA256SUMS`: fingerprints of these evidence files.
All 28 packaged specification resources were also compared byte-for-byte with
their final checked-in source paths. Old unnumbered spec resources are absent.
Historical evidence/mirrors were not rewritten. The sibling runtime was used
only to resolve provider-reference targets and anchors; no files or commits were
written there. These checks do not claim new runtime/platform qualification.
@@ -0,0 +1,6 @@
1e6833fdcbc45f3c7e98eb948853d146e995d6d175ee8f0d7c7eaf2997649de6 README.md
8302f59b2bcf2cc9efef753b26f817bee4fcf1a53d9e9f8087522ee1730aa013 content-verification.json
9181e0b8eb616f73a27aa65b304878778a8c07e18f6abfde05d9374a2a184621 installed-reference-index.json
f80e769dc456b8f4803811f0f391c0d9bbe8f7afcfce038944112a60eabf89d7 navigation.log
908c11a200bdd366355a558cc6edc74421a2c9a893c9dee84f57f3fdf060032e regression.log.gz
3a6b6ba35f8bdb024c4290b56ec1193585efbffd34dca196f465c09d79b51f72 results.json
@@ -0,0 +1,170 @@
{
"mapped_chapters": [
{
"source": "docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md",
"destination": "docs/specs/compiler-languages/pbs/14. Typed Arrays and Optional Execution Specification.md",
"body_preserved": true,
"original_sha256": "fe0e0d0eccfacd5b3f5ca220ec8c7a7c82f7bc527c5317d4b0651443b021f73e",
"destination_sha256": "6140d19a9aac04f0a0ef90321b19fa36779b264626061d3e841cd23be1efdf07"
},
{
"source": "docs/compiler/pbs/specs/first-class-functions-and-captures.md",
"destination": "docs/specs/compiler-languages/pbs/15. First-Class Functions and Captures Specification.md",
"body_preserved": true,
"original_sha256": "6523139b7232938993254b6ed91c46769e8bdee67d9b9158f9476c73d0d2216d",
"destination_sha256": "510c13899a498137df539ae0df8bbb5b969cc955591a074a734d76e26e45d8a4"
},
{
"source": "docs/compiler/pbs/specs/generic-contracts.md",
"destination": "docs/specs/compiler-languages/pbs/16. Generic Contracts Specification.md",
"body_preserved": true,
"original_sha256": "e61f3a1a2d3ebe17f680dddee805de56f8e57356a98ea3821885da1ba70d1d98",
"destination_sha256": "d1b20ca41bda3a47782d24c9793eaba1a2ef24fa378fe899c25d34ffe060c84e"
},
{
"source": "docs/compiler/pbs/specs/generic-structs-and-free-functions.md",
"destination": "docs/specs/compiler-languages/pbs/17. Generic Structs and Free Functions Specification.md",
"body_preserved": true,
"original_sha256": "8d5804910106bfa3f654edcefd2a7d196d70fdf19fd67b86bc80d8d766ffe25b",
"destination_sha256": "c56a68e6e76aa32d4d4c631f89f286604315197bdfc50981c5547c005fae1556"
},
{
"source": "docs/compiler/pbs/specs/input-and-existing-type-runtime-alignment.md",
"destination": "docs/specs/compiler-languages/pbs/18. Input and Existing Type Runtime Alignment Specification.md",
"body_preserved": true,
"original_sha256": "3ad61545fd377377b769e356c419b10d58aa12c8eb80eba993145d5990d06449",
"destination_sha256": "30bd2f9bd20a2d65cc0f23396d2b893088252f08c673ab26baff252614c20ad5"
},
{
"source": "docs/compiler/pbs/specs/service-constants-and-runtime-math.md",
"destination": "docs/specs/compiler-languages/pbs/19. Service Constants and Runtime Math Specification.md",
"body_preserved": true,
"original_sha256": "ad18ab0bc5605f4600554eae8c0fa676b3c3c5de285e92290b6c708ed4b3170d",
"destination_sha256": "98d51fc380ee8e43837b655ccf9af6bbec892bc9a5e5f7ddcf701642b1a7c006"
},
{
"source": "docs/compiler/pbs/specs/runtime-random-integration.md",
"destination": "docs/specs/compiler-languages/pbs/20. Runtime Random Integration Specification.md",
"body_preserved": true,
"original_sha256": "da5258e630d286690a50a1a1a687e670429f0e15f710245b3134bb16043b56c8",
"destination_sha256": "a148e7b7c397eab1853b8c63fc90526e869e9c26f13c179d1cf88db7c3db1559"
},
{
"source": "docs/compiler/pbs/specs/sdk-list-and-cursor.md",
"destination": "docs/specs/compiler-languages/pbs/21. SDK List and Cursor Specification.md",
"body_preserved": true,
"original_sha256": "7f46e87702529c8ea94660a644580c0c884bb27a965a2612d32a92bc31ff9b52",
"destination_sha256": "037ee143e9748a34a3de569ea935449450f225d96759bc983839a49e5a7d892c"
},
{
"source": "docs/compiler/pbs/specs/sdk-linked-and-cursor.md",
"destination": "docs/specs/compiler-languages/pbs/22. SDK Linked and Cursor Specification.md",
"body_preserved": true,
"original_sha256": "bd399f1923353390c6bd7e8613c53a1656e99fbb37e750abd840ceee77dd4c68",
"destination_sha256": "d7c0ad5756920033e4f9d12c7980f5d1262431feea8b59857381a2cff0717f03"
},
{
"source": "docs/compiler/pbs/specs/sdk-set-and-identity.md",
"destination": "docs/specs/compiler-languages/pbs/23. SDK Set and Identity Specification.md",
"body_preserved": true,
"original_sha256": "4af3aa15ce6da20ae83c39ab4fcca38beba6f634ee5e55bf5f6edb0b5018ad50",
"destination_sha256": "ec94a33bd55600fb12deb2d02abe2a985ea3b5f559ddc222c52f89336c6d5bb7"
},
{
"source": "docs/compiler/pbs/specs/sdk-map-and-keyval.md",
"destination": "docs/specs/compiler-languages/pbs/24. SDK Map and Keyval Specification.md",
"body_preserved": true,
"original_sha256": "12135be9ff129493eb332f4bb9c05e36d7667e001f52669d03d90221d1232d9a",
"destination_sha256": "3c1912adacca020f17747430275619a0cc9972a02835a7aac66ca053403978cc"
},
{
"source": "docs/compiler/pbs/specs/sdk-stack-and-queue.md",
"destination": "docs/specs/compiler-languages/pbs/25. SDK Stack and Queue Specification.md",
"body_preserved": true,
"original_sha256": "a47f6fc58068a333119e73201a1a04b5ba96c916ccf6c22a4a13161ee92e7629",
"destination_sha256": "90e6bf7bae68872a5294c7d5bede4ecd4f7cfc26513c26d6cffe82f046ab56fb"
},
{
"source": "docs/compiler/general/specs/runtime-catalog-support.md",
"destination": "docs/specs/compiler/24. Runtime Catalog Support Specification.md",
"body_preserved": true,
"original_sha256": "b86f24c8ce609b0994b9fcfabfff0ec2a78a0fafaf242b931db10ba2325d30fb",
"destination_sha256": "cae949ceafa346348fb71a31bdb001ec967014df028f93907a104e872510aa62"
},
{
"source": "docs/compiler/general/specs/typed-registry-and-pbx-v0.md",
"destination": "docs/specs/compiler/25. Typed Registry and PBX v0 Specification.md",
"body_preserved": true,
"original_sha256": "a42de4571212c8dff1eef91d23c0dba601775f6e0d7955ee4b9b17f6befff274",
"destination_sha256": "95ccf43d7622fd6a1a63f8e9bc98222d0df044c188dba3e2a86915bc752d25b0"
}
],
"immutable_files_verified": 65,
"immutable_sha256": {
"discussion/lessons/DSC-0082-pbs-runtime-random-integration/evidence.json": "e2ec8184e0f62a57a7d1647bb471f8a14349408abdea3dfac17207d2203d5a2f",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/SHA256SUMS": "ae8bd14891e5f9d6ad62c0b5535bd3217bf1dc90dbdc4174646f7a55772995b6",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/TEST-p.studio.compiler.backend.irvm.PbsGuestLifecycleTest.xml.gz": "e520456a82c905db92598e4a314b1614d409358674e73d0dcd61416b146d3c6d",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/fixtures.sha256": "638814b1afabc2e156de2eb6f018400aab7fea2c9b69c7f956ab16251dd5ed60",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/frontend.log.gz": "ceb059e502313f0327e0560a4532c57f4a341776d054fee1558c54e6de82c4b1",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/regression-and-installed.log.gz": "44619de3dcc5ca667a2dbe951146eba0cf21a919f8d0a1610dc5fec8ade1f33d",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/runtime-dev.log.gz": "cd7051255fed7a2760fbec8be05b9e8a98b224f704828a26e28ee71097810bbf",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/runtime-release.log.gz": "3bd1c9aceb4a05bfcd5ddaa4a1d8e2ed96270e3666b7f4ce46a91f7e7bf902ee",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/sources.sha256": "bd704a8fe37c15f2b404c3924e49b06f5a8b3a1e389be9252cd3dae953b67f7a",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/summary.json": "867e02d58fcd451a68a54c59ae63e0d57d2c08fc79861d5d0d8b20ee832b5d81",
"discussion/lessons/DSC-0084-pbs-guest-lifecycle-hooks/evidence/workflow.txt": "d7e7bdfdb38395e54163d7b9d24d7a6f1ce5fb5d017feac63c6e0fc463c7afaf",
"discussion/lessons/DSC-0090-pbs-sdk-list/runtime-conformance-evidence.json": "9790633203a0694c0cc3b30081116d9245db4a53491bd75b168d0ca02d6aeb52",
"discussion/lessons/DSC-0091-pbs-sdk-linked/runtime-conformance-evidence.json": "bd3b7f24c1d2720afea49917f64dad7f1f0a001bdb9e9812bb4aaad16f8cdf1c",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/SHA256SUMS": "34db4219c9173ebb433baab58f32d600b6d325f9bd884e47a48f83b22e9fa405",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/conformance-debug.log.gz": "fb48082c878378f7fa01009361380b38be074a0b711edc605c531c9fb575ff5a",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/conformance-release.log.gz": "4e5b52584c70bca57c3b715558102b663daf51cf84bebf549600bdf11c88cab4",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/distribution-tests.log.gz": "774b5aa6f29a3e4d986bab805427b7d0a0c53445749e03a93db4320cee376302",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/environment.txt": "1510a88944e6a632e4373d35e3e5855a06a1273f7f0be3b590d811faa209d830",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/fixtures.sha256.gz": "5b136af3ee037ba0879c02cc57c135350ed446853dedfd41a7455a532e4852e6",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/gradle-results.json": "b7a05d6c252b869cd2a909edd40ef16a094279d6aee4379daa67b607753cfe2b",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/hashing-conformance.log.gz": "3e4e33aa6338142b79a4740945c50b149c572980ad108219d930e3909dd73f8a",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/hashing-tests.log.gz": "6c4a1723e53ad40a2315a509a43a6a0058db145cc006ee4bc7a346cd12333fee",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/provider-catalog.log.gz": "79b81e38a9ecf948c7381796c77aa30929dbcfcd2f4eb0a5ead71032fbb5bf04",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/provider-hash-remaining.log.gz": "2f53ddd02d054c4c801aeaf20981f83eb28961b9b973fd025c10aed6673dd254",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/provider-identity-debug.log.gz": "0d2a846ee52a7a40662c1720055ffdf36179cdbaf846696e07d7ab0149d4367d",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/provider-identity-private-debug.log.gz": "0255d42eb28c98566741fa17987480969ab89b35a113c568481240713f69aa1e",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/regression.log.gz": "f6ca7e0c4865b83031d8f21e166248209089a91466103d193cb14ffd8e533df7",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/set-conformance.log.gz": "9f9bf7af13da11147a1388ea86a41f8e59202b4d08333dca24d4385d5329dc21",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/set-tests.log.gz": "60b879014ec61aad58eb6aba651e28fb017077c3c17a6f06b2851f99be50ca72",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/source.sha256": "2d0b3b19a447fa29a4ae127842db26d4adacb400af77837c09edd8ea0c9874c3",
"discussion/lessons/DSC-0092-pbs-sdk-set/evidence/workflow.txt": "0e245cc1d83d697f9ffb3fb0a8dd18800cdc0892c23def0d4e14737c3cb42cbc",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/SHA256SUMS": "3b675bbd28c69f6cfc08611a045a5adcee47b546080c50c7aa18468d478c5633",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/conformance-debug.log.gz": "08b3115f4dc03a2a637b4133fd4a7ec6a27395183b8de1d778953e71c2e7df9f",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/conformance-release.log.gz": "5efbde06fc26364560cf5e4e717d8023769ce322edb624b01d80e957dfe1a701",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/environment.json": "325cb8c0638609340e398352e1c7a006b232ad24c7f860958f84017193266576",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/fixtures.sha256.gz": "8e8453dbd3b4e336d6fcf5d49337cb03ef2a3365d8e905f4db52d7ce6a8d1000",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/gradle-results.json": "effff1a1552e7210bdb0486e44996d668dfb1d1e1cd1c0f076fe7a47a837f0f6",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/map-results.json": "be95e4f4aa5c8d2718c8cc356b3eaa68cce050632f0ea6d1ed5051f482013b4e",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/regression.log.gz": "5af47b805bcf2c794d95bfaf517fe592e6b24116ba87d1c46a490fbbc18fbce1",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/source.sha256": "8569d628c2e0305e403197ef8b7c92cb9156bae817529a01f828c7ef340ce3ea",
"discussion/lessons/DSC-0093-pbs-sdk-map-keyval/evidence/workflow.txt": "e93ad3067041f75297210adbf1f6cfd6a30a090c44d74afaf0059b6a1bee1faf",
"discussion/lessons/DSC-0094-pbs-generic-structs/evidence.json": "fb82fab4caf77094fba012085df288c0218881a3c0a68e7cfb6b554968bab383",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/conformance-debug.log.gz": "df08969fd266c7b8844146a42bcfc63d078792d0fa69441c5660a553a73e0255",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/conformance-release.log.gz": "346711a7d78590e803d478520423584d60501fc70ea4856a1ed4b565ba25c7d1",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/generated-pbx-manifest.json": "f2679f21014e51812a5a79e8de26297828a7ba8685142811bff786f5fd5f5453",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/gradle-packaged-final.log.gz": "dc391a4532e28387573f4b65b02395b38ed164fd851d0b4423a4408396a46bd0",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/gradle-regression.log.gz": "85eb690857eea9e1961cf1011fff23c2f9e66185868a38681624c66a7cea3e92",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/provider-catalog.log.gz": "bab6e8190952884c3a24cf2f0cdf46890f294b150ff6accfb60f58a82aabacc3",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/provider-copy-tests.log.gz": "a0b8f2692556846cd7b418ae91993ddd3d0c6fef1f6fb2aa4551b962996b4d3e",
"discussion/lessons/DSC-0096-runtime-storage-isa-consumer-migration/runtime-conformance-evidence.json": "b4f69e1a2d22734053126a579de52c42bff22a2bf58f1dcdb3820a6e085ac156",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/SHA256SUMS": "d6f11fbec59c8b7894d7d7ca57ba89c6982c6543cd3d42ef79956512a77c43f2",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/conformance-debug.log.gz": "4e16e23cfc9d75228649d632f590183523fb6a854ac0f2d940eaffe021b6a70d",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/conformance-release.log.gz": "c74d26c969512b48895178a7bdbc542c15c736b5f2a41b7b864bafb58dadc837",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/environment.json": "c6d5b81a62d8e9a274615f2ca0aaf0b0f4a7159e57be8911f8f9926a507a5811",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/fixtures.sha256.gz": "31a231667d6dab2d50eac1814d12b9fe24deea737fd0933146a78ae3458138df",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/gradle-results.json": "0bc694f54f81807ed1d856d10e370eb652ca833ba9fc1f8a229feb8bdaee4f8c",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/regression.log.gz": "23844d7c633f5d92e3b0a0998582272383eeb1a293571553809b274303806d01",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/source.sha256": "7f405c7a5cd9d47c6b46fe903e019fe4dfe8e189f9596b8133e9510ceb14a784",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/stack-queue-results.json": "64272efe4bf46ab787455c5a82a20e5857f8ca72e39a2bdcfcde191221b0e63f",
"discussion/lessons/DSC-0097-pbs-sdk-stack-queue/evidence/workflow.txt": "2a42448fbc6324cc52b1840e6f337d92843a6d9209854307096916dbf8d3d6bb",
"docs/vm-arch/ARCHITECTURE.md": "d7e3487bb2d9718bba810cf4cfaec175dcbf9b079f7df12a4fad537bd1606146",
"docs/vm-arch/BUILTIN_CONSTANTS.csv": "e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039",
"docs/vm-arch/INTRINSICS.csv": "7c1c363f5f0f941b3ab27cfc72af41e13e44cd4371c687db8300721288f47e63",
"docs/vm-arch/ISA_CORE.md": "6b3207f81d3bd782e4f9b445b19c80b64bc599d8aebc5f01d8627a477bd09c8b",
"docs/vm-arch/runtime-catalog.properties": "ee236a887514d31f8996c5186796fee353ad89d112614ebbf23c9ed17a84deed"
}
}
@@ -0,0 +1,717 @@
{
"schemaVersion": 1,
"owner": "pbs",
"references": [
{
"id": "pbs:spec:1",
"title": "PBS Language Charter",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/1. Language Charter.md",
"sha256": "eac12dcc1a8d8b2a20a98cdf95d380501826c16dad476bd7360432770acfd8bc",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:10",
"title": "PBS Memory and Lifetime Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/10. Memory and Lifetime Specification.md",
"sha256": "1d8d4797fddb565d57f0dca0dc35d88a80b81366eae57173b5dc4c83d2ebf080",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:11",
"title": "PBS AST Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/11. AST Specification.md",
"sha256": "f9b731243f69ae1434eb4e0400c341367ddb23eea84e8df9adbb2f58d037bdef",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:12",
"title": "PBS Diagnostics Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/12. Diagnostics Specification.md",
"sha256": "255fbb5767b0e57bcb0147aa6059018a2f37992251b21d1cc2afef509fadcd01",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:13",
"title": "PBS Lowering IRBackend Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/13. Lowering IRBackend Specification.md",
"sha256": "ee21aa9ba4916478ced6d4d291aed6e39ca79a14c7526a42676a0251864befa6",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:14",
"title": "Typed arrays and optional execution",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/14. Typed Arrays and Optional Execution Specification.md",
"sha256": "6140d19a9aac04f0a0ef90321b19fa36779b264626061d3e841cd23be1efdf07",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:typed-arrays-and-optional-execution.md",
"title": "Typed arrays and optional execution",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/14. Typed Arrays and Optional Execution Specification.md",
"sha256": "6140d19a9aac04f0a0ef90321b19fa36779b264626061d3e841cd23be1efdf07",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:15",
"title": "First-class functions and explicit value captures",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/15. First-Class Functions and Captures Specification.md",
"sha256": "510c13899a498137df539ae0df8bbb5b969cc955591a074a734d76e26e45d8a4",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:first-class-functions-and-captures.md",
"title": "First-class functions and explicit value captures",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/15. First-Class Functions and Captures Specification.md",
"sha256": "510c13899a498137df539ae0df8bbb5b969cc955591a074a734d76e26e45d8a4",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:16",
"title": "PBS Generic Contracts",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/16. Generic Contracts Specification.md",
"sha256": "d1b20ca41bda3a47782d24c9793eaba1a2ef24fa378fe899c25d34ffe060c84e",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:generic-contracts.md",
"title": "PBS Generic Contracts",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/16. Generic Contracts Specification.md",
"sha256": "d1b20ca41bda3a47782d24c9793eaba1a2ef24fa378fe899c25d34ffe060c84e",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:17",
"title": "Concrete Generic Structs and Free Functions",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/17. Generic Structs and Free Functions Specification.md",
"sha256": "c56a68e6e76aa32d4d4c631f89f286604315197bdfc50981c5547c005fae1556",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:generic-structs-and-free-functions.md",
"title": "Concrete Generic Structs and Free Functions",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/17. Generic Structs and Free Functions Specification.md",
"sha256": "c56a68e6e76aa32d4d4c631f89f286604315197bdfc50981c5547c005fae1556",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:18",
"title": "PBS input and existing value runtime alignment",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/18. Input and Existing Type Runtime Alignment Specification.md",
"sha256": "30bd2f9bd20a2d65cc0f23396d2b893088252f08c673ab26baff252614c20ad5",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:input-and-existing-type-runtime-alignment.md",
"title": "PBS input and existing value runtime alignment",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/18. Input and Existing Type Runtime Alignment Specification.md",
"sha256": "30bd2f9bd20a2d65cc0f23396d2b893088252f08c673ab26baff252614c20ad5",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:19",
"title": "Service constants and runtime math",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/19. Service Constants and Runtime Math Specification.md",
"sha256": "98d51fc380ee8e43837b655ccf9af6bbec892bc9a5e5f7ddcf701642b1a7c006",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:service-constants-and-runtime-math.md",
"title": "Service constants and runtime math",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/19. Service Constants and Runtime Math Specification.md",
"sha256": "98d51fc380ee8e43837b655ccf9af6bbec892bc9a5e5f7ddcf701642b1a7c006",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:2",
"title": "PBS Governance and Versioning",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/2. Governance and Versioning.md",
"sha256": "8fd78f7f4962cfe5d0243199ea71e0c563a8e3999437e1adcdfeb0df256aed75",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:20",
"title": "PBS Runtime Random Integration",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/20. Runtime Random Integration Specification.md",
"sha256": "a148e7b7c397eab1853b8c63fc90526e869e9c26f13c179d1cf88db7c3db1559",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:runtime-random-integration.md",
"title": "PBS Runtime Random Integration",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/20. Runtime Random Integration Specification.md",
"sha256": "a148e7b7c397eab1853b8c63fc90526e869e9c26f13c179d1cf88db7c3db1559",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:21",
"title": "SDK List and snapshot Cursor",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/21. SDK List and Cursor Specification.md",
"sha256": "037ee143e9748a34a3de569ea935449450f225d96759bc983839a49e5a7d892c",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:sdk-list-and-cursor.md",
"title": "SDK List and snapshot Cursor",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/21. SDK List and Cursor Specification.md",
"sha256": "037ee143e9748a34a3de569ea935449450f225d96759bc983839a49e5a7d892c",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:22",
"title": "SDK Linked and bidirectional snapshot capture",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/22. SDK Linked and Cursor Specification.md",
"sha256": "d7c0ad5756920033e4f9d12c7980f5d1262431feea8b59857381a2cff0717f03",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:sdk-linked-and-cursor.md",
"title": "SDK Linked and bidirectional snapshot capture",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/22. SDK Linked and Cursor Specification.md",
"sha256": "d7c0ad5756920033e4f9d12c7980f5d1262431feea8b59857381a2cff0717f03",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:23",
"title": "SDK Set, Identity and hashing",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/23. SDK Set and Identity Specification.md",
"sha256": "ec94a33bd55600fb12deb2d02abe2a985ea3b5f559ddc222c52f89336c6d5bb7",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:sdk-set-and-identity.md",
"title": "SDK Set, Identity and hashing",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/23. SDK Set and Identity Specification.md",
"sha256": "ec94a33bd55600fb12deb2d02abe2a985ea3b5f559ddc222c52f89336c6d5bb7",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:24",
"title": "SDK Map and read-only Keyval associations",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/24. SDK Map and Keyval Specification.md",
"sha256": "3c1912adacca020f17747430275619a0cc9972a02835a7aac66ca053403978cc",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:sdk-map-and-keyval.md",
"title": "SDK Map and read-only Keyval associations",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/24. SDK Map and Keyval Specification.md",
"sha256": "3c1912adacca020f17747430275619a0cc9972a02835a7aac66ca053403978cc",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:25",
"title": "SDK Stack and Queue",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/25. SDK Stack and Queue Specification.md",
"sha256": "90e6bf7bae68872a5294c7d5bede4ecd4f7cfc26513c26d6cffe82f046ab56fb",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:sdk-stack-and-queue.md",
"title": "SDK Stack and Queue",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/25. SDK Stack and Queue Specification.md",
"sha256": "90e6bf7bae68872a5294c7d5bede4ecd4f7cfc26513c26d6cffe82f046ab56fb",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:3",
"title": "PBS Core Syntax Specification",
"kind": "SYNTAX",
"resource": "pbs-knowledge/specs/3. Core Syntax Specification.md",
"sha256": "b0feed2b4ad90049b9dbb703c058926b15e6c47c263fd29efc7d9187d6ad4eb7",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:4",
"title": "PBS Static Semantics Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/4. Static Semantics Specification.md",
"sha256": "4da635db643a9d00aed30d51296b539e8d78a2b55459494898abbdb7e5ac0ab3",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:5",
"title": "PBS Manifest, Module, Stdlib, and SDK Resolution Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md",
"sha256": "c137f9be1eb382c3bbf48e49dc0e4ac4f4092bc8b7f88dfcbdabe6ac5f582f24",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:6",
"title": "VM-owned vs Host-backed",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/6. VM-owned vs Host-backed.md",
"sha256": "443fff2759475c602e225f71cadb84192550efce692ceb66a7c383de425995a1",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:6.1",
"title": "Intrinsics and Builtin Types Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/6.1. Intrinsics and Builtin Types Specification.md",
"sha256": "fc935bf25cf50c7dc9444580805d8be033d78a53aa1519efcddea2ea6f1c88dc",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:6.2",
"title": "Host ABI Binding and Loader Resolution Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/6.2. Host ABI Binding and Loader Resolution Specification.md",
"sha256": "939e77cab3e9620e2b88e0250d8d0a1963997b85deac62b5ed291c9e9f20bf05",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:7",
"title": "Cartridge Manifest and Runtime Capabilities Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md",
"sha256": "7a933b5cfe2a6519a4edc9054d49631c74c11597392a942047b4d480bdb0c789",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:8",
"title": "PBS Stdlib Environment Packaging and Loading Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/8. Stdlib Environment Packaging and Loading Specification.md",
"sha256": "145f629db68e4800044a2333e31941f2e65b58904eddbd1b301b923cf756a562",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:spec:9",
"title": "PBS Dynamic Semantics Specification",
"kind": "SEMANTICS",
"resource": "pbs-knowledge/specs/9. Dynamic Semantics Specification.md",
"sha256": "2e987459d1860f9e851005664e3127c98ab46a878098c58755a5a6513a0178ac",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:quickstart",
"title": "PBS Specs",
"kind": "QUICKSTART",
"resource": "pbs-knowledge/specs/README.md",
"sha256": "0c97ce725d2b0264f57052874c955701279833c42adbfefac892288360556d9e",
"sdkVersion": null,
"target": null
},
{
"id": "pbs:sdk:game:1:core/color/main.pbs",
"title": "PBS SDK 1 @core:color / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/core/color/main.pbs",
"sha256": "9f53b51de963c3524dc94f4c29d28ec2df8323f68325bef3baee59d86e639f57",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:core/color/mod.barrel",
"title": "PBS SDK 1 @core:color / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/core/color/mod.barrel",
"sha256": "d27ddb4c8dd7bc88d5623483246e05110d966af695338b24846a87a171ab5ca9",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/asset/main.pbs",
"title": "PBS SDK 1 @sdk:asset / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/asset/main.pbs",
"sha256": "f2c6a717e6d93ad8185ed097a9860cd02067673d7a7a264659680098ab296db5",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/asset/mod.barrel",
"title": "PBS SDK 1 @sdk:asset / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/asset/mod.barrel",
"sha256": "d508aa056a444fa4a03343d2284f955e70afa33899ec87fe45982125181abf21",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/collections/main.pbs",
"title": "PBS SDK 1 @sdk:collections / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/collections/main.pbs",
"sha256": "ac41b92f699aba21fc885b00e6ae59d313f24e084d5436655b493257430364db",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/collections/mod.barrel",
"title": "PBS SDK 1 @sdk:collections / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/collections/mod.barrel",
"sha256": "6567377cbb58c2e2332556fa759667e63923b7e1cfb44fe65e440c6db309d15c",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/composer/main.pbs",
"title": "PBS SDK 1 @sdk:composer / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/composer/main.pbs",
"sha256": "588e767def8524d3769cefd1601cd3d43406ead1d38c2f77a7cfa774c1823ff4",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/composer/mod.barrel",
"title": "PBS SDK 1 @sdk:composer / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/composer/mod.barrel",
"sha256": "643deb907dd8cf3ecbfdd061c9cffa10e9b03c8ff3a0b6768925fc347f954e64",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/gfx/main.pbs",
"title": "PBS SDK 1 @sdk:gfx / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/gfx/main.pbs",
"sha256": "1ad24c64723a4a488847f3c8e08bf7161be6b961d53e5db7243e54a0210b3296",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/gfx/mod.barrel",
"title": "PBS SDK 1 @sdk:gfx / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/gfx/mod.barrel",
"sha256": "88f95f637d4982cca334582329437bc8ddf33135f6e7d64fbaf744ca806964c6",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/hash/main.pbs",
"title": "PBS SDK 1 @sdk:hash / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/hash/main.pbs",
"sha256": "5fefadf0c171849db43a84a8e96ee9b65f9085630c54fc2605b478b052202f3e",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/hash/mod.barrel",
"title": "PBS SDK 1 @sdk:hash / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/hash/mod.barrel",
"sha256": "96c5efc77fa829cd1ada41551455d5ab702af7d93003bff166a917cfe94d5c91",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/input/main.pbs",
"title": "PBS SDK 1 @sdk:input / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/input/main.pbs",
"sha256": "d11c86bd0d8eac9b1a154495e88ad47bd5d3bc66697203699a05844a26a6e7a3",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/input/mod.barrel",
"title": "PBS SDK 1 @sdk:input / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/input/mod.barrel",
"sha256": "72b6ad3d2ab5595779e76a4e9382befae7cab6f00f55d189691821b3bae36c04",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/log/main.pbs",
"title": "PBS SDK 1 @sdk:log / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/log/main.pbs",
"sha256": "0dc20fc6dbe6cfd50b5817846e6c655480d2db2ac127a262ef1fb77e1ea10816",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/log/mod.barrel",
"title": "PBS SDK 1 @sdk:log / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/log/mod.barrel",
"sha256": "977bbb548f9e465baf2b61e38af278238ab9e52ff5fd19dbe214aaf5405294c0",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/math/main.pbs",
"title": "PBS SDK 1 @sdk:math / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/math/main.pbs",
"sha256": "c51fc028504c17a9e14518dc026277d42658a9567dd88d50a0a140f8321381d0",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/math/mod.barrel",
"title": "PBS SDK 1 @sdk:math / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/math/mod.barrel",
"sha256": "b522c3a04b1f53a600196b903f0b7a346bc5aaf762a121c9fb1bb2736239fd6c",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/mathf/main.pbs",
"title": "PBS SDK 1 @sdk:mathf / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/mathf/main.pbs",
"sha256": "642af3933021103294b8439b1c950382f76a477aa439f09fdbe465a98a15035c",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/mathf/mod.barrel",
"title": "PBS SDK 1 @sdk:mathf / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/mathf/mod.barrel",
"sha256": "0f1f5f3961b3a53b0b19839e6d27f8b008022e1fd78e447669877c632ad2c49a",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/random/main.pbs",
"title": "PBS SDK 1 @sdk:random / main.pbs",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/random/main.pbs",
"sha256": "c21c12d99c5a033a1e4026432bbab56393ad09c0fe2d36711504ccca01ce93b5",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:sdk:game:1:sdk/random/mod.barrel",
"title": "PBS SDK 1 @sdk:random / mod.barrel",
"kind": "SDK",
"resource": "game/stdlib/1/sdk/random/mod.barrel",
"sha256": "7924c022a140b9bc634f3699175c8775f24093d3aa82e650752232971b0380fb",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:LIFECYCLE.md",
"title": "PBS Game / SDK 1 example: LIFECYCLE.md",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/LIFECYCLE.md",
"sha256": "fc078b7f68be79179bddfeeee744e05bf299c32f0ae1352be628a4b4a82a8669",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:prometeu.json",
"title": "PBS Game / SDK 1 example: prometeu.json",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/prometeu.json",
"sha256": "d858da746b04800892c180f45d9f6b51eedc325c801f2b767820b66cacb56669",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/arrays.pbs",
"title": "PBS Game / SDK 1 example: src/arrays.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/arrays.pbs",
"sha256": "db19768350c471d4585121f74042458c8f4050a68c2a3302c2e2fa9a37d21f89",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/closures.pbs",
"title": "PBS Game / SDK 1 example: src/closures.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/closures.pbs",
"sha256": "570cd71c7bb4de98b512c2671d410c057a188f8861f3e5e77dfdb8a26d7d64bd",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/collections.pbs",
"title": "PBS Game / SDK 1 example: src/collections.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/collections.pbs",
"sha256": "1dc2910220e0b7ee7f5e51105986d088eaa8035fb4e793ba457aa4c6449eb836",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/contracts.pbs",
"title": "PBS Game / SDK 1 example: src/contracts.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/contracts.pbs",
"sha256": "7a854cca79f8d8160e2a5cfc1108f562701f11b45d5981b539d2c27189f8a524",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/generics.pbs",
"title": "PBS Game / SDK 1 example: src/generics.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/generics.pbs",
"sha256": "a791cabb967558f53fb745533d040789179cd15a2c8c389e9ad1ecea79cf8ad5",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/hashing.pbs",
"title": "PBS Game / SDK 1 example: src/hashing.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/hashing.pbs",
"sha256": "51a535c87ea1f6cfe63921c16116325e98ff5b792c52d29c554708f6f747fbbe",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/lifecycle.pbs",
"title": "PBS Game / SDK 1 example: src/lifecycle.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/lifecycle.pbs",
"sha256": "eea76258ef59e43be782bba2813e9398952fe97a224e2011f5b8ffbf16bfccae",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/linked.pbs",
"title": "PBS Game / SDK 1 example: src/linked.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/linked.pbs",
"sha256": "061d9f67c7b01bec16d6b60eee68ec023bdd6478cc1bbbeda0c83c914f040550",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/main.pbs",
"title": "PBS Game / SDK 1 example: src/main.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/main.pbs",
"sha256": "08bd09f2f36465ee4e7ae93c7382ce4307dcbe8fbad80a746a7eea858c358822",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/maps.pbs",
"title": "PBS Game / SDK 1 example: src/maps.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/maps.pbs",
"sha256": "25d85ee0698f6e5e0ffae561ebf639a5942b4c990418fcbd5d9a4992c37109ea",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/math.pbs",
"title": "PBS Game / SDK 1 example: src/math.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/math.pbs",
"sha256": "a3fde92e079565ae2b67b755b6eb0d4dfeccbc5f578c61e36d144de825bce83a",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/mod.barrel",
"title": "PBS Game / SDK 1 example: src/mod.barrel",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/mod.barrel",
"sha256": "75c5e944a7ca74896cbe526ad5ec40ab64ed8779e2abc22e5c325232c16bbdd5",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/random.pbs",
"title": "PBS Game / SDK 1 example: src/random.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/random.pbs",
"sha256": "0b18a24ba471d5b533347d47145ae6d995c83e14b701696c8654d383a15b9e1a",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/sets.pbs",
"title": "PBS Game / SDK 1 example: src/sets.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/sets.pbs",
"sha256": "af301f0399bbf960efb011bc9a64bc203198b5dd808cfce4e726d28460f081a5",
"sdkVersion": 1,
"target": "Game"
},
{
"id": "pbs:example:game:1:src/stack-queue.pbs",
"title": "PBS Game / SDK 1 example: src/stack-queue.pbs",
"kind": "EXAMPLE",
"resource": "pbs-knowledge/examples/game/1/src/stack-queue.pbs",
"sha256": "053b62206cb45a5c5736ef43b58c869031bd0524a06b29be1353bba25826abe2",
"sdkVersion": 1,
"target": "Game"
}
]
}
@@ -0,0 +1 @@
Markdown: 180 files; 470 local links; 66 provider links (checked); 0 failures
@@ -199,11 +199,11 @@ they are not silently relabeled as schema conformance or fixed in runtime here.
## 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).
- [Common Registry/PBX](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
- [Runtime catalog consumer](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
- [List/Cursor](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md),
[Linked](../../../docs/specs/compiler-languages/pbs/22.%20SDK%20Linked%20and%20Cursor%20Specification.md) and
[Array/optional](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.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,
@@ -10,7 +10,7 @@ tags: [compiler-pbs, collections, stack, queue, snapshot-cursor, failure-phases]
**Worker:** Lesson Worker. **Owner domain:** `compiler/pbs`.
DSC-0097 executed accepted DEC-0080 through PLN-0158, covering R1–R9 completely.
The durable normative reference is [SDK Stack and Queue](../../../docs/compiler/pbs/specs/sdk-stack-and-queue.md).
The durable normative reference is [SDK Stack and Queue](../../../docs/specs/compiler-languages/pbs/25.%20SDK%20Stack%20and%20Queue%20Specification.md).
[Qualification evidence](evidence/README.md) retains commands, fingerprints,
counts, raw logs and coverage after disposal of the workflow control artifacts.
@@ -183,8 +183,8 @@ Avoid these maintenance mistakes:
## Durable references
- [Stack/Queue spec](../../../docs/compiler/pbs/specs/sdk-stack-and-queue.md) and
[shared Cursor](../../../docs/compiler/pbs/specs/sdk-list-and-cursor.md).
- [Stack/Queue spec](../../../docs/specs/compiler-languages/pbs/25.%20SDK%20Stack%20and%20Queue%20Specification.md) and
[shared Cursor](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md).
- [SDK algorithms](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs).
- [Source/PBX corpus](../../../prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsStackQueueTest.java).
- [Conformance module](../../../tools/pbx-conformance/stack_queue.rs) and
+36
View File
@@ -0,0 +1,36 @@
# Specification Guide
Specifications live under this tree and are organized by contract owner:
| Owner | Canonical corpus | Responsibility |
| --- | --- | --- |
| `compiler/general` | [General compiler](compiler/README.md) | Shared compilation, linking, typed handoff, emission and acceptance |
| `compiler/pbs` | [PBS language](compiler-languages/pbs/README.md) | PBS source, semantics, SDK and frontend projections |
| `packer` | [Packer](packer/README.md) | Assets, artifacts, packing and diagnostics |
| `studio` | [Studio](studio/README.md) | Shell, workspaces, adapters and visual/automation integration |
New compiler languages receive their own corpus under `compiler-languages/`.
Shared compiler policy stays in `compiler/`; PBS is not the root for other domains.
Each domain README provides a chapter index and reading order. Numbered chapters
are normative within their stated scope. Feature chapters own their detailed
contracts; cross-cutting chapters reference those rules rather than maintaining
competing versions. Write specifications and durable lessons in English.
The runtime repository owns PBX, ISA, admission and VM execution. Studio's
[VM architecture references and catalog mirrors](../vm-arch/README.md) retain
their separate provenance and synchronization policy. [Roadmaps](../roadmaps/)
describe cross-domain planning, not an alternative contract source.
The operational lifecycle is `agenda -> decision -> plan -> implement -> lesson`.
Keep its artifacts in `discussion/` and use the local `discussion` CLI for state
transitions, validation and housekeeping. See [repository instructions](../../AGENTS.md).
## Navigation verification
Run `python3 tools/documentation/verify.py` from the repository root to check local
links and anchors. Pass `--runtime ../runtime` to also check provider references
against an available read-only runtime checkout. The byte-exact architecture/ISA
mirrors retain the link context of their runtime originals; the checker resolves
them there. Ordinary builds and installed documentation reads do not require that
checkout.
@@ -82,7 +82,7 @@ Before implementation starts, PBS must define at least:
7. AST Specification.
8. Diagnostics Specification.
9. Lowering IRBackend Specification.
10. Shared acceptance specs in `docs/general/specs` (Conformance, Compatibility, Verification).
10. Shared acceptance specs in `docs/specs/compiler` (Conformance, Compatibility, Verification).
## 11. Decision Rule
@@ -39,8 +39,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
@@ -126,7 +126,7 @@ They are runtime views over an underlying identity-bearing value together with t
### 7.5 Function values and closures
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).
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](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
## 8. Identity, Aliasing, and Copy Behavior
@@ -177,7 +177,7 @@ At minimum, those roots include:
- currently active local/frame state,
- reachable fields of reachable struct instances,
- service singleton roots,
- retained callback state that remains reachable,
- retained closure state that remains reachable,
- and any other runtime roots required to preserve already-observable PBS behavior.
If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.
@@ -325,4 +325,7 @@ This document is ready to move beyond temporary draft status only when:
## 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.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter supplies shared reachability and ownership rules; Array storage
and complete-group packing are defined by that owner.
@@ -180,23 +180,27 @@ This document is healthy when:
## 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.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter preserves syntax and type arguments in the AST; the owner chapter
defines Array application admissibility and execution.
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.
Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md)
and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.
## 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).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.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).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Guest hook marker identity
@@ -299,27 +299,31 @@ This document is ready to move beyond temporary status only when:
## 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.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.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.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter owns diagnostic classification and source attribution; the owner
chapter defines which Array forms are rejected.
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.
Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md)
and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.
## 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).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.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).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Guest lifecycle diagnostics and conformance
@@ -241,27 +241,31 @@ At frontend `IRBackend` emission time:
## 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.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.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.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter owns source-to-common-IR projection; the owner chapter defines
Array storage, optional carriers and complete-group requirements.
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.
Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md)
and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.
## 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).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.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).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Lowering optional runtime hook roles
@@ -1,6 +1,17 @@
# 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.
Status: Normative. Owner: `compiler/pbs`.
Scope: Typed Arrays and Optional Execution.
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.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types and construction
@@ -76,35 +87,34 @@ Conformance must compile real PBS through typed IR and production PBX into the p
## 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)
- [Core syntax](3.%20Core%20Syntax%20Specification.md)
- [Static semantics](4.%20Static%20Semantics%20Specification.md)
- [Dynamic semantics](9.%20Dynamic%20Semantics%20Specification.md)
- [Existing type runtime alignment](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md)
[SDK List and Cursor](sdk-list-and-cursor.md) define logical size, growth and
[SDK List and Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.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.
See [Runtime Random integration](20.%20Runtime%20Random%20Integration%20Specification.md) for opaque generator aliases in typed storage and captures.
[Map/Keyval](sdk-map-and-keyval.md) stores V in generic node fields and therefore
[Map/Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md) stores V in generic node fields and therefore
admits optional values. Its outer lookup/previous-value optional describes entry
existence independently of stored V; some(none) is distinct from absent none.
This does not change Array's direct optional-element restriction.
## 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 contracts](16.%20Generic%20Contracts%20Specification.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
[Generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.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);
[List mutation-phase contract](21.%20SDK%20List%20and%20Cursor%20Specification.md#mutation-preparation-visible-writes-and-faults)
and [Linked contract](22.%20SDK%20Linked%20and%20Cursor%20Specification.md#mutation-phases-and-lifetime);
per-instruction storage guarantees do not imply whole-method rollback.
@@ -1,6 +1,17 @@
# 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.
Status: Normative. Owner: `compiler/pbs`.
Scope: First-Class Functions and Captures.
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.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types and calls
@@ -75,14 +86,13 @@ Function creation and calls remain subject to existing resource checks and runti
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.
See [Runtime Random integration](20.%20Runtime%20Random%20Integration%20Specification.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 contracts](16.%20Generic%20Contracts%20Specification.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
[Generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.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
@@ -1,6 +1,17 @@
# 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. [Set, SDK Identity and hashing](sdk-set-and-identity.md) are consumers with their own public policy; the examples below illustrate generic language syntax, not the SDK Identity declaration.
Status: Normative. Owner: `compiler/pbs`.
Scope: Generic Contracts.
This specification extends nominal contracts with explicit type parameters. Registry, PBX, instruction, ownership and resource contracts remain governed by the runtime provider. [Set, SDK Identity and hashing](23.%20SDK%20Set%20and%20Identity%20Specification.md) are consumers with their own public policy; the examples below illustrate generic language syntax, not the SDK Identity declaration.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Declaration and application
@@ -17,7 +28,7 @@ declare contract Converter<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.
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](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.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.
@@ -71,4 +82,4 @@ Navigation reaches generic declarations, parameters and argument declarations. H
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.
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](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.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.
@@ -1,10 +1,21 @@
# Concrete Generic Structs and Free Functions
Owner: `compiler/pbs`. This specification adds parameterized state and executable
Status: Normative. Owner: `compiler/pbs`.
Scope: Generic Structs and Free Functions.
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.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Declarations and identity
Structs and module-level named free functions may declare one or more distinct,
@@ -58,7 +69,7 @@ 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).
in [Runtime Random integration](20.%20Runtime%20Random%20Integration%20Specification.md).
## Composition and symbolic capabilities
@@ -265,9 +276,9 @@ 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).
- [SDK Map and Keyval](sdk-map-and-keyval.md), a two-parameter source consumer
- [Generic contracts](16.%20Generic%20Contracts%20Specification.md).
- [Typed arrays and optional execution](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [First-class functions and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
- [Concrete Registry and PBX handoff](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
- [SDK Map and Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md), a two-parameter source consumer
preserving separate key/value policies and complete optional/grouped fields.
@@ -1,8 +1,19 @@
# 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).
Status: Normative. Owner: `compiler/pbs`.
Scope: Input and Existing Type Runtime Alignment.
Common ABI authority:
[typed Registry/PBX](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md) and
[runtime catalogs](../../compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Source types and exact carriers
@@ -1,8 +1,19 @@
# Service constants and runtime math
Owner: compiler/pbs. Common catalog authority: compiler/general. Numeric behavior,
Status: Normative. Owner: `compiler/pbs`.
Scope: Service Constants and Runtime Math.
Common catalog authority: compiler/general. Numeric behavior,
exact identities, faults and virtual costs remain owned by the runtime.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Services are the public namespaces
A service groups methods and immutable constants. The service barrel entry exports
@@ -113,6 +124,6 @@ remain separately pending; local results and cross-compilation do not qualify th
## References
- [Common runtime catalog support](../../general/specs/runtime-catalog-support.md)
- [Common runtime catalog support](../../compiler/24.%20Runtime%20Catalog%20Support%20Specification.md)
- [Runtime numeric contract](../../../../../runtime/docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md)
- [Production conformance harness](../../../../tools/pbx-conformance/README.md)
@@ -136,7 +136,7 @@ Every accepted change MUST update, when relevant:
- diagnostics documentation,
- conformance tests,
- compatibility matrix/changelog.
- For executable FE/BE conformance-relevant code changes, the backend conformance matrix (`docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`) MUST be updated and pass hard-gate policy checks.
- For executable FE/BE conformance-relevant code changes, the backend conformance matrix (`docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`) MUST be updated and pass hard-gate policy checks.
## 12. Conflict Resolution
@@ -1,6 +1,17 @@
# 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.
Status: Normative. Owner: `compiler/pbs`.
Scope: Runtime Random Integration.
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.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Source surface
@@ -64,8 +75,8 @@ Null receivers and present typed-null Array elements MUST be covered by separate
## 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).
- [Typed arrays and optional execution](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
- [First-class functions and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
- [Runtime math and exact numeric carriers](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
- [Runtime Random v1](../../../../../runtime/docs/specs/runtime/02e-vm-owned-random-core.md).
- [Provider handoff](../../../../../runtime/docs/vm-arch/random-producer-handoff.md).
@@ -1,11 +1,22 @@
# SDK List and snapshot Cursor
Owner: `compiler/pbs`. List and Cursor algorithms belong to the executable PBS
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK List and Cursor.
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).
[arrays and optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md),
[generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) and
[generic contracts](16.%20Generic%20Contracts%20Specification.md).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Type, identity and construction
@@ -176,10 +187,10 @@ faults. List itself rejects directly optional elements.
## Reuse, costs and conformance
The shared implementation is independent of List representation.
[Stack/Queue](sdk-stack-and-queue.md) capture in their LIFO/FIFO removal orders.
[Linked](sdk-linked-and-cursor.md) uses Cursor<T> for forward and reverse captures.
[Set](sdk-set-and-identity.md) produces Cursor<T>; Map<K,V> uses
Cursor<keyval<K,V>> as specified by [Map/Keyval](sdk-map-and-keyval.md).
[Stack/Queue](25.%20SDK%20Stack%20and%20Queue%20Specification.md) capture in their LIFO/FIFO removal orders.
[Linked](22.%20SDK%20Linked%20and%20Cursor%20Specification.md) uses Cursor<T> for forward and reverse captures.
[Set](23.%20SDK%20Set%20and%20Identity%20Specification.md) produces Cursor<T>; Map<K,V> uses
Cursor<keyval<K,V>> as specified by [Map/Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md).
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.
@@ -1,10 +1,21 @@
# SDK Linked and bidirectional snapshot capture
Owner: `compiler/pbs`. Linked algorithms belong to executable PBS SDK source.
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Linked and Cursor.
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).
compiler/provider mechanisms. This contract builds on [generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md),
[arrays and optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) and the
[shared Cursor protocol](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Type, identity and construction
@@ -131,5 +142,5 @@ 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)
See [generic Registry/PBX storage](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
for the language-neutral instruction contract.
@@ -1,10 +1,21 @@
# SDK Set, Identity and hashing
Owner: `compiler/pbs`. Set algorithms belong to executable PBS SDK source. Typed
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Set and Identity.
Set algorithms belong to executable PBS SDK source. Typed
reference queries, storage, admission, faults and resource limits are generic
compiler/provider mechanisms. This contract builds on [generic structs](generic-structs-and-free-functions.md),
[generic contracts](generic-contracts.md), [Array/optional](typed-arrays-and-optional-execution.md)
and the [shared snapshot Cursor](sdk-list-and-cursor.md#cursor-protocol).
compiler/provider mechanisms. This contract builds on [generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md),
[generic contracts](16.%20Generic%20Contracts%20Specification.md), [Array/optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
and the [shared snapshot Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types, construction and operations
@@ -235,8 +246,8 @@ PBX. Normal compilation uses versioned Studio catalogs/resources without a sibli
checkout. Runtime ownership, limits and semantics remain the provider contract;
Set adds no VM collection instruction/syscall or provider source change.
Identity/hash are reused by [Map/Keyval](sdk-map-and-keyval.md). Its API, representation
Identity/hash are reused by [Map/Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md). Its API, representation
and implementation are separate consumers; sharing policy does not impose a shared
physical table or universal entry type. See the
[common typed Registry contract](../../general/specs/typed-registry-and-pbx-v0.md)
and [catalog consumer rules](../../general/specs/runtime-catalog-support.md).
[common typed Registry contract](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
and [catalog consumer rules](../../compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
@@ -1,12 +1,23 @@
# SDK Map and read-only Keyval associations
Owner: `compiler/pbs`. Map algorithms execute as PBS SDK source. This contract
builds on [generic structs](generic-structs-and-free-functions.md),
[Array/optional](typed-arrays-and-optional-execution.md),
[Set/Identity/hash](sdk-set-and-identity.md) and the
[shared snapshot Cursor](sdk-list-and-cursor.md#cursor-protocol).
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Map and Keyval.
Map algorithms execute as PBS SDK source. This contract
builds on [generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md),
[Array/optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md),
[Set/Identity/hash](23.%20SDK%20Set%20and%20Identity%20Specification.md) and the
[shared snapshot Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
Registry/PBX, storage, ownership, faults and resource limits remain provider contracts.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types, construction and public API
`@sdk:collections` exports invariant ordinary generic structs `map<K,V>` and
@@ -1,10 +1,21 @@
# SDK Stack and Queue
Owner: `compiler/pbs`. Algorithms execute as PBS SDK source over existing typed
Status: Normative. Owner: `compiler/pbs`.
Scope: SDK Stack and Queue.
Algorithms execute as PBS SDK source over existing typed
storage, complete-group copies, terminal checks and shared snapshot Cursor.
This contract builds on [Array/optional](typed-arrays-and-optional-execution.md),
[generic structs](generic-structs-and-free-functions.md) and
[List/shared Cursor](sdk-list-and-cursor.md#cursor-protocol).
This contract builds on [Array/optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md),
[generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) and
[List/shared Cursor](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Types, identity and construction
@@ -20,10 +20,10 @@ This document defines syntax only. Runtime behavior, optimizer policy, and bytec
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. This document
4. Legacy references (`docs/specs/random/pbs_old/*`)
4. Retired PBS drafts are historical context only and carry no normative authority.
If a rule here conflicts with higher authority, it is invalid.
@@ -76,8 +76,8 @@ Keywords are not valid identifiers.
Active keywords in `.pbs`:
- `import`, `from`, `as`
- `service`, `host`, `fn`, `apply`, `bind`, `new`, `implements`, `using`, `ctor`
- `declare`, `struct`, `contract`, `error`, `enum`, `callback`, `global`, `Self`, `this`
- `service`, `host`, `fn`, `apply`, `new`, `implements`, `using`, `ctor`
- `declare`, `struct`, `contract`, `error`, `enum`, `global`, `Self`, `this`
- `pub`, `mut`
- `let`, `const`
- `if`, `else`, `switch`, `default`, `for`, `from`, `until`, `step`, `while`, `break`, `continue`, `return`
@@ -96,6 +96,10 @@ Reserved (not active syntax in v1 core):
- `spawn`, `yield`, `sleep`
- `match`
Retired source forms `declare callback` and `bind(...)` MUST be rejected;
[function values and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md)
defines their replacement. Retired tokens are not active declaration/call syntax.
Note:
- `host` is used only by reserved SDK/toolchain `declare host` surfaces in v1 core; ordinary user-authored modules MUST reject those declarations.
@@ -366,7 +370,7 @@ Rules:
### 7.2 First-class function values
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).
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](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
### 7.3 Services
@@ -380,7 +384,7 @@ ServiceMember ::= 'fn' Identifier ParamList ReturnAnn? Block | ConstDecl
Rules:
- `declare service Name { ... }` declares a nominal service type together with its canonical module-owned singleton value `Name`.
- 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).
- A service body contains method declarations and `declare const` members. SDK service intrinsic signatures may terminate with `;`; see [Service constants and runtime math](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
- Service methods have an implicit receiver binding `this` of type `Self` and do not declare `this: Self` explicitly.
- Services do not declare fields.
- Services do not declare `ctor`.
@@ -446,7 +450,7 @@ Rules:
- A `declare const` initializer is required unless another specification explicitly permits a reserved declaration-only shell such as builtin constant metadata.
- A `declare const` initializer, when present, MUST be a constant expression as defined by static semantics.
- `declare const` values are compile-time constants, not runtime-initialized module storage.
- A reserved top-level builtin constant shell MAY use attributes such as `BuiltinConst(...)` and omit the initializer when another specification explicitly defines VM-owned materialization.
- A reserved top-level or SDK service builtin constant shell MAY use attributes such as `BuiltinConst(...)` and omit the initializer when another specification explicitly defines VM-owned materialization.
## 8. Type syntax
@@ -611,7 +615,7 @@ Rules:
- `new Type(args...)` is the canonical struct construction surface.
- `new Type.ctorName(args...)` is the canonical named-constructor surface.
- Struct construction arguments are positional and follow the declared struct field order.
- `as` is reserved in expressions for explicit contract-view conversion only; it does not denote a general cast surface in v1 core.
- `as` expresses explicit contract-view conversion or the supported numeric conversions defined by [input and value alignment](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md). It is not an unrestricted cast.
- A contract-view `as` target is a visible contract type, including explicit arguments such as `Identity<int>`, never a qualified module path. Existing numeric conversions retain their value-alignment rules.
- `this` is an implicit receiver name available only inside struct method, service method, and `ctor` bodies.
- `Self` is valid only inside struct method declarations, service method declarations, and `ctor` declarations.
@@ -1199,25 +1203,27 @@ fn test(e: Enum) -> str {
## 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.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter owns the source syntax and spans consumed by that feature.
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.
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](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.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).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.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).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
## Controlled guest lifecycle marker syntax
@@ -20,8 +20,8 @@ It is intended to:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `3. Core Syntax Specification.md`
4. This document
@@ -87,7 +87,7 @@ Rules:
- `Init` is valid only on a top-level userland `fn` declaration with lifecycle-admissible signature.
- `Frame` is valid only on a top-level userland `fn` declaration with lifecycle-admissible signature.
- `InitAllowed` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
- `Host` is invalid on ordinary user-authored modules, top-level `fn`, struct methods, service methods, callbacks, contracts, and constants.
- `Host` is invalid on ordinary user-authored modules, top-level `fn`, struct methods, service methods, lambdas, contracts, and constants.
- `Host` metadata is consumed by the compiler during host-binding lowering.
- `AssetLowering` MUST declare exactly the named argument `param`.
- `AssetLowering.param` MUST be a zero-based integer literal that names a valid host parameter position.
@@ -95,7 +95,7 @@ Rules:
- `AssetLowering` metadata is consumed by backend-owned host-call lowering to rewrite the targeted symbolic `Addressable` operand into runtime-facing `asset_id`.
- The `Host` attribute syntax itself is not exported as runtime metadata; instead, its canonical identity participates in PBX host-binding emission as defined by the Host ABI Binding specification.
- `BuiltinType` is valid only on a reserved top-level `declare builtin type` declaration.
- `BuiltinConst` is valid only on a reserved top-level `declare const` declaration that omits an initializer.
- `BuiltinConst` is valid on reserved top-level and SDK service `declare const` shells that omit an initializer, as defined by [service constants and runtime math](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
- `IntrinsicCall` is valid on a method signature inside a reserved `declare builtin type` body or an SDK service body. SDK service signatures have no implementation body and bind their exact declared argument/result carriers to the common intrinsic catalog.
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
- `Init` and `Frame` are consumed by lifecycle analysis and lowering rather than by ordinary runtime reflection.
@@ -195,7 +195,7 @@ The following constructs are callable in v1 core:
- top-level `fn`,
- struct methods on concrete receivers,
- contract values,
- callback values,
- structural `Fn` values,
- service methods,
- host methods on declared host owners,
- builtin intrinsic methods on declared builtin types.
@@ -252,7 +252,7 @@ Rules:
- Project init must be colocated with `[Frame]`.
- PBS static semantics and lowering admit those markers and translate them into a typed `IRLifecycleDeclaration`.
- PBS MUST NOT materialize module init, project-init wrapper, published frame wrapper, physical entrypoint, or boot guard; those artifacts belong to common lifecycle assembly.
- `InitAllowed` is valid only on SDK host methods and is invalid on userland `fn`, `global`, `service`, `const`, `struct`, `contract`, and callback surfaces.
- `InitAllowed` is valid only on SDK host methods and is invalid on userland `fn`, `global`, `service`, `const`, `struct`, `contract`, and lambda surfaces.
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Host` attribute.
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Capability` attribute.
- A `Host` attribute MUST declare exactly the named arguments `module`, `name`, and `version`.
@@ -349,7 +349,7 @@ Rules:
### 3.6 Structs, services, methods, and contracts
Service constants follow [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
Service constants follow [Service constants and runtime math](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
They are immutable members exported with their service. Qualified constant reads
materialize the constant without constructing a singleton or invoking a method.
@@ -376,7 +376,7 @@ Rules:
- A named `ctor` declared in a struct body is not a method, but it does introduce an implicit under-construction `this`.
- A `ctor` has no declared return annotation and is not a `fn`.
- A `ctor` completes by falling off the end of its body after initializing the enclosing struct instance.
- Every field of the enclosing struct must be definitely assigned on every completing `ctor` path.
- Every field of the enclosing struct must be definitely assigned on every completing `ctor` path, including ordinary/generic owners and opaque Random fields. Provider reference defaults do not exempt PBS constructors; [generic construction](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md#construction-and-expected-types) owns this complete rule.
- Named constructors participate in overload resolution by name plus parameter signature.
- `return;` and `return expr;` are both invalid inside `ctor` bodies.
- Methods declared in a struct body belong to the direct method namespace of that concrete struct type.
@@ -395,7 +395,7 @@ Rules:
- Methods declared directly inside a struct or service follow the visibility of their enclosing owner declaration; they do not have independent visibility.
- A struct value or service singleton value may be coerced to a contract value when exactly one visible `implements Contract for Owner ...` applies.
- Contract coercion may happen by explicit `expr as ContractType` or by contextual typing in assignments, parameter passing, and returns.
- `as` in expression position is reserved for explicit contract coercion only; no other cast semantics exist in v1 core.
- `as` supports explicit contract coercion and the numeric conversions owned by [input and value alignment](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md); other casts remain invalid.
- The contract in `expr as ContractType` is resolved through ordinary scope/import rules and may carry explicit type arguments. Aliases preserve declaration identity.
- A contract value carries the underlying struct reference or service singleton value together with the selected contract implementation for runtime dispatch.
- Calling `contractValue.method(...)` uses dynamic dispatch through the contract value.
@@ -442,7 +442,7 @@ fn demo() -> int {
### 3.7 Structural function values
[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.
[First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md) defines structural Fn compatibility, explicit snapshot captures and lambda typing. Assignment of a named function requires exactly one matching overload. Bare method extraction remains invalid; use an explicit receiver-capturing lambda.
### 3.8 Canonical application
@@ -457,7 +457,7 @@ Rules:
- `apply` is an infix operator that is right-associative.
- `f1 apply f2 apply x` is defined as `f1 apply (f2 apply x)`.
- `f1 apply f2 apply f3 apply params` is defined as `f1 apply (f2 apply (f3 apply params))`.
- The left operand of `apply` must resolve to one of: a callable candidate set, a bound struct method target, a bound service method target, a contract-method target, or a callback value.
- The left operand of `apply` must resolve to one of: a callable candidate set, a bound struct method target, a bound service method target, a contract-method target, or a `Fn` value.
- The right operand of `apply` is an argument expression.
- If the callable input arity is `0`, the argument expression must be `()`.
- If the callable input arity is `1`, the argument expression is checked against the carrier type of the single input slot.
@@ -497,7 +497,7 @@ Rules:
- If the selected callable output arity is `1`, the result of `apply` is the carrier type of the single output slot.
- If the selected callable output arity is `2..6`, the result of `apply` has the named output tuple shape of the selected callable.
- Multi-slot output tuple results expose their labels for member projection.
- If the selected callable is a callback value, the visible multi-slot output labels come from the callback type rather than from the original source `fn`.
- If the selected callable is a `Fn` value, the visible multi-slot output labels come from the `Fn` type rather than from the original source `fn`.
- If the selected callable returns `()`, the application result is unit.
Example:
@@ -749,10 +749,10 @@ At minimum, deterministic static diagnostics are required for:
- invalid named constructor target,
- unresolved named constructor overload,
- ambiguous named constructor overload,
- incompatible 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 host method to callback type,
- incompatible top-level `fn` assignment to `Fn` type,
- ambiguous overloaded top-level `fn` assignment to `Fn` type,
- attempted assignment of service method to `Fn` type,
- attempted assignment of host method to `Fn` type,
- `apply` on a non-callable target,
- arity mismatch in `apply`,
- argument type mismatch in `apply`,
@@ -816,28 +816,29 @@ At minimum, deterministic static diagnostics are required for:
## 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.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.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.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter supplies shared static checks; Array-specific admissibility and
contextual construction are defined by that owner.
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.
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](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.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).
The [generic contract chapter](16.%20Generic%20Contracts%20Specification.md)
owns the complete application, substitution, coherence and bounded-validation rules.
Compilation and editor analysis MUST share that resolution.
## 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).
The [generic struct and free-function chapter](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md)
owns the complete application, substitution, coherence and bounded-validation rules.
Compilation and editor analysis MUST share that resolution.
## Controlled guest lifecycle admission
@@ -562,11 +562,11 @@ new coverage; existing behavior MUST NOT regress.
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).
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.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).
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
@@ -56,8 +56,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
@@ -45,8 +45,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
@@ -242,7 +242,7 @@ changes the rule:
- user-declared structs,
- services,
- contracts,
- callbacks,
- function values,
- `optional`,
- `result`,
- and any type with runtime-variable or heap-defined width.
@@ -563,4 +563,4 @@ The current temporary contract is:
## 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.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.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.
@@ -13,7 +13,7 @@ Its purpose is to make runtime behavior convergent across implementations by fix
- runtime evaluation of expressions and statements,
- abrupt completion and propagation behavior,
- runtime behavior of effect surfaces such as `optional` and `result`,
- the execution boundary between ordinary PBS code, callbacks, contract calls, and host-backed calls.
- the execution boundary between ordinary PBS code, function values, contract calls, and host-backed calls.
## 2. Scope
@@ -22,7 +22,7 @@ This document defines:
- the observable execution model of PBS core,
- evaluation order for expressions, statements, and blocks,
- runtime branch selection for `if` and `switch`,
- runtime application behavior for `apply`, call sugar, methods, contracts, callbacks, and host-backed call surfaces,
- runtime application behavior for `apply`, call sugar, methods, contracts, function values, and host-backed call surfaces,
- runtime behavior of `optional`, `result<E>`, `else`, `!`, and `handle`,
- abrupt completion (`return`, `break`, `continue`) and trap propagation,
- determinism requirements that affect execution behavior.
@@ -39,8 +39,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `3. Core Syntax Specification.md`
4. `4. Static Semantics Specification.md`
5. This document
@@ -265,7 +265,7 @@ The same observable call model applies to:
- struct methods,
- service methods,
- contract calls,
- callback calls,
- `Fn` calls,
- host-backed calls.
Callable-specific dispatch may differ internally, but it does not change the user-visible sequencing model defined in this document.
@@ -281,7 +281,7 @@ If a callable returns:
### 11.3 Closure creation and invocation
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).
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](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
## 12. Branch Selection
@@ -377,11 +377,14 @@ This document is ready to move beyond temporary draft status only when:
## 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.
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.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.
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
defines the complete type, optional-flow and storage contract.
This chapter supplies common evaluation and abrupt-completion rules; Array-specific
evaluation, presence and mutation rules are defined by that owner.
## Controlled pause and resume hooks
+55 -5
View File
@@ -1,5 +1,7 @@
# PBS Specs
Owner: `compiler/pbs`. Canonical source: `docs/specs/compiler-languages/pbs`.
This directory contains the normative PBS specification set.
## Installed Quickstart (Informative)
@@ -82,7 +84,7 @@ Specs define the official PBS language/frontend contract.
They exist to make behavior, constraints, and interfaces stable across implementations and reviews.
Cross-language acceptance rules are not defined here.
Those are maintained in `docs/general/specs`.
Those are maintained in `docs/specs/compiler`.
## Expected Format
@@ -143,12 +145,60 @@ That means:
- 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`
copying a generator shares its state. Read `pbs:spec:20`
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.
## Authority and reading order
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
Read syntax and static semantics (3–4), module/SDK resolution (5), host/intrinsic
boundaries (6–8), execution/memory (9–10), and compiler projections (11–13).
Thematic chapters 14–25 own their complete feature contracts. Base chapters
retain syntax, AST, diagnostics and lowering responsibilities and refer to those
owners for detailed rules. The accepted explicit-initialization rule in chapter 17
applies to every completing ordinary/generic constructor, including Random fields.
[General compiler specifications](../../compiler/README.md) own shared handoff
and acceptance; the [runtime mirror policy](../../../vm-arch/README.md) identifies
the provider's separate ABI/execution authority. Keep those boundaries explicit.
## Chapter index
- [1. Language Charter](1.%20Language%20Charter.md)
- [2. Governance and Versioning](2.%20Governance%20and%20Versioning.md)
- [3. Core Syntax Specification](3.%20Core%20Syntax%20Specification.md)
- [4. Static Semantics Specification](4.%20Static%20Semantics%20Specification.md)
- [5. Manifest, Stdlib, and SDK Resolution Specification](5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md)
- [6. VM-owned vs Host-backed](6.%20VM-owned%20vs%20Host-backed.md)
- [6.1. Intrinsics and Builtin Types Specification](6.1.%20Intrinsics%20and%20Builtin%20Types%20Specification.md)
- [6.2. Host ABI Binding and Loader Resolution Specification](6.2.%20Host%20ABI%20Binding%20and%20Loader%20Resolution%20Specification.md)
- [7. Cartridge Manifest and Runtime Capabilities Specification](7.%20Cartridge%20Manifest%20and%20Runtime%20Capabilities%20Specification.md)
- [8. Stdlib Environment Packaging and Loading Specification](8.%20Stdlib%20Environment%20Packaging%20and%20Loading%20Specification.md)
- [9. Dynamic Semantics Specification](9.%20Dynamic%20Semantics%20Specification.md)
- [10. Memory and Lifetime Specification](10.%20Memory%20and%20Lifetime%20Specification.md)
- [11. AST Specification](11.%20AST%20Specification.md)
- [12. Diagnostics Specification](12.%20Diagnostics%20Specification.md)
- [13. Lowering IRBackend Specification](13.%20Lowering%20IRBackend%20Specification.md)
- [14. Typed Arrays and Optional Execution Specification](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
- [15. First-Class Functions and Captures Specification](15.%20First-Class%20Functions%20and%20Captures%20Specification.md)
- [16. Generic Contracts Specification](16.%20Generic%20Contracts%20Specification.md)
- [17. Generic Structs and Free Functions Specification](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md)
- [18. Input and Existing Type Runtime Alignment Specification](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md)
- [19. Service Constants and Runtime Math Specification](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md)
- [20. Runtime Random Integration Specification](20.%20Runtime%20Random%20Integration%20Specification.md)
- [21. SDK List and Cursor Specification](21.%20SDK%20List%20and%20Cursor%20Specification.md)
- [22. SDK Linked and Cursor Specification](22.%20SDK%20Linked%20and%20Cursor%20Specification.md)
- [23. SDK Set and Identity Specification](23.%20SDK%20Set%20and%20Identity%20Specification.md)
- [24. SDK Map and Keyval Specification](24.%20SDK%20Map%20and%20Keyval%20Specification.md)
- [25. SDK Stack and Queue Specification](25.%20SDK%20Stack%20and%20Queue%20Specification.md)
## Installed reference compatibility
Each numbered chapter is indexed as `pbs:spec:<number>`; this README is
`pbs:quickstart`. Published filename-based IDs for chapters 14–25 remain aliases
of the same canonical packaged text and hash. New callers should use the numbered
IDs returned by project context. The alias catalog is generated by the frontend
build from this single source directory. It does not read a second spec tree.
The internal resource path is `pbs-knowledge/specs/<numbered filename>.md`;
reference clients resolve IDs through the catalog instead of constructing paths.
@@ -1,7 +1,7 @@
# 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).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -37,8 +37,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
4. `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
5. `20. IRBackend to IRVM Lowering Specification.md`
@@ -36,7 +36,7 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. `1. Language Charter.md`
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
4. `9. Dynamic Semantics Specification.md`
@@ -1,7 +1,7 @@
# 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).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -43,8 +43,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `20. IRBackend to IRVM Lowering Specification.md`
4. `21. IRVM Optimization Pipeline Specification.md`
5. `15. Bytecode and PBX Mapping Specification.md`
@@ -1,7 +1,7 @@
# 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).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -46,8 +46,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. This document
4. Frontend-specific lowering specifications, including `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
@@ -33,8 +33,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `20. IRBackend to IRVM Lowering Specification.md`
4. `15. Bytecode and PBX Mapping Specification.md`
5. This document
@@ -1,7 +1,7 @@
# 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).
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
@@ -33,8 +33,8 @@ This document does not define:
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `14. Name Resolution and Module Linking Specification.md`
4. `20. IRBackend to IRVM Lowering Specification.md`
5. `21. IRVM Optimization Pipeline Specification.md`
@@ -1,6 +1,15 @@
# Runtime catalog support
Status: normative. Owner: `compiler/general`.
Status: Normative. Owner: `compiler/general`.
Scope: Runtime Catalog Support.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Authority and update boundary
@@ -115,14 +124,13 @@ selected runtime MUST identify revision, platform and configuration and distingu
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
See [typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.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)
The [PBS input and value alignment contract](../compiler-languages/pbs/18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.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
@@ -130,7 +138,7 @@ explicit identity and width; common lowering resolves constant groups against
not introduce another catalog. Source execution and the full installed example
are separate consumer gates beyond CSV parity.
The [PBS hashing/Identity facade](../../pbs/specs/sdk-set-and-identity.md#hash-facade-and-typed-query-boundary)
The [PBS hashing/Identity facade](../compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md#hash-facade-and-typed-query-boundary)
consumes hash.i64@1, hash.float@1 and hash.string@1 with exact schema-2 profiles,
null admission and attempted costs. Reference hash/equality are typed Registry
instructions rather than intrinsic catalog rows. Consumer support includes their
@@ -1,10 +1,21 @@
# Typed common Registry and PBX v0
Status: normative. Owner: `compiler/general`. Runtime contract reference:
Status: Normative. Owner: `compiler/general`.
Scope: Typed Registry and PBX v0.
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.
## Authority and scope
This chapter is the canonical owner of the detailed contract described below.
The [domain reading guide](README.md) identifies related chapters and their
separate responsibilities. Cross-cutting chapters refer here for these rules.
Runtime-owned ABI, instruction, resource and execution contracts retain their
authority; this chapter specifies their compiler or PBS consumer requirements.
## Ownership and handoff
Every executable frontend MUST provide its semantic types through the common
@@ -155,7 +166,7 @@ consumes both complete groups and costs 4+w(left)+w(right). Immediates are stati
program-local TypeIds (u32 LE after u16 LE opcode), and results preserve provider
faults, signed long bits, provenance and charged attempts, including unused results.
Set algorithms and equality policy remain frontend/SDK consumers, described for
PBS in [Set/Identity](../../pbs/specs/sdk-set-and-identity.md).
PBS in [Set/Identity](../compiler-languages/pbs/23.%20SDK%20Set%20and%20Identity%20Specification.md).
HOSTCALL references a declared canonical `(module, name, version)` identity
with exact argument/result slot ABI. Duplicate identities with conflicting ABI,
@@ -201,7 +212,6 @@ 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),
@@ -266,7 +276,6 @@ the current PC; they neither roll back nor complete a method. No atomic observat
of source operations by host/debugger is promised. SDK methods introduce no user
callbacks or explicit suspension during the updates that complete their invariants.
## Producer-selected guest hook roots
BeforePause/BeforeResume role targets and their transitive dependencies MUST
+38 -16
View File
@@ -1,25 +1,47 @@
# General Specs
# General Compiler Specifications
This directory contains shared acceptance specifications for all supported languages in Prometeu.
Owner: `compiler/general`. Canonical source: `docs/specs/compiler`.
## Scope
These specifications define shared frontend/backend acceptance, compilation,
linking, typed handoff and emission. They apply across supported languages.
[Language contracts](../compiler-languages/pbs/README.md) define PBS rules and
refer to this layer for shared policy rather than duplicating it.
These specs are above language-specific specs and should be reused by each language line.
## Authority and reading order
Typical topics:
The runtime owns PBX binary layout, Core ISA, admission and VM execution.
Read the [mirror and provenance policy](../../vm-arch/README.md) for that boundary.
Chapters 24–25 own the detailed compiler catalog/typed-Registry consumer contracts;
earlier pipeline, verification and matrix chapters reference them for these topics.
Equal storage widths never replace logical identity or transfer runtime authority.
- conformance gates and evidence,
- compatibility publication policy,
- verification/safety acceptance boundaries,
- artifact/runtime acceptance contracts.
Start with pipeline entry points (23), then name/linking (14), typed handoff (25),
lowering/optimization (20–21), runtime/catalog integration (16, 18, 24), and
conformance/verification/compatibility (13, 17, 19, 22). Existing chapter numbers
are stable and do not imply language-version numbers.
Current backend-facing chapter additions:
## Chapter index
- `20. IRBackend to IRVM Lowering Specification.md`
- `21. IRVM Optimization Pipeline Specification.md`
- `22. Backend Spec-to-Test Conformance Matrix.md`
- `23. Compiler Pipeline Entry Points Specification.md`
- [13. Conformance Test Specification](13.%20Conformance%20Test%20Specification.md)
- [14. Name Resolution and Module Linking Specification](14.%20Name%20Resolution%20and%20Module%20Linking%20Specification.md)
- [15. Bytecode and PBX Mapping Specification](15.%20Bytecode%20and%20PBX%20Mapping%20Specification.md)
- [16. Runtime Execution and Initialization Specification](16.%20Runtime%20Execution%20and%20Initialization%20Specification.md)
- [17. Compatibility and Evolution Policy](17.%20Compatibility%20and%20Evolution%20Policy.md)
- [18. Standard Library Surface Specification](18.%20Standard%20Library%20Surface%20Specification.md)
- [19. Verification and Safety Checks Specification](19.%20Verification%20and%20Safety%20Checks%20Specification.md)
- [20. IRBackend to IRVM Lowering Specification](20.%20IRBackend%20to%20IRVM%20Lowering%20Specification.md)
- [21. IRVM Optimization Pipeline Specification](21.%20IRVM%20Optimization%20Pipeline%20Specification.md)
- [22. Backend Spec-to-Test Conformance Matrix](22.%20Backend%20Spec-to-Test%20Conformance%20Matrix.md)
- [23. Compiler Pipeline Entry Points Specification](23.%20Compiler%20Pipeline%20Entry%20Points%20Specification.md)
- [24. Runtime Catalog Support Specification](24.%20Runtime%20Catalog%20Support%20Specification.md)
- [25. Typed Registry and PBX v0 Specification](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
## Rule
## Editorial and workflow rules
Language-specific specs (for example `docs/pbs/specs`) must reference this layer instead of duplicating cross-language acceptance policy.
Write specs in English with title, status, scope, authority, normative rules,
non-goals and conformance/exit criteria. Keep one owner per detailed contract;
summaries link to it. Only settled decisions may change normative behavior.
Agendas, decisions and plans live in `discussion/`, and completed teaching
material lives in `discussion/lessons/`; they are not parallel spec sources.
See the [specification guide](../README.md) for other domains.
+6 -1
View File
@@ -1,5 +1,7 @@
# Packer Specs
Owner: `packer`. Canonical source: `docs/specs/packer`.
This directory contains the normative packer specification set.
## Purpose
@@ -47,7 +49,7 @@ Specs should normally be fed by:
1. agendas that frame the open topic,
2. decisions that close the architectural question,
3. pull-request plans that define propagation,
3. plans that define propagation,
4. then spec integration.
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
@@ -77,3 +79,6 @@ Recommended order:
4. build artifacts;
5. diagnostics and Studio operation model;
6. versioning and trust.
See the [specification guide](../README.md) for compiler, language and provider boundaries.
@@ -36,10 +36,10 @@ This specification extends:
For packer-facing semantics, this specification must align with:
- [`../../packer/specs/1. Domain and Artifact Boundary Specification.md`](../../packer/specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`](../../packer/specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../../packer/specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- [`../packer/1. Domain and Artifact Boundary Specification.md`](../packer/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../packer/2. Workspace, Registry, and Asset Identity Specification.md`](../packer/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../packer/3. Asset Declaration and Virtual Asset Contract Specification.md`](../packer/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../packer/5. Diagnostics, Operations, and Studio Integration Specification.md`](../packer/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local behavior.
+5
View File
@@ -1,5 +1,7 @@
# Studio Specs
Owner: `studio`. Canonical source: `docs/specs/studio`.
This directory contains the normative Studio specification set.
## Purpose
@@ -95,3 +97,6 @@ automated results and user-confirmed manual acceptance are consolidated in
[LSN-0077](../../../discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md).
The earlier HTTP evidence was not substituted for these gates. The embedded
terminal remains separate.
See the [specification guide](../README.md) for compiler, language and provider boundaries.
+2 -2
View File
@@ -28,7 +28,7 @@ that the mirrors are synchronized. If the runtime repository is not available
in the same checkout, synchronization evidence must be produced against the
canonical runtime revision before merging.
Compiler-owned transformation contracts remain under `docs/compiler/general/specs`.
Compiler-owned transformation contracts remain under `docs/specs/compiler`.
Those specifications define `IRBackend -> IRVM -> PBX` emission, but they MUST
conform to the runtime-owned PBX and ISA contracts and MUST NOT redefine runtime
execution semantics.
@@ -52,7 +52,7 @@ build output in a temporary directory. Missing or different evidence sources fai
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).
[Runtime catalog support](../specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
The selected provider publishes intrinsic schema 2 (25 columns). Manual compiler
metadata must retain every nullable bit, invocation/scratch/context profile and
@@ -23,6 +23,7 @@ public final class InstalledKnowledgeProbe {
if (arguments.length == 1 && arguments[0].equals("--catalog-only")) return;
Path root = Files.createDirectory(Path.of("example")).toRealPath();
var docs = provider.documentation().orElseThrow().references(1, p.studio.AppMode.Game);
verifySpecificationAliases(provider.getClass().getClassLoader(), docs);
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");
@@ -129,6 +130,28 @@ public final class InstalledKnowledgeProbe {
if (!condition) throw new AssertionError(message);
}
private static void verifySpecificationAliases(ClassLoader loader,
java.util.List<p.studio.compiler.services.FrontendReferenceProvider.Reference> docs) throws Exception {
var resource = loader.getResource("pbs-knowledge/index.json");
check(resource != null && resource.getProtocol().equals("jar"), "Reference index must come from installed JAR");
var entries = new java.util.HashMap<String, com.fasterxml.jackson.databind.JsonNode>();
try (var stream = resource.openStream()) {
new ObjectMapper().readTree(stream).get("references")
.forEach(entry -> entries.put(entry.get("id").asText(), entry));
}
var aliases = docs.stream().filter(ref -> ref.id().startsWith("pbs:spec:") && ref.id().endsWith(".md")).toList();
check(aliases.size() == 12, "All 12 published filename IDs must remain installed");
for (var alias : aliases) {
var old = entries.get(alias.id());
var chapter = docs.stream().filter(ref -> ref.id().matches("pbs:spec:[0-9]+")
&& entries.get(ref.id()).get("resource").equals(old.get("resource"))).findFirst().orElseThrow();
check(chapter.text().equals(alias.text()), "Installed alias text mismatch: " + alias.id());
check(entries.get(chapter.id()).get("sha256").equals(old.get("sha256")), "Installed alias hash mismatch: " + alias.id());
check(loader.getResource(old.get("resource").asText()).getProtocol().equals("jar"), "Alias must use a canonical JAR resource");
}
System.out.println("Installed specification aliases verified: 12 canonical resources");
}
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[]>();
@@ -15,6 +15,7 @@ class InstalledKnowledgeTest {
String log = runProbe();
assertTrue(log.contains("references; example compiled"), log);
assertTrue(log.contains("Packaged external sources verified"), log);
assertTrue(log.contains("Installed specification aliases verified: 12 canonical resources"), log);
assertTrue(log.contains("Installed List/Cursor execution fixture generated"), log);
assertTrue(log.contains("Installed Linked execution fixture generated"), log);
assertTrue(log.contains("Installed map execution fixture generated"), log);
@@ -13,11 +13,9 @@ dependencies {
// 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 pbsAlignmentSpecs = rootProject.layout.projectDirectory.dir("docs/compiler/pbs/specs")
val pbsResources = layout.projectDirectory.dir("src/main/resources")
val generatePbsKnowledge by tasks.registering(Sync::class) {
from(pbsSpecs) { include("*.md"); into("pbs-knowledge/specs") }
from(pbsAlignmentSpecs) { include("*.md"); into("pbs-knowledge/specs") }
into(layout.buildDirectory.dir("generated/pbsKnowledge"))
inputs.files(fileTree(pbsResources) { include("game/stdlib/**/*.pbs", "game/stdlib/**/*.barrel", "pbs-knowledge/examples/**") })
doLast {
@@ -29,13 +27,37 @@ val generatePbsKnowledge by tasks.registering(Sync::class) {
entries.add(linkedMapOf("id" to id, "title" to title, "kind" to kind,
"resource" to resource, "sha256" to digest, "sdkVersion" to sdk, "target" to target))
}
(pbsSpecs.asFile.listFiles()!!.toList() + (pbsAlignmentSpecs.asFile.listFiles()?.toList() ?: emptyList())).filter { it.extension == "md" }.sortedBy { it.name }.forEach { source ->
// Published filename IDs alias the single canonical numbered resource.
val legacyReferenceIds = mapOf(
"14" to "typed-arrays-and-optional-execution.md",
"15" to "first-class-functions-and-captures.md",
"16" to "generic-contracts.md",
"17" to "generic-structs-and-free-functions.md",
"18" to "input-and-existing-type-runtime-alignment.md",
"19" to "service-constants-and-runtime-math.md",
"20" to "runtime-random-integration.md",
"21" to "sdk-list-and-cursor.md",
"22" to "sdk-linked-and-cursor.md",
"23" to "sdk-set-and-identity.md",
"24" to "sdk-map-and-keyval.md",
"25" to "sdk-stack-and-queue.md"
)
val sources = checkNotNull(pbsSpecs.asFile.listFiles()) { "Missing canonical PBS specifications: $pbsSpecs" }
.filter { it.extension == "md" }.sortedBy { it.name }
check(legacyReferenceIds.keys.all { chapter -> sources.any { it.name.substringBefore(". ") == chapter } }) {
"Missing canonical target for a published PBS reference ID"
}
sources.forEach { source ->
val chapter = source.name.substringBefore(". ")
val quickstart = source.name == "README.md"
val title = source.readLines().first { it.startsWith("# ") }.removePrefix("# ")
val kind = if (quickstart) "QUICKSTART" else if (chapter == "3") "SYNTAX" else "SEMANTICS"
val resource = "pbs-knowledge/specs/${source.name}"
entry(if (quickstart) "pbs:quickstart" else "pbs:spec:$chapter",
source.readLines().first { it.startsWith("# ") }.removePrefix("# "),
if (quickstart) "QUICKSTART" else if (chapter == "3") "SYNTAX" else "SEMANTICS",
"pbs-knowledge/specs/${source.name}", source)
title, kind, resource, source)
legacyReferenceIds[chapter]?.let { legacy ->
entry("pbs:spec:$legacy", title, kind, resource, source)
}
}
fileTree(pbsResources) { include("game/stdlib/**/*.pbs", "game/stdlib/**/*.barrel") }.files.sorted().forEach { source ->
val path = source.relativeTo(pbsResources.asFile).invariantSeparatorsPath
@@ -9,6 +9,35 @@ import java.util.*;
import static org.junit.jupiter.api.Assertions.*;
class PbsDocumentationTest {
@Test void publishedFeatureIdsResolveToTheSameCanonicalChapterResourceAndHash() throws Exception {
// These IDs were published before the chapters were numbered.
var legacyIds = List.of("typed-arrays-and-optional-execution.md",
"first-class-functions-and-captures.md", "generic-contracts.md",
"generic-structs-and-free-functions.md", "input-and-existing-type-runtime-alignment.md",
"service-constants-and-runtime-math.md", "runtime-random-integration.md",
"sdk-list-and-cursor.md", "sdk-linked-and-cursor.md", "sdk-set-and-identity.md",
"sdk-map-and-keyval.md", "sdk-stack-and-queue.md");
var references = new PbsDocumentation().references(1, AppMode.Game).stream()
.collect(java.util.stream.Collectors.toMap(FrontendReferenceProvider.Reference::id, ref -> ref));
var entries = new HashMap<String, com.fasterxml.jackson.databind.JsonNode>();
try (var stream = getClass().getClassLoader().getResourceAsStream("pbs-knowledge/index.json")) {
assertNotNull(stream);
new com.fasterxml.jackson.databind.ObjectMapper().readTree(stream).get("references")
.forEach(entry -> entries.put(entry.get("id").asText(), entry));
}
for (int i = 0; i < legacyIds.size(); i++) {
String oldId = "pbs:spec:" + legacyIds.get(i);
String chapterId = "pbs:spec:" + (14 + i);
assertNotNull(references.get(oldId), oldId);
assertNotNull(references.get(chapterId), chapterId);
assertEquals(references.get(chapterId).text(), references.get(oldId).text(), oldId);
assertEquals(references.get(chapterId).kind(), references.get(oldId).kind(), oldId);
assertEquals(entries.get(chapterId).get("resource"), entries.get(oldId).get("resource"), oldId);
assertEquals(entries.get(chapterId).get("sha256"), entries.get(oldId).get("sha256"), oldId);
assertTrue(entries.get(oldId).get("resource").asText().startsWith("pbs-knowledge/specs/" + (14 + i) + ". "));
}
}
@Test void installedIndexHasAllKindsUniqueIdsAndExactSdkSources() throws Exception {
var references = new PbsDocumentation().references(1, AppMode.Game);
assertEquals(references.size(), references.stream().map(FrontendReferenceProvider.Reference::id).distinct().count());
@@ -178,10 +178,9 @@ class BackendConformanceMatrixSpecTest {
private Path locateRepoRoot() {
var cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize();
while (cursor != null) {
final var hasDocs = Files.isDirectory(cursor.resolve("docs/compiler/general/specs"));
final var hasCurrentDocs = Files.isDirectory(cursor.resolve("docs/specs/compiler"));
final var hasCompiler = Files.isDirectory(cursor.resolve("prometeu-compiler"));
if ((hasDocs || hasCurrentDocs) && hasCompiler) {
if (hasCurrentDocs && hasCompiler) {
return cursor;
}
cursor = cursor.getParent();
+104
View File
@@ -0,0 +1,104 @@
#!/usr/bin/env python3
"""Check repository Markdown navigation without fetching or modifying sources.
Runtime mirrors keep provider-relative links and exact bytes. Pass --runtime to
also check provider links against a local read-only checkout; otherwise those
references are reported separately and do not make ordinary builds depend on it.
"""
import argparse
import re
import subprocess
from pathlib import Path
from urllib.parse import unquote
def prose(text):
"""Exclude fenced examples; their sample links are not document navigation."""
lines = []
fence = None
for line in text.splitlines():
match = re.match(r"^\s{0,3}(`{3,}|~{3,})", line)
if match:
marker = match.group(1)
if fence is None:
fence = marker
elif marker[0] == fence[0] and len(marker) >= len(fence):
fence = None
lines.append("")
else:
lines.append(line if fence is None else "")
return "\n".join(lines)
def anchors(text):
found = set(re.findall(r'(?:id|name)=["\']([^"\']+)["\']', text))
counts = {}
for heading in re.findall(r"^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$", prose(text), re.M):
heading = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", heading)
heading = re.sub(r"<[^>]+>", "", heading).lower()
slug = re.sub(r"[^\w\-\s]", "", heading).replace(" ", "-")
count = counts.get(slug, 0)
counts[slug] = count + 1
found.add(slug + (f"-{count}" if count else ""))
return found
def verify(root, runtime):
tracked = subprocess.check_output(
["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
cwd=root, text=True).split("\0")
files = {root / name for name in tracked if name.endswith(".md")}
files.update((root / "discussion/workflow").rglob("*.md"))
files.add(root / "AGENTS.md")
files = sorted(path for path in files if path.is_file())
mirror_names = {"docs/vm-arch/ARCHITECTURE.md", "docs/vm-arch/ISA_CORE.md"}
failures = []
local_count = provider_count = 0
anchor_cache = {}
for source in files:
relative = source.relative_to(root).as_posix()
content = prose(source.read_text())
links = re.findall(r"\]\(([^)\n]+)\)", content)
links += re.findall(r"^\s*\[[^\]]+\]:\s*(\S+)", content, re.M)
for link in links:
link = link.strip().strip("<>")
if re.match(r"[a-zA-Z][a-zA-Z\d+.-]*:", link) or link.startswith("//"):
continue
path, _, fragment = link.partition("#")
target = (source.parent / unquote(path)).resolve() if path else source
provider = False
if relative in mirror_names:
provider = True
if runtime:
target = ((runtime / relative).parent / unquote(path)).resolve() if path else runtime / relative
elif target.is_relative_to(root.parent / "runtime"):
provider = True
if runtime:
target = runtime / target.relative_to(root.parent / "runtime")
if provider:
provider_count += 1
if runtime is None:
continue
else:
local_count += 1
if not target.exists():
failures.append(f"{relative}: missing target {link}")
elif fragment and target.suffix == ".md":
if target not in anchor_cache:
anchor_cache[target] = anchors(target.read_text())
if unquote(fragment) not in anchor_cache[target]:
failures.append(f"{relative}: missing anchor {link}")
for failure in failures:
print(failure)
mode = "checked" if runtime else "classified; use --runtime to check"
print(f"Markdown: {len(files)} files; {local_count} local links; "
f"{provider_count} provider links ({mode}); {len(failures)} failures")
return bool(failures)
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2])
parser.add_argument("--runtime", type=Path)
args = parser.parse_args()
raise SystemExit(verify(args.root.resolve(), args.runtime.resolve() if args.runtime else None))