agendas, decisions and specs changes
This commit is contained in:
+4
-1
@@ -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`
|
||||
-116
@@ -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`
|
||||
-117
@@ -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`
|
||||
|
||||
-111
@@ -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`
|
||||
|
||||
-111
@@ -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`
|
||||
+102
@@ -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`
|
||||
+86
@@ -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`
|
||||
+88
@@ -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`
|
||||
+89
@@ -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`
|
||||
-97
@@ -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`
|
||||
-94
@@ -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`
|
||||
|
||||
-107
@@ -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`
|
||||
-93
@@ -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
|
||||
|
||||
|
||||
+5
-5
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
+5
-5
@@ -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
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user