agendas, decisions and specs changes

This commit is contained in:
2026-03-24 13:42:19 +00:00
parent 96f971bbe4
commit 150a257e0c
46 changed files with 830 additions and 1315 deletions
+4 -1
View File
@@ -53,6 +53,9 @@ Use it to:
- define precedence, scope, rules, and exit criteria,
- provide the baseline for implementation, verification, and conformance.
`docs/pbs/specs` is language-specific.
Cross-language acceptance specs live in `docs/general/specs`.
Specs must not operate as discussion backlogs.
If a point is still disputed or underspecified, it belongs in `agendas/` or `decisions/`, not directly in `specs/`.
@@ -83,5 +86,5 @@ The preferred pipeline is:
- `agendas/` stores open questions.
- `decisions/` stores closed answers.
- `specs/` stores the normative contract.
- `specs/` stores the PBS-specific normative contract.
- `pull-requests/` stores reviewable change packages.
@@ -1,123 +0,0 @@
# PBS IR and Lowering Agenda
Status: Active
## Purpose
Drive the decisions needed to turn `12. IR and Lowering Specification.md` from a skeleton into a normative lowering contract that can guide implementation.
## Context
The language now has substantial source-level semantics, but lowering still lacks closure around:
- which semantic obligations IR must preserve,
- whether one canonical IR shape is normative,
- how core constructs map into lowered control flow and data flow,
- how services, contracts, callbacks, tuples, `optional`, and `result` lower,
- and which invariants belong in lowering versus PBX/bytecode mapping.
This agenda should keep the focus on semantic preservation and artifact obligations, not on one compiler's class hierarchy.
## Decisions To Produce
1. Decide the normative status of IR:
canonical IR, canonical obligations only, or hybrid.
2. Decide the required lowering preconditions after parsing, resolution, and type checking.
3. Decide the lowered forms required for expressions, control flow, abrupt completion, and propagation.
4. Decide the lowering story for callbacks, services, contracts, tuples, `optional`, and `result`.
5. Decide the boundary between this spec and `15. Bytecode and PBX Mapping Specification.md`.
6. Decide the artifact invariants that must hold before verifier or loader stages.
## Core Questions
1. Which evaluation-order guarantees from dynamic semantics must be explicit in lowered form?
2. Which memory and identity facts must remain explicit through IR rather than inferred later?
3. Do callback formation and contract dispatch need dedicated runtime artifacts or only preserved semantic obligations?
4. What is the minimal lowering model for builtin projections, builtin constants, and intrinsic member calls beyond what is already fixed?
5. Which host-binding failures are lowering failures versus later verifier or loader failures?
## Proposed Workshop Sequence
### Workshop 1: Lowering Contract and IR Status
Purpose:
- decide whether PBS standardizes one canonical IR or only preserved obligations,
- and close lowering preconditions after parsing, resolution, and type checking.
Expected decisions:
- canonical IR versus obligations-only model,
- required bound-program inputs,
- and minimal preserved semantic facts.
### Workshop 2: Control Flow, Evaluation Order, and Propagation
Purpose:
- close the lowering model for expressions, branching, abrupt completion, `optional`, and `result`.
Expected decisions:
- explicit evaluation-order preservation,
- lowered forms for `else`, `!`, and `handle`,
- and trap versus propagation boundaries.
### Workshop 3: Callables, Services, Contracts, and Callbacks
Purpose:
- close the lowering story for callable categories beyond ordinary top-level functions.
Expected decisions:
- callback formation model,
- service and contract dispatch shape,
- and runtime-artifact obligations for callable categories.
### Workshop 4: Builtins, Host Bindings, and Artifact Invariants
Purpose:
- close builtin lowering, host-binding emission, and the invariants required before verifier and loader stages.
Expected decisions:
- builtin projection and intrinsic lowering obligations,
- host-binding emission boundary versus PBX mapping,
- and artifact invariants consumed by `15` and `19`.
## Expected Spec Material
The resulting spec work should be able to add or close sections for:
- lowering preconditions,
- preserved semantic obligations,
- control-flow lowering,
- callable lowering by category,
- tuple, `optional`, and `result` lowering,
- callback, service, and contract lowering,
- builtin and host-binding lowering,
- artifact invariants before PBX emission,
- and source-to-artifact trace hooks consumed by diagnostics and conformance.
## Non-Goals
- Freezing optimizer internals.
- Freezing one in-memory compiler IR data model.
- Repeating the bytecode ISA.
- Defining loader patching internals.
- Designing performance heuristics.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/6. VM-owned vs Host-backed.md`
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md`
@@ -1,116 +0,0 @@
# PBS IR and Lowering Workshop 1
Status: Active
## Purpose
Run the first focused discussion for `12. IR and Lowering Specification.md` on the front door of lowering:
- what the lowering contract consumes,
- whether IR itself is normative,
- and which semantic obligations must be preserved independent of IR shape.
## Why This Slice First
This slice should come first because every later lowering discussion depends on knowing:
- what counts as a well-formed input to lowering,
- and whether the spec standardizes one IR shape or only semantic preservation duties.
## Proposed Meeting Order
1. Reconfirm already-settled lowering inputs.
2. Close the preconditions for lowering.
3. Close the normative status of IR.
4. Close the minimum preserved semantic obligations.
5. Record construct-specific issues for later workshops.
## Decisions To Produce
1. The normative status of IR in PBS v1.
2. The minimum required input state before lowering begins.
3. The semantic facts that lowering must preserve regardless of IR architecture.
4. The boundary between `12` and `15`.
## Candidate Decisions
### 1. Standardize Preserved Obligations, Not One Canonical In-Memory IR
Candidate direction:
- PBS v1 does not require one canonical compiler IR data model,
- but it does require one stable set of preserved semantic obligations.
Rationale:
- This keeps the spec implementation-neutral while still preventing semantic drift.
Alternative to discuss:
- define one normative abstract IR grammar in the spec.
### 2. Lowering Preconditions Require A Fully Bound Program
Candidate direction:
- parsing, name resolution, visibility/linking, and type checking must already be complete,
- reserved builtin and host metadata must already be validated,
- callable sets and canonical identities must already be resolved.
Rationale:
- Lowering should not invent unresolved semantic answers.
### 3. Minimum Preserved Obligations Include Evaluation Order, Identity, and Host Boundary Facts
Candidate direction:
- lowering must preserve:
source-observable evaluation order,
abrupt-completion behavior,
value-identity and aliasing facts,
host-boundary crossings,
and trap-versus-propagation distinctions.
Rationale:
- These are the semantic anchors later workshops will rely on.
### 4. `15` Owns Final Artifact Layout, `12` Owns The Contract Before It
Candidate direction:
- `12` defines the semantic and artifact-facing invariants a lowered program must satisfy,
- `15` defines the final PBX and bytecode mapping details.
Rationale:
- This keeps the lowering spec from collapsing into artifact byte layout.
## Questions To Resolve In The Room
1. Is obligations-only precise enough, or does PBS need a normative abstract IR?
2. Should canonical identity resolution be fully complete before lowering?
3. Which semantic facts are mandatory to preserve explicitly rather than infer later?
4. Does `12` need one explicit “bound program” model?
5. How much artifact vocabulary can `12` use before it starts stealing `15`'s job?
## Expected Outputs
1. a decision record on IR status,
2. a decision record on lowering preconditions,
3. and a checklist of preserved semantic obligations for `12`.
## Explicit Deferrals For Workshop 2
- control-flow shapes,
- propagation operators,
- and callable-category-specific lowering.
## Inputs
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
@@ -1,117 +0,0 @@
# PBS IR and Lowering Workshop 2
Status: Active
## Purpose
Run the second focused discussion for `12. IR and Lowering Specification.md` on control flow and propagation:
- evaluation order,
- branching,
- abrupt completion,
- `optional`,
- `result`,
- `!`,
- and `handle`.
## Why This Slice Second
This slice follows naturally from Workshop 1 because it applies the preserved-obligations model to the core execution constructs.
## Proposed Meeting Order
1. Reconfirm the preserved semantic obligations from Workshop 1.
2. Close evaluation-order preservation in lowered form.
3. Close the lowered model for branching and abrupt completion.
4. Close the lowered model for `optional` and `result` propagation.
5. Record callable and runtime-artifact issues for Workshop 3.
## Decisions To Produce
1. How evaluation order is preserved explicitly.
2. How abrupt completion is represented in lowered control flow.
3. The lowered shape of `optional else`, `expr!`, and `handle`.
4. The boundary between propagation and trap in lowering.
## Candidate Decisions
### 1. Lowering Must Make Single Evaluation Explicit
Candidate direction:
- call target formation,
- argument evaluation,
- `if` conditions,
- `switch` selectors,
- `some(expr)` payload formation,
- and `bind(context, fn_name)` capture
must each lower to explicit once-only evaluation points.
Rationale:
- These are already language-observable guarantees.
### 2. Branching Lowers To Explicit Control Transfers
Candidate direction:
- `if` and `switch` lower to explicit branch structure,
- non-selected arms do not evaluate,
- and tail-result formation is explicit rather than implicit.
Rationale:
- This keeps the dynamic-semantics contract visible through lowering.
### 3. Propagation Uses Dedicated Lowered Paths
Candidate direction:
- `optional else` lowers to a presence test plus fallback path,
- `expr!` lowers to success-path unpack plus immediate error propagation path,
- `handle` lowers to explicit arm dispatch over the error case space.
Rationale:
- These constructs are semantically distinct enough that ordinary expression lowering should not blur them.
### 4. Trap Is Not Rewritten Into Result Flow
Candidate direction:
- lowered trap paths remain fatal abort paths outside ordinary `result` propagation,
- and `handle` never intercepts trap.
Rationale:
- This preserves the existing semantics cleanly.
## Questions To Resolve In The Room
1. Does `12` need dedicated abstract operations for propagation, or only obligations on the emitted control flow?
2. How explicit must once-only evaluation be in the spec text?
3. Does `switch` lowering need one canonical decision-tree shape?
4. Is `handle` best specified as arm dispatch plus remap semantics, or as a more abstract effect-preservation rule?
5. Which of these details belong to `12` versus `15`?
## Expected Outputs
1. a decision record for evaluation-order preservation,
2. a decision record for propagation lowering,
3. and control-flow section targets for `12`.
## Explicit Deferrals For Workshop 3
- services,
- contracts,
- callbacks,
- and runtime dispatch artifacts.
## Inputs
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
- `docs/pbs/agendas/12.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md`
@@ -1,111 +0,0 @@
# PBS IR and Lowering Workshop 3
Status: Active
## Purpose
Run the third focused discussion for `12. IR and Lowering Specification.md` on callable categories beyond ordinary top-level functions:
- callbacks,
- services,
- contracts,
- methods,
- and dispatch obligations.
## Why This Slice Third
This slice should come after control-flow lowering because it builds on the general execution model while introducing runtime-dispatch and identity-sensitive concerns.
## Proposed Meeting Order
1. Reconfirm callable categories and identity facts already fixed.
2. Close callback formation and invocation lowering.
3. Close service and method lowering.
4. Close contract-view and dispatch lowering.
5. Record builtin and host-binding specifics for Workshop 4.
## Decisions To Produce
1. The lowering story for callback formation and invocation.
2. The lowering story for service singleton methods.
3. The lowering story for contracts and dispatch.
4. Which runtime-artifact facts must be explicit versus implementation-defined.
## Candidate Decisions
### 1. Callback Lowering Must Preserve Captured Identity And Retention
Candidate direction:
- callback values created by `bind` lower to a representation that preserves:
target callable identity,
captured context identity,
and retention-bearing lifetime facts.
Rationale:
- These are already required by memory and semantics specs.
### 2. Service Lowering Preserves Singleton Identity
Candidate direction:
- service method calls lower through the module-owned singleton identity,
- and lowering must not accidentally materialize new service instances.
Rationale:
- This is a language-observable property.
### 3. Contract Lowering Must Preserve Selected Implementation Identity
Candidate direction:
- contract values lower as runtime-dispatchable views over an underlying owner plus implementation selection,
- but `12` does not freeze one concrete table or object layout yet.
Rationale:
- This keeps the semantic contract clear while deferring layout choices.
### 4. Receiver-Bearing Method Calls Need Explicit Lowered Receiver Handling
Candidate direction:
- struct, service, and contract method calls lower through an explicit receiver-bearing callable shape,
- even if the backend later optimizes the representation.
Rationale:
- This keeps receiver identity and call semantics visible in the spec.
## Questions To Resolve In The Room
1. Does contract dispatch need a dedicated runtime artifact category in the spec?
2. Does callback lowering need one explicit abstract representation?
3. How much of method dispatch belongs in `12` versus runtime execution specs?
4. Are service methods lowered like receiver calls or like specialized global calls?
5. Which of these constructs need explicit artifact invariants before `15`?
## Expected Outputs
1. a decision record for callback lowering,
2. a decision record for service and contract lowering,
3. and callable-category section targets for `12`.
## Explicit Deferrals For Workshop 4
- builtin projection lowering,
- builtin constants,
- host-binding emission,
- and verifier-facing artifact invariants.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
- `docs/pbs/agendas/12.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md`
@@ -1,111 +0,0 @@
# PBS IR and Lowering Workshop 4
Status: Active
## Purpose
Run the fourth focused discussion for `12. IR and Lowering Specification.md` on the backend-facing edges:
- builtin projections,
- builtin constants,
- intrinsic member calls,
- host-binding emission,
- and artifact invariants required before verifier or loader stages.
## Why This Slice Last
This slice should come last because it depends on the general lowering contract plus the special ownership rules around VM-owned versus host-backed behavior.
## Proposed Meeting Order
1. Reconfirm already-settled builtin and host-binding facts.
2. Close lowering obligations for builtin projections and constants.
3. Close lowering obligations for intrinsic member calls.
4. Close host-binding emission obligations.
5. Close pre-verifier and pre-loader artifact invariants.
## Decisions To Produce
1. Builtin lowering obligations beyond already-settled metadata consumption.
2. Host-binding emission obligations before loader resolution.
3. The artifact invariants required before verifier/loader stages.
4. The exact boundary between `12`, `15`, and `19`.
## Candidate Decisions
### 1. Builtin Projections Stay VM-Owned Through Lowering
Candidate direction:
- builtin projection access lowers through VM-owned operations only,
- and never through host-binding tables or host syscall paths.
Rationale:
- This is already settled; `12` needs only to make the preserved obligation explicit.
### 2. Builtin Constants Lower Through Materialization, Not Constant Folding Semantics
Candidate direction:
- builtin constants lower through their VM-owned materialization path,
- not through ordinary user-authored compile-time constant evaluation.
Rationale:
- This keeps builtin shells distinct from ordinary `declare const`.
### 3. Host-Binding Emission Must Be Explicit Before `15`
Candidate direction:
- lowering must produce canonical host-binding entries,
- deduplicate them by canonical identity,
- and emit host-backed callsites in the pre-load form already fixed elsewhere.
Rationale:
- This is the bridge between bound source and artifact mapping.
### 4. `12` Defines Artifact Invariants, `15` Defines Encoding
Candidate direction:
- `12` states what must be true of the emitted artifact boundary,
- `15` states exactly how those facts appear in PBX and bytecode form,
- `19` states what must be verified.
Rationale:
- This keeps the three backend-facing specs from overlapping.
## Questions To Resolve In The Room
1. Does `12` need any abstract instruction vocabulary for builtins and host calls?
2. Which invariants belong to lowering rather than to verification?
3. How much ordering and dedup detail should `12` restate versus reference from other specs?
4. Should intrinsic lowering be specified as abstract op families or only semantic obligations?
5. What exact artifact guarantees must `13` eventually assert?
## Expected Outputs
1. a decision record for builtin lowering obligations,
2. a decision record for host-binding emission obligations,
3. and an artifact-invariants checklist spanning `12`, `15`, and `19`.
## Explicit Deferrals
- exact bytecode instruction encodings,
- exact PBX section layout,
- and verifier algorithm details.
## Inputs
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
- `docs/pbs/agendas/12.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md`
@@ -0,0 +1,122 @@
# PBS Frontend IR and Lowering Agenda
Status: Active
## Purpose
Drive closure of `13. Lowering IRBackend Specification.md` for frontend scope only.
This agenda exists to define the first normative lowering boundary:
- PBS source to frontend IR (`IRBackend` / `IRBackendFile`),
- deterministic diagnostic behavior for unsupported or invalid source forms,
- and test-backed acceptance criteria for Gate U.
## Scope Boundary
In scope:
- lexer/parser/AST/linking outputs consumed by frontend lowering,
- semantic facts that must be preserved in frontend IR,
- deterministic rejection classes and diagnostic attribution,
- and conformance evidence for frontend gates.
Out of scope:
- VM lowering,
- bytecode/PBX mapping,
- runtime execution behavior,
- verifier/loader algorithms.
## Decisions To Produce
1. Decide whether `13` standardizes one frontend IR shape or only preserved obligations.
2. Decide the minimum preconditions before frontend lowering begins.
3. Decide which semantic facts must be explicit in frontend IR for v1.
4. Decide the minimum deterministic rejection set for unsupported frontend-lowering cases.
5. Decide the gate evidence expected from tests (`lexer/parser/AST/IRBackend/diagnostics`).
## Core Questions
1. What is the minimum frontend IR contract that keeps implementation practical and testable now?
2. Which source-observable guarantees must already be explicit before any backend stage exists?
3. Which constructs are in-scope for v1 lowering and which must fail deterministically?
4. What diagnostics identity must be stable for lowering-related frontend failures?
5. Which regression fixtures become mandatory Gate U evidence?
## Proposed Workshop Sequence
### Workshop 1: Frontend Lowering Contract and Preconditions
Purpose:
- close input preconditions,
- and close the normative status of frontend IR.
Expected decisions:
- obligations-only versus canonical frontend IR model,
- and minimum required bound-program state before lowering.
### Workshop 2: Expressions, Control Flow, and Propagation in Frontend IR
Purpose:
- close frontend-lowering obligations for core expression/control-flow forms.
Expected decisions:
- once-only evaluation obligations in frontend IR terms,
- representation obligations for branching and propagation constructs.
### Workshop 3: Callable Categories in Frontend IR
Purpose:
- close frontend-lowering obligations for functions, callbacks, services, and contracts as source-level categories.
Expected decisions:
- minimum callable metadata preserved in frontend IR,
- and deterministic rejection boundaries for unsupported callable forms.
### Workshop 4: Builtins, Diagnostics, and Test Gates
Purpose:
- close builtin-facing frontend obligations plus gate-ready diagnostics/test evidence.
Expected decisions:
- frontend treatment of builtin shells/metadata at lowering boundary,
- minimum diagnostics identity and attribution for lowering-related failures,
- and required fixture families for Gate U.
## Expected Spec Material
The resulting `13` content should close:
- lowering preconditions for frontend scope,
- frontend IR preserved-obligation model,
- construct-by-construct frontend lowering baseline,
- deterministic unsupported-case rejection policy,
- and frontend-facing diagnostic/test evidence hooks.
## Non-Goals
- Defining VM or bytecode artifacts.
- Freezing runtime semantics in this agenda.
- Defining verifier or loader internals.
- Freezing optimizer architecture.
## Inputs
- `docs/pbs/specs/3. Core Syntax Specification.md`
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
@@ -0,0 +1,102 @@
# PBS Frontend IR and Lowering Workshop 1
Status: Closed (2026-03-05)
## Purpose
Run the first focused discussion for `13. Lowering IRBackend Specification.md` in frontend scope:
- what frontend lowering consumes,
- what frontend lowering must produce,
- and whether one canonical frontend IR shape is required.
## Why This Slice First
Every later workshop depends on a stable contract for:
- preconditions before lowering,
- and which frontend IR obligations are normative.
## Proposed Meeting Order
1. Reconfirm frontend-only scope boundary for agenda 13.
2. Close minimum preconditions before frontend lowering starts.
3. Close normative status of frontend IR shape versus obligations.
4. Close minimum preserved semantic facts for v1.
5. Record construct-specific gaps for Workshops 2 to 4.
## Decisions To Produce
1. Normative status of frontend IR in v1.
2. Required input state before frontend lowering begins.
3. Minimum preserved semantic facts at frontend-lowering boundary.
4. Minimum deterministic rejection policy for unsupported lowering inputs.
## Candidate Decisions
### 1. Standardize Preserved Obligations, Not One In-Memory Class Graph
Candidate direction:
- v1 standardizes preserved frontend obligations and observable outcomes,
- not one mandatory Java object model.
### 2. Frontend Lowering Requires Fully Parsed and Linked Source
Candidate direction:
- parser and linking outcomes are already complete,
- type/name diagnostics already produced where required,
- and lowering does not invent unresolved semantic answers.
### 3. Minimum Preserved Facts For V1 Frontend IR
Candidate direction:
- callable identity,
- parameter arity,
- declared return surface,
- and source attribution anchor (`file + span`) for diagnostics.
### 4. Unsupported Constructs Must Fail Deterministically
Candidate direction:
- constructs outside v1 frontend-lowering slice fail with stable diagnostics,
- never silently degrade into partial/implicit behavior.
## Questions To Resolve In The Room
1. Which facts are mandatory in v1 `IRFunction` versus optional?
2. Is obligations-only precise enough for conformance tests?
3. Which rejected constructs must already have fixed diagnostic codes?
4. What is the exact pass/fail boundary between parser/linking and frontend lowering errors?
## Expected Outputs
1. a decision note on frontend IR normative status,
2. a decision note on lowering preconditions,
3. and a checklist of preserved frontend-lowering obligations.
## Decision Outcome (2026-03-05)
1. `13` remains normative by preserved obligations, not by one mandatory in-memory IR shape.
2. Frontend lowering starts only after parse/linking completion and required prior diagnostics.
3. Minimum v1 frontend IR facts are mandatory: callable identity, arity, declared return surface, and source anchor (`file + span`).
4. Unsupported frontend-lowering forms must fail deterministically with stable diagnostics.
5. Scope boundary confirmed: `IRBackend` is the first lowering (frontend responsibility); `IRVM` is a later lowering (backend responsibility) and is out of `13` agenda scope.
6. Evidence baseline confirmed for now: Gate U only (`lexer/parser/AST/IRBackend/diagnostics`), without S-U requirement at this stage.
7. Conformance-valid IR claim rule: only when the full PBS spec surface is implemented at `IRBackend` level.
## Explicit Deferrals For Workshop 2
- expression/control-flow construct mapping details,
- and propagation construct obligations.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/agendas/13. IR and Lowering Agenda.md`
@@ -0,0 +1,86 @@
# PBS Frontend IR and Lowering Workshop 2
Status: Active
## Purpose
Run the second focused discussion for `13. Lowering IRBackend Specification.md` on frontend-lowering obligations for:
- expression evaluation order,
- branching behavior,
- and propagation-related constructs at frontend IR boundary.
## Why This Slice Second
After Workshop 1 closes contract/preconditions, this workshop closes construct-level obligations that must be testable in frontend scope.
## Proposed Meeting Order
1. Reconfirm preserved obligations from Workshop 1.
2. Close once-only evaluation obligations in frontend IR terms.
3. Close branch and abrupt-completion representation obligations.
4. Close propagation construct obligations (`optional`, `result`, `!`, `handle`) at frontend boundary.
5. Record callable-category leftovers for Workshop 3.
## Decisions To Produce
1. Which evaluation-order guarantees must remain explicit in frontend IR obligations.
2. Which branch/abrupt-completion facts are mandatory in v1 frontend lowering.
3. Which propagation constructs are in-scope versus deterministic rejection in v1 slice.
4. Which diagnostics are required when unsupported propagation constructs are used.
## Candidate Decisions
### 1. Frontend Lowering Must Preserve Once-Only Evaluation Facts
Candidate direction:
- source-observable single-evaluation points are preserved as explicit lowering obligations,
- independent of one exact IR node taxonomy.
### 2. Branching Obligations Are Normative At Frontend Boundary
Candidate direction:
- selected/non-selected branch semantics remain explicit in frontend lowering contract,
- with no implicit permissive fallbacks.
### 3. Propagation Constructs Have Explicit V1 Status
Candidate direction:
- each construct is marked `supported in v1 frontend lowering` or `deterministic reject`,
- and this status is mirrored in Gate U fixtures.
### 4. Diagnostics Identity Must Be Stable For Unsupported Forms
Candidate direction:
- unsupported forms emit stable code/severity/primary attribution,
- so regression tests can lock behavior.
## Questions To Resolve In The Room
1. Which propagation constructs are fully represented now versus deferred?
2. What minimum frontend IR evidence is enough to prove evaluation-order obligations?
3. Which failures should be classified as parse/static errors versus lowering errors?
4. Which fixture shapes are mandatory for Gate U here?
## Expected Outputs
1. a decision note on expression/control-flow lowering obligations,
2. a decision note on propagation status map (support/reject),
3. and fixture targets for frontend conformance tests.
## Explicit Deferrals For Workshop 3
- callable-category representation details,
- and service/contract/callback-specific obligations.
## Inputs
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md`
@@ -0,0 +1,88 @@
# PBS Frontend IR and Lowering Workshop 3
Status: Active
## Purpose
Run the third focused discussion for `13. Lowering IRBackend Specification.md` on callable categories in frontend scope:
- top-level functions,
- callbacks,
- services,
- and contracts as source-level callable surfaces.
## Why This Slice Third
Callable categories depend on the core expression/control-flow obligations from Workshop 2 and now need explicit frontend representation/rejection boundaries.
## Proposed Meeting Order
1. Reconfirm callable and identity facts already settled by syntax/static/linking specs.
2. Close frontend-lowering obligations for function and callback forms.
3. Close frontend-lowering obligations for service/contract callable surfaces.
4. Close deterministic rejection policy for unsupported callable forms.
5. Record builtin/diagnostics gate closure points for Workshop 4.
## Decisions To Produce
1. Minimum callable metadata preserved by frontend IR for each callable category.
2. V1 support map for callable categories (`supported` versus deterministic reject).
3. Required diagnostics identity for rejected callable forms.
4. Required regression fixtures for callable categories in Gate U.
## Candidate Decisions
### 1. Callable Identity Must Be Explicit In Frontend IR Contract
Candidate direction:
- callable name/category/arity/source attribution are mandatory preserved facts,
- regardless of internal object-model differences.
### 2. Callback/Service/Contract Surfaces Need Explicit V1 Status
Candidate direction:
- each callable surface is classified now as `represented` or `rejected`,
- with no silent fallback behavior.
### 3. Unsupported Callable Forms Are Deterministic Diagnostics
Candidate direction:
- unsupported callable patterns must emit stable diagnostics,
- and become mandatory regression tests.
### 4. Gate U Must Cover Callable Categories Explicitly
Candidate direction:
- representative valid+invalid fixtures per callable category are mandatory,
- including diagnostics assertions for rejected forms.
## Questions To Resolve In The Room
1. Which callable category fields are mandatory in `IRBackend` today?
2. Which callable constructs remain deferred in v1 frontend scope?
3. What is the minimum fixture set to protect callable behavior regressions?
4. Which diagnostics codes must be fixed now versus later?
## Expected Outputs
1. a decision note on callable frontend-lowering obligations,
2. a decision note on callable support/rejection map,
3. and Gate U fixture requirements for callable categories.
## Explicit Deferrals For Workshop 4
- builtin-specific lowering obligations,
- and final diagnostics/gate packaging for spec closure.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md`
@@ -0,0 +1,89 @@
# PBS Frontend IR and Lowering Workshop 4
Status: Active
## Purpose
Run the fourth focused discussion for `13. Lowering IRBackend Specification.md` to close frontend-specific pending points:
- builtin-facing source semantics at frontend lowering boundary,
- diagnostics stability for lowering-related failures,
- and test-gate evidence needed to close v1 frontend slice.
## Why This Slice Last
This workshop should close only after Workshops 1 to 3 define the base lowering contract and callable status map.
## Proposed Meeting Order
1. Reconfirm frontend-only scope and deferred backend concerns.
2. Close builtin-shell obligations at frontend lowering boundary.
3. Close diagnostics identity/attribution obligations for lowering-related failures.
4. Close minimum gate evidence package (Gate U).
5. Produce closure checklist for spec `13` frontend slice.
## Decisions To Produce
1. Frontend-lowering obligations for builtin-facing constructs in v1.
2. Stable diagnostics contract for frontend-lowering rejections.
3. Mandatory fixture families to prove `13` frontend obligations.
4. Explicit list of deferred topics that belong to future backend-focused agenda.
## Candidate Decisions
### 1. Builtin Surfaces Are Frontend-Validated Before Any Backend Contract
Candidate direction:
- builtin names and metadata usage are validated at frontend scope per existing specs,
- and lowering emits deterministic outcomes or deterministic rejection.
### 2. Diagnostics Contract Is Mandatory For Frontend-Lowering Failures
Candidate direction:
- code/severity/primary attribution are fixed and test-backed for required rejection classes,
- enabling reliable regression protection.
### 3. Gate Evidence Is Small But Mandatory
Candidate direction:
- each required obligation has at least one positive and one negative fixture where applicable,
- with assertions for lexer/parser/AST/IRBackend/diagnostics.
### 4. Backend Topics Are Explicitly Deferred
Candidate direction:
- VM lowering, bytecode mapping, runtime, verifier, and loader remain out of this agenda,
- and are listed as deferred backlog topics.
## Questions To Resolve In The Room
1. Which builtin scenarios are mandatory in v1 fixture corpus?
2. Which lowering-related diagnostics are mandatory to freeze now?
3. What is the minimum evidence bar to declare `13` frontend slice closed?
4. Which open points are explicitly deferred without blocking frontend progress?
## Expected Outputs
1. a decision note on builtin frontend-lowering obligations,
2. a decision note on diagnostics/test evidence obligations,
3. and a closure checklist for `13` frontend scope.
## Explicit Deferrals
- VM lowering design,
- bytecode/PBX mapping,
- runtime execution contracts,
- verifier and loader internals.
## Inputs
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md`
@@ -1,113 +0,0 @@
# PBS Compatibility and Evolution Policy Agenda
Status: Active
## Purpose
Drive the closure of `17. Compatibility and Evolution Policy.md` so PBS can make explicit promises before implementation and release claims expand.
## Context
The current skeleton identifies the right policy areas, but it still leaves open:
- compatibility domains and windows,
- the separation between source, stdlib, artifact, and runtime compatibility,
- deprecation and removal duties,
- migration-tooling versus documentation-only obligations,
- and whether phased implementation claims need distinct compatibility labels.
This agenda should produce a policy that is strict enough to protect users and toolchains, while still allowing deliberate evolution.
## Decisions To Produce
1. Decide the compatibility domains PBS speaks about normatively.
2. Decide the compatibility promise and window for each domain.
3. Decide the deprecation and removal policy for source, stdlib, and artifact surfaces.
4. Decide when migration tooling is mandatory versus when written guidance is enough.
5. Decide whether phased implementation or conformance claims need distinct compatibility labels.
## Core Questions
1. What exact promise is made to old source code, published cartridges, stdlib consumers, and emitted artifacts?
2. Is PBX compatibility governed independently from source compatibility?
3. How do stdlib-line changes affect downstream dependency projects over time?
4. Which incompatible changes require migration tooling rather than only release notes?
5. How are compatibility claims constrained by conformance level and runtime line?
## Proposed Workshop Sequence
### Workshop 1: Compatibility Domains and Promise Levels
Purpose:
- define the domains PBS makes compatibility promises about,
- and decide the strength of each promise.
Expected decisions:
- source, stdlib, cartridge, artifact, and runtime domain boundaries,
- and behavioral versus binary compatibility split.
### Workshop 2: Deprecation, Removal, and Migration Duties
Purpose:
- close the lifecycle policy for changes that affect published users.
Expected decisions:
- deprecation windows,
- removal preconditions,
- and migration tooling versus documentation-only obligations.
### Workshop 3: Compatibility Matrices and Published Claims
Purpose:
- decide how compatibility claims are expressed across language line, stdlib line, runtime line, and conformance level.
Expected decisions:
- matrix shape,
- supported-line expectations,
- and alignment with `13`.
### Workshop 4: Artifact and PBX Compatibility Policy
Purpose:
- decide whether artifact compatibility has an independent policy track from source compatibility.
Expected decisions:
- PBX compatibility promise,
- runtime-loading compatibility boundaries,
- and obligations when the artifact line changes.
## Expected Spec Material
The resulting spec work should be able to add or close sections for:
- compatibility domains,
- compatibility windows and support lines,
- behavioral versus binary compatibility,
- deprecation and removal discipline,
- migration obligations,
- compatibility matrices across language, stdlib, and runtime lines,
- and labeling rules for partial or staged implementation claims.
## Non-Goals
- Defining one release calendar.
- Replacing governance with case-by-case exceptions.
- Treating every editorial clarification as a compatibility event.
- Designing product marketing labels.
## Inputs
- `docs/pbs/specs/1. Language Charter.md`
- `docs/pbs/specs/2. Governance and Versioning.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
@@ -1,97 +0,0 @@
# PBS Compatibility Workshop 1
Status: Active
## Purpose
Run the first focused discussion for `17. Compatibility and Evolution Policy.md` on the top-level policy model:
- which compatibility domains PBS recognizes,
- and what strength of promise applies to each.
## Why This Slice First
This slice should come first because every deprecation, migration, and matrix policy depends on a clean definition of domains and promise levels.
## Proposed Meeting Order
1. Reconfirm already-settled governance and versioning inputs.
2. Close the compatibility domains.
3. Close the promise level for each domain.
4. Close behavioral versus binary compatibility terminology.
5. Record migration and matrix issues for later workshops.
## Decisions To Produce
1. The compatibility domains PBS speaks about normatively.
2. The promise level for each domain.
3. The behavioral versus binary compatibility split.
4. The relationship between claim level and compatibility promise.
## Candidate Decisions
### 1. Recognize Separate Domains
Candidate direction:
- PBS should distinguish at least:
source compatibility,
stdlib compatibility,
cartridge/runtime compatibility,
artifact compatibility,
and conformance-claim compatibility.
Rationale:
- Different breakages affect different users and toolchains.
### 2. Promise Strength Differs By Domain
Candidate direction:
- source and published-cartridge behavior get the strongest promise,
- stdlib and artifact domains may have tighter line-based conditions,
- partial conformance claims get narrower promises than full ones.
Rationale:
- This avoids one vague compatibility slogan that means too many things.
### 3. Separate Behavioral From Binary Compatibility
Candidate direction:
- source-level and runtime-observable behavior compatibility is not the same as artifact binary compatibility,
- and the policy should state both explicitly.
Rationale:
- This prevents PBX policy from silently driving all evolution policy.
## Questions To Resolve In The Room
1. What are the minimum compatibility domains that PBS must name explicitly?
2. Which domains deserve the strongest guarantees?
3. Is cartridge compatibility mainly behavioral, binary, or both?
4. How does staged conformance affect compatibility promises?
5. Does stdlib compatibility belong as its own domain or inside source compatibility?
## Expected Outputs
1. a decision record for compatibility domains,
2. a promise-level matrix draft,
3. and terminology targets for `17`.
## Explicit Deferrals For Workshop 2
- deprecation windows,
- migration-tooling duties,
- and artifact-line change policy.
## Inputs
- `docs/pbs/specs/2. Governance and Versioning.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/decisions/Conformance Claim Levels Decision.md`
- `docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md`
@@ -1,94 +0,0 @@
# PBS Compatibility Workshop 2
Status: Active
## Purpose
Run the second focused discussion for `17. Compatibility and Evolution Policy.md` on lifecycle discipline:
- deprecation,
- removal,
- migration duties,
- and when tooling is mandatory versus documentation-only guidance.
## Why This Slice Second
This slice follows domain definition because the right deprecation and migration policy depends on what kind of surface is changing.
## Proposed Meeting Order
1. Reconfirm the compatibility domains and promise strengths from Workshop 1.
2. Close deprecation requirements by domain.
3. Close removal preconditions.
4. Close migration-tooling versus documentation obligations.
5. Record matrix consequences for Workshop 3.
## Decisions To Produce
1. Deprecation windows by domain.
2. Removal preconditions by domain.
3. Migration-tooling obligations.
4. The policy for changes that are incompatible but still deliberate.
## Candidate Decisions
### 1. Deprecation Must Precede Removal For User-Facing Stable Surfaces
Candidate direction:
- source and stdlib user-facing surfaces require explicit deprecation before removal,
- unless the change is confined to a new major line.
Rationale:
- This matches additive-first evolution goals.
### 2. Migration Tooling Is Required Only For High-Frequency Or High-Impact Breaks
Candidate direction:
- some incompatible changes require tooling,
- others may be served by precise migration notes,
- and the policy should name the factors that trigger tooling duty.
Rationale:
- This is more realistic than requiring tools for every break.
### 3. Removal Must Be Paired With An Announced Support Boundary
Candidate direction:
- removal is allowed only with a clearly documented support boundary and migration path or explanation.
Rationale:
- This makes policy operational rather than rhetorical.
## Questions To Resolve In The Room
1. Which domains require deprecation before removal?
2. What triggers mandatory migration tooling?
3. Can artifact-line changes skip deprecation if they stay behind a new major line?
4. How should deprecated stdlib APIs be tested in conformance while still supported?
5. When is documentation-only migration guidance enough?
## Expected Outputs
1. a decision record for deprecation policy,
2. a decision record for migration duties,
3. and lifecycle section targets for `17`.
## Explicit Deferrals For Workshop 3
- compatibility matrices,
- published-claim aging,
- and artifact compatibility line policy.
## Inputs
- `docs/pbs/specs/2. Governance and Versioning.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md`
@@ -1,107 +0,0 @@
# PBS Compatibility Workshop 3
Status: Decision recorded
## Purpose
Run the third focused discussion for `17. Compatibility and Evolution Policy.md` on support claims over time:
- compatibility matrices,
- supported combinations,
- published claims,
- and how those claims age or retire.
## Resolution Snapshot
This workshop direction is now recorded in:
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
Integrated spec follow-up belongs to:
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
## Why This Slice Third
This slice follows domain and lifecycle policy because matrix policy is where those choices become operational.
## Proposed Meeting Order
1. Reconfirm domain and lifecycle decisions from Workshops 1 and 2.
2. Close the shape of the compatibility matrix.
3. Close what counts as a published support claim.
4. Close how claims retire or narrow over time.
5. Record artifact-specific leftovers for Workshop 4.
## Decisions To Produce
1. The compatibility-matrix dimensions PBS must publish.
2. The policy for published support claims.
3. The relationship between claims, conformance, and regression.
4. The retirement policy for supported combinations.
## Candidate Decisions
### 1. Publish A Matrix Across The Major Compatibility Domains
Candidate direction:
- the matrix should cover at least:
language line,
stdlib line,
runtime line,
and conformance claim level.
Rationale:
- These are the main axes users will rely on.
### 2. Published Claims Must Be Backed By Conformance Or Regression Evidence
Candidate direction:
- support claims are not just prose;
- they must correspond to maintained test evidence where support is promised.
Rationale:
- This aligns policy with `13`.
### 3. Unsupported Combinations Must Be Explicit
Candidate direction:
- the matrix must allow explicit “unsupported” states rather than implying silence equals support.
Rationale:
- This reduces accidental ambiguity.
## Questions To Resolve In The Room
1. What exact axes belong in the official matrix?
2. Must every supported combination have conformance evidence?
3. How should experimental or provisional combinations be labeled?
4. When support is dropped, how is that reflected in the matrix and docs?
5. Which parts of this are policy versus test-harness detail?
## Expected Outputs
1. a decision record for the compatibility-matrix model,
2. a published-claims policy note,
3. and alignment tasks for `13`.
## Explicit Deferrals For Workshop 4
- PBX compatibility,
- binary-loading policy,
- and artifact-line changes.
## Inputs
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md`
- `docs/pbs/agendas/17.2. Compatibility Workshop 2 - Deprecation, Removal, and Migration Duties.md`
@@ -1,93 +0,0 @@
# PBS Compatibility Workshop 4
Status: Active
## Purpose
Run the fourth focused discussion for `17. Compatibility and Evolution Policy.md` on artifact compatibility:
- PBX compatibility,
- runtime-loading compatibility,
- and how artifact-line changes are versioned and promised.
## Why This Slice Last
This slice should come last because artifact policy is the most backend-dependent and should be informed by the broader domain and matrix decisions first.
## Proposed Meeting Order
1. Reconfirm the source, stdlib, cartridge, and matrix policy already chosen.
2. Decide whether artifact compatibility is an independent policy track.
3. Decide PBX and runtime-loading promise boundaries.
4. Decide how artifact-line changes are versioned and communicated.
5. Record final integration tasks for `17`, `15`, and `19`.
## Decisions To Produce
1. Whether artifact compatibility is independent from source compatibility.
2. The promise boundary for PBX and loader compatibility.
3. The versioning and communication policy for artifact-line changes.
4. The relationship between artifact policy and published cartridge support.
## Candidate Decisions
### 1. Artifact Compatibility Is A Distinct Policy Track
Candidate direction:
- PBX and emitted-artifact compatibility should be named explicitly rather than assumed from source compatibility.
Rationale:
- Binary and loader compatibility carry different risks and evolution constraints.
### 2. Runtime Loading Promise Must Be Stated By Supported Line
Candidate direction:
- artifact compatibility should be expressed against explicit runtime and artifact lines,
- not as a timeless blanket guarantee.
Rationale:
- This keeps the promise honest and testable.
### 3. Artifact-Line Breaks Require Explicit Version Signaling
Candidate direction:
- incompatible artifact changes require an explicit line or major-boundary signal,
- plus migration or tooling guidance when older published cartridges are affected.
Rationale:
- This aligns artifact evolution with the broader compatibility policy.
## Questions To Resolve In The Room
1. How strong should PBX compatibility promises be?
2. Are published cartridges protected mainly by source compatibility or by explicit artifact-line support?
3. What counts as an artifact compatibility break?
4. Must artifact-line changes always align with major language-version changes?
5. How should loader support boundaries be documented and tested?
## Expected Outputs
1. a decision record for artifact compatibility policy,
2. a PBX/runtime promise note,
3. and final section targets for `17`.
## Explicit Deferrals
- exact PBX layout details,
- exact loader algorithms,
- and binary test harness implementation.
## Inputs
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.md`
@@ -142,7 +142,7 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
## 12. Validation Notes
@@ -5,8 +5,8 @@ Cycle: Conformance agenda closure pass
Superseded by:
- `docs/pbs/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/19. Verification and Safety Checks Specification.md` (Quality-Gate Baseline)
Superseded on: 2026-03-04
@@ -84,7 +84,7 @@ This model is intentionally small. It is sufficient to prevent fake portability
The adopted boundary is:
- `13. Conformance Test Specification.md` defines which invariant families are pass/fail conformance obligations and which fixture assumptions must be declared;
- `12. IR and Lowering Specification.md` defines the semantic and artifact-boundary facts that lowering must preserve before loader or verifier work begins;
- `13. Lowering IRBackend Specification.md` defines the semantic and artifact-boundary facts that lowering must preserve before loader or verifier work begins;
- `15. Bytecode and PBX Mapping Specification.md` defines the PBX/bytecode-visible mapping of those facts into inspectable artifact surfaces;
- `19. Verification and Safety Checks Specification.md` defines the later validation and rejection obligations applied after lowering and, where relevant, after loader patching.
@@ -113,16 +113,16 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
It should also constrain later work in:
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
- `docs/pbs/agendas/12.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md`
- `docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md`
## 9. Validation Notes
@@ -5,8 +5,8 @@ Cycle: Conformance and compatibility agenda closure pass
Superseded by:
- `docs/pbs/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)
- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)
Superseded on: 2026-03-04
@@ -146,13 +146,13 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
It should also constrain later work in:
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md`
## 11. Validation Notes
@@ -5,8 +5,8 @@ Cycle: Conformance agenda closure pass
Superseded by:
- `docs/pbs/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)
- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)
Superseded on: 2026-03-04
@@ -146,14 +146,14 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
It should also constrain later work in:
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md`
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md`
@@ -198,11 +198,11 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
## 13. Validation Notes
@@ -331,7 +331,7 @@ This decision should feed at least:
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
The unresolved cost and retention wording for these surfaces should be completed through:
@@ -113,12 +113,12 @@ This decision should feed at least:
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md`
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
## 9. Validation Notes
@@ -117,8 +117,8 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
## 12. Validation Notes
@@ -108,7 +108,7 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/specs/3. Core Syntax Specification.md`
## 11. Validation Notes
@@ -121,19 +121,19 @@ Implementations may internally perform some of these checks during environment v
This decision record does not yet close:
- the full stdlib-surface policy of `18. Standard Library Surface Specification.md`,
- and the final lowering consequences in `12. IR and Lowering Specification.md`.
- and the final lowering consequences in `13. Lowering IRBackend Specification.md`.
## 11. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/18. Standard Library Surface Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/general/specs/18. Standard Library Surface Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## 12. Validation Notes
@@ -125,19 +125,19 @@ This decision record does not yet close:
- per-overload import syntax,
- aliasing policy for callable imports beyond the already-closed generic alias rules,
- and any lowering consequences in `12. IR and Lowering Specification.md`.
- and any lowering consequences in `13. Lowering IRBackend Specification.md`.
## 10. Spec Impact
This decision should feed at least:
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
## 11. Validation Notes
@@ -157,13 +157,13 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md`
- `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md`
- `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md`
@@ -212,13 +212,13 @@ This decision record does not yet close:
This decision should feed at least:
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
It should also constrain future work in:
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md`
- `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md`
- `docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md`
@@ -179,7 +179,7 @@ This decision should feed at least:
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
## 12. Validation Notes
+4 -4
View File
@@ -79,10 +79,10 @@ Before implementation starts, PBS must define at least:
4. Memory and Lifetime Specification.
5. Host ABI Binding Specification.
6. Module/Package Specification.
7. Diagnostics Specification.
8. IR and Lowering Specification.
9. Conformance Test Specification.
10. Compatibility and Evolution Policy.
7. AST Specification.
8. Diagnostics Specification.
9. Lowering IRBackend Specification.
10. Shared acceptance specs in `docs/general/specs` (Conformance, Compatibility, Verification).
## 11. Decision Rule
+105
View File
@@ -0,0 +1,105 @@
# PBS AST Specification
Status: Draft v0
Applies to: canonical AST contract emitted by PBS parser/frontend before IRBackend lowering
## 1. Purpose
This document defines the PBS AST contract used as the frontend boundary between syntax parsing and IRBackend lowering.
Its purpose is to keep AST behavior deterministic enough that:
- parser outputs are stable across implementations,
- diagnostics attribution remains source-anchored,
- and lowering to `IRBackend` starts from a predictable tree contract.
## 2. Scope
This document defines:
- minimum AST node families required for PBS v1 source forms,
- source-span attribution obligations for AST nodes,
- parser-output invariants consumed by static semantics and lowering,
- and AST-facing rejection boundaries for malformed syntax.
This document does not define:
- static-semantics type rules,
- VM/runtime execution behavior,
- bytecode/PBX mapping,
- or backend-specific IR/optimizer internals.
## 3. Authority and Precedence
Normative precedence:
1. `3. Core Syntax Specification.md`
2. `4. Static Semantics Specification.md`
3. `12. Diagnostics Specification.md`
4. `13. Lowering IRBackend Specification.md`
5. This document
If a rule here conflicts with higher-precedence syntax or semantic rules, the higher-precedence rule wins.
## 4. Normative Inputs
This document depends on:
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `12. Diagnostics Specification.md`
- `13. Lowering IRBackend Specification.md`
## 5. AST Contract Baseline
At minimum, parser output must provide:
1. one file/root node per parsed source file;
2. declaration nodes required by the active PBS syntax surface;
3. statement and expression nodes for accepted executable forms;
4. stable source attribution (`file`, `start`, `end`) on nodes used by diagnostics and lowering;
5. deterministic child ordering matching source-observable evaluation order.
## 6. Structural Invariants
Minimum structural invariants:
1. AST preserves declaration nesting and lexical block hierarchy from source.
2. Node spans are stable and must not overlap in impossible parent/child order.
3. Recovered parser output (after syntax errors) must remain internally consistent enough for additional diagnostics.
4. Unsupported syntax forms are rejected deterministically and must not be rewritten into semantically different valid AST shapes.
## 7. Diagnostics Integration
AST-related diagnostics must follow `12. Diagnostics Specification.md`:
- stable `diagnostic code`,
- stable `severity`,
- stable primary source attribution.
Parser/AST diagnostics are in `syntax` phase unless another higher-precedence rule assigns a different phase.
## 8. Conformance and Test Evidence
AST conformance evidence is provided through Gate U fixtures as defined in `docs/general/specs/13. Conformance Test Specification.md`.
At minimum, fixtures must cover:
1. representative valid AST shapes,
2. deterministic syntax rejection and recovery behavior,
3. stable source attribution for required diagnostics.
## 9. Non-Goals
- Defining one programming-language-neutral AST framework.
- Freezing one parser implementation architecture.
- Encoding runtime behavior in AST rules.
## 10. Exit Criteria
This document is healthy when:
1. required AST node families are explicit,
2. attribution and structural invariants are explicit,
3. deterministic AST-facing rejection classes are test-backed,
4. and lowering preconditions for `13` are unambiguous.
@@ -47,7 +47,7 @@ Normative precedence:
6. `7. Cartridge Manifest and Runtime Capabilities Specification.md`
7. `9. Dynamic Semantics Specification.md`
8. `10. Memory and Lifetime Specification.md`
9. `12. IR and Lowering Specification.md`
9. `13. Lowering IRBackend Specification.md`
10. This document
If a diagnostic rule here contradicts a normative acceptance/rejection rule in a higher-precedence document, the higher-precedence document wins.
@@ -63,13 +63,13 @@ This document depends on, at minimum:
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
- `12. IR and Lowering Specification.md`
- `13. Lowering IRBackend Specification.md`
Relevant backend-facing integration points also include:
- `15. Bytecode and PBX Mapping Specification.md`
- `16. Runtime Execution and Initialization Specification.md`
- `19. Verification and Safety Checks Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
## 5. Already-Settled Inputs
@@ -1,156 +0,0 @@
# PBS IR and Lowering Specification
Status: Draft v0 (Skeleton)
Applies to: lowering of bound PBS programs into internal compiler IR and runtime-facing artifacts
## 1. Purpose
This document will define the normative lowering contract from PBS source semantics to implementation artifacts.
Its purpose is to make backend-facing behavior explicit enough that:
- different compilers lower the same bound program compatibly,
- host-binding emission does not drift from frontend resolution,
- builtin and intrinsic lowering does not drift from VM-owned metadata,
- later verifier and loader behavior can rely on stable artifact expectations,
- conformance can test more than parser and binder behavior.
## 2. Scope
This document is intended to define:
- the minimum semantic obligations of the compiler after parsing, binding, and type checking,
- the role of internal IR as an implementation stage,
- what semantic facts lowering must preserve,
- lowering of control flow, calls, callbacks, services, contracts, constants, and host-backed calls,
- lowering of builtin projections, builtin constants, and intrinsic member calls,
- artifact-facing requirements that must hold before loader/verifier consumption.
This document does not define:
- the full PBX binary layout,
- optimizer heuristics or performance tuning strategy,
- the exact in-memory data structures of one compiler implementation,
- runtime GC algorithm internals.
## 3. Authority and Precedence
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`)
3. `3. Core Syntax Specification.md`
4. `4. Static Semantics Specification.md`
5. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
6. `6. VM-owned vs Host-backed.md`
7. `6.1. Intrinsics and Builtin Types Specification.md`
8. `6.2. Host ABI Binding and Loader Resolution Specification.md`
9. `9. Dynamic Semantics Specification.md`
10. `10. Memory and Lifetime Specification.md`
11. This document
If a lowering rule here contradicts a higher-precedence semantic rule, the higher-precedence rule wins.
## 4. Normative Inputs
This document depends on, at minimum:
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `6. VM-owned vs Host-backed.md`
- `6.1. Intrinsics and Builtin Types Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
This document is expected to close in coordination with `15. Bytecode and PBX Mapping Specification.md` and `16. Runtime Execution and Initialization Specification.md`.
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- The compiler consumes reserved `Host` metadata while resolving host-backed SDK members.
- The compiler consumes reserved `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, and `Slot` metadata while resolving builtin shells.
- The compiler emits canonical host-binding declarations into the PBX `SYSC` table.
- The compiler emits host-backed callsites in pre-load form as `HOSTCALL <sysc_index>`.
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
- The loader, not the compiler, resolves canonical host bindings to final numeric syscall identifiers.
- Builtin projection lowering remains VM-owned and does not emit host-binding metadata.
- Builtin constants lower through VM-owned materialization rather than through ordinary compile-time constant evaluation.
- Builtin intrinsic member calls lower through a VM-owned intrinsic path rather than through `SYSC`, `HOSTCALL`, or `SYSCALL`.
- Stdlib interface modules are compile-time-only and do not emit executable bytecode by themselves.
- Backend-originated failures only enter the PBS-facing diagnostics contract when they remain source-attributable and user-actionable.
## 6. Current Lowering and Artifact Boundary Baseline
The current backend-facing division of responsibility is:
- this document defines what semantic and artifact-boundary facts lowering must preserve before verifier or loader validation,
- `15. Bytecode and PBX Mapping Specification.md` defines how those facts appear in PBX/bytecode-visible form,
- and `19. Verification and Safety Checks Specification.md` defines which later safety and validity checks are applied after lowering and, where relevant, after loader patching.
At minimum, the current lowering baseline requires:
1. admitted host-backed uses lower to canonical host-binding declarations and pre-load call references rather than to resolved syscall identifiers;
2. canonical host-binding declarations remain deduplicated by canonical identity and ordered by first occurrence;
3. VM-owned builtin projections, builtin constants, and intrinsic callsites remain outside host-binding metadata surfaces;
4. stdlib interface modules remain compile-time-only and do not emit executable bytecode by themselves;
5. lowering preserves enough attribution metadata that at least one source location can later be recovered for backend failures that remain source-attributable and user-actionable.
This document defines those obligations as preserved facts, not as one exact PBX encoding.
## 7. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. lowering preconditions,
2. semantic obligations preserved by IR,
3. lowering of expressions and control flow,
4. lowering of callable categories,
5. lowering of `optional` and `result<E>` constructs,
6. lowering of callbacks, services, and contracts,
7. lowering of builtin projections, builtin constants, and builtin intrinsic calls,
8. host-binding emission,
9. artifact invariants required before verifier/loader stages.
## 8. TODO
The following items remain to be closed before this document can be considered complete.
### 8.1 Depends on `9. Dynamic Semantics Specification.md`
- Which evaluation-order guarantees must be preserved explicitly in lowering.
- Which traps, abrupt completions, and propagation paths require dedicated lowered forms.
- Whether callback formation and contract dispatch need dedicated runtime artifacts or only implementation-defined IR shapes.
### 8.2 Depends on `10. Memory and Lifetime Specification.md`
- Which lowered operations allocate, alias, retain, or cross the host-memory boundary.
- Which runtime storage/identity facts IR must preserve explicitly versus infer later.
### 8.3 Still open across this document and adjacent backend-facing specs
- Whether one canonical IR is normative or only the preserved semantic obligations are normative.
- The exact mapping from bound PBS constructs to PBX/bytecode-facing artifacts beyond already-settled host-binding and intrinsic behavior.
- Lowering strategy for services, contracts, callbacks, tuples, and result propagation.
- Whether declaration-based intrinsic preload forms such as `INTRCALL` are part of v1 lowering or whether compilers should emit final `INTRINSIC <id>` directly for a selected VM line.
- Which additional artifact invariants beyond the current conformance baseline belong here versus in `15`.
- Which richer attribution/debug hooks, if any, should be added beyond the minimum one-location recovery baseline already required for in-scope backend failures.
## 9. Non-Goals
- Freezing one optimizer design.
- Requiring one compiler implementation architecture.
- Repeating the full bytecode ISA specification.
- Defining loader-side patching internals already owned elsewhere.
## 10. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. every semantically distinct core construct has an explicit lowering story,
2. the boundary between source semantics, compiler IR, and emitted artifacts is clear,
3. host-binding emission is fully aligned with the Host ABI spec,
4. builtin and intrinsic lowering is fully aligned with the VM-owned builtin spec,
5. the document no longer relies on unresolved backend `TODO` items for ordinary v1 lowering behavior.
@@ -1,129 +0,0 @@
# PBS Conformance Test Specification
Status: Draft v1 (Quality-Gate Baseline)
Applies to: executable quality gates for PBS language frontends and language-level regression evidence
## 1. Purpose
This document defines the minimum quality-gate contract for PBS language implementations.
The goal is practical and test-driven:
- keep quality measurable while language, lowering, and runtime integration are still evolving,
- require only gates that can be proved with tests today,
- avoid freezing speculative backend policy too early.
## 2. Scope
This document defines:
- required unit-test gates for language frontend work,
- required regression gate behavior for published language behavior,
- and the boundary for runtime integration regression tests when a backend can emit executable artifacts.
This document does not define:
- runtime semantics or VM behavior taxonomy,
- full artifact-level compatibility matrices,
- one test harness layout,
- or one repository structure for fixtures.
## 3. Authority and Precedence
Normative precedence:
1. `1. Language Charter.md`
2. `2. Governance and Versioning.md`
3. `3. Core Syntax Specification.md`
4. `4. Static Semantics Specification.md`
5. `11. Diagnostics Specification.md`
6. `12. IR and Lowering Specification.md`
7. This document
This document must not weaken normative requirements from higher-precedence specs.
## 4. Normative Inputs
This document depends on:
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `11. Diagnostics Specification.md`
- `12. IR and Lowering Specification.md`
- `17. Compatibility and Evolution Policy.md`
## 5. Quality Gate Model
PBS v1 uses two practical gate families.
### 5.1 Gate U: Language Unit Quality Gate (Required)
Every language frontend integrated into Studio/compiler must have passing unit tests that cover, at minimum:
1. lexer behavior (valid tokenization and deterministic lexical rejection),
2. parser behavior (valid parse and deterministic syntax rejection),
3. AST shape for representative valid programs,
4. frontend-to-IR backend emission (`IRBackend`/`IRBackendFile`) for representative valid programs,
5. diagnostics surface for required rejection cases (`code`, `severity`, and primary attribution).
This gate is mandatory for each language regardless of backend maturity.
### 5.2 Gate I: Integration Regression Gate With Runtime (Conditional)
When a language backend can emit executable artifacts (for example bytecode), integration regression tests must be introduced for that language.
At minimum, those tests must:
1. compile selected fixtures through the executable pipeline for that language,
2. execute them against the runtime line declared for that backend,
3. assert deterministic observable outcomes for supported fixtures,
4. and preserve fixed bugs and published supported examples as regression tests.
Until executable artifact emission exists for a language, Gate I is explicitly `deferred` for that language and does not block frontend progress.
## 6. Regression Policy
Published supported behavior must remain regression-protected.
At minimum, each language corpus must retain:
1. bug reproductions for fixes that remain in supported scope,
2. published supported examples,
3. and core gate fixtures required to justify the language support state.
Regression grouping by language is expected; one shared monolithic corpus is not required.
## 7. Claims and Evidence
For PBS quality claims at this stage:
- a language may be considered `frontend-ready` only with Gate U passing,
- a language may be considered `integration-ready` only with Gate U and Gate I passing where Gate I applies,
- and a published support claim must map to executable evidence from these gates.
The exact publication vocabulary is owned by `17. Compatibility and Evolution Policy.md`.
## 8. Explicit Deferrals
The following are intentionally deferred until backend/runtime contracts stabilize further:
- detailed artifact-level conformance taxonomy,
- verifier-facing conformance taxonomy,
- full compatibility matrix axes beyond the current minimum support table,
- and one mandatory fixture repository layout.
## 9. Non-Goals
- Replacing normative language specs with tests.
- Defining runtime semantics in this document.
- Freezing backend architecture decisions prematurely.
- Treating performance benchmarks as conformance gates.
## 10. Exit Criteria
This document is in a healthy state when:
1. every active language has an explicit Gate U status,
2. languages with executable backends have an explicit Gate I status,
3. published supported language behavior has regression evidence,
4. and no support claim exists without mapped test evidence.
@@ -0,0 +1,109 @@
# PBS Lowering IRBackend Specification
Status: Draft v1 (Frontend Scope)
Applies to: first lowering boundary from bound PBS frontend model into `IRBackend`/`IRBackendFile`
## 1. Purpose
This document defines the normative frontend lowering contract from PBS source semantics to `IRBackend`.
Its purpose is to keep the first lowering deterministic and shared across implementations while PBS and backend design evolve.
## 2. Scope
This document defines:
- required preconditions before lowering starts,
- semantic obligations preserved in `IRBackend`,
- deterministic rejection behavior for unsupported frontend-lowering forms,
- and diagnostics attribution obligations for lowering failures in frontend scope.
This document does not define:
- VM lowering (`IRVM`),
- bytecode/PBX mapping,
- runtime execution behavior,
- verifier/loader internals.
Those concerns belong to shared acceptance specs under `docs/general/specs`.
## 3. Authority and Precedence
Normative precedence:
1. `3. Core Syntax Specification.md`
2. `4. Static Semantics Specification.md`
3. `11. AST Specification.md`
4. `12. Diagnostics Specification.md`
5. This document
If a lowering rule here conflicts with higher-precedence syntax/semantics rules, the higher-precedence rule wins.
## 4. Normative Inputs
This document depends on:
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `11. AST Specification.md`
- `12. Diagnostics Specification.md`
## 5. Lowering Preconditions
Frontend lowering into `IRBackend` may start only when:
1. source has been tokenized and parsed,
2. required syntax diagnostics have been emitted,
3. linking/name-resolution outcomes required for the current lowering slice are available,
4. and no unresolved semantic ambiguity is deferred to lowering.
Lowering must not invent unresolved semantic answers that belong to syntax/static/linking phases.
## 6. IRBackend Preserved Obligations
For each callable admitted by the current lowering slice, `IRBackend` must preserve at minimum:
1. callable identity (name/category as applicable),
2. callable arity,
3. declared return surface information,
4. source attribution anchor (`file + span`) for diagnostics and traceability.
The normative contract is obligation-based, not tied to one mandatory in-memory class graph.
## 7. Deterministic Rejection Policy
If a source form is outside current frontend-lowering support:
1. rejection must be deterministic,
2. diagnostics must expose stable `code`, `severity`, and primary attribution,
3. and unsupported forms must not silently degrade into different valid lowered behavior.
## 8. Conformance Boundary
`IRBackend` is the first lowering boundary (frontend responsibility).
Conformance-valid claims at this boundary require evidence from `docs/general/specs/13. Conformance Test Specification.md` and must only be published when the full claimed PBS surface is implemented at `IRBackend` level.
## 9. Explicit Deferrals
The following are intentionally out of scope for this document:
- `IRBackend -> IRVM` lowering,
- artifact encoding and binary layout,
- runtime lifecycle behavior,
- verifier and loader checks.
## 10. Non-Goals
- Freezing one optimizer strategy.
- Freezing one compiler architecture.
- Repeating runtime or bytecode authority.
## 11. Exit Criteria
This document is healthy when:
1. lowering preconditions are explicit,
2. preserved `IRBackend` obligations are explicit,
3. deterministic rejection policy is explicit and test-backed,
4. and scope boundaries with general/backend acceptance specs are explicit.
@@ -1,405 +0,0 @@
# PBS Name Resolution and Module Linking Specification
Status: Draft v1 (Normative)
Applies to: scope formation, name lookup, imports, exports, barrel visibility, cross-module resolution, and semantic linking of PBS programs
## 1. Purpose
This document defines the normative name-resolution and semantic-linking model for PBS v1.
Its purpose is to make the visible declaration space of a PBS program deterministic enough that:
- frontend implementations do not invent lookup or collision rules,
- diagnostics can classify failures consistently,
- conformance can test source-facing rejection classes,
- and lowering begins from an already-linked visible program.
## 2. Scope
This document defines:
- module scope construction,
- lookup order by namespace,
- import and alias resolution,
- barrel-mediated visibility,
- reserved stdlib shell resolution for builtin and host-backed surfaces,
- callable visibility across modules,
- and linking-time rejection conditions before lowering.
This document does not define:
- runtime execution behavior,
- optimizer or backend internals,
- full PBX binary linking,
- or loader/runtime artifact behavior after lowering.
## 3. Authority and Precedence
Normative precedence:
1. `3. Core Syntax Specification.md`
2. `4. Static Semantics Specification.md`
3. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
4. `6. VM-owned vs Host-backed.md`
5. `6.1. Intrinsics and Builtin Types Specification.md`
6. `6.2. Host ABI Binding and Loader Resolution Specification.md`
7. `8. Stdlib Environment Packaging and Loading Specification.md`
8. `18. Standard Library Surface Specification.md`
9. This document
If a rule here conflicts with higher-precedence specs, it is invalid.
## 4. Normative Inputs
This document depends on, at minimum:
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `6. VM-owned vs Host-backed.md`
- `6.1. Intrinsics and Builtin Types Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `8. Stdlib Environment Packaging and Loading Specification.md`
- `18. Standard Library Surface Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- PBS has distinct type, value, callable, and host-owner namespaces.
- `mod.barrel` is the single source of module visibility.
- Imports target modules, not files.
- Reserved stdlib project spaces are resolved only from the selected stdlib environment.
- Only `pub` symbols may be imported from another module.
- Reserved stdlib/interface modules may expose compile-time-only shells for both host-backed and VM-owned surfaces.
- Source-visible builtin names are resolved through imported builtin shell declarations rather than by hardcoded source spelling alone.
- Canonical builtin identity and canonical intrinsic identity are governed by builtin metadata rather than by the imported PBS-visible declaration name alone.
- Canonical host identity is governed by host metadata rather than by imported owner spelling alone.
## 6. Module Scope Construction
### 6.1 Module collection
For one module:
- the compiler collects top-level declarations from all `.pbs` files in that module,
- forms one module-level declaration space,
- and only then applies `mod.barrel` to determine `mod` and `pub` visibility.
Rules:
- declaration existence is not derived from barrel entries,
- module-internal top-level declaration availability does not depend on source-file order,
- and `mod.barrel` is a visibility filter over existing declarations rather than a declaration source.
### 6.2 Lexical scope
Inside executable bodies:
- lexical block scope nests normally over module scope,
- nearest local bindings win within value lookup,
- and lexical nesting remains independent from cross-module visibility.
## 7. Lookup Order By Namespace
Lookup in PBS remains namespace-based.
### 7.1 Value position
Value-position lookup follows this order:
1. nearest local lexical bindings,
2. parameters in the current lexical function scope,
3. visible module-local values,
4. visible imported values.
For lookup purposes, parameters and local `let` bindings participate in one nearest lexical value layer.
### 7.2 Type position
Type-position lookup follows this order:
1. visible module-local type declarations,
2. visible imported type declarations,
3. builtin simple types `int`, `float`, `bool`, and `str` as always-available reserved type names.
Builtin simple types:
- are not treated as ordinary imported declarations,
- do not participate in ordinary import competition,
- and remain always available without import.
### 7.3 Callable position
Callable-position lookup follows this order:
1. visible module-local callables,
2. visible imported callables.
Callable lookup operates only on already-formed visible callable sets as defined later in this document.
### 7.4 Host-owner position
Host-owner lookup follows this order:
1. visible module-local host owners,
2. visible imported host owners.
Host-owner lookup remains separate from type, value, and callable lookup.
## 8. Import Surface And Naming
### 8.1 Effective local imported name
The local visible name introduced by an import is always the post-alias name when an alias is present.
Rules:
- `import { X } from @project:path;` introduces the visible local name `X`,
- `import { X as Y } from @project:path;` introduces only the visible local name `Y`,
- and alias spelling changes only the local visible name, never canonical builtin identity or canonical host identity.
### 8.2 Named import
`import { X } from @project:path;`:
- resolves the target module,
- checks that `X` is exported and importable from that module,
- and introduces `X` into the corresponding namespace locally.
### 8.3 Whole-module import
`import { * } from @project:path;`:
- resolves the target module,
- introduces the target module's exported visible names under their exported spellings,
- but does not create a module-valued binding,
- does not create a namespace object,
- and does not authorize qualified member access by itself.
If PBS later wants module-object or namespace-qualified source semantics, that must be added explicitly rather than inferred from this import form.
## 9. Collision And Ambiguity Rules
### 9.1 Local versus imported
If a module-local declaration and an imported declaration produce the same visible name in the same namespace:
- the program is rejected,
- and the implementation must not silently shadow either declaration.
This includes function names.
A module-local function and an imported function with the same visible name are rejected rather than merged.
### 9.2 Imported versus imported
If two imports produce the same visible name in the same namespace:
- the program is not rejected only when both imports resolve to the same canonical underlying declaration after module resolution,
- such same-origin duplication is redundant but tolerated,
- and the program is rejected if the imports resolve to different canonical underlying declarations.
### 9.3 Namespace separation
Names in different namespaces do not collide merely by spelling.
For example:
- a host owner and a type declaration do not collide by spelling alone,
- because host-owner namespace remains distinct from type namespace.
### 9.4 Non-callable names do not merge
Non-callable namespaces do not merge by name.
## 10. Callable Sets And Cross-Module Linking
### 10.1 Imported callable set
`import { f } from @project:path;` imports the exported callable set named `f` from the target module.
Rules:
- the imported callable set for `f` consists only of those overload signatures of `f` that are exported through that module's `mod.barrel`,
- non-exported overloads in the target module do not participate in the imported callable set,
- and import operates on the exported callable name rather than on one overload at a time.
### 10.2 Same-origin versus different-origin callable imports
If the same visible callable name is imported more than once:
- same-origin duplicate imports are tolerated as redundancy when they resolve to the same canonical callable-set origin,
- different-origin imports are rejected immediately,
- and the implementation must not wait until a callsite to reject different-origin callable-name collisions.
### 10.3 Local versus imported callable names
If a module-local function name and an imported function name are the same visible callable name:
- the program is rejected immediately,
- and the implementation must not merge the local and imported callable sets.
### 10.4 Overload-resolution boundary
PBS separates:
- callable-set formation,
- and overload resolution at a callsite.
Rules:
- the implementation must first form one unambiguous visible callable set,
- only then may ordinary overload resolution operate on the candidate signatures of that set,
- and callsite context must not be used to resolve ambiguity between different imported callable origins.
## 11. Reserved Stdlib Shell Resolution
### 11.1 Reserved shells as imported declarations
Source-visible declarations exposed by reserved builtin shells are imported into their ordinary corresponding namespaces.
This means:
- builtin-exposed types enter type lookup as imported type declarations,
- builtin-exposed constants enter value lookup as imported values,
- and host owners enter host-owner lookup as imported host-owner declarations.
`declare builtin type` itself remains a reserved stdlib/toolchain declaration form rather than ordinary user-authored source syntax.
### 11.2 Builtin simple types versus imported builtin shells
PBS distinguishes:
- the predeclared builtin simple-type set `int`, `float`, `bool`, `str`,
- and imported builtin shells such as `Vec2` or `Color`.
Imported builtin shells are not promoted to the same always-available status as builtin simple types.
### 11.3 Intrinsic member lookup
Builtin intrinsic methods:
- never participate in free lookup,
- are not introduced by import as free functions,
- and are resolved only through member lookup on a receiver already known to have the corresponding builtin type.
Alias changes to the imported builtin type affect only the local visible owner spelling, not the canonical builtin or intrinsic identity.
### 11.4 Collision policy for reserved shells
Reserved builtin shells and host owners follow the same collision policy as ordinary imported declarations.
Rules:
- same visible name in the same namespace is an error unless another already-closed rule explicitly permits otherwise,
- reserved-shell status does not authorize silent shadowing,
- and host owners do not collide with types or values merely by spelling because host-owner namespace remains separate.
### 11.5 Reserved project-space policy
For source-level policy:
- builtin shells are preferred under `@core:*`,
- and host-facing capability surfaces remain the natural fit for `@sdk:*`.
### 11.6 Canonical identity
Canonical builtin identity and canonical host identity are not derived from local alias spelling.
Duplicate canonical builtin identities or duplicate canonical host identities in one resolved environment are rejected as linking failures.
## 12. Linking Phase Boundary And Deterministic Failures
### 12.1 Normative phase baseline
PBS v1 adopts the following normative phase baseline for name resolution and related frontend failures:
1. `syntax`
2. `manifest/import resolution`
3. `linking`
4. `static semantics`
### 12.2 Syntax
`syntax` owns malformed import grammar and other token-shape or grammar-shape failures.
### 12.3 Manifest and import resolution
`manifest/import resolution` owns failures to resolve:
- project space,
- reserved stdlib space,
- dependency graph target,
- module path,
- or environment source.
### 12.4 Linking
`linking` owns assembly of visible declarations across files and modules.
At minimum, `linking` owns:
1. import of non-exported names,
2. unresolved barrel entries against module declarations,
3. collisions between visible imported names from different canonical origins,
4. local-versus-import visibility collisions,
5. callable-origin conflicts across module boundaries,
6. duplicate canonical builtin identities in one resolved environment,
7. duplicate canonical host identities in one resolved environment.
### 12.5 Static semantics
`static semantics` owns:
1. duplicate local declarations,
2. declaration validity,
3. type checking,
4. member lookup once the receiver type is known,
5. overload resolution within an already-formed visible callable set.
Member lookup failure on an already-typed builtin receiver therefore belongs to `static semantics`.
### 12.6 Imported-origin conflicts are rejected before callsite analysis
Conflicts between different imported origins are rejected in `linking` immediately.
The implementation must not:
- wait for a specific callsite,
- use overload resolution to rescue imported-origin ambiguity,
- or defer visible declaration conflicts to later typing work.
## 13. Deterministic Resolution Failures
At minimum, a conforming implementation must reject:
1. import of a non-exported builtin type shell,
2. import of a non-exported builtin constant shell,
3. import of a non-exported host owner shell,
4. import of any non-exported name from a resolved module,
5. unresolved barrel entries against module declarations,
6. local-versus-import same-namespace collisions,
7. imported same-name collisions from different canonical origins,
8. local-versus-import function-name collisions,
9. duplicate visible builtin type declarations that claim the same canonical builtin identity in one resolved environment,
10. duplicate visible builtin constants that claim the same canonical builtin constant identity in one resolved environment,
11. duplicate visible host owners that claim the same canonical host identity in one resolved environment,
12. member lookup on a builtin receiver where the imported builtin shell does not declare the requested field or intrinsic member,
13. any resolution path that attempts to derive host or builtin canonical identity from alias spelling alone.
## 14. Non-Goals
- Reopening the already-settled import surface syntax.
- Defining runtime loader behavior.
- Freezing one compiler symbol-table implementation.
- Freezing one internal compiler pass graph.
## 15. Exit Criteria
This document is ready to move beyond its current draft status only when:
1. name lookup is deterministic across all relevant scopes,
2. barrel and module linking behavior is explicit,
3. reserved stdlib shell resolution is explicit for host-backed and VM-owned surfaces,
4. cross-module callable visibility and ambiguity behavior are normatively defined,
5. and the phase ownership of source-facing name-resolution failures is explicit enough for diagnostics and conformance.
@@ -1,114 +0,0 @@
# PBS Bytecode and PBX Mapping Specification
Status: Draft v0 (Skeleton)
Applies to: mapping from lowered PBS programs into PBX sections, bytecode-facing artifacts, and related source-to-artifact invariants
## 1. Purpose
This document will define the normative mapping between lowered PBS semantics and emitted PBX/bytecode-facing artifacts.
## 2. Scope
This document is intended to define:
- artifact-level obligations after lowering,
- mapping of semantic constructs into PBX-visible structures,
- source-to-artifact invariants required by verifier and loader stages,
- interaction points with host-binding metadata such as `SYSC`,
- interaction points with VM-owned builtin and intrinsic metadata.
This document does not define:
- the full bytecode ISA,
- UI/tooling presentation,
- one compiler's internal IR representation.
## 3. Authority and Precedence
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`)
3. `6.1. Intrinsics and Builtin Types Specification.md`
4. `6.2. Host ABI Binding and Loader Resolution Specification.md`
5. `12. IR and Lowering Specification.md`
6. This document
If a rule here conflicts with higher-precedence authorities, it is invalid.
## 4. Normative Inputs
This document depends on, at minimum:
- `6.1. Intrinsics and Builtin Types Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `12. IR and Lowering Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- The compiler emits host-binding declarations into PBX `SYSC`.
- Host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>`.
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
- The loader resolves host bindings and rewrites `HOSTCALL` into `SYSCALL`.
- VM-owned builtin projections, builtin constants, and intrinsic callsites do not emit host-binding metadata.
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
- V1 source-attribution hooks for diagnostics/conformance need only support recovery of at least one source location for source-attributable backend failures; one exact source-map format is not yet required.
## 6. Current Conformance-Facing Mapping Baseline
The current boundary across backend-facing specs is:
- `12. IR and Lowering Specification.md` defines what facts must be preserved by lowering,
- this document defines how the PBS-facing artifact facts appear in PBX/bytecode-visible form,
- and `19. Verification and Safety Checks Specification.md` defines later validity checks after the artifact is formed and, where relevant, patched by the loader.
The current conformance-facing artifact baseline is invariant-based.
At minimum, the PBS-facing artifact contract currently includes:
1. canonical host-binding declarations in `SYSC` for admitted host-backed uses;
2. `SYSC` deduplication by canonical identity and ordering by first occurrence;
3. host-backed callsites emitted in pre-load form as `HOSTCALL <sysc_index>`;
4. no host-binding metadata emission for VM-owned builtin projections, builtin constants, or intrinsic callsites;
5. no executable bytecode emission for stdlib interface modules by themselves;
6. enough source-attribution information to recover at least one source location for backend failures that remain in the PBS-facing diagnostics/conformance surface.
This baseline does not require one full-image PBX golden.
## 7. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. artifact mapping goals,
2. section-level invariants,
3. callsite and control-flow mapping invariants,
4. metadata mapping obligations,
5. intrinsic and builtin artifact obligations,
6. source-attribution hooks for diagnostics/conformance.
## 8. TODO
The following items remain to be closed in future agenda discussion.
- Which PBX sections beyond `SYSC` are part of the PBS-facing contract.
- Whether a distinct intrinsic declaration section is part of the PBS-facing contract in v1.
- Which source-level constructs require dedicated artifact patterns versus implementation freedom.
- How much of artifact ordering, numbering, and layout is normative at PBS level versus owned purely by PBX authority.
- Whether compilers should emit final `INTRINSIC <id>` directly for a selected VM line or may emit a declaration-based preload form such as `INTRCALL <decl_index>`.
- Which richer debug/source-map surfaces, if any, are added beyond the minimum attribution hooks already sufficient for v1 diagnostics and conformance.
## 9. Non-Goals
- Repeating the full PBX or ISA documentation.
- Mandating one binary-emitter implementation strategy.
- Defining loader patching internals already owned elsewhere.
## 10. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. the PBS-to-artifact boundary is explicit,
2. artifact-level invariants needed by verifier and loader are normative,
3. the document no longer relies on unresolved `TODO` items for ordinary v1 artifact mapping behavior.
@@ -1,155 +0,0 @@
# PBS Runtime Execution and Initialization Specification
Status: Draft v1 (Temporary)
Applies to: runtime startup, entry behavior, module/service initialization, and execution lifecycle of PBS programs after successful load
## 1. Purpose
This document defines the PBS-visible runtime entry and execution-lifecycle contract after successful artifact load.
Its purpose is to keep runtime startup, frame-driven execution, and fatal-failure behavior aligned with:
- runtime authority,
- dynamic semantics,
- memory/lifetime guarantees,
- and the closed capability-gated host model.
## 2. Scope
This document defines:
- when PBS program execution may begin,
- which preconditions must already hold before userland runs,
- the runtime execution model of a loaded PBS program instance,
- the only normative frame/safepoint boundary in v1,
- and which startup or fatal-failure outcomes are PBS-visible.
This document does not define:
- loader-side host resolution details,
- the full packaging or process model,
- scheduler models outside the v1 single-threaded execution contract,
- shutdown/finalization APIs or hooks,
- or subsystem-specific host resource lifecycles.
## 3. Authority and Precedence
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. `1. Language Charter.md`
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
4. `9. Dynamic Semantics Specification.md`
5. `10. Memory and Lifetime Specification.md`
6. This document
If a rule here conflicts with higher-precedence authorities, it is invalid.
## 4. Normative Inputs
This document depends on, at minimum:
- `1. Language Charter.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- `FRAME_SYNC`-based execution semantics are preserved.
- Loader-side host binding resolution and capability gating happen before program execution begins.
- A PBS program instance executes single-threaded in v1.
- Dynamic semantics are deterministic at the language-observable level.
- Any runtime trap aborts PBS program execution and enters the runtime/firmware crash path rather than a userland recovery path.
- Service values are canonical module-owned singleton values.
- Top-level executable statements are forbidden in PBS source modules.
## 6. Runtime Entry Preconditions
PBS userland execution may begin only after all of the following are true:
1. the program artifact has been accepted by the relevant runtime/load authority,
2. capability gating and host-binding resolution required for startup have completed successfully,
3. runtime state required to begin frame-driven execution has been established,
4. and no prior fatal startup failure has occurred.
If these preconditions are not satisfied, ordinary PBS userland execution does not begin.
This document does not define loader-internal sequencing in detail; it only defines that the userland-visible start boundary occurs after successful load- and capability-level admission.
## 7. Program Instance Model
Each loaded PBS program executes as one single-threaded program instance in v1.
Within a program instance:
- userland execution is not concurrently interleaved by another userland thread,
- the dynamic-semantics evaluation order defined in `9. Dynamic Semantics Specification.md` remains authoritative,
- and runtime/host activity must not perturb that language-level sequencing.
PBS source modules do not contribute a user-authored top-level execution phase. Any startup activity that exists outside ordinary function/method execution is runtime-owned unless and until another specification makes a narrower PBS-visible contract explicit.
## 8. Frame Boundary and Host Work
`FRAME_SYNC` is the only normative runtime step boundary and the only normative safepoint in PBS v1.
Consequences:
- the runtime may use the interval around `FRAME_SYNC` to process host-side demands and internal work,
- userland execution must remain semantically ordered as defined by `9. Dynamic Semantics Specification.md`,
- and PBS user code cannot rely on any other boundary as a guaranteed safepoint, collection point, or scheduling point.
Internal runtime work may exist outside `FRAME_SYNC`, but it must remain semantically invisible to PBS userland unless a higher-precedence authority explicitly defines otherwise.
## 9. Failure and Non-Start Conditions
PBS distinguishes between two broad classes of failure at this layer:
1. non-start conditions, where userland never begins because artifact admission, capability checks, or required startup preconditions fail;
2. fatal runtime traps, where an already-running PBS program aborts.
Traps are not recoverable in PBS userland. When a trap occurs:
- it does not enter `result` flow,
- it is not intercepted by `handle`,
- and it aborts the PBS program execution path into the runtime/firmware crash path.
This document does not define a userland-visible trap catalog.
## 10. Service and Module Initialization Boundaries
The current v1 baseline is intentionally narrow:
- service values are canonical singleton values,
- top-level executable statements do not exist,
- and no userland-visible module-initialization statement phase is defined here.
The exact timing at which service-owned runtime state becomes initialized and observable remains an open item for this document. Until that is closed, implementations must not infer extra userland-visible initialization hooks beyond what is already guaranteed by higher-precedence specs.
## 11. TODO
The following items remain open for later closure:
- the exact runtime entry contract between successful load and first userland-observable execution,
- whether service-owned runtime state has a more precise initialization point than the baseline stated here,
- which runtime lifecycle boundaries, if any, are userland-observable beyond `FRAME_SYNC` and trap abort,
- and whether shutdown behavior has any PBS-visible contract in v1.
## 12. Non-Goals
- Defining OS/process lifecycle outside Prometeu runtime authority.
- Reopening the ban on top-level executable statements.
- Designing a future async runtime.
- Defining userland recovery from trap.
## 13. Exit Criteria
This document is ready to move beyond temporary status only when:
1. runtime startup and non-start boundaries are normatively described,
2. service and module runtime lifecycle assumptions are explicit enough to remove the remaining TODO items,
3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority,
4. and the document no longer relies on unresolved TODO items for ordinary v1 runtime startup behavior.
@@ -1,118 +0,0 @@
# PBS Compatibility and Evolution Policy
Status: Draft v0 (Quality-Gate Baseline)
Applies to: practical support states and compatibility publication policy tied to executable quality gates
## 1. Purpose
This document defines how PBS support is published at the current project stage.
The policy is intentionally minimal:
- publish only support claims that are backed by tests,
- use a small support-state model that a solo project can maintain,
- and avoid over-specifying compatibility promises before backend/runtime contracts settle.
## 2. Scope
This document defines:
- support-state vocabulary for language lines,
- minimum published support table fields,
- and how support-state changes must be recorded.
This document does not define:
- full deprecation-window math per domain,
- one binary/PBX compatibility model,
- one release process implementation.
## 3. Authority and Precedence
Normative precedence:
1. `1. Language Charter.md`
2. `2. Governance and Versioning.md`
3. `13. Conformance Test Specification.md`
4. This document
If a rule here conflicts with higher-precedence authorities, it is invalid.
## 4. Normative Inputs
This document depends on:
- `2. Governance and Versioning.md`
- `13. Conformance Test Specification.md`
## 5. Support States
PBS currently uses three support states:
- `unsupported`
- `experimental`
- `supported`
Meaning:
- `unsupported`: no compatibility promise.
- `experimental`: active development; behavior may change; tests may exist but are not yet a stable support promise.
- `supported`: active compatibility promise for declared scope, backed by required quality gates.
## 6. Gate-Backed Support Rule
Support states must map to quality-gate evidence:
1. `frontend-ready` evidence requires Gate U from `13`.
2. `integration-ready` evidence requires Gate U plus Gate I when Gate I applies to the language/backend.
3. `supported` state requires maintained evidence for the scope being promised.
No published `supported` claim may exist without mapped test evidence.
## 7. Minimum Published Support Table
A published support table must include, at minimum:
1. language identifier,
2. language line/version scope,
3. runtime line (or `N/A` when Gate I is not applicable yet),
4. Gate U status,
5. Gate I status (`pass`, `fail`, or `deferred`),
6. support state (`unsupported`, `experimental`, `supported`),
7. optional notes.
No additional matrix dimensions are mandatory at this stage.
## 8. Support-State Changes
When support changes, the project must update together:
1. support table state,
2. gate evidence status,
3. and a short rationale note when users could be affected.
This document requires visibility of change, not a specific changelog format.
## 9. Explicit Deferrals
The following remain intentionally open:
- domain-specific promise strength beyond the current gate-backed model,
- exact deprecation/removal windows,
- PBX/binary compatibility policy details,
- mandatory migration tooling triggers.
## 10. Non-Goals
- Simulating large-organization compatibility governance.
- Freezing domains that are still not implemented.
- Requiring one matrix tooling format.
## 11. Exit Criteria
This document is in a healthy state when:
1. every active language line has an explicit support state,
2. every `supported` state has mapped gate evidence,
3. support changes are reflected in table + evidence + note,
4. and no compatibility promise depends on undocumented assumptions.
@@ -1,185 +0,0 @@
# PBS Standard Library Surface Specification
Status: Draft v0 (Skeleton)
Applies to: normative stdlib-facing API surface, reserved stdlib project spaces, and versioned standard-library contracts exposed to PBS programs
## 1. Purpose
This document will define the normative user-facing standard-library surface for PBS.
## 2. Scope
This document is intended to define:
- what counts as part of the PBS stdlib contract,
- how stdlib modules are grouped and versioned,
- which APIs are normative versus implementation-private,
- how VM-owned builtin shells are exposed to user code,
- how reserved stdlib project spaces expose user-facing surfaces over host-backed capabilities.
This document does not define:
- one physical packaging layout,
- registry/publication mechanics,
- host loader behavior,
- implementation-private helper modules.
## 3. Authority and Precedence
Normative precedence:
1. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
2. `8. Stdlib Environment Packaging and Loading Specification.md`
3. `6. VM-owned vs Host-backed.md`
4. `6.1. Intrinsics and Builtin Types Specification.md`
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
6. This document
If a rule here conflicts with higher-precedence specs, it is invalid.
## 4. Normative Inputs
This document depends on, at minimum:
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `6. VM-owned vs Host-backed.md`
- `6.1. Intrinsics and Builtin Types Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `8. Stdlib Environment Packaging and Loading Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- Reserved stdlib project spaces include `@sdk:*` and `@core:*`.
- Stdlib interface modules are compile-time-only and loaded as PBS-like modules.
- User code must import stdlib modules explicitly.
- Canonical host identity comes from reserved host-binding metadata, not from source owner spelling.
- VM-owned builtin type, builtin constant, and intrinsic surfaces may be exposed through reserved stdlib shells without transferring semantic ownership away from the VM.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. stdlib contract boundaries,
2. reserved stdlib project spaces and module families,
3. normative versus non-normative API surfaces,
4. VM-owned builtin shells exposed to user code,
5. host-backed SDK surfaces exposed to user code,
6. versioning and deprecation expectations for stdlib APIs.
## 7. TODO
The following items remain to be closed in future agenda discussion.
- Which stdlib modules are mandatory in each active stdlib line.
- Which APIs are part of the normative core teaching surface versus optional library growth.
- Whether `@core:*` is specified as language-adjacent utility surface or as ordinary stdlib contract.
- How stdlib API evolution is documented and conformance-tested.
- Whether some interface modules remain toolchain-private and outside user-facing stdlib surface.
- Whether builtin shells may appear in `@sdk:*` as well as `@core:*`, or whether `@sdk:*` should remain host-facing only by policy.
## 8. Non-Goals
- Replacing the resolution/packaging specs.
- Defining all future libraries in one pass.
- Hardcoding one distribution format.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. the normative user-facing stdlib surface is explicitly bounded,
2. reserved project-space API responsibilities are clear,
3. VM-owned and host-backed stdlib surfaces are explicitly separated,
4. stdlib versioning and deprecation expectations are aligned with compatibility policy,
5. the document no longer relies on unresolved `TODO` items for ordinary v1 stdlib contract claims.
## 10. Reserved Project-Space Responsibilities
The current stdlib direction distinguishes two user-facing reserved spaces.
### 10.1 `@core:*`
`@core:*` is the preferred surface for VM-owned declarations that belong to the
language-adjacent semantic platform.
Examples:
- builtin type shells,
- builtin constants,
- and other VM-owned helper declarations that are not host capability surfaces.
### 10.2 `@sdk:*`
`@sdk:*` is the preferred surface for host-backed capability-facing APIs.
Examples:
- `declare host` surfaces,
- capability-facing wrappers over host services,
- and domain SDK modules whose execution meaning ultimately depends on host-backed operations.
Rules:
- source packaging location is part of the stdlib contract surface,
- but ownership remains governed by the VM-owned vs host-backed classification,
- and placing a builtin shell in stdlib does not make it host-backed.
## 11. Builtin Shell Surfaces
Reserved stdlib modules may expose builtin declarations as compile-time-only
shells.
Rules:
- stdlib builtin shells may expose `declare builtin type` declarations,
- stdlib builtin shells may expose reserved `declare const` declarations carrying `BuiltinConst(...)`,
- stdlib builtin shells may expose builtin methods carrying `IntrinsicCall(...)`,
- these shells exist for import, name resolution, type checking, and lowering,
- and these shells do not provide executable PBS bodies for builtin behavior.
Stdlib is therefore the delivery surface, not the semantic owner.
## 12. Host-backed SDK Surfaces
Reserved stdlib modules may expose host-backed declarations as compile-time-only
shells.
Rules:
- host-backed stdlib surfaces use `declare host`,
- host-backed method signatures carry `Host(...)`,
- user code may import those host owners through ordinary stdlib module imports,
- and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`.
## 13. Stdlib Contract Expectations for Builtin MVP
For the current builtin MVP, stdlib should be able to expose at least:
1. a builtin type shell for `Color`,
2. a builtin type shell for `Vec2`,
3. a builtin type shell for `Pixel`,
4. a builtin constant shell for `vec2.zero`,
5. and any associated documentation-level or teaching-level module organization needed to make those surfaces discoverable.
Illustrative example:
```pbs
import { Vec2, ZERO } from @core:math;
```
The imported names are source-visible conveniences.
Their canonical runtime-facing identities still come from builtin metadata such
as `BuiltinType(name="vec2", version=1)` and
`BuiltinConst(target="vec2", name="zero", version=1)`.
## 14. Deterministic Stdlib Surface Failures
At minimum, a conforming implementation must reject:
1. a stdlib builtin shell that attempts to use host-binding metadata for VM-owned intrinsic behavior,
2. a stdlib host shell that attempts to use builtin metadata in place of host-binding metadata,
3. a user-facing stdlib module that exports executable PBS bodies for builtin semantics,
4. a stdlib line that exposes conflicting canonical builtin identities through the same resolved environment,
5. a stdlib line that exposes conflicting canonical host identities through the same resolved environment.
@@ -1,104 +0,0 @@
# PBS Verification and Safety Checks Specification
Status: Draft v0 (Quality-Gate Baseline)
Applies to: test-backed safety gates for compiler stages and integration regression safety checks
## 1. Purpose
This document defines the minimum safety/verification quality gates that can be enforced now.
The intent is to keep safety measurable without over-specifying future verifier internals before backend and runtime integration stabilize.
## 2. Scope
This document defines:
- compiler-stage safety checks that must be covered by tests now,
- conditional integration safety regression checks for executable backends,
- and evidence requirements for safety-related support claims.
This document does not define:
- full verifier algorithm internals,
- full bytecode/runtime proof obligations,
- or one mandatory verifier implementation architecture.
## 3. Authority and Precedence
Normative precedence:
1. `2. Governance and Versioning.md`
2. `11. Diagnostics Specification.md`
3. `12. IR and Lowering Specification.md`
4. `13. Conformance Test Specification.md`
5. `15. Bytecode and PBX Mapping Specification.md`
6. This document
If a rule here conflicts with higher-precedence authorities, it is invalid.
## 4. Normative Inputs
This document depends on:
- `11. Diagnostics Specification.md`
- `12. IR and Lowering Specification.md`
- `13. Conformance Test Specification.md`
- `15. Bytecode and PBX Mapping Specification.md`
## 5. Safety Gate Model
PBS currently uses two safety gate families.
### 5.1 Gate S-U: Compiler-Stage Safety Unit Tests (Required)
At minimum, test coverage must exist for:
1. deterministic rejection of malformed source input at lexer/parser level,
2. deterministic rejection of in-scope frontend semantic failures,
3. deterministic dependency/manifest validation failures,
4. stable diagnostics identity for required rejection surfaces (`code`, `severity`, primary attribution).
This gate is mandatory regardless of backend maturity.
### 5.2 Gate S-I: Integration Safety Regression With Runtime (Conditional)
For languages/backends that emit executable artifacts, integration safety regression tests must be introduced.
At minimum, these tests must cover:
1. deterministic rejection behavior for known malformed/unsupported integration scenarios in supported scope,
2. preservation of fixed safety regressions,
3. and repeatability across the declared runtime line for that backend.
When executable artifact emission is not yet present, Gate S-I is explicitly `deferred`.
## 6. Evidence Requirements
Safety claims must map to gate evidence:
- `S-U` evidence is required for baseline safety posture,
- `S-I` evidence is additionally required for integration-ready safety claims,
- and no published safety-related support claim should exist without current gate evidence.
## 7. Explicit Deferrals
The following are intentionally deferred:
- full verifier obligation catalog,
- formal proof of runtime safety properties,
- richer source-map/debug attribution standards beyond current minimum diagnostics needs.
## 8. Non-Goals
- Replacing runtime/bytecode authority.
- Freezing verifier architecture before implementation maturity.
- Defining performance tooling in a safety spec.
## 9. Exit Criteria
This document is in a healthy state when:
1. required compiler-stage safety checks are test-backed,
2. executable backends have explicit S-I status (`pass`/`fail`/`deferred`),
3. safety regressions are preserved in tests,
4. and safety-related support claims remain evidence-backed.
@@ -67,7 +67,7 @@ This document depends on, at minimum:
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `6. VM-owned vs Host-backed.md`
- `12. IR and Lowering Specification.md`
- `13. Lowering IRBackend Specification.md`
- `15. Bytecode and PBX Mapping Specification.md`
## 5. Core Model
+12 -1
View File
@@ -4,10 +4,13 @@ This directory contains the normative PBS specification set.
## Purpose
Specs define the official PBS contract.
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`.
## Expected Format
The exact structure may vary by document, but a spec should usually contain:
@@ -46,3 +49,11 @@ Specs should normally be fed by:
3. then spec integration.
If a spec edit would require guessing an unresolved design choice, the correct action is to stop and surface the missing decision first.
## Current Chapter Focus
The active PBS chapter focus is:
- `11. AST Specification.md`
- `12. Diagnostics Specification.md`
- `13. Lowering IRBackend Specification.md`