agendas, decisions and specs changes

This commit is contained in:
2026-03-24 13:42:19 +00:00
parent 96f971bbe4
commit 150a257e0c
46 changed files with 830 additions and 1315 deletions
@@ -1,123 +0,0 @@
# PBS IR and Lowering Agenda
Status: Active
## Purpose
Drive the decisions needed to turn `12. IR and Lowering Specification.md` from a skeleton into a normative lowering contract that can guide implementation.
## Context
The language now has substantial source-level semantics, but lowering still lacks closure around:
- which semantic obligations IR must preserve,
- whether one canonical IR shape is normative,
- how core constructs map into lowered control flow and data flow,
- how services, contracts, callbacks, tuples, `optional`, and `result` lower,
- and which invariants belong in lowering versus PBX/bytecode mapping.
This agenda should keep the focus on semantic preservation and artifact obligations, not on one compiler's class hierarchy.
## Decisions To Produce
1. Decide the normative status of IR:
canonical IR, canonical obligations only, or hybrid.
2. Decide the required lowering preconditions after parsing, resolution, and type checking.
3. Decide the lowered forms required for expressions, control flow, abrupt completion, and propagation.
4. Decide the lowering story for callbacks, services, contracts, tuples, `optional`, and `result`.
5. Decide the boundary between this spec and `15. Bytecode and PBX Mapping Specification.md`.
6. Decide the artifact invariants that must hold before verifier or loader stages.
## Core Questions
1. Which evaluation-order guarantees from dynamic semantics must be explicit in lowered form?
2. Which memory and identity facts must remain explicit through IR rather than inferred later?
3. Do callback formation and contract dispatch need dedicated runtime artifacts or only preserved semantic obligations?
4. What is the minimal lowering model for builtin projections, builtin constants, and intrinsic member calls beyond what is already fixed?
5. Which host-binding failures are lowering failures versus later verifier or loader failures?
## Proposed Workshop Sequence
### Workshop 1: Lowering Contract and IR Status
Purpose:
- decide whether PBS standardizes one canonical IR or only preserved obligations,
- and close lowering preconditions after parsing, resolution, and type checking.
Expected decisions:
- canonical IR versus obligations-only model,
- required bound-program inputs,
- and minimal preserved semantic facts.
### Workshop 2: Control Flow, Evaluation Order, and Propagation
Purpose:
- close the lowering model for expressions, branching, abrupt completion, `optional`, and `result`.
Expected decisions:
- explicit evaluation-order preservation,
- lowered forms for `else`, `!`, and `handle`,
- and trap versus propagation boundaries.
### Workshop 3: Callables, Services, Contracts, and Callbacks
Purpose:
- close the lowering story for callable categories beyond ordinary top-level functions.
Expected decisions:
- callback formation model,
- service and contract dispatch shape,
- and runtime-artifact obligations for callable categories.
### Workshop 4: Builtins, Host Bindings, and Artifact Invariants
Purpose:
- close builtin lowering, host-binding emission, and the invariants required before verifier and loader stages.
Expected decisions:
- builtin projection and intrinsic lowering obligations,
- host-binding emission boundary versus PBX mapping,
- and artifact invariants consumed by `15` and `19`.
## Expected Spec Material
The resulting spec work should be able to add or close sections for:
- lowering preconditions,
- preserved semantic obligations,
- control-flow lowering,
- callable lowering by category,
- tuple, `optional`, and `result` lowering,
- callback, service, and contract lowering,
- builtin and host-binding lowering,
- artifact invariants before PBX emission,
- and source-to-artifact trace hooks consumed by diagnostics and conformance.
## Non-Goals
- Freezing optimizer internals.
- Freezing one in-memory compiler IR data model.
- Repeating the bytecode ISA.
- Defining loader patching internals.
- Designing performance heuristics.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/6. VM-owned vs Host-backed.md`
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md`
@@ -1,116 +0,0 @@
# PBS IR and Lowering Workshop 1
Status: Active
## Purpose
Run the first focused discussion for `12. IR and Lowering Specification.md` on the front door of lowering:
- what the lowering contract consumes,
- whether IR itself is normative,
- and which semantic obligations must be preserved independent of IR shape.
## Why This Slice First
This slice should come first because every later lowering discussion depends on knowing:
- what counts as a well-formed input to lowering,
- and whether the spec standardizes one IR shape or only semantic preservation duties.
## Proposed Meeting Order
1. Reconfirm already-settled lowering inputs.
2. Close the preconditions for lowering.
3. Close the normative status of IR.
4. Close the minimum preserved semantic obligations.
5. Record construct-specific issues for later workshops.
## Decisions To Produce
1. The normative status of IR in PBS v1.
2. The minimum required input state before lowering begins.
3. The semantic facts that lowering must preserve regardless of IR architecture.
4. The boundary between `12` and `15`.
## Candidate Decisions
### 1. Standardize Preserved Obligations, Not One Canonical In-Memory IR
Candidate direction:
- PBS v1 does not require one canonical compiler IR data model,
- but it does require one stable set of preserved semantic obligations.
Rationale:
- This keeps the spec implementation-neutral while still preventing semantic drift.
Alternative to discuss:
- define one normative abstract IR grammar in the spec.
### 2. Lowering Preconditions Require A Fully Bound Program
Candidate direction:
- parsing, name resolution, visibility/linking, and type checking must already be complete,
- reserved builtin and host metadata must already be validated,
- callable sets and canonical identities must already be resolved.
Rationale:
- Lowering should not invent unresolved semantic answers.
### 3. Minimum Preserved Obligations Include Evaluation Order, Identity, and Host Boundary Facts
Candidate direction:
- lowering must preserve:
source-observable evaluation order,
abrupt-completion behavior,
value-identity and aliasing facts,
host-boundary crossings,
and trap-versus-propagation distinctions.
Rationale:
- These are the semantic anchors later workshops will rely on.
### 4. `15` Owns Final Artifact Layout, `12` Owns The Contract Before It
Candidate direction:
- `12` defines the semantic and artifact-facing invariants a lowered program must satisfy,
- `15` defines the final PBX and bytecode mapping details.
Rationale:
- This keeps the lowering spec from collapsing into artifact byte layout.
## Questions To Resolve In The Room
1. Is obligations-only precise enough, or does PBS need a normative abstract IR?
2. Should canonical identity resolution be fully complete before lowering?
3. Which semantic facts are mandatory to preserve explicitly rather than infer later?
4. Does `12` need one explicit “bound program” model?
5. How much artifact vocabulary can `12` use before it starts stealing `15`'s job?
## Expected Outputs
1. a decision record on IR status,
2. a decision record on lowering preconditions,
3. and a checklist of preserved semantic obligations for `12`.
## Explicit Deferrals For Workshop 2
- control-flow shapes,
- propagation operators,
- and callable-category-specific lowering.
## Inputs
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
@@ -1,117 +0,0 @@
# PBS IR and Lowering Workshop 2
Status: Active
## Purpose
Run the second focused discussion for `12. IR and Lowering Specification.md` on control flow and propagation:
- evaluation order,
- branching,
- abrupt completion,
- `optional`,
- `result`,
- `!`,
- and `handle`.
## Why This Slice Second
This slice follows naturally from Workshop 1 because it applies the preserved-obligations model to the core execution constructs.
## Proposed Meeting Order
1. Reconfirm the preserved semantic obligations from Workshop 1.
2. Close evaluation-order preservation in lowered form.
3. Close the lowered model for branching and abrupt completion.
4. Close the lowered model for `optional` and `result` propagation.
5. Record callable and runtime-artifact issues for Workshop 3.
## Decisions To Produce
1. How evaluation order is preserved explicitly.
2. How abrupt completion is represented in lowered control flow.
3. The lowered shape of `optional else`, `expr!`, and `handle`.
4. The boundary between propagation and trap in lowering.
## Candidate Decisions
### 1. Lowering Must Make Single Evaluation Explicit
Candidate direction:
- call target formation,
- argument evaluation,
- `if` conditions,
- `switch` selectors,
- `some(expr)` payload formation,
- and `bind(context, fn_name)` capture
must each lower to explicit once-only evaluation points.
Rationale:
- These are already language-observable guarantees.
### 2. Branching Lowers To Explicit Control Transfers
Candidate direction:
- `if` and `switch` lower to explicit branch structure,
- non-selected arms do not evaluate,
- and tail-result formation is explicit rather than implicit.
Rationale:
- This keeps the dynamic-semantics contract visible through lowering.
### 3. Propagation Uses Dedicated Lowered Paths
Candidate direction:
- `optional else` lowers to a presence test plus fallback path,
- `expr!` lowers to success-path unpack plus immediate error propagation path,
- `handle` lowers to explicit arm dispatch over the error case space.
Rationale:
- These constructs are semantically distinct enough that ordinary expression lowering should not blur them.
### 4. Trap Is Not Rewritten Into Result Flow
Candidate direction:
- lowered trap paths remain fatal abort paths outside ordinary `result` propagation,
- and `handle` never intercepts trap.
Rationale:
- This preserves the existing semantics cleanly.
## Questions To Resolve In The Room
1. Does `12` need dedicated abstract operations for propagation, or only obligations on the emitted control flow?
2. How explicit must once-only evaluation be in the spec text?
3. Does `switch` lowering need one canonical decision-tree shape?
4. Is `handle` best specified as arm dispatch plus remap semantics, or as a more abstract effect-preservation rule?
5. Which of these details belong to `12` versus `15`?
## Expected Outputs
1. a decision record for evaluation-order preservation,
2. a decision record for propagation lowering,
3. and control-flow section targets for `12`.
## Explicit Deferrals For Workshop 3
- services,
- contracts,
- callbacks,
- and runtime dispatch artifacts.
## Inputs
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
- `docs/pbs/agendas/12.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md`
@@ -1,111 +0,0 @@
# PBS IR and Lowering Workshop 3
Status: Active
## Purpose
Run the third focused discussion for `12. IR and Lowering Specification.md` on callable categories beyond ordinary top-level functions:
- callbacks,
- services,
- contracts,
- methods,
- and dispatch obligations.
## Why This Slice Third
This slice should come after control-flow lowering because it builds on the general execution model while introducing runtime-dispatch and identity-sensitive concerns.
## Proposed Meeting Order
1. Reconfirm callable categories and identity facts already fixed.
2. Close callback formation and invocation lowering.
3. Close service and method lowering.
4. Close contract-view and dispatch lowering.
5. Record builtin and host-binding specifics for Workshop 4.
## Decisions To Produce
1. The lowering story for callback formation and invocation.
2. The lowering story for service singleton methods.
3. The lowering story for contracts and dispatch.
4. Which runtime-artifact facts must be explicit versus implementation-defined.
## Candidate Decisions
### 1. Callback Lowering Must Preserve Captured Identity And Retention
Candidate direction:
- callback values created by `bind` lower to a representation that preserves:
target callable identity,
captured context identity,
and retention-bearing lifetime facts.
Rationale:
- These are already required by memory and semantics specs.
### 2. Service Lowering Preserves Singleton Identity
Candidate direction:
- service method calls lower through the module-owned singleton identity,
- and lowering must not accidentally materialize new service instances.
Rationale:
- This is a language-observable property.
### 3. Contract Lowering Must Preserve Selected Implementation Identity
Candidate direction:
- contract values lower as runtime-dispatchable views over an underlying owner plus implementation selection,
- but `12` does not freeze one concrete table or object layout yet.
Rationale:
- This keeps the semantic contract clear while deferring layout choices.
### 4. Receiver-Bearing Method Calls Need Explicit Lowered Receiver Handling
Candidate direction:
- struct, service, and contract method calls lower through an explicit receiver-bearing callable shape,
- even if the backend later optimizes the representation.
Rationale:
- This keeps receiver identity and call semantics visible in the spec.
## Questions To Resolve In The Room
1. Does contract dispatch need a dedicated runtime artifact category in the spec?
2. Does callback lowering need one explicit abstract representation?
3. How much of method dispatch belongs in `12` versus runtime execution specs?
4. Are service methods lowered like receiver calls or like specialized global calls?
5. Which of these constructs need explicit artifact invariants before `15`?
## Expected Outputs
1. a decision record for callback lowering,
2. a decision record for service and contract lowering,
3. and callable-category section targets for `12`.
## Explicit Deferrals For Workshop 4
- builtin projection lowering,
- builtin constants,
- host-binding emission,
- and verifier-facing artifact invariants.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
- `docs/pbs/agendas/12.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md`
@@ -1,111 +0,0 @@
# PBS IR and Lowering Workshop 4
Status: Active
## Purpose
Run the fourth focused discussion for `12. IR and Lowering Specification.md` on the backend-facing edges:
- builtin projections,
- builtin constants,
- intrinsic member calls,
- host-binding emission,
- and artifact invariants required before verifier or loader stages.
## Why This Slice Last
This slice should come last because it depends on the general lowering contract plus the special ownership rules around VM-owned versus host-backed behavior.
## Proposed Meeting Order
1. Reconfirm already-settled builtin and host-binding facts.
2. Close lowering obligations for builtin projections and constants.
3. Close lowering obligations for intrinsic member calls.
4. Close host-binding emission obligations.
5. Close pre-verifier and pre-loader artifact invariants.
## Decisions To Produce
1. Builtin lowering obligations beyond already-settled metadata consumption.
2. Host-binding emission obligations before loader resolution.
3. The artifact invariants required before verifier/loader stages.
4. The exact boundary between `12`, `15`, and `19`.
## Candidate Decisions
### 1. Builtin Projections Stay VM-Owned Through Lowering
Candidate direction:
- builtin projection access lowers through VM-owned operations only,
- and never through host-binding tables or host syscall paths.
Rationale:
- This is already settled; `12` needs only to make the preserved obligation explicit.
### 2. Builtin Constants Lower Through Materialization, Not Constant Folding Semantics
Candidate direction:
- builtin constants lower through their VM-owned materialization path,
- not through ordinary user-authored compile-time constant evaluation.
Rationale:
- This keeps builtin shells distinct from ordinary `declare const`.
### 3. Host-Binding Emission Must Be Explicit Before `15`
Candidate direction:
- lowering must produce canonical host-binding entries,
- deduplicate them by canonical identity,
- and emit host-backed callsites in the pre-load form already fixed elsewhere.
Rationale:
- This is the bridge between bound source and artifact mapping.
### 4. `12` Defines Artifact Invariants, `15` Defines Encoding
Candidate direction:
- `12` states what must be true of the emitted artifact boundary,
- `15` states exactly how those facts appear in PBX and bytecode form,
- `19` states what must be verified.
Rationale:
- This keeps the three backend-facing specs from overlapping.
## Questions To Resolve In The Room
1. Does `12` need any abstract instruction vocabulary for builtins and host calls?
2. Which invariants belong to lowering rather than to verification?
3. How much ordering and dedup detail should `12` restate versus reference from other specs?
4. Should intrinsic lowering be specified as abstract op families or only semantic obligations?
5. What exact artifact guarantees must `13` eventually assert?
## Expected Outputs
1. a decision record for builtin lowering obligations,
2. a decision record for host-binding emission obligations,
3. and an artifact-invariants checklist spanning `12`, `15`, and `19`.
## Explicit Deferrals
- exact bytecode instruction encodings,
- exact PBX section layout,
- and verifier algorithm details.
## Inputs
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/agendas/12. IR and Lowering Agenda.md`
- `docs/pbs/agendas/12.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md`
@@ -0,0 +1,122 @@
# PBS Frontend IR and Lowering Agenda
Status: Active
## Purpose
Drive closure of `13. Lowering IRBackend Specification.md` for frontend scope only.
This agenda exists to define the first normative lowering boundary:
- PBS source to frontend IR (`IRBackend` / `IRBackendFile`),
- deterministic diagnostic behavior for unsupported or invalid source forms,
- and test-backed acceptance criteria for Gate U.
## Scope Boundary
In scope:
- lexer/parser/AST/linking outputs consumed by frontend lowering,
- semantic facts that must be preserved in frontend IR,
- deterministic rejection classes and diagnostic attribution,
- and conformance evidence for frontend gates.
Out of scope:
- VM lowering,
- bytecode/PBX mapping,
- runtime execution behavior,
- verifier/loader algorithms.
## Decisions To Produce
1. Decide whether `13` standardizes one frontend IR shape or only preserved obligations.
2. Decide the minimum preconditions before frontend lowering begins.
3. Decide which semantic facts must be explicit in frontend IR for v1.
4. Decide the minimum deterministic rejection set for unsupported frontend-lowering cases.
5. Decide the gate evidence expected from tests (`lexer/parser/AST/IRBackend/diagnostics`).
## Core Questions
1. What is the minimum frontend IR contract that keeps implementation practical and testable now?
2. Which source-observable guarantees must already be explicit before any backend stage exists?
3. Which constructs are in-scope for v1 lowering and which must fail deterministically?
4. What diagnostics identity must be stable for lowering-related frontend failures?
5. Which regression fixtures become mandatory Gate U evidence?
## Proposed Workshop Sequence
### Workshop 1: Frontend Lowering Contract and Preconditions
Purpose:
- close input preconditions,
- and close the normative status of frontend IR.
Expected decisions:
- obligations-only versus canonical frontend IR model,
- and minimum required bound-program state before lowering.
### Workshop 2: Expressions, Control Flow, and Propagation in Frontend IR
Purpose:
- close frontend-lowering obligations for core expression/control-flow forms.
Expected decisions:
- once-only evaluation obligations in frontend IR terms,
- representation obligations for branching and propagation constructs.
### Workshop 3: Callable Categories in Frontend IR
Purpose:
- close frontend-lowering obligations for functions, callbacks, services, and contracts as source-level categories.
Expected decisions:
- minimum callable metadata preserved in frontend IR,
- and deterministic rejection boundaries for unsupported callable forms.
### Workshop 4: Builtins, Diagnostics, and Test Gates
Purpose:
- close builtin-facing frontend obligations plus gate-ready diagnostics/test evidence.
Expected decisions:
- frontend treatment of builtin shells/metadata at lowering boundary,
- minimum diagnostics identity and attribution for lowering-related failures,
- and required fixture families for Gate U.
## Expected Spec Material
The resulting `13` content should close:
- lowering preconditions for frontend scope,
- frontend IR preserved-obligation model,
- construct-by-construct frontend lowering baseline,
- deterministic unsupported-case rejection policy,
- and frontend-facing diagnostic/test evidence hooks.
## Non-Goals
- Defining VM or bytecode artifacts.
- Freezing runtime semantics in this agenda.
- Defining verifier or loader internals.
- Freezing optimizer architecture.
## Inputs
- `docs/pbs/specs/3. Core Syntax Specification.md`
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
@@ -0,0 +1,102 @@
# PBS Frontend IR and Lowering Workshop 1
Status: Closed (2026-03-05)
## Purpose
Run the first focused discussion for `13. Lowering IRBackend Specification.md` in frontend scope:
- what frontend lowering consumes,
- what frontend lowering must produce,
- and whether one canonical frontend IR shape is required.
## Why This Slice First
Every later workshop depends on a stable contract for:
- preconditions before lowering,
- and which frontend IR obligations are normative.
## Proposed Meeting Order
1. Reconfirm frontend-only scope boundary for agenda 13.
2. Close minimum preconditions before frontend lowering starts.
3. Close normative status of frontend IR shape versus obligations.
4. Close minimum preserved semantic facts for v1.
5. Record construct-specific gaps for Workshops 2 to 4.
## Decisions To Produce
1. Normative status of frontend IR in v1.
2. Required input state before frontend lowering begins.
3. Minimum preserved semantic facts at frontend-lowering boundary.
4. Minimum deterministic rejection policy for unsupported lowering inputs.
## Candidate Decisions
### 1. Standardize Preserved Obligations, Not One In-Memory Class Graph
Candidate direction:
- v1 standardizes preserved frontend obligations and observable outcomes,
- not one mandatory Java object model.
### 2. Frontend Lowering Requires Fully Parsed and Linked Source
Candidate direction:
- parser and linking outcomes are already complete,
- type/name diagnostics already produced where required,
- and lowering does not invent unresolved semantic answers.
### 3. Minimum Preserved Facts For V1 Frontend IR
Candidate direction:
- callable identity,
- parameter arity,
- declared return surface,
- and source attribution anchor (`file + span`) for diagnostics.
### 4. Unsupported Constructs Must Fail Deterministically
Candidate direction:
- constructs outside v1 frontend-lowering slice fail with stable diagnostics,
- never silently degrade into partial/implicit behavior.
## Questions To Resolve In The Room
1. Which facts are mandatory in v1 `IRFunction` versus optional?
2. Is obligations-only precise enough for conformance tests?
3. Which rejected constructs must already have fixed diagnostic codes?
4. What is the exact pass/fail boundary between parser/linking and frontend lowering errors?
## Expected Outputs
1. a decision note on frontend IR normative status,
2. a decision note on lowering preconditions,
3. and a checklist of preserved frontend-lowering obligations.
## Decision Outcome (2026-03-05)
1. `13` remains normative by preserved obligations, not by one mandatory in-memory IR shape.
2. Frontend lowering starts only after parse/linking completion and required prior diagnostics.
3. Minimum v1 frontend IR facts are mandatory: callable identity, arity, declared return surface, and source anchor (`file + span`).
4. Unsupported frontend-lowering forms must fail deterministically with stable diagnostics.
5. Scope boundary confirmed: `IRBackend` is the first lowering (frontend responsibility); `IRVM` is a later lowering (backend responsibility) and is out of `13` agenda scope.
6. Evidence baseline confirmed for now: Gate U only (`lexer/parser/AST/IRBackend/diagnostics`), without S-U requirement at this stage.
7. Conformance-valid IR claim rule: only when the full PBS spec surface is implemented at `IRBackend` level.
## Explicit Deferrals For Workshop 2
- expression/control-flow construct mapping details,
- and propagation construct obligations.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/agendas/13. IR and Lowering Agenda.md`
@@ -0,0 +1,86 @@
# PBS Frontend IR and Lowering Workshop 2
Status: Active
## Purpose
Run the second focused discussion for `13. Lowering IRBackend Specification.md` on frontend-lowering obligations for:
- expression evaluation order,
- branching behavior,
- and propagation-related constructs at frontend IR boundary.
## Why This Slice Second
After Workshop 1 closes contract/preconditions, this workshop closes construct-level obligations that must be testable in frontend scope.
## Proposed Meeting Order
1. Reconfirm preserved obligations from Workshop 1.
2. Close once-only evaluation obligations in frontend IR terms.
3. Close branch and abrupt-completion representation obligations.
4. Close propagation construct obligations (`optional`, `result`, `!`, `handle`) at frontend boundary.
5. Record callable-category leftovers for Workshop 3.
## Decisions To Produce
1. Which evaluation-order guarantees must remain explicit in frontend IR obligations.
2. Which branch/abrupt-completion facts are mandatory in v1 frontend lowering.
3. Which propagation constructs are in-scope versus deterministic rejection in v1 slice.
4. Which diagnostics are required when unsupported propagation constructs are used.
## Candidate Decisions
### 1. Frontend Lowering Must Preserve Once-Only Evaluation Facts
Candidate direction:
- source-observable single-evaluation points are preserved as explicit lowering obligations,
- independent of one exact IR node taxonomy.
### 2. Branching Obligations Are Normative At Frontend Boundary
Candidate direction:
- selected/non-selected branch semantics remain explicit in frontend lowering contract,
- with no implicit permissive fallbacks.
### 3. Propagation Constructs Have Explicit V1 Status
Candidate direction:
- each construct is marked `supported in v1 frontend lowering` or `deterministic reject`,
- and this status is mirrored in Gate U fixtures.
### 4. Diagnostics Identity Must Be Stable For Unsupported Forms
Candidate direction:
- unsupported forms emit stable code/severity/primary attribution,
- so regression tests can lock behavior.
## Questions To Resolve In The Room
1. Which propagation constructs are fully represented now versus deferred?
2. What minimum frontend IR evidence is enough to prove evaluation-order obligations?
3. Which failures should be classified as parse/static errors versus lowering errors?
4. Which fixture shapes are mandatory for Gate U here?
## Expected Outputs
1. a decision note on expression/control-flow lowering obligations,
2. a decision note on propagation status map (support/reject),
3. and fixture targets for frontend conformance tests.
## Explicit Deferrals For Workshop 3
- callable-category representation details,
- and service/contract/callback-specific obligations.
## Inputs
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md`
@@ -0,0 +1,88 @@
# PBS Frontend IR and Lowering Workshop 3
Status: Active
## Purpose
Run the third focused discussion for `13. Lowering IRBackend Specification.md` on callable categories in frontend scope:
- top-level functions,
- callbacks,
- services,
- and contracts as source-level callable surfaces.
## Why This Slice Third
Callable categories depend on the core expression/control-flow obligations from Workshop 2 and now need explicit frontend representation/rejection boundaries.
## Proposed Meeting Order
1. Reconfirm callable and identity facts already settled by syntax/static/linking specs.
2. Close frontend-lowering obligations for function and callback forms.
3. Close frontend-lowering obligations for service/contract callable surfaces.
4. Close deterministic rejection policy for unsupported callable forms.
5. Record builtin/diagnostics gate closure points for Workshop 4.
## Decisions To Produce
1. Minimum callable metadata preserved by frontend IR for each callable category.
2. V1 support map for callable categories (`supported` versus deterministic reject).
3. Required diagnostics identity for rejected callable forms.
4. Required regression fixtures for callable categories in Gate U.
## Candidate Decisions
### 1. Callable Identity Must Be Explicit In Frontend IR Contract
Candidate direction:
- callable name/category/arity/source attribution are mandatory preserved facts,
- regardless of internal object-model differences.
### 2. Callback/Service/Contract Surfaces Need Explicit V1 Status
Candidate direction:
- each callable surface is classified now as `represented` or `rejected`,
- with no silent fallback behavior.
### 3. Unsupported Callable Forms Are Deterministic Diagnostics
Candidate direction:
- unsupported callable patterns must emit stable diagnostics,
- and become mandatory regression tests.
### 4. Gate U Must Cover Callable Categories Explicitly
Candidate direction:
- representative valid+invalid fixtures per callable category are mandatory,
- including diagnostics assertions for rejected forms.
## Questions To Resolve In The Room
1. Which callable category fields are mandatory in `IRBackend` today?
2. Which callable constructs remain deferred in v1 frontend scope?
3. What is the minimum fixture set to protect callable behavior regressions?
4. Which diagnostics codes must be fixed now versus later?
## Expected Outputs
1. a decision note on callable frontend-lowering obligations,
2. a decision note on callable support/rejection map,
3. and Gate U fixture requirements for callable categories.
## Explicit Deferrals For Workshop 4
- builtin-specific lowering obligations,
- and final diagnostics/gate packaging for spec closure.
## Inputs
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/14. Name Resolution and Module Linking Specification.md`
- `docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md`
@@ -0,0 +1,89 @@
# PBS Frontend IR and Lowering Workshop 4
Status: Active
## Purpose
Run the fourth focused discussion for `13. Lowering IRBackend Specification.md` to close frontend-specific pending points:
- builtin-facing source semantics at frontend lowering boundary,
- diagnostics stability for lowering-related failures,
- and test-gate evidence needed to close v1 frontend slice.
## Why This Slice Last
This workshop should close only after Workshops 1 to 3 define the base lowering contract and callable status map.
## Proposed Meeting Order
1. Reconfirm frontend-only scope and deferred backend concerns.
2. Close builtin-shell obligations at frontend lowering boundary.
3. Close diagnostics identity/attribution obligations for lowering-related failures.
4. Close minimum gate evidence package (Gate U).
5. Produce closure checklist for spec `13` frontend slice.
## Decisions To Produce
1. Frontend-lowering obligations for builtin-facing constructs in v1.
2. Stable diagnostics contract for frontend-lowering rejections.
3. Mandatory fixture families to prove `13` frontend obligations.
4. Explicit list of deferred topics that belong to future backend-focused agenda.
## Candidate Decisions
### 1. Builtin Surfaces Are Frontend-Validated Before Any Backend Contract
Candidate direction:
- builtin names and metadata usage are validated at frontend scope per existing specs,
- and lowering emits deterministic outcomes or deterministic rejection.
### 2. Diagnostics Contract Is Mandatory For Frontend-Lowering Failures
Candidate direction:
- code/severity/primary attribution are fixed and test-backed for required rejection classes,
- enabling reliable regression protection.
### 3. Gate Evidence Is Small But Mandatory
Candidate direction:
- each required obligation has at least one positive and one negative fixture where applicable,
- with assertions for lexer/parser/AST/IRBackend/diagnostics.
### 4. Backend Topics Are Explicitly Deferred
Candidate direction:
- VM lowering, bytecode mapping, runtime, verifier, and loader remain out of this agenda,
- and are listed as deferred backlog topics.
## Questions To Resolve In The Room
1. Which builtin scenarios are mandatory in v1 fixture corpus?
2. Which lowering-related diagnostics are mandatory to freeze now?
3. What is the minimum evidence bar to declare `13` frontend slice closed?
4. Which open points are explicitly deferred without blocking frontend progress?
## Expected Outputs
1. a decision note on builtin frontend-lowering obligations,
2. a decision note on diagnostics/test evidence obligations,
3. and a closure checklist for `13` frontend scope.
## Explicit Deferrals
- VM lowering design,
- bytecode/PBX mapping,
- runtime execution contracts,
- verifier and loader internals.
## Inputs
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/pbs/specs/12. Diagnostics Specification.md`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md`
@@ -1,113 +0,0 @@
# PBS Compatibility and Evolution Policy Agenda
Status: Active
## Purpose
Drive the closure of `17. Compatibility and Evolution Policy.md` so PBS can make explicit promises before implementation and release claims expand.
## Context
The current skeleton identifies the right policy areas, but it still leaves open:
- compatibility domains and windows,
- the separation between source, stdlib, artifact, and runtime compatibility,
- deprecation and removal duties,
- migration-tooling versus documentation-only obligations,
- and whether phased implementation claims need distinct compatibility labels.
This agenda should produce a policy that is strict enough to protect users and toolchains, while still allowing deliberate evolution.
## Decisions To Produce
1. Decide the compatibility domains PBS speaks about normatively.
2. Decide the compatibility promise and window for each domain.
3. Decide the deprecation and removal policy for source, stdlib, and artifact surfaces.
4. Decide when migration tooling is mandatory versus when written guidance is enough.
5. Decide whether phased implementation or conformance claims need distinct compatibility labels.
## Core Questions
1. What exact promise is made to old source code, published cartridges, stdlib consumers, and emitted artifacts?
2. Is PBX compatibility governed independently from source compatibility?
3. How do stdlib-line changes affect downstream dependency projects over time?
4. Which incompatible changes require migration tooling rather than only release notes?
5. How are compatibility claims constrained by conformance level and runtime line?
## Proposed Workshop Sequence
### Workshop 1: Compatibility Domains and Promise Levels
Purpose:
- define the domains PBS makes compatibility promises about,
- and decide the strength of each promise.
Expected decisions:
- source, stdlib, cartridge, artifact, and runtime domain boundaries,
- and behavioral versus binary compatibility split.
### Workshop 2: Deprecation, Removal, and Migration Duties
Purpose:
- close the lifecycle policy for changes that affect published users.
Expected decisions:
- deprecation windows,
- removal preconditions,
- and migration tooling versus documentation-only obligations.
### Workshop 3: Compatibility Matrices and Published Claims
Purpose:
- decide how compatibility claims are expressed across language line, stdlib line, runtime line, and conformance level.
Expected decisions:
- matrix shape,
- supported-line expectations,
- and alignment with `13`.
### Workshop 4: Artifact and PBX Compatibility Policy
Purpose:
- decide whether artifact compatibility has an independent policy track from source compatibility.
Expected decisions:
- PBX compatibility promise,
- runtime-loading compatibility boundaries,
- and obligations when the artifact line changes.
## Expected Spec Material
The resulting spec work should be able to add or close sections for:
- compatibility domains,
- compatibility windows and support lines,
- behavioral versus binary compatibility,
- deprecation and removal discipline,
- migration obligations,
- compatibility matrices across language, stdlib, and runtime lines,
- and labeling rules for partial or staged implementation claims.
## Non-Goals
- Defining one release calendar.
- Replacing governance with case-by-case exceptions.
- Treating every editorial clarification as a compatibility event.
- Designing product marketing labels.
## Inputs
- `docs/pbs/specs/1. Language Charter.md`
- `docs/pbs/specs/2. Governance and Versioning.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
@@ -1,97 +0,0 @@
# PBS Compatibility Workshop 1
Status: Active
## Purpose
Run the first focused discussion for `17. Compatibility and Evolution Policy.md` on the top-level policy model:
- which compatibility domains PBS recognizes,
- and what strength of promise applies to each.
## Why This Slice First
This slice should come first because every deprecation, migration, and matrix policy depends on a clean definition of domains and promise levels.
## Proposed Meeting Order
1. Reconfirm already-settled governance and versioning inputs.
2. Close the compatibility domains.
3. Close the promise level for each domain.
4. Close behavioral versus binary compatibility terminology.
5. Record migration and matrix issues for later workshops.
## Decisions To Produce
1. The compatibility domains PBS speaks about normatively.
2. The promise level for each domain.
3. The behavioral versus binary compatibility split.
4. The relationship between claim level and compatibility promise.
## Candidate Decisions
### 1. Recognize Separate Domains
Candidate direction:
- PBS should distinguish at least:
source compatibility,
stdlib compatibility,
cartridge/runtime compatibility,
artifact compatibility,
and conformance-claim compatibility.
Rationale:
- Different breakages affect different users and toolchains.
### 2. Promise Strength Differs By Domain
Candidate direction:
- source and published-cartridge behavior get the strongest promise,
- stdlib and artifact domains may have tighter line-based conditions,
- partial conformance claims get narrower promises than full ones.
Rationale:
- This avoids one vague compatibility slogan that means too many things.
### 3. Separate Behavioral From Binary Compatibility
Candidate direction:
- source-level and runtime-observable behavior compatibility is not the same as artifact binary compatibility,
- and the policy should state both explicitly.
Rationale:
- This prevents PBX policy from silently driving all evolution policy.
## Questions To Resolve In The Room
1. What are the minimum compatibility domains that PBS must name explicitly?
2. Which domains deserve the strongest guarantees?
3. Is cartridge compatibility mainly behavioral, binary, or both?
4. How does staged conformance affect compatibility promises?
5. Does stdlib compatibility belong as its own domain or inside source compatibility?
## Expected Outputs
1. a decision record for compatibility domains,
2. a promise-level matrix draft,
3. and terminology targets for `17`.
## Explicit Deferrals For Workshop 2
- deprecation windows,
- migration-tooling duties,
- and artifact-line change policy.
## Inputs
- `docs/pbs/specs/2. Governance and Versioning.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/decisions/Conformance Claim Levels Decision.md`
- `docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md`
@@ -1,94 +0,0 @@
# PBS Compatibility Workshop 2
Status: Active
## Purpose
Run the second focused discussion for `17. Compatibility and Evolution Policy.md` on lifecycle discipline:
- deprecation,
- removal,
- migration duties,
- and when tooling is mandatory versus documentation-only guidance.
## Why This Slice Second
This slice follows domain definition because the right deprecation and migration policy depends on what kind of surface is changing.
## Proposed Meeting Order
1. Reconfirm the compatibility domains and promise strengths from Workshop 1.
2. Close deprecation requirements by domain.
3. Close removal preconditions.
4. Close migration-tooling versus documentation obligations.
5. Record matrix consequences for Workshop 3.
## Decisions To Produce
1. Deprecation windows by domain.
2. Removal preconditions by domain.
3. Migration-tooling obligations.
4. The policy for changes that are incompatible but still deliberate.
## Candidate Decisions
### 1. Deprecation Must Precede Removal For User-Facing Stable Surfaces
Candidate direction:
- source and stdlib user-facing surfaces require explicit deprecation before removal,
- unless the change is confined to a new major line.
Rationale:
- This matches additive-first evolution goals.
### 2. Migration Tooling Is Required Only For High-Frequency Or High-Impact Breaks
Candidate direction:
- some incompatible changes require tooling,
- others may be served by precise migration notes,
- and the policy should name the factors that trigger tooling duty.
Rationale:
- This is more realistic than requiring tools for every break.
### 3. Removal Must Be Paired With An Announced Support Boundary
Candidate direction:
- removal is allowed only with a clearly documented support boundary and migration path or explanation.
Rationale:
- This makes policy operational rather than rhetorical.
## Questions To Resolve In The Room
1. Which domains require deprecation before removal?
2. What triggers mandatory migration tooling?
3. Can artifact-line changes skip deprecation if they stay behind a new major line?
4. How should deprecated stdlib APIs be tested in conformance while still supported?
5. When is documentation-only migration guidance enough?
## Expected Outputs
1. a decision record for deprecation policy,
2. a decision record for migration duties,
3. and lifecycle section targets for `17`.
## Explicit Deferrals For Workshop 3
- compatibility matrices,
- published-claim aging,
- and artifact compatibility line policy.
## Inputs
- `docs/pbs/specs/2. Governance and Versioning.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md`
@@ -1,107 +0,0 @@
# PBS Compatibility Workshop 3
Status: Decision recorded
## Purpose
Run the third focused discussion for `17. Compatibility and Evolution Policy.md` on support claims over time:
- compatibility matrices,
- supported combinations,
- published claims,
- and how those claims age or retire.
## Resolution Snapshot
This workshop direction is now recorded in:
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
Integrated spec follow-up belongs to:
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
## Why This Slice Third
This slice follows domain and lifecycle policy because matrix policy is where those choices become operational.
## Proposed Meeting Order
1. Reconfirm domain and lifecycle decisions from Workshops 1 and 2.
2. Close the shape of the compatibility matrix.
3. Close what counts as a published support claim.
4. Close how claims retire or narrow over time.
5. Record artifact-specific leftovers for Workshop 4.
## Decisions To Produce
1. The compatibility-matrix dimensions PBS must publish.
2. The policy for published support claims.
3. The relationship between claims, conformance, and regression.
4. The retirement policy for supported combinations.
## Candidate Decisions
### 1. Publish A Matrix Across The Major Compatibility Domains
Candidate direction:
- the matrix should cover at least:
language line,
stdlib line,
runtime line,
and conformance claim level.
Rationale:
- These are the main axes users will rely on.
### 2. Published Claims Must Be Backed By Conformance Or Regression Evidence
Candidate direction:
- support claims are not just prose;
- they must correspond to maintained test evidence where support is promised.
Rationale:
- This aligns policy with `13`.
### 3. Unsupported Combinations Must Be Explicit
Candidate direction:
- the matrix must allow explicit “unsupported” states rather than implying silence equals support.
Rationale:
- This reduces accidental ambiguity.
## Questions To Resolve In The Room
1. What exact axes belong in the official matrix?
2. Must every supported combination have conformance evidence?
3. How should experimental or provisional combinations be labeled?
4. When support is dropped, how is that reflected in the matrix and docs?
5. Which parts of this are policy versus test-harness detail?
## Expected Outputs
1. a decision record for the compatibility-matrix model,
2. a published-claims policy note,
3. and alignment tasks for `13`.
## Explicit Deferrals For Workshop 4
- PBX compatibility,
- binary-loading policy,
- and artifact-line changes.
## Inputs
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md`
- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md`
- `docs/pbs/agendas/17.2. Compatibility Workshop 2 - Deprecation, Removal, and Migration Duties.md`
@@ -1,93 +0,0 @@
# PBS Compatibility Workshop 4
Status: Active
## Purpose
Run the fourth focused discussion for `17. Compatibility and Evolution Policy.md` on artifact compatibility:
- PBX compatibility,
- runtime-loading compatibility,
- and how artifact-line changes are versioned and promised.
## Why This Slice Last
This slice should come last because artifact policy is the most backend-dependent and should be informed by the broader domain and matrix decisions first.
## Proposed Meeting Order
1. Reconfirm the source, stdlib, cartridge, and matrix policy already chosen.
2. Decide whether artifact compatibility is an independent policy track.
3. Decide PBX and runtime-loading promise boundaries.
4. Decide how artifact-line changes are versioned and communicated.
5. Record final integration tasks for `17`, `15`, and `19`.
## Decisions To Produce
1. Whether artifact compatibility is independent from source compatibility.
2. The promise boundary for PBX and loader compatibility.
3. The versioning and communication policy for artifact-line changes.
4. The relationship between artifact policy and published cartridge support.
## Candidate Decisions
### 1. Artifact Compatibility Is A Distinct Policy Track
Candidate direction:
- PBX and emitted-artifact compatibility should be named explicitly rather than assumed from source compatibility.
Rationale:
- Binary and loader compatibility carry different risks and evolution constraints.
### 2. Runtime Loading Promise Must Be Stated By Supported Line
Candidate direction:
- artifact compatibility should be expressed against explicit runtime and artifact lines,
- not as a timeless blanket guarantee.
Rationale:
- This keeps the promise honest and testable.
### 3. Artifact-Line Breaks Require Explicit Version Signaling
Candidate direction:
- incompatible artifact changes require an explicit line or major-boundary signal,
- plus migration or tooling guidance when older published cartridges are affected.
Rationale:
- This aligns artifact evolution with the broader compatibility policy.
## Questions To Resolve In The Room
1. How strong should PBX compatibility promises be?
2. Are published cartridges protected mainly by source compatibility or by explicit artifact-line support?
3. What counts as an artifact compatibility break?
4. Must artifact-line changes always align with major language-version changes?
5. How should loader support boundaries be documented and tested?
## Expected Outputs
1. a decision record for artifact compatibility policy,
2. a PBX/runtime promise note,
3. and final section targets for `17`.
## Explicit Deferrals
- exact PBX layout details,
- exact loader algorithms,
- and binary test harness implementation.
## Inputs
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
- `docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.md`