clean up
This commit is contained in:
@@ -0,0 +1,53 @@
|
||||
# AST Contract and Root Model Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-05
|
||||
Related Agenda: `docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md`
|
||||
|
||||
## Context
|
||||
|
||||
PBS introduced `11. AST Specification.md` as the language-specific AST layer between parser output and frontend lowering to `IRBackend`.
|
||||
|
||||
The open question was whether AST should be standardized by one mandatory implementation model (for example one Java class hierarchy) or by observable contract obligations.
|
||||
|
||||
## Decision
|
||||
|
||||
PBS adopts an obligations-first AST contract.
|
||||
|
||||
The specification standardizes required observable AST behavior and invariants, not one mandatory in-memory representation.
|
||||
|
||||
The following are required:
|
||||
|
||||
1. one AST root per source file;
|
||||
2. deterministic child ordering consistent with source order;
|
||||
3. mandatory source attribution (`file`, `start`, `end`) on nodes consumed by diagnostics or lowering;
|
||||
4. explicit declaration/statement/expression node families for the supported v1 source slice;
|
||||
5. deterministic rejection for unsupported forms, without permissive synthetic AST that hides rejection.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. AST conformance is implementation-language agnostic.
|
||||
2. Missing required attribution on mandatory nodes is non-conformant.
|
||||
3. Parser recovery may produce partial AST, but structural integrity must remain valid for continued diagnostics.
|
||||
4. Lowering and diagnostics are allowed to depend on the required AST invariants above.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
1. This decision does not freeze one parser architecture.
|
||||
2. This decision does not define full static-semantics rules.
|
||||
3. This decision does not define `IRBackend -> IRVM` lowering.
|
||||
4. This decision does not define runtime/bytecode/verifier policies.
|
||||
|
||||
## Spec Impact
|
||||
|
||||
1. `docs/pbs/specs/11. AST Specification.md` must encode the obligations-first contract and invariants.
|
||||
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains the authority for diagnostic identity/phase/attribution payload rules consumed by AST-facing diagnostics.
|
||||
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume the mandatory AST invariants as lowering preconditions.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
At minimum, Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:
|
||||
|
||||
1. valid AST shape fixtures for representative declarations/statements/expressions;
|
||||
2. deterministic syntax rejection fixtures with stable diagnostics;
|
||||
3. attribution checks (`file/start/end`) on nodes required by diagnostics and lowering.
|
||||
@@ -0,0 +1,69 @@
|
||||
# AST Declarations and Type Surfaces Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-05
|
||||
Related Agenda: `docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md`
|
||||
|
||||
## Context
|
||||
|
||||
After closing the AST contract/root model, PBS needed a precise declaration-layer AST decision for v1 so parser output, diagnostics, and IRBackend lowering remain aligned.
|
||||
|
||||
The open points were:
|
||||
|
||||
- mandatory declaration families in AST,
|
||||
- declaration identity preservation,
|
||||
- declaration metadata requirements for downstream phases,
|
||||
- AST/static-semantics phase boundary,
|
||||
- rejection and recovery behavior for malformed declarations,
|
||||
- and minimum Gate U evidence.
|
||||
|
||||
## Decision
|
||||
|
||||
PBS adopts the following declaration/type-surface AST policy for v1:
|
||||
|
||||
1. Mandatory declaration families include:
|
||||
- imports,
|
||||
- top-level `fn`,
|
||||
- `struct`, `contract`, `service`, `error`, `enum`, `callback`,
|
||||
- `declare const`,
|
||||
- and declaration nodes required by barrel/linking flow.
|
||||
2. Declaration identity is preserved at AST boundary; implementations must not prematurely merge declarations (including overload sets).
|
||||
3. Minimum declaration metadata includes:
|
||||
- declaration name,
|
||||
- declared signature/surface (parameters/return when applicable),
|
||||
- stable source attribution (`file/start/end`),
|
||||
- and required declaration-level syntactic flags/attributes needed by later phases.
|
||||
4. AST/static boundary is explicit:
|
||||
- AST preserves structure,
|
||||
- static/linking phases own semantic compatibility and resolution rules.
|
||||
5. Unsupported declaration forms are deterministic parser/AST rejection with stable diagnostics.
|
||||
6. Recovery may continue after declaration syntax errors, but recovered AST must remain structurally coherent and attribution-consistent.
|
||||
7. Gate U evidence must include positive and negative declaration fixtures with AST-shape, attribution, and diagnostics assertions.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. Declaration AST remains obligations-first and implementation-language agnostic.
|
||||
2. Overload identity is not collapsed at AST layer.
|
||||
3. Missing required declaration metadata on mandatory nodes is non-conformant.
|
||||
4. Recovery must not fabricate permissive declaration shapes that hide syntax failures.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
1. This decision does not define static type-checking algorithms.
|
||||
2. This decision does not define lowering from `IRBackend` to `IRVM`.
|
||||
3. This decision does not define runtime/bytecode/verifier policy.
|
||||
4. This decision does not freeze one parser architecture.
|
||||
|
||||
## Spec Impact
|
||||
|
||||
1. `docs/pbs/specs/11. AST Specification.md` must encode declaration families, identity preservation, metadata minimums, and recovery/rejection invariants.
|
||||
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains authority for diagnostic identity/phase/attribution semantics consumed by declaration diagnostics.
|
||||
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume declaration metadata invariants as lowering preconditions.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:
|
||||
|
||||
1. valid declaration fixtures for each mandatory family,
|
||||
2. malformed declaration fixtures with deterministic rejection diagnostics,
|
||||
3. AST assertions for declaration identity, spans, and required metadata fields.
|
||||
@@ -0,0 +1,64 @@
|
||||
# AST Diagnostics, Recovery, and Gate Evidence Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-05
|
||||
Related Agenda: `docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md`
|
||||
|
||||
## Context
|
||||
|
||||
After closing AST contract, declaration surfaces, and statement/expression surfaces, PBS needed to close AST-facing diagnostics and parser-recovery policy plus the minimum Gate U evidence baseline.
|
||||
|
||||
Additionally, localization policy needed explicit alignment: diagnostics wording is locale-dependent and should be keyed by stable message tokens/template ids.
|
||||
|
||||
## Decision
|
||||
|
||||
PBS adopts the following AST diagnostics/recovery/evidence policy:
|
||||
|
||||
1. AST must preserve diagnostic fidelity:
|
||||
- required syntax diagnostics remain stable in `code`, `severity`, `phase`, `primary file`, and `primary span`.
|
||||
2. Human-readable message text is locale/rendering-dependent and not a conformance identity key.
|
||||
3. Stable diagnostics identity for i18n is carried by:
|
||||
- `diagnostic code`,
|
||||
- `phase`,
|
||||
- `message template id` (token),
|
||||
- and primary attribution.
|
||||
4. Parser recovery is allowed to continue diagnostics, but recovered AST must remain structurally coherent and attribution-consistent.
|
||||
5. Recovery must not fabricate permissive valid shapes that hide real syntax failures.
|
||||
6. Gate U AST evidence must include:
|
||||
- representative valid AST fixtures,
|
||||
- malformed/recovery fixtures,
|
||||
- deterministic diagnostics assertions,
|
||||
- and attribution assertions (`file/start/end`) on required nodes.
|
||||
7. Minimum mandatory negative fixture families include:
|
||||
- unexpected token in declaration context,
|
||||
- missing required closer (`)`, `}`, or `;`) as applicable,
|
||||
- non-associative forbidden chain forms,
|
||||
- unsupported form outside the active syntax slice with deterministic rejection.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. Diagnostics identity is token-based and locale-agnostic.
|
||||
2. Recovery cannot downgrade a required rejection into accepted semantics.
|
||||
3. AST attribution quality remains sufficient for `12` diagnostics contract and `13` lowering preconditions.
|
||||
4. Gate U fixtures must lock rejection stability for required AST-facing failures.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
1. This decision does not define transport-specific wire schemas.
|
||||
2. This decision does not define static type-checking rules.
|
||||
3. This decision does not define backend/runtime/verifier algorithms.
|
||||
4. This decision does not require one exact localized wording set.
|
||||
|
||||
## Spec Impact
|
||||
|
||||
1. `docs/pbs/specs/11. AST Specification.md` must encode recovery integrity and AST-facing rejection/recovery invariants.
|
||||
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains authority for diagnostics identity fields, including template/token identity.
|
||||
3. `docs/general/specs/13. Conformance Test Specification.md` provides Gate U evidence obligations referenced here.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Gate U validation should assert:
|
||||
|
||||
1. stable diagnostic identity keys (`code`, `phase`, template/token id, primary attribution),
|
||||
2. recovery integrity without semantic masking,
|
||||
3. deterministic results for the mandatory negative fixture families above.
|
||||
@@ -0,0 +1,51 @@
|
||||
# AST Statements and Expressions Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-05
|
||||
Related Agenda: `docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md`
|
||||
|
||||
## Context
|
||||
|
||||
After closing AST contract/root and declaration surfaces, PBS needed a precise v1 decision for statement/expression AST obligations, including precedence/associativity representation, unsupported-form behavior, and Gate U evidence.
|
||||
|
||||
## Decision
|
||||
|
||||
PBS adopts the following statement/expression AST policy for v1:
|
||||
|
||||
1. Mandatory statement/expression AST families must cover the supported PBS core syntax slice, including at minimum:
|
||||
- statements: `block`, `let`, `return`, expression statement, and other supported statement forms;
|
||||
- expressions: `identifier`, literals, `unary`, `binary`, `call`, `group`, and other supported expression forms.
|
||||
2. Precedence and associativity parsing outcomes are normative via AST shape and must be preserved explicitly.
|
||||
3. Non-associative or forbidden chained forms are deterministic reject with stable diagnostics.
|
||||
4. AST remains structural; semantic compatibility/type decisions are owned by static semantics/linking phases.
|
||||
5. Unsupported statement/expression forms are deterministic reject and must not be represented by permissive synthetic placeholder nodes that mask real rejection.
|
||||
6. Parser recovery may continue after syntax errors, but recovered AST must remain structurally coherent with stable attribution.
|
||||
7. Gate U evidence must include positive and negative fixtures with AST-shape assertions and diagnostics assertions.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. Statement/expression AST obligations are implementation-language agnostic.
|
||||
2. AST shape must not be post-rewritten in a way that changes source-observable parse meaning.
|
||||
3. Required nodes for diagnostics/lowering must preserve stable `file/start/end`.
|
||||
4. Recovery must preserve integrity and must not silently convert invalid syntax into valid semantics.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
1. This decision does not define static type-checking algorithms.
|
||||
2. This decision does not define `IRBackend -> IRVM` lowering.
|
||||
3. This decision does not define runtime/bytecode/verifier policy.
|
||||
4. This decision does not freeze one parser implementation strategy.
|
||||
|
||||
## Spec Impact
|
||||
|
||||
1. `docs/pbs/specs/11. AST Specification.md` must encode statement/expression node-family obligations, precedence/associativity shape obligations, and recovery/rejection invariants.
|
||||
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains the authority for stable diagnostics identity/phase/attribution requirements.
|
||||
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume statement/expression AST invariants as lowering preconditions.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:
|
||||
|
||||
1. valid fixtures proving expected precedence/associativity AST shape;
|
||||
2. invalid fixtures for non-associative or unsupported forms with deterministic diagnostics;
|
||||
3. assertions for stable node attribution (`file/start/end`) where diagnostics and lowering consume those nodes.
|
||||
@@ -0,0 +1,154 @@
|
||||
# Allocation and Cost Visibility Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial allocation-and-cost closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a minimal but explicit contract for which runtime cost facts matter semantically and which belong only to diagnostics/profiling quality.
|
||||
|
||||
Earlier decisions already fixed important inputs:
|
||||
|
||||
- `bind(context, fn_name)` has real retention/storage consequences,
|
||||
- `optional`, `result`, `handle`, `!`, `if`, and `switch` are not intended to hide implicit allocation semantics,
|
||||
- host/userland interaction is stack-only across the boundary,
|
||||
- and value categories already distinguish copied payload from preserved aliasing.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following cost-visibility baseline:
|
||||
|
||||
1. The normatively relevant cost facts are:
|
||||
- whether an operation may allocate VM-owned runtime storage,
|
||||
- whether an operation retains state beyond the current evaluation,
|
||||
- whether an operation copies payload versus preserves aliasing,
|
||||
- whether an operation crosses the host boundary,
|
||||
- and whether an operation may trap.
|
||||
2. `bind(context, fn_name)` is normatively retention-bearing and requires runtime storage sufficient to keep the callback target and captured context alive.
|
||||
3. `apply` is not allocation-bearing by itself.
|
||||
4. `optional`, `result`, `handle`, `!`, `if`, and `switch` are not allocation-bearing by themselves.
|
||||
5. Host-boundary crossing is a normatively relevant cost fact, but concrete host-side allocation details belong to subsystem-specific contracts rather than to a general PBS rule.
|
||||
6. Quantitative reporting such as exact byte counts, exact object counts, or precise collector timing is not a normative language guarantee in v1.
|
||||
|
||||
## 3. Normatively Relevant Cost Facts
|
||||
|
||||
The following cost facts are part of the PBS semantic model and may be relied on by later tooling/spec work:
|
||||
|
||||
- VM allocation-bearing versus non-allocation-bearing behavior,
|
||||
- retention-bearing versus non-retention-bearing behavior,
|
||||
- copy versus aliasing preservation,
|
||||
- host-boundary crossing,
|
||||
- trap possibility.
|
||||
|
||||
These facts matter because they affect how advanced tooling, diagnostics, and performance reasoning should interpret a construct.
|
||||
|
||||
## 4. `bind`
|
||||
|
||||
`bind(context, fn_name)` is the strongest closed cost case in the current PBS core.
|
||||
|
||||
Rules:
|
||||
|
||||
- `bind` is not semantically free,
|
||||
- `bind` is retention-bearing,
|
||||
- `bind` requires runtime storage sufficient to preserve the callback target and captured context,
|
||||
- the captured context remains alive while the callback value remains alive.
|
||||
|
||||
This decision does not require the spec to freeze the exact runtime layout used to implement that storage.
|
||||
|
||||
## 5. Non-Allocation-Bearing Surfaces
|
||||
|
||||
The following constructs are not allocation-bearing by themselves in PBS v1:
|
||||
|
||||
- `optional`
|
||||
- `result`
|
||||
- `handle`
|
||||
- `!`
|
||||
- `if`
|
||||
- `switch`
|
||||
- `apply`
|
||||
|
||||
If allocation or retention occurs while evaluating one of these constructs, that cost arises from:
|
||||
|
||||
- subexpression evaluation,
|
||||
- called targets,
|
||||
- payload formation already defined elsewhere,
|
||||
- or runtime behavior outside the surface itself.
|
||||
|
||||
## 6. Copy Versus Aliasing
|
||||
|
||||
Copy versus aliasing is a normatively relevant cost fact.
|
||||
|
||||
The language already distinguishes:
|
||||
|
||||
- pure values copied by value,
|
||||
- identity-bearing values passed by preserved aliasing,
|
||||
- carriers that preserve the semantics of their contained values.
|
||||
|
||||
Tooling and later specs may rely on these distinctions even if PBS v1 does not require a warning at every such site.
|
||||
|
||||
## 7. Host Boundary
|
||||
|
||||
Crossing the host boundary is a normatively relevant cost fact.
|
||||
|
||||
However, this decision does not impose a universal rule for:
|
||||
|
||||
- host-side allocation volume,
|
||||
- host-side object count,
|
||||
- or host-side retention internals.
|
||||
|
||||
Those details belong to subsystem-specific contracts when and if they become relevant.
|
||||
|
||||
## 8. Normative Versus Best-Effort Reporting
|
||||
|
||||
### 8.1 Normative facts
|
||||
|
||||
The following facts are normative and may be surfaced by diagnostics/tooling:
|
||||
|
||||
- whether a construct is retention-bearing,
|
||||
- whether a construct crosses the host boundary,
|
||||
- whether semantics preserve aliasing or copy payload,
|
||||
- whether a construct may trap.
|
||||
|
||||
### 8.2 Best-effort facts
|
||||
|
||||
The following facts are not normative language guarantees in v1:
|
||||
|
||||
- exact byte counts,
|
||||
- exact object counts,
|
||||
- exact collector timing,
|
||||
- exact host-side allocation volume,
|
||||
- precise performance ranking beyond the semantic facts above.
|
||||
|
||||
These may be surfaced by implementations as profiling or tooling enrichment, but they are not part of the core language contract.
|
||||
|
||||
## 9. Invariants
|
||||
|
||||
- The language must not imply hidden allocation semantics where none were intentionally specified.
|
||||
- `bind` remains the canonical retention-bearing callback-forming construct in v1.
|
||||
- Cost visibility must be strong enough for advanced tooling without forcing exact runtime accounting into the language spec.
|
||||
- Host-boundary cost reporting must not pretend to know subsystem-specific runtime internals unless those are explicitly specified.
|
||||
|
||||
## 10. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the final diagnostics wording for warnings or notes,
|
||||
- subsystem-specific host cost contracts,
|
||||
- precise collection/profiling metrics,
|
||||
- optimizer-facing reporting policy.
|
||||
|
||||
## 11. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
|
||||
## 12. Validation Notes
|
||||
|
||||
The intended split is:
|
||||
|
||||
- semantic cost facts are explicit,
|
||||
- `bind` is the main retained-storage construct already closed,
|
||||
- most other core surfaces are not allocation-bearing by themselves,
|
||||
- and quantitative performance reporting remains tooling-quality rather than normative language behavior.
|
||||
@@ -0,0 +1,133 @@
|
||||
# Artifact-Level Conformance and Fixture Model Decision
|
||||
|
||||
Status: Superseded
|
||||
Cycle: Conformance agenda closure pass
|
||||
|
||||
Superseded by:
|
||||
|
||||
- `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
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needed a decision for the point where conformance stops being source-only and begins asserting artifact-facing behavior.
|
||||
|
||||
The open questions from the conformance agenda closure pass and Workshop 3 were:
|
||||
|
||||
- whether artifact-level conformance is mandatory for every claim or only for full toolchain claims,
|
||||
- whether conformance should snapshot whole binaries or only stable invariants,
|
||||
- what the smallest honest fixture model is for stdlib and host-backed scenarios,
|
||||
- and how `13`, `12`, `15`, and `19` divide responsibility.
|
||||
|
||||
The adopted direction needed to keep full conformance meaningful without freezing one emitter layout, one repository structure, or one implementation-specific binary image.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following artifact-level conformance baseline:
|
||||
|
||||
1. Artifact-level conformance belongs only to `full toolchain conformance`.
|
||||
2. `frontend conformance` and `source-runtime conformance` do not require artifact-level oracle checks.
|
||||
3. Full toolchain conformance must assert stable artifact invariants rather than one opaque byte-for-byte binary snapshot.
|
||||
4. The conformance fixture model must explicitly declare the resolved environment assumptions that affect observable admission or lowering behavior.
|
||||
5. `12` defines what semantic and artifact-boundary facts lowering must preserve.
|
||||
6. `15` defines how the conformance-facing artifact facts appear in PBX/bytecode-visible form.
|
||||
7. `19` defines which later safety and validation obligations are checked by loader and verifier rather than by lowering itself.
|
||||
|
||||
## 3. Artifact-Level Oracle Baseline
|
||||
|
||||
The v1 artifact-level oracle is invariant-based.
|
||||
|
||||
Full toolchain conformance must be able to assert, at minimum:
|
||||
|
||||
1. required canonical host-binding declarations are emitted for admitted host-backed uses;
|
||||
2. `SYSC` entries are deduplicated by canonical identity;
|
||||
3. `SYSC` entry order follows first occurrence in the lowered program;
|
||||
4. host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>` referencing the emitted canonical binding set;
|
||||
5. VM-owned builtin projections, builtin constants, and intrinsic callsites do not leak into host-binding metadata such as `SYSC`;
|
||||
6. stdlib interface modules remain compile-time-only and do not emit executable bytecode by themselves;
|
||||
7. emitted artifacts preserve at least one source-attribution hook for backend failures that remain source-attributable and user-actionable under the diagnostics contract.
|
||||
|
||||
This baseline does not require:
|
||||
|
||||
- one full PBX binary snapshot,
|
||||
- one exact section byte layout outside the stable invariants above,
|
||||
- one exact source-map format,
|
||||
- or one verifier-internal trace shape.
|
||||
|
||||
## 4. Fixture Model
|
||||
|
||||
Conformance fixtures must model the resolved environment honestly whenever the selected environment affects acceptance, lowering, or artifact meaning.
|
||||
|
||||
Every fixture that depends on environment selection must declare, as applicable:
|
||||
|
||||
- selected stdlib environment or reserved stdlib line,
|
||||
- selected host registry line,
|
||||
- granted capability set,
|
||||
- and selected runtime line.
|
||||
|
||||
If an axis is irrelevant for a fixture, the fixture should declare that explicitly rather than leaving it implicit.
|
||||
|
||||
The minimum reusable fixture families for v1 are:
|
||||
|
||||
1. source-only fixtures whose expectations do not depend on host registry or runtime selection;
|
||||
2. stdlib-resolved fixtures that name the selected stdlib environment when reserved modules affect acceptance or behavior;
|
||||
3. host-admitted fixtures that name both host registry line and granted capabilities for positive host-backed cases;
|
||||
4. host-rejected fixtures that name the missing or unauthorized capability or host-registry condition for deterministic negative cases;
|
||||
5. full-toolchain artifact fixtures that name the runtime line whenever emitted intrinsic or host-binding form depends on the selected executable target line.
|
||||
|
||||
This model is intentionally small. It is sufficient to prevent fake portability claims while avoiding one mandatory repository layout.
|
||||
|
||||
## 5. Boundary Across `13`, `12`, `15`, and `19`
|
||||
|
||||
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;
|
||||
- `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.
|
||||
|
||||
Conformance therefore does not require `12` to define one binary encoding and does not require `15` to redefine semantic ownership already fixed in `12`.
|
||||
|
||||
## 6. Invariants
|
||||
|
||||
- Artifact-level conformance is required only for the full toolchain claim.
|
||||
- The v1 artifact oracle is invariant-based, not whole-image-based.
|
||||
- Fixture assumptions that change observable behavior must be explicit.
|
||||
- Host-binding metadata remains distinct from VM-owned builtin and intrinsic lowering.
|
||||
- The boundary among lowering, encoding, and verification must remain reviewable and non-overlapping.
|
||||
- Source-attributable backend failures must retain at least one recoverable source location, but richer debug surfaces remain optional.
|
||||
|
||||
## 7. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- which PBX sections beyond the current stable invariant baseline become part of the PBS-facing contract,
|
||||
- whether intrinsic declarations require an additional dedicated PBX preload section in v1,
|
||||
- the full verifier test surface for conformance,
|
||||
- the compatibility-matrix policy for aging and retirement of published combinations,
|
||||
- or one repository structure for the conformance corpus.
|
||||
|
||||
## 8. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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/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/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md`
|
||||
|
||||
## 9. Validation Notes
|
||||
|
||||
The intended operational reading is:
|
||||
|
||||
- a direct interpreter may still claim `source-runtime conformance` without artifact checks,
|
||||
- a full compiler toolchain must expose enough artifact surface to prove the stable invariants above,
|
||||
- and a host-backed test is not valid conformance evidence unless the selected registry, capability set, and runtime assumptions are declared where they affect the outcome.
|
||||
@@ -0,0 +1,164 @@
|
||||
# Compatibility Matrix and Published Claims Decision
|
||||
|
||||
Status: Superseded
|
||||
Cycle: Conformance and compatibility agenda closure pass
|
||||
|
||||
Superseded by:
|
||||
|
||||
- `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
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needed one operational policy for how support claims are published, tested, aged, and retired over time.
|
||||
|
||||
The open questions from the conformance closure pass, especially Workshop 4, and from `17. Compatibility and Evolution Policy Agenda.md`, Workshop 3 were:
|
||||
|
||||
- what enters the regression corpus,
|
||||
- which compatibility dimensions PBS must publish explicitly,
|
||||
- what counts as a published support claim,
|
||||
- how claims relate to conformance evidence,
|
||||
- and how supported combinations retire without becoming ambiguous.
|
||||
|
||||
The adopted direction needed to ensure that compatibility tables and support statements are executable commitments rather than prose-only promises.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline policy:
|
||||
|
||||
1. Published support claims must be represented by an explicit compatibility matrix.
|
||||
2. Every published supported combination must be backed by maintained conformance or regression evidence appropriate to the claim level being published.
|
||||
3. The regression corpus is not limited to bug reproductions; it also includes already-published normative examples, accepted behavior claims, and supported matrix combinations.
|
||||
4. Unsupported combinations must be stated explicitly rather than inferred from silence.
|
||||
5. Claim retirement must be deliberate: when support narrows or ends, the matrix entry, supporting tests, and migration/support note must all change together.
|
||||
|
||||
## 3. Compatibility Matrix Baseline
|
||||
|
||||
The minimum PBS compatibility matrix must expose, at minimum, the following dimensions where support is published:
|
||||
|
||||
1. language line,
|
||||
2. stdlib line when reserved stdlib environment selection affects the claim,
|
||||
3. runtime line when execution target selection affects the claim,
|
||||
4. conformance claim level.
|
||||
|
||||
The matrix must also expose an explicit support state for each published combination.
|
||||
|
||||
The minimum support states are:
|
||||
|
||||
- `supported`
|
||||
- `unsupported`
|
||||
- `provisional`
|
||||
|
||||
Meanings:
|
||||
|
||||
- `supported` means the combination is promised by the publisher and backed by maintained evidence.
|
||||
- `unsupported` means the combination is intentionally not promised and tools may reject or decline it without violating the published support policy.
|
||||
- `provisional` means the combination is published as incomplete or experimental and must not be confused with ordinary stable support.
|
||||
|
||||
Silence must not be used where a published matrix exists and a reasonable reader could infer support.
|
||||
|
||||
## 4. Published Claims and Evidence
|
||||
|
||||
A published support claim exists whenever a publisher represents, in user-facing or tool-facing form, that a combination or behavior is supported, conforming, or maintained.
|
||||
|
||||
This includes, at minimum:
|
||||
|
||||
- a matrix entry marked `supported`,
|
||||
- an unqualified or qualified PBS conformance claim,
|
||||
- compatibility statements in product or release documentation,
|
||||
- and published examples or fixtures presented as normative or supported behavior.
|
||||
|
||||
Every published claim must map to maintained executable evidence.
|
||||
|
||||
The evidence may be:
|
||||
|
||||
- conformance tests,
|
||||
- regression tests,
|
||||
- or both,
|
||||
|
||||
provided the evidence covers the claim scope actually being published.
|
||||
|
||||
`frontend conformance`, `source-runtime conformance`, and `full toolchain conformance` may therefore have different evidence sets, but each published claim still needs evidence inside its own scope.
|
||||
|
||||
## 5. Regression Corpus Policy
|
||||
|
||||
The regression corpus must preserve already-published behavior inside the scope of active support claims.
|
||||
|
||||
At minimum, the regression corpus must include:
|
||||
|
||||
1. bug reproductions for behavior that was fixed and remains within a supported scope;
|
||||
2. published examples that are treated as normative or supported behavior;
|
||||
3. accepted conformance claims and the behavior they promise;
|
||||
4. supported compatibility-matrix combinations and their required outcomes.
|
||||
|
||||
The regression corpus may be organized into separate slices by claim level or domain.
|
||||
|
||||
What matters normatively is:
|
||||
|
||||
- published supported behavior is regression-protected,
|
||||
- evidence remains attributable to the claim it protects,
|
||||
- and narrowing support requires deliberate retirement rather than silent drift.
|
||||
|
||||
## 6. Retirement and Narrowing Policy
|
||||
|
||||
When a supported combination is retired or narrowed:
|
||||
|
||||
1. the matrix entry must change explicitly;
|
||||
2. the old support state must not remain implied by stale documentation;
|
||||
3. the corresponding evidence must be retired, reclassified, or moved to a historical/non-supporting corpus deliberately;
|
||||
4. a migration, support-boundary, or rationale note must accompany the change when users could reasonably depend on the retired combination.
|
||||
|
||||
Retirement does not require one universal changelog format in this decision.
|
||||
|
||||
It does require that the support boundary become visible and reviewable.
|
||||
|
||||
## 7. Boundary Between `13` and `17`
|
||||
|
||||
The adopted split is:
|
||||
|
||||
- `13. Conformance Test Specification.md` defines the executable evidence obligations: what must enter the conformance or regression corpus and how supported claims become test-backed;
|
||||
- `17. Compatibility and Evolution Policy.md` defines the publication policy: which matrix dimensions and support states are required and how supported combinations age or retire.
|
||||
|
||||
This keeps `13` test-oriented and `17` promise-oriented while ensuring both documents describe the same support contract.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- Published support claims must be test-backed.
|
||||
- A compatibility matrix is normative only when its states have executable meaning.
|
||||
- `unsupported` must be explicit when omission would mislead users.
|
||||
- `provisional` must not be mistaken for ordinary supported compatibility.
|
||||
- Regression protection follows published supported behavior, not only bug history.
|
||||
- Narrowing support is a deliberate policy act, not an accidental omission.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- exact compatibility-window lengths by domain,
|
||||
- exact migration-tooling triggers,
|
||||
- PBX-specific binary compatibility policy,
|
||||
- release tooling implementation,
|
||||
- or one repository layout for matrix and regression data.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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/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
|
||||
|
||||
The intended operational reading is:
|
||||
|
||||
- if a publisher marks one matrix row as `supported`, there must be maintained evidence for that row;
|
||||
- if a combination is no longer supported, the matrix must say so explicitly rather than simply dropping mention of it;
|
||||
- and if an example or claim is published as supported behavior, it belongs in the regression story even if it did not originate as a bug report.
|
||||
@@ -0,0 +1,167 @@
|
||||
# Conformance Claim Levels Decision
|
||||
|
||||
Status: Superseded
|
||||
Cycle: Conformance agenda closure pass
|
||||
|
||||
Superseded by:
|
||||
|
||||
- `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
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needed a conformance-claim model that stays honest while the conformance corpus matures across frontend, runtime, and artifact-facing work.
|
||||
|
||||
The open questions from the conformance agenda closure pass and Workshop 1 were:
|
||||
|
||||
- whether PBS should use one conformance label or staged claims,
|
||||
- what a partial implementation is allowed to claim,
|
||||
- how published conformance claims must describe missing coverage,
|
||||
- and how claim levels constrain later compatibility policy.
|
||||
|
||||
The adopted direction needed to avoid two failure modes:
|
||||
|
||||
- pretending an unfinished backend is already full PBS v1 conformance,
|
||||
- and allowing vague marketing language that hides excluded domains such as artifact emission or verifier behavior.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts staged conformance claims.
|
||||
|
||||
The canonical claim levels are:
|
||||
|
||||
1. `frontend conformance`
|
||||
2. `source-runtime conformance`
|
||||
3. `full toolchain conformance`
|
||||
|
||||
These claims mean:
|
||||
|
||||
1. `frontend conformance` covers deterministic source acceptance and rejection behavior through parsing, manifest/import resolution, linking/static semantics, and the stable diagnostics surface required for those rejection tests.
|
||||
2. `source-runtime conformance` covers all frontend obligations plus source-level runtime, memory/identity, and host-boundary behavior already defined as language-observable in the active specs.
|
||||
3. `full toolchain conformance` covers all source-runtime obligations plus the artifact-facing, loader-facing, verifier-facing, and compatibility obligations required by the full active PBS v1 spec set.
|
||||
|
||||
Only `full toolchain conformance` may be published without qualifier as `PBS v1 conforming`.
|
||||
|
||||
Any narrower claim must remain explicitly qualified in published wording, for example:
|
||||
|
||||
- `PBS v1 frontend conforming`
|
||||
- `PBS v1 source-runtime conforming`
|
||||
|
||||
An implementation that does not satisfy one complete canonical level must not claim PBS conformance merely because it implements a subset such as parsing-only or parser-plus-binder behavior.
|
||||
|
||||
Any partial claim must explicitly state excluded domains when they matter to user expectations, including as applicable:
|
||||
|
||||
- artifact emission,
|
||||
- loader interaction,
|
||||
- verifier behavior,
|
||||
- supported runtime line,
|
||||
- selected stdlib environment,
|
||||
- host-registry line,
|
||||
- and capability assumptions.
|
||||
|
||||
The unqualified claim `PBS v1 conforming` is reserved until the artifact-facing conformance surface is fully closed in `13`, `12`, `15`, and `19`.
|
||||
|
||||
## 3. Claim Meanings
|
||||
|
||||
### 3.1 Frontend Conformance
|
||||
|
||||
`frontend conformance` is the minimum canonical PBS conformance claim.
|
||||
|
||||
It requires:
|
||||
|
||||
- deterministic parsing behavior,
|
||||
- deterministic source rejection for in-scope syntax, linking, and static-semantics failures,
|
||||
- deterministic manifest/import resolution outcomes,
|
||||
- regression protection for already-published behavior inside that claim scope,
|
||||
- and the stable diagnostics fields required by the diagnostics contract for those failures.
|
||||
|
||||
It does not imply:
|
||||
|
||||
- runtime execution support,
|
||||
- host-backed call execution,
|
||||
- artifact emission,
|
||||
- loader integration,
|
||||
- or verifier integration.
|
||||
|
||||
### 3.2 Source-Runtime Conformance
|
||||
|
||||
`source-runtime conformance` extends `frontend conformance`.
|
||||
|
||||
It additionally requires:
|
||||
|
||||
- source-level runtime oracle coverage,
|
||||
- source-level memory and identity oracle coverage,
|
||||
- host-boundary behavior already fixed by the Host ABI and capability specs at source-visible level,
|
||||
- and regression protection for already-published behavior inside that claim scope.
|
||||
|
||||
It does not by itself imply:
|
||||
|
||||
- one normative PBX image shape,
|
||||
- one artifact-level golden contract,
|
||||
- loader patching behavior beyond source-visible requirements,
|
||||
- or verifier-surface conformance.
|
||||
|
||||
### 3.3 Full Toolchain Conformance
|
||||
|
||||
`full toolchain conformance` is the top-level PBS v1 conformance claim.
|
||||
|
||||
It requires:
|
||||
|
||||
- all `source-runtime conformance` obligations,
|
||||
- all artifact-level oracle requirements once closed,
|
||||
- loader/verifier-facing acceptance and rejection obligations that belong to PBS-facing conformance,
|
||||
- required fixture modeling for stdlib, registry, capability, and runtime lines,
|
||||
- and maintained regression/compatibility evidence for every published supported combination inside the claim.
|
||||
|
||||
Until those artifact-facing obligations are normatively closed, implementations may publish only the narrower qualified claims above.
|
||||
|
||||
## 4. Naming and Publication Rules
|
||||
|
||||
- If the word `conforming` is used in a PBS v1 product claim, it must use one of the canonical claim levels.
|
||||
- The bare wording `PBS v1 conforming` is reserved for the full toolchain claim only.
|
||||
- `frontend` and `source-runtime` claims must keep the qualifier adjacent to the published claim and must not be shortened to imply full PBS v1 conformance.
|
||||
- If an implementation is still below `frontend conformance`, it should describe itself as partial, experimental, or implementation-specific rather than conforming.
|
||||
- Published conformance claims must state the tested scope when environment selection changes observable behavior.
|
||||
|
||||
## 5. Invariants
|
||||
|
||||
- PBS conformance is staged, not all-or-nothing, during the v1 maturation path.
|
||||
- The meaning of the unqualified top-level claim must remain stronger than any partial claim.
|
||||
- Partial claims must not hide excluded domains behind vague wording.
|
||||
- Conformance claims and compatibility claims are related but not identical; compatibility policy may refine promise strength per claim level without redefining the claim levels themselves.
|
||||
- Published claims must be backed by executable evidence in the conformance or regression corpus appropriate to that claim level.
|
||||
|
||||
## 6. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the full fixture model for stdlib, host-registry, capability, and runtime-line scenarios,
|
||||
- the final artifact-level oracle for PBX or lowering invariants,
|
||||
- the compatibility-matrix dimensions and retirement policy,
|
||||
- or the exact repository layout of the conformance corpus.
|
||||
|
||||
## 7. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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/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`
|
||||
|
||||
## 8. Validation Notes
|
||||
|
||||
The intended operational reading is:
|
||||
|
||||
- a parser-plus-binder implementation may claim `frontend conformance` only if it actually satisfies the complete frontend obligations, including deterministic rejection behavior and the stable diagnostics surface in scope,
|
||||
- an interpreter or direct-execution implementation may claim `source-runtime conformance` without yet claiming artifact or verifier conformance,
|
||||
- and no implementation should imply full PBS v1 conformance until the artifact-facing contract is normatively testable.
|
||||
@@ -0,0 +1,215 @@
|
||||
# Diagnostics Contract Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Diagnostics agenda closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needed one coherent diagnostics contract that closes the open questions from the diagnostics agenda:
|
||||
|
||||
- diagnostic identity,
|
||||
- attribution and cross-file reporting,
|
||||
- wording and localization boundaries,
|
||||
- warning and cost-diagnostics policy,
|
||||
- and the boundary between PBS-facing diagnostics and backend/artifact-facing failures.
|
||||
|
||||
The adopted direction needed to stay deterministic and conformance-friendly without freezing one editor UX, one compiler architecture, or one backend-internal reporting format.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following diagnostics baseline:
|
||||
|
||||
1. Every PBS-facing diagnostic has a mandatory `diagnostic code`.
|
||||
2. Every PBS-facing diagnostic has a mandatory `severity`.
|
||||
3. The stable external diagnostic phases include:
|
||||
- `syntax`,
|
||||
- `static semantics`,
|
||||
- `manifest/import resolution`,
|
||||
- `linking`,
|
||||
- `host-binding/capability admission`,
|
||||
- and load-facing rejection when directly attributable to malformed or unauthorized PBS-facing artifact usage.
|
||||
4. `linking` is a first-class diagnostics phase and should remain visible to users as part of the didactic pipeline.
|
||||
5. The minimum source-facing payload is:
|
||||
- `diagnostic code`,
|
||||
- `severity`,
|
||||
- `phase`,
|
||||
- `primary file`,
|
||||
- `primary span/location`,
|
||||
- and a human-readable message.
|
||||
6. The diagnostics model must also carry a stable `message template id` with stable named placeholders for localized rendering.
|
||||
7. Human wording is not byte-for-byte normative. The normative contract is the stable association among diagnostic code, message template id, placeholders, and rejection meaning.
|
||||
8. Implementations may localize rendered messages by language, provided the rendered message preserves the same normative rejection meaning.
|
||||
9. For future interoperability-oriented transports such as a possible LSP integration, implementations should preserve the ability to render an English default/fallback message even when a product renders another locale locally.
|
||||
10. In cross-file failures, the primary site must be the source location where the user action triggered the failure.
|
||||
11. `notes` and `related sites` are optional by default.
|
||||
12. For `duplicate` and `conflict` classes, at least one related site is mandatory.
|
||||
13. `hint` is a reserved diagnostics category in v1, but hint content is not mandatory.
|
||||
14. `help` and guided remediation are outside the core conformance contract in v1.
|
||||
15. Warnings are supported and recommended in v1, but they are not part of the minimum mandatory conformance baseline.
|
||||
16. Qualitative cost facts may be surfaced as warnings or notes, especially for:
|
||||
- retention-bearing `bind`,
|
||||
- host-boundary crossings,
|
||||
- and observable copy-versus-alias behavior.
|
||||
17. Quantitative reporting such as byte counts, allocation counts, and performance ranking is outside the diagnostics contract and belongs to profiling/tooling.
|
||||
18. Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract.
|
||||
19. Pure artifact corruption, verifier internals, loader internals, and compiler implementation bugs remain outside the PBS-facing diagnostics contract unless they are directly attributable to validly analyzed PBS source or to malformed/unauthorized PBS-facing artifact usage already in scope.
|
||||
20. When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format.
|
||||
|
||||
## 3. Diagnostic Identity and Payload
|
||||
|
||||
The minimum stable identity of a PBS-facing diagnostic is not free-form wording.
|
||||
|
||||
The stable identity is carried by:
|
||||
|
||||
- `diagnostic code`,
|
||||
- stable phase attribution,
|
||||
- and the rejection class semantics represented by the code/template pair.
|
||||
|
||||
The minimum externally relevant fields are:
|
||||
|
||||
- `diagnostic code`,
|
||||
- `severity`,
|
||||
- `phase`,
|
||||
- `primary file`,
|
||||
- `primary span/location`,
|
||||
- `message template id`,
|
||||
- stable named placeholders,
|
||||
- and a rendered human-readable message.
|
||||
|
||||
This baseline keeps diagnostics testable and localizable without forcing one exact byte-for-byte phrasing.
|
||||
|
||||
## 4. Cross-File Attribution
|
||||
|
||||
Cross-file attribution follows an action-first rule.
|
||||
|
||||
Rules:
|
||||
|
||||
- import failures point primarily to the importing site,
|
||||
- barrel failures point primarily to the barrel entry or reference site that triggered the failure,
|
||||
- linking or cross-module lookup failures point primarily to the use or reference site that could not be resolved,
|
||||
- related sites may be attached when known,
|
||||
- and `duplicate` or `conflict` diagnostics must include at least one related site in addition to the primary site.
|
||||
|
||||
This keeps diagnostics actionable for users and stable enough for conformance.
|
||||
|
||||
## 5. Message Rendering and Localization
|
||||
|
||||
PBS v1 permits localized diagnostics, including localized editor-first experiences.
|
||||
|
||||
The normative boundary is:
|
||||
|
||||
- codes are stable,
|
||||
- template ids are stable,
|
||||
- placeholders are stable,
|
||||
- and rendered wording may vary by locale and product surface.
|
||||
|
||||
Examples in specs should therefore be treated as illustrative unless a spec explicitly marks a template shape or placeholder contract as normative.
|
||||
|
||||
## 6. Categories, Notes, and Hints
|
||||
|
||||
The stable visible categories currently reserved are:
|
||||
|
||||
- `error`,
|
||||
- `warning`,
|
||||
- `note`,
|
||||
- `hint`.
|
||||
|
||||
`notes` are optional by default in v1.
|
||||
|
||||
`hint` exists in the diagnostics model from v1 onward so implementations can grow into educational guidance without changing the core schema.
|
||||
|
||||
This decision does not require one exact distinction between short hints and richer remediation flows.
|
||||
|
||||
## 7. Warning and Cost-Diagnostics Boundary
|
||||
|
||||
PBS v1 deliberately keeps warnings out of the minimum conformance baseline.
|
||||
|
||||
This means:
|
||||
|
||||
- implementations may emit warnings,
|
||||
- the editor can use warnings aggressively for pedagogy,
|
||||
- but conformance does not currently fail merely because an implementation omits optional warnings.
|
||||
|
||||
The diagnostics contract does recognize the importance of qualitative cost facts already fixed elsewhere, but it does not promote them to mandatory warnings in v1.
|
||||
|
||||
## 8. Backend-Originated Failure Boundary
|
||||
|
||||
PBS-facing diagnostics stop where failures stop being source-attributable and user-actionable.
|
||||
|
||||
In scope for PBS-facing diagnostics:
|
||||
|
||||
- lowering failures that reflect a normative source-facing lowering rule or impossibility,
|
||||
- verifier or loader rejections that are directly attributable to malformed or unauthorized PBS-facing artifact usage,
|
||||
- and backend-originated failures that can still be mapped back to source in a way the user can act on.
|
||||
|
||||
Out of scope for PBS-facing diagnostics:
|
||||
|
||||
- internal compiler exceptions,
|
||||
- implementation bugs,
|
||||
- artifact corruption not attributable to valid PBS source or to in-scope malformed/unauthorized artifact usage,
|
||||
- and backend-internal failure surfaces with no stable user-facing source attribution.
|
||||
|
||||
## 9. Conformance Boundary
|
||||
|
||||
The conformance surface for diagnostics should check only stable external fields.
|
||||
|
||||
Conformance may assert:
|
||||
|
||||
- rejection versus acceptance,
|
||||
- diagnostic code,
|
||||
- severity/category when in scope,
|
||||
- phase,
|
||||
- source attribution,
|
||||
- and related-site requirements for narrow classes such as `duplicate` or `conflict`.
|
||||
|
||||
Conformance should not require:
|
||||
|
||||
- one exact rendered message,
|
||||
- one exact localized wording,
|
||||
- one exact note shape outside explicitly required classes,
|
||||
- one verifier/loader internal format,
|
||||
- or one profiling/reporting style.
|
||||
|
||||
Warnings remain outside pass/fail conformance in v1, though any emitted warning must remain semantically compatible with the spec.
|
||||
|
||||
## 10. Invariants
|
||||
|
||||
- The diagnostics contract must remain deterministic across conforming implementations.
|
||||
- Diagnostic identity must not depend on one locale or one exact rendered sentence.
|
||||
- `linking` remains a visible diagnostics phase rather than being collapsed away into a generic resolution bucket.
|
||||
- Cross-file diagnostics must remain action-oriented from the user's point of view.
|
||||
- Localized rendering must not erase the stable machine-readable identity of a diagnostic.
|
||||
- The contract must stay narrow enough that more than one toolchain can implement it.
|
||||
- Backend-internal reporting must not leak into the PBS language contract unless the failure is source-attributable and user-actionable.
|
||||
|
||||
## 11. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the full warning catalog for future versions,
|
||||
- whether a future version promotes a subset of warnings into mandatory conformance,
|
||||
- exact remediation/help-content policy,
|
||||
- exact source-map or artifact-offset formats,
|
||||
- verifier trace schemas,
|
||||
- transport-specific LSP field mapping,
|
||||
- or internal compiler bug-reporting policy.
|
||||
|
||||
## 12. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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
|
||||
|
||||
The intended operational reading is:
|
||||
|
||||
- diagnostics are machine-identifiable first and human-rendered second,
|
||||
- localized editor UX is fully compatible with the contract,
|
||||
- a future interoperable transport can still fall back to English rendering,
|
||||
- warnings are available for pedagogy without being required for conformance,
|
||||
- and backend-originated failures only enter the PBS-facing contract when they still behave like actionable source diagnostics rather than internal tool failures.
|
||||
@@ -0,0 +1,128 @@
|
||||
# Dynamic Semantics - Branch Selection Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial branch-selection closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a closed runtime contract for `if` and `switch` before the dynamic semantics spec can be completed.
|
||||
|
||||
The remaining questions were:
|
||||
|
||||
- whether conditions and selectors are evaluated once,
|
||||
- whether non-selected branches evaluate at all,
|
||||
- which selector categories are admitted for `switch`,
|
||||
- and whether branch selection itself may trap.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following branch-selection rules:
|
||||
|
||||
1. `if` evaluates its condition exactly once.
|
||||
2. `switch` evaluates its selector exactly once.
|
||||
3. Only the selected branch or arm executes.
|
||||
4. Non-selected branches and arms perform no evaluation.
|
||||
5. `if` and `switch` are trap-free by themselves; only selected subexpressions may trap.
|
||||
6. `switch` is limited to statically discriminable selector categories.
|
||||
7. `switch` does not accept `result`, `error`, structs, string objects, or heap-backed types as selectors in v1.
|
||||
|
||||
## 3. `if`
|
||||
|
||||
For:
|
||||
|
||||
```text
|
||||
if cond { then_block } else { else_block }
|
||||
```
|
||||
|
||||
the runtime behaves as follows:
|
||||
|
||||
1. evaluate `cond` exactly once,
|
||||
2. if it yields `true`, execute only `then_block`,
|
||||
3. if it yields `false`, execute only `else_block`.
|
||||
|
||||
The non-selected branch is not evaluated, even partially.
|
||||
|
||||
Any trap associated with `if` arises only from:
|
||||
|
||||
- evaluating `cond`,
|
||||
- or executing the selected branch.
|
||||
|
||||
## 4. `switch`
|
||||
|
||||
### 4.1 Selector evaluation
|
||||
|
||||
For:
|
||||
|
||||
```text
|
||||
switch selector { ... }
|
||||
```
|
||||
|
||||
the runtime:
|
||||
|
||||
1. evaluates `selector` exactly once,
|
||||
2. determines the matching arm using the canonical matching rule for the selector category,
|
||||
3. executes exactly one selected arm.
|
||||
|
||||
No non-selected arm is evaluated.
|
||||
|
||||
### 4.2 Admitted selector categories
|
||||
|
||||
In v1, `switch` is restricted to selector categories with static, deterministic matching behavior.
|
||||
|
||||
These include:
|
||||
|
||||
- literal-comparable scalar values,
|
||||
- enum values,
|
||||
- `str` values with canonical static identity,
|
||||
- and other compile-time-constant-compatible selector categories only if explicitly admitted elsewhere.
|
||||
|
||||
`switch` does not accept:
|
||||
|
||||
- `result` values,
|
||||
- `error` values,
|
||||
- structs,
|
||||
- string object/reference types distinct from canonical `str`,
|
||||
- or heap-backed selector categories.
|
||||
|
||||
Dynamic or structural matching belongs to a future `match`-style construct rather than to `switch`.
|
||||
|
||||
### 4.3 Matching rule
|
||||
|
||||
`switch` arm selection is exact and deterministic for the admitted selector type.
|
||||
|
||||
- Enum selectors match by canonical enum-case identity.
|
||||
- Scalar selectors match by the exact equality rule already defined for that scalar category.
|
||||
- `str` selectors match by canonical static string identity rather than by heap-object comparison.
|
||||
|
||||
`switch` does not perform structural matching, guard evaluation, or user-defined equality dispatch.
|
||||
|
||||
## 5. Invariants
|
||||
|
||||
- `if` and `switch` never evaluate more than one branch or arm.
|
||||
- Branch selection is deterministic for the same selector value.
|
||||
- `switch` remains a static discriminant-selection construct, not a result/error-processing construct.
|
||||
- Error processing with logic belongs to `handle`, not to `switch`.
|
||||
|
||||
## 6. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the final future design of `match`,
|
||||
- whether additional scalar-like selector categories will be admitted later,
|
||||
- the complete memory/cost wording associated with selector evaluation.
|
||||
|
||||
## 7. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
|
||||
- `docs/pbs/specs/4. Static Semantics Specification.md`
|
||||
- `docs/pbs/specs/3. Core Syntax Specification.md`
|
||||
|
||||
## 8. Validation Notes
|
||||
|
||||
The intended split is:
|
||||
|
||||
- `if` and `switch` perform static, deterministic branch selection,
|
||||
- `handle` processes modeled `result` errors,
|
||||
- future dynamic or structural branching belongs to `match`, not to `switch`.
|
||||
@@ -0,0 +1,355 @@
|
||||
# Dynamic Semantics - Effect Surfaces Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial effect-surfaces closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 already commits to several effect and control surfaces in syntax and static semantics, but their runtime behavior must be closed before normative dynamic semantics can be written.
|
||||
|
||||
This decision record captures the first closed subset of that work:
|
||||
|
||||
- `optional`,
|
||||
- `result<E>`,
|
||||
- `!` propagation,
|
||||
- `handle` processing.
|
||||
|
||||
Allocation, retention, copy visibility, and heap-facing cost wording are delegated to the memory and heap decision track.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline runtime rules for `optional` and `result<E>` surfaces:
|
||||
|
||||
1. `optional` is a runtime presence/absence carrier with canonical `some(payload)` and `none` states.
|
||||
2. `some(expr)` evaluates `expr` eagerly and exactly once before forming the `some` carrier.
|
||||
3. `opt else fallback` evaluates the left operand exactly once and evaluates `fallback` only when the left operand is `none`.
|
||||
4. `optional` is trap-free by itself; only subexpression evaluation may trap.
|
||||
5. `result<E>` is the runtime carrier for expected, modelable failure in function return flow.
|
||||
6. `expr!` evaluates `expr` exactly once and performs immediate enclosing-function error propagation on failure.
|
||||
7. `handle expr { ... }` evaluates `expr` exactly once and, on error, executes exactly one matching arm.
|
||||
8. A `handle` arm may execute user-defined logic.
|
||||
9. A `handle` arm must terminate with either `ok(payload)` or `err(E2.case)`.
|
||||
10. `ok(payload)` in a `handle` arm recovers locally and yields the payload as the value of the `handle` expression.
|
||||
11. `err(E2.case)` in a `handle` arm performs immediate enclosing-function return with that error.
|
||||
12. `handle` supports a short remap form `E1.case -> E2.case` as sugar for a block that returns `err(E2.case)`.
|
||||
13. Neither `!` nor `handle` intercepts or converts traps.
|
||||
14. `apply` is the canonical universal call surface for PBS v1 across all callable categories.
|
||||
15. `apply` chains parse right-associatively but preserve the already-closed left-to-right observable evaluation model.
|
||||
16. `apply` does not introduce implicit composition of `optional` or `result` surfaces.
|
||||
17. `bind(context, fn_name)` forms a nominal callback value by attaching a struct context to a top-level function target.
|
||||
18. `bind` evaluates its context expression exactly once, captures the same runtime context identity without copying it, and injects that context as the first argument when the callback is invoked.
|
||||
19. `bind` is not a general closure mechanism and is trap-free at the language level.
|
||||
|
||||
## 3. `optional`
|
||||
|
||||
### 3.1 Runtime model
|
||||
|
||||
`optional` has exactly two runtime states:
|
||||
|
||||
- `some(payload)`
|
||||
- `none`
|
||||
|
||||
`none` is the canonical absence of payload.
|
||||
|
||||
### 3.2 Construction
|
||||
|
||||
`some(expr)`:
|
||||
|
||||
- evaluates `expr` eagerly,
|
||||
- evaluates it exactly once,
|
||||
- then forms the `some(payload)` carrier from the produced payload.
|
||||
|
||||
### 3.3 Extraction
|
||||
|
||||
`opt else fallback`:
|
||||
|
||||
1. evaluates `opt` exactly once,
|
||||
2. if the result is `some(payload)`, yields the extracted payload and does not evaluate `fallback`,
|
||||
3. if the result is `none`, evaluates `fallback` and yields that value.
|
||||
|
||||
`else` is extraction with fallback, not error handling.
|
||||
|
||||
### 3.4 Trap behavior
|
||||
|
||||
`optional` itself does not trap.
|
||||
|
||||
Any trap associated with `some(expr)` or `opt else fallback` arises only from:
|
||||
|
||||
- evaluating `expr`,
|
||||
- evaluating the left operand,
|
||||
- or evaluating the fallback when it is needed.
|
||||
|
||||
## 4. `result<E>`
|
||||
|
||||
### 4.1 Runtime role
|
||||
|
||||
`result<E>` is the runtime carrier for success-or-modeled-failure at function boundaries and in expressions whose static type is `result<E> P`.
|
||||
|
||||
In v1, `ok(...)` and `err(...)` are special result-flow forms.
|
||||
|
||||
They are not general-purpose first-class userland constructors for arbitrary data modeling.
|
||||
|
||||
They are valid in:
|
||||
|
||||
- function return flow for `result<E>`,
|
||||
- and `handle` arms, where they control recovery or propagation.
|
||||
|
||||
### 4.2 `!` propagation
|
||||
|
||||
`expr!`:
|
||||
|
||||
1. evaluates `expr` exactly once,
|
||||
2. if `expr` yields success, yields the extracted success payload as the value of the expression,
|
||||
3. if `expr` yields error, performs immediate enclosing-function return with the same `err(...)`.
|
||||
|
||||
`!` does not:
|
||||
|
||||
- remap the error,
|
||||
- intercept traps,
|
||||
- or continue ordinary evaluation after the propagated error path is chosen.
|
||||
|
||||
### 4.3 `handle`
|
||||
|
||||
`handle expr { ... }`:
|
||||
|
||||
1. evaluates `expr` exactly once,
|
||||
2. if `expr` yields success, yields the extracted success payload directly,
|
||||
3. if `expr` yields error, selects exactly one matching handle arm,
|
||||
4. executes the selected arm,
|
||||
5. requires that arm to terminate with either `ok(payload)` or `err(E2.case)`.
|
||||
|
||||
### 4.4 `handle` arm results
|
||||
|
||||
The selected `handle` arm has two admissible result forms:
|
||||
|
||||
- `ok(payload)`
|
||||
- `err(E2.case)`
|
||||
|
||||
Their semantics are:
|
||||
|
||||
- `ok(payload)` recovers locally and makes the `handle` expression yield `payload`,
|
||||
- `err(E2.case)` performs immediate enclosing-function return with `err(E2.case)`.
|
||||
|
||||
The `payload` in `ok(payload)` must be compatible with the success payload shape produced by the surrounding `handle` expression.
|
||||
|
||||
The `E2.case` in `err(E2.case)` must belong to the target error type required by the enclosing context.
|
||||
|
||||
### 4.5 `handle` sugar
|
||||
|
||||
For the common remap-only case, `handle` supports a short arm form:
|
||||
|
||||
```text
|
||||
E1.case -> E2.case
|
||||
```
|
||||
|
||||
This is sugar for:
|
||||
|
||||
```text
|
||||
E1.case -> { err(E2.case) }
|
||||
```
|
||||
|
||||
Recovery with `ok(payload)` requires the explicit block form.
|
||||
|
||||
### 4.6 `handle` scope
|
||||
|
||||
`handle` may execute user-defined logic inside an arm, but it remains specific to modeled `result` errors.
|
||||
|
||||
It does not provide:
|
||||
|
||||
- trap interception,
|
||||
- arbitrary processing of non-`result` failure channels,
|
||||
- or a general-purpose exception system.
|
||||
|
||||
## 5. Invariants
|
||||
|
||||
- `optional` models absence, not failure.
|
||||
- Expected recoverable failure remains in `result<E>`, not in `optional`.
|
||||
- `!` is an early-return propagation surface.
|
||||
- `handle` is a typed result-processing surface with controlled recovery or propagation.
|
||||
- Success paths produce payload values directly.
|
||||
- Error paths in `result<E>` remain explicit and typed.
|
||||
- Trap remains outside ordinary recoverable error flow.
|
||||
- `apply` remains the single semantic call surface even when user code uses direct-call sugar.
|
||||
- Callable-specific dispatch differences do not change the user-visible call pipeline.
|
||||
- Effect boundaries remain explicit; `apply` does not auto-lift through `optional` or `result`.
|
||||
|
||||
## 6. `apply`
|
||||
|
||||
### 6.1 Canonical role
|
||||
|
||||
`apply` is the canonical universal call surface in PBS v1.
|
||||
|
||||
Direct call syntax is only sugar over `apply` and does not define separate runtime semantics.
|
||||
|
||||
The same observable call model applies to:
|
||||
|
||||
- top-level functions,
|
||||
- struct methods,
|
||||
- service methods,
|
||||
- contract calls,
|
||||
- callback calls,
|
||||
- host-backed calls.
|
||||
|
||||
### 6.2 Shared observable pipeline
|
||||
|
||||
For `lhs apply rhs`, the shared observable runtime pipeline is:
|
||||
|
||||
1. form the call target from `lhs`,
|
||||
2. evaluate any receiver or callable artifact needed for target formation exactly once,
|
||||
3. evaluate `rhs` exactly once,
|
||||
4. invoke the resolved target,
|
||||
5. produce one of:
|
||||
- normal return,
|
||||
- explicit `result<Error>` propagation,
|
||||
- or `trap`.
|
||||
|
||||
Callable-specific dispatch strategy may differ internally, but it does not change this user-visible sequencing model.
|
||||
|
||||
### 6.3 Chained `apply`
|
||||
|
||||
`apply` chains are parsed right-associatively.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
f1 apply f2 apply f3 apply params
|
||||
```
|
||||
|
||||
parses as:
|
||||
|
||||
```text
|
||||
f1 apply (f2 apply (f3 apply params))
|
||||
```
|
||||
|
||||
The observable evaluation order still follows the already-closed left-to-right model:
|
||||
|
||||
1. form the target of `f1`,
|
||||
2. evaluate the argument expression for `f1`,
|
||||
3. within that argument expression, form the target of `f2`,
|
||||
4. evaluate the argument expression for `f2`,
|
||||
5. within that argument expression, form the target of `f3`,
|
||||
6. evaluate `params`,
|
||||
7. invoke `f3`,
|
||||
8. invoke `f2`,
|
||||
9. invoke `f1`.
|
||||
|
||||
### 6.4 Effect boundaries
|
||||
|
||||
`apply` does not introduce implicit effect composition.
|
||||
|
||||
If a callable returns:
|
||||
|
||||
- `optional<P>`, extraction remains explicit through `else`,
|
||||
- `result<E> P`, propagation or remapping remains explicit through `!` or `handle`.
|
||||
|
||||
PBS v1 does not auto-lift ordinary call chains through `optional` or `result` boundaries.
|
||||
|
||||
## 7. `bind`
|
||||
|
||||
### 7.1 Role
|
||||
|
||||
`bind(context, fn_name)` is the explicit callback-formation mechanism in PBS v1.
|
||||
|
||||
It exists to attach a struct context to a compatible top-level function without introducing general lexical closures.
|
||||
|
||||
### 7.2 Context and target
|
||||
|
||||
`bind` requires:
|
||||
|
||||
- a context expression whose runtime value is a struct instance,
|
||||
- a top-level function target whose first parameter is compatible with that struct type,
|
||||
- and an expected callback type already validated by static semantics.
|
||||
|
||||
### 7.3 Runtime artifact
|
||||
|
||||
`bind(context, fn_name)` produces a nominal callback value that stores:
|
||||
|
||||
- the resolved top-level function target,
|
||||
- the captured runtime identity of the context value.
|
||||
|
||||
The context is not copied or rematerialized during binding.
|
||||
|
||||
When the callback is later invoked, the runtime behaves as if it calls:
|
||||
|
||||
```text
|
||||
fn_name(context, ...)
|
||||
```
|
||||
|
||||
where `context` is the same captured runtime instance.
|
||||
|
||||
### 7.4 Evaluation and identity
|
||||
|
||||
The context expression is evaluated exactly once at bind time.
|
||||
|
||||
That evaluation exists only to obtain the struct instance that will be attached to the callback.
|
||||
|
||||
After capture:
|
||||
|
||||
- the same runtime context identity remains attached,
|
||||
- mutations performed through the callback observe and affect that same context instance,
|
||||
- `bind` does not create a detached copy of the context.
|
||||
|
||||
### 7.5 Storage and retention
|
||||
|
||||
`bind` is not semantically free.
|
||||
|
||||
Forming a callback through `bind` requires runtime storage sufficient to keep:
|
||||
|
||||
- the callback target identity,
|
||||
- and the captured context alive while the callback value remains alive.
|
||||
|
||||
For the purposes of PBS v1 semantics, `bind` should be treated as a callback-forming operation with real retention and heap-facing consequences, even though the final memory/lifetime wording belongs in the dedicated memory specification.
|
||||
|
||||
### 7.6 Trap behavior
|
||||
|
||||
At the language-semantics level, `bind` is trap-free.
|
||||
|
||||
Incompatible context type, incompatible function target, or invalid callback shape are compile-time errors rather than runtime traps.
|
||||
|
||||
`bind` introduces no ordinary recoverable error surface and no bind-specific trap surface.
|
||||
|
||||
### 7.7 Non-goal
|
||||
|
||||
`bind` is not:
|
||||
|
||||
- general closure capture,
|
||||
- arbitrary local-environment capture,
|
||||
- or a promise that future closure features must behave identically.
|
||||
|
||||
It is the explicit v1 callback-binding mechanism only.
|
||||
|
||||
## 8. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the final memory/lifetime wording for allocation, copy, and retention visibility,
|
||||
- the final catalog of trap sources that may arise from subexpression evaluation.
|
||||
|
||||
## 9. Spec Impact
|
||||
|
||||
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/12. Diagnostics Specification.md`
|
||||
|
||||
The unresolved cost and retention wording for these surfaces should be completed through:
|
||||
|
||||
- `docs/pbs/agendas/Memory and Lifetime - Agenda.md`
|
||||
- `docs/pbs/agendas/Heap Model - Agenda.md`
|
||||
|
||||
## 10. Validation Notes
|
||||
|
||||
The intended behavior is:
|
||||
|
||||
- `some(expr)` is eager,
|
||||
- `opt else fallback` is short-circuit on `some`,
|
||||
- `!` propagates the same typed error unchanged,
|
||||
- `handle` remaps typed errors without introducing custom logic,
|
||||
- `apply` remains the universal call surface across callable kinds,
|
||||
- chained `apply` does not create implicit optional/result composition,
|
||||
- `bind` captures a struct context identity without copying it,
|
||||
- `bind` forms a callback with real retention/storage consequences,
|
||||
- `handle` may recover with `ok(payload)` or propagate with `err(E2.case)`,
|
||||
- short-form `handle` arms are sugar for propagation-only remap blocks,
|
||||
- `trap` remains outside both `!` and `handle`.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Dynamic Semantics - Execution Model Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial execution-model closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS needs a closed execution-model baseline before effect surfaces and memory/lifetime semantics can be specified normatively.
|
||||
|
||||
The key open questions were:
|
||||
|
||||
- whether execution is single-threaded per program instance,
|
||||
- which runtime effects are observable to user code,
|
||||
- what the default evaluation order is,
|
||||
- which constructs guarantee single evaluation,
|
||||
- how abrupt completion behaves,
|
||||
- how `result<Error>` differs from `trap`,
|
||||
- and how host calls interact with `FRAME_SYNC` without perturbing user-visible sequencing.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following execution-model baseline:
|
||||
|
||||
1. Execution is single-threaded per program instance.
|
||||
2. User-visible execution is deterministic and does not expose concurrent interleaving.
|
||||
3. The default evaluation rule is strict left-to-right unless a construct explicitly states otherwise.
|
||||
4. Call evaluation proceeds by forming the call target first, then evaluating arguments left-to-right, then invoking the target.
|
||||
5. Abrupt completion terminates the current construct immediately and prevents later sibling evaluation.
|
||||
6. Recoverable, expected failures belong to `result<Error>`, not to `trap`.
|
||||
7. `trap` is reserved for non-recoverable runtime failures outside ordinary userland error flow.
|
||||
8. Any trap aborts the current PBS program execution rather than returning control to ordinary userland flow.
|
||||
9. `FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
10. `FRAME_SYNC` remains the execution boundary for userland progress; host-side work during that boundary must not reorder PBS-observable semantics.
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
- PBS v1 does not expose a user-visible concurrent execution model.
|
||||
- User-visible sequencing is defined by evaluation order, branch selection, abrupt completion, result propagation, trap propagation, and host-call boundaries.
|
||||
- Traps are not recoverable in userland and do not resume PBS execution.
|
||||
- VM-internal frame layout, temporary storage, and lowering steps are not observable unless they change the semantic effects above.
|
||||
- Unless a construct states otherwise, subexpressions are evaluated once and in left-to-right order.
|
||||
- `return`, `break`, `continue`, result propagation via `!`, and `trap` abort further evaluation in the current construct.
|
||||
- Host calls must not introduce user-visible reordering of already-defined PBS evaluation order.
|
||||
- No normative safepoint exists in v1 other than `FRAME_SYNC`.
|
||||
|
||||
## 4. Call Evaluation Rule
|
||||
|
||||
The runtime call rule for v1 is:
|
||||
|
||||
1. Form the call target.
|
||||
2. Evaluate any receiver that participates in target formation.
|
||||
3. Evaluate arguments in source order from left to right.
|
||||
4. Invoke the resolved target.
|
||||
5. Produce one of:
|
||||
- normal return,
|
||||
- explicit `result<Error>` propagation,
|
||||
- or `trap`.
|
||||
|
||||
This rule applies to canonical `apply` and to ordinary call sugar that desugars to `apply`.
|
||||
|
||||
## 5. Error Boundary
|
||||
|
||||
`result<Error>` and `trap` are distinct runtime categories.
|
||||
|
||||
### 5.1 `result<Error>`
|
||||
|
||||
`result<Error>` is the required mechanism for failures that are:
|
||||
|
||||
- expected by the API contract,
|
||||
- recoverable in ordinary userland control flow,
|
||||
- modelable through an explicit PBS error type.
|
||||
|
||||
Such failures may be:
|
||||
|
||||
- processed with `handle`,
|
||||
- propagated with `!`,
|
||||
- and discussed as part of ordinary function contract design.
|
||||
|
||||
### 5.2 `trap`
|
||||
|
||||
`trap` is reserved for failures that are:
|
||||
|
||||
- outside the ordinary userland contract,
|
||||
- not suitably representable as the declared `result<Error>` surface,
|
||||
- caused by runtime or host invariant failure,
|
||||
- or severe enough that ordinary userland recovery is not part of the v1 language model.
|
||||
|
||||
PBS v1 does not define `try/catch` for traps.
|
||||
Traps are not part of ordinary recoverable control flow.
|
||||
Once a trap is raised, PBS userland execution aborts and control transfers to runtime or firmware crash handling outside the ordinary language model.
|
||||
|
||||
## 6. Consequences
|
||||
|
||||
- User-authored code does not explicitly throw traps as part of ordinary PBS semantics.
|
||||
- API surfaces must not use trap as a substitute for a modelable `result<Error>` failure.
|
||||
- Host-backed operations must expose predictable operational failures through `result<Error>` when those failures are part of the callable contract.
|
||||
- Residual host or runtime failures that cannot be represented by the declared PBS contract may still trap.
|
||||
- The language-level consequence of trap is program abort rather than catchable failure handling.
|
||||
- In v1, no safepoint inventory is normative beyond `FRAME_SYNC`.
|
||||
|
||||
## 7. Explicit Non-Decisions
|
||||
|
||||
This decision does not yet close:
|
||||
|
||||
- the exact list of constructs with explicit single-evaluation wording as finally integrated into the dynamic-semantics spec,
|
||||
- the final wording split between dynamic semantics and runtime-initialization for trap/crash handoff.
|
||||
|
||||
Those points must be integrated by the remaining dynamic-semantics and memory/lifetime decisions.
|
||||
|
||||
## 8. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
|
||||
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
|
||||
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
|
||||
|
||||
It should also constrain future work in:
|
||||
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `docs/general/specs/13. Conformance Test Specification.md`
|
||||
|
||||
## 9. Validation Notes
|
||||
|
||||
The intended rule is:
|
||||
|
||||
- expected domain failure: `result<Error>`
|
||||
- remappable, processable, or propagatable failure: `result<Error>`
|
||||
- runtime invariant breakage or non-contract catastrophic failure: `trap`
|
||||
|
||||
In practical terms, a host-backed API must not rely on trap for ordinary operational failures if those failures can be declared and modeled explicitly in PBS. The only normative safepoint in v1 is `FRAME_SYNC`, and any trap aborts PBS userland execution rather than returning through an in-language recovery path.
|
||||
@@ -0,0 +1,130 @@
|
||||
# GC and Reachability Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial GC-and-reachability closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 uses GC as the baseline runtime model, but the language still needs a precise statement of:
|
||||
|
||||
- what reachability guarantees are normative,
|
||||
- what reclamation guarantees are normative,
|
||||
- what remains implementation-defined,
|
||||
- how GC interacts with the single normative safepoint at `FRAME_SYNC`,
|
||||
- and what user code may or may not observe.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following GC-and-reachability baseline:
|
||||
|
||||
1. GC is the baseline runtime model for VM-owned memory in PBS core.
|
||||
2. Reachability is the normative liveness criterion for GC-managed values.
|
||||
3. Eventual reclamation is the strongest reclamation guarantee in v1.
|
||||
4. `FRAME_SYNC` is the only normative safepoint relevant to GC-observable behavior.
|
||||
5. User code cannot observe reclamation directly.
|
||||
6. PBS v1 defines no user-authored finalizers, destructors, or reclamation callbacks.
|
||||
7. Implementations may perform internal GC work outside `FRAME_SYNC` only if doing so creates no additional user-visible semantic effects.
|
||||
|
||||
## 3. Normative Reachability Contract
|
||||
|
||||
For GC-managed VM-owned values, liveness is defined by reachability from the runtime roots that matter to PBS semantics.
|
||||
|
||||
At minimum, these roots include:
|
||||
|
||||
- currently active local/frame state,
|
||||
- reachable fields of reachable struct instances,
|
||||
- service singleton roots,
|
||||
- retained callback state that remains reachable,
|
||||
- and any other runtime roots required to preserve already-observable PBS behavior.
|
||||
|
||||
If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.
|
||||
|
||||
If a value becomes unreachable, user code must not rely on when reclamation occurs.
|
||||
|
||||
## 4. Reclamation Guarantee
|
||||
|
||||
PBS v1 guarantees eventual reclamation, not prompt reclamation.
|
||||
|
||||
This means:
|
||||
|
||||
- unreachable GC-managed memory may be reclaimed later,
|
||||
- the language does not promise immediate reclamation,
|
||||
- the language does not promise reclamation at a specific frame boundary,
|
||||
- and the language does not expose a semantic event when reclamation occurs.
|
||||
|
||||
## 5. Safepoint Relationship
|
||||
|
||||
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
|
||||
For GC semantics, this means:
|
||||
|
||||
- the language does not promise any additional observable GC safepoints,
|
||||
- no user-visible program rule may depend on another safepoint existing,
|
||||
- and any internal collector work outside `FRAME_SYNC` must remain semantically invisible to PBS userland.
|
||||
|
||||
The spec does not require a specific collector architecture.
|
||||
It only constrains what may become observable.
|
||||
|
||||
## 6. Observability
|
||||
|
||||
User code cannot observe reclamation directly.
|
||||
|
||||
PBS v1 provides no user-visible mechanism for:
|
||||
|
||||
- detecting that a value was collected,
|
||||
- registering a callback on reclamation,
|
||||
- forcing immediate collection,
|
||||
- or sequencing user code against GC timing.
|
||||
|
||||
GC-related information may appear in diagnostics, profiling, or runtime tooling, but those surfaces are not ordinary language semantics.
|
||||
|
||||
## 7. Finalization and Cleanup
|
||||
|
||||
PBS v1 forbids user-authored finalizers and destructor-like reclamation hooks.
|
||||
|
||||
GC reclamation of pure VM-owned values does not trigger user code.
|
||||
|
||||
Host-backed cleanup policy is not defined by GC finalization semantics in this decision.
|
||||
If host-backed resources require explicit or contract-specific cleanup rules, those belong to the host-boundary decision track rather than to GC finalization in userland.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- Reachability, not timing, is the normative semantic axis.
|
||||
- Reclamation timing remains implementation-defined.
|
||||
- No direct user-visible behavior is allowed to depend on collector timing.
|
||||
- The only normative safepoint is `FRAME_SYNC`.
|
||||
- GC must not create extra user-visible sequencing effects outside the already-closed execution model.
|
||||
|
||||
## 9. Beginner-Facing Model
|
||||
|
||||
The user-facing explanation should be:
|
||||
|
||||
- if a value can still be reached by the program, it remains alive,
|
||||
- once it can no longer be reached, the runtime may clean it up later,
|
||||
- the program does not control or directly observe that cleanup moment.
|
||||
|
||||
## 10. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the exact collector algorithm,
|
||||
- host-backed resource cleanup semantics,
|
||||
- diagnostics wording for GC-related tooling surfaces,
|
||||
- the full root-set wording as finally integrated into the memory specification.
|
||||
|
||||
## 11. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
|
||||
|
||||
## 12. Validation Notes
|
||||
|
||||
The intended split is:
|
||||
|
||||
- GC defines reachability and eventual reclamation,
|
||||
- `FRAME_SYNC` is the only normative safepoint,
|
||||
- reclamation timing is not user-observable,
|
||||
- host-backed cleanup is a separate boundary question rather than a user finalization feature.
|
||||
@@ -0,0 +1,115 @@
|
||||
# Host Memory Boundary Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial host-boundary closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS needs a user-visible contract for the boundary between VM-owned semantics and host-provided runtime services.
|
||||
|
||||
At the current stage of the language, userland does not expose complex host-owned resource models.
|
||||
The runtime offers features and the frontend consumes them; PBS should be careful not to project unnecessary language-level memory abstractions into runtime internals too early.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following host-memory boundary baseline:
|
||||
|
||||
1. Cross-boundary interaction between host and PBS userland is restricted to stack-only values.
|
||||
2. PBS userland does not expose host memory as ordinary language values.
|
||||
3. Raw pointers are not exposed in PBS userland.
|
||||
4. Borrowed host-memory views are not exposed in PBS userland.
|
||||
5. Pinning is not exposed in PBS v1.
|
||||
6. Zero-copy transfer is not exposed in PBS v1.
|
||||
7. Heap-shared boundary values between host and PBS userland are not part of the v1 model.
|
||||
8. Long-lived host resources, if later exposed, must be specified explicitly by subsystem contract rather than inferred from a general host-memory model.
|
||||
|
||||
## 3. Boundary Rule
|
||||
|
||||
The host/userland boundary in PBS v1 is value-based rather than memory-sharing-based.
|
||||
|
||||
This means:
|
||||
|
||||
- host-backed interaction happens through explicit call boundaries,
|
||||
- data crossing that boundary is limited to stack-only value forms,
|
||||
- and userland never receives direct access to host-owned memory regions.
|
||||
|
||||
PBS therefore does not model host memory as something the language can directly hold, borrow, pin, or traverse.
|
||||
|
||||
## 4. What Is Not Exposed
|
||||
|
||||
PBS v1 does not expose any general userland model for:
|
||||
|
||||
- raw host pointers,
|
||||
- borrowed host slices or views,
|
||||
- pinned host memory,
|
||||
- zero-copy host/userland transfer,
|
||||
- shared heap objects spanning host memory and VM memory.
|
||||
|
||||
These features are out of scope for the v1 language model.
|
||||
|
||||
## 5. Role of Syscalls
|
||||
|
||||
At the current stage, host interaction should be understood primarily through syscall-style host-backed contracts.
|
||||
|
||||
Those contracts may accept and return stack-only values, but they do not imply that PBS userland owns, borrows, or directly manipulates host memory.
|
||||
|
||||
## 6. Long-Lived Host Resources
|
||||
|
||||
PBS v1 does not yet define a general-purpose language model for long-lived host-owned resources such as:
|
||||
|
||||
- banks,
|
||||
- mixers,
|
||||
- or other subsystem-specific retained resources.
|
||||
|
||||
If such resources are exposed later, they must be specified by explicit subsystem contract rather than by assuming a general host-memory-handle model in core PBS.
|
||||
|
||||
## 7. Failure Model Scope
|
||||
|
||||
This decision does not force a universal language-level error projection for all runtime-internal host behavior.
|
||||
|
||||
It only closes the memory-boundary side of the question:
|
||||
|
||||
- PBS userland does not directly manipulate host memory,
|
||||
- and cross-boundary interaction remains stack-value-based.
|
||||
|
||||
Concrete error modeling for particular host-backed surfaces belongs to the contract of those surfaces rather than to a general raw-memory boundary rule.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- The host/runtime may own internal memory and resource lifetimes that PBS userland never sees directly.
|
||||
- PBS userland remains insulated from host-memory unsoundness by not exposing raw memory access at the language level.
|
||||
- The absence of pointers and borrowed host views is a core v1 safety property.
|
||||
- Boundary simplicity takes priority over premature expressiveness in this area.
|
||||
|
||||
## 9. Beginner-Facing Model
|
||||
|
||||
The user-facing explanation should be:
|
||||
|
||||
- the runtime can provide services to PBS programs,
|
||||
- programs pass ordinary values into those services and receive ordinary values back,
|
||||
- but programs do not directly hold or manipulate host memory.
|
||||
|
||||
## 10. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the future design of subsystem-specific long-lived host resources,
|
||||
- the future design of any explicit resource-release APIs,
|
||||
- the concrete error contract of each host-backed surface,
|
||||
- the final wording of host-boundary diagnostics.
|
||||
|
||||
## 11. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
|
||||
- `docs/pbs/specs/6. VM-owned vs Host-backed.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
|
||||
## 12. Validation Notes
|
||||
|
||||
The intended split is:
|
||||
|
||||
- runtime and host internals may remain complex,
|
||||
- PBS userland sees only stack-only value exchange across the boundary,
|
||||
- and any richer host-resource model must be introduced later by explicit subsystem contract.
|
||||
@@ -0,0 +1,64 @@
|
||||
# IRVM Optimization Stage Placement Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-07
|
||||
Related Agendas:
|
||||
|
||||
- `docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md`
|
||||
- `docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md`
|
||||
- `docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
|
||||
|
||||
## Context
|
||||
|
||||
Ao fechar a trilha backend executavel (`IRBackend -> IRVM -> bytecode`), surgiu a necessidade de definir onde a otimizacao deve ocorrer.
|
||||
|
||||
As opcoes praticas eram:
|
||||
|
||||
1. otimizar no runtime,
|
||||
2. otimizar durante emissao de bytecode,
|
||||
3. otimizar em etapa dedicada sobre `IRVM` antes da emissao.
|
||||
|
||||
O runtime atual privilegia determinismo, loader/verifier estritos e execucao numeric-only.
|
||||
|
||||
## Decision
|
||||
|
||||
PBS adota etapa dedicada de otimizacao entre lowering e emissao:
|
||||
|
||||
1. `LowerToIRVM` gera `IRVM`;
|
||||
2. `OptimizeIRVM` aplica transformacoes `IRVM -> IRVM` semanticamente equivalentes;
|
||||
3. `EmitBytecode` serializa o `IRVM` otimizado em artefato pre-load.
|
||||
|
||||
A etapa `OptimizeIRVM` passa a ser parte canônica do pipeline backend executavel.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. `OptimizeIRVM` e compile-time, nao runtime.
|
||||
2. `OptimizeIRVM` MUST preservar semantica observavel do programa.
|
||||
3. `OptimizeIRVM` MUST preservar contratos de chamada/retorno/slots.
|
||||
4. `OptimizeIRVM` MUST preservar determinismo para o mesmo grafo de entrada admitido.
|
||||
5. `OptimizeIRVM` MUST respeitar `vm_profile` alvo e nao deixar opcodes internos nao-eliminados para a emissao final.
|
||||
6. `EmitBytecode` continua responsavel por produzir artefato pre-load conforme contrato de loader/verifier.
|
||||
7. Runtime nao assume papel de otimizador semantico do programa.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
1. Esta decisao nao define o catalogo completo de passes de otimizacao.
|
||||
2. Esta decisao nao define heuristicas de custo/performance por alvo.
|
||||
3. Esta decisao nao redefine regras de verifier/loader do runtime.
|
||||
4. Esta decisao nao define fluxo de packer/cartucho.
|
||||
|
||||
## Spec Impact
|
||||
|
||||
1. A orquestracao de pipeline em `18.0` passa a incluir `OptimizeIRVM` entre `LowerToIRVM` e `EmitBytecode`.
|
||||
2. A futura spec de `IRVM` (`18.2`) deve explicitar pre/post-condicoes da etapa de otimizacao.
|
||||
3. A futura spec de marshaling (`18.3`) deve explicitar que a emissao opera sobre `IRVM` pos-otimizacao.
|
||||
4. `docs/general/specs/19. Verification and Safety Checks Specification.md` deve refletir cobertura de regressao para pipeline com otimizacao intermediaria.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Para validacao minima da decisao:
|
||||
|
||||
1. o pipeline executa na ordem `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`;
|
||||
2. fixtures equivalentes com e sem otimizacao produzem comportamento runtime equivalente;
|
||||
3. casos negativos de loader/verifier continuam falhando de forma deterministica apos a introducao de `OptimizeIRVM`.
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
# Lifetime Control and Future Profiles Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial lifetime-control policy closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 no longer uses the old RC/HIP model as an active core-language direction.
|
||||
|
||||
The remaining question is not how to design explicit lifetime control now, but how the project should treat legacy concepts and what policy should govern any future reintroduction of lifetime-oriented language features.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following lifetime-control policy baseline:
|
||||
|
||||
1. No lifetime-control keyword is reserved in core PBS merely for possible future use.
|
||||
2. If a lifetime-control surface is not active in v1, it should not remain in the language as a reserved future-only keyword on that basis alone.
|
||||
3. Advanced memory workflows should default to library/tooling-first exploration rather than syntax-first activation.
|
||||
4. GC remains the default core model; future explicit lifetime control, if ever introduced, must be profile-gated rather than silently folded into the default language.
|
||||
5. Future lifetime-oriented syntax may be introduced only when there is concrete evidence that library/tooling approaches are insufficient.
|
||||
|
||||
## 3. Legacy RC/HIP Concepts
|
||||
|
||||
Legacy concepts such as:
|
||||
|
||||
- `alloc`
|
||||
- `borrow`
|
||||
- `take`
|
||||
- `weak`
|
||||
- pool-style and arena-style control patterns
|
||||
- object reuse patterns
|
||||
|
||||
do not remain active merely by historical inertia.
|
||||
|
||||
For PBS v1 policy:
|
||||
|
||||
- legacy concepts may survive as historical or design-reference material,
|
||||
- but they do not imply reserved syntax commitment,
|
||||
- and they do not imply a roadmap promise of later activation.
|
||||
|
||||
## 4. Language Versus Library Boundary
|
||||
|
||||
The default policy is:
|
||||
|
||||
- library first,
|
||||
- tooling first,
|
||||
- profile later only if justified,
|
||||
- syntax last.
|
||||
|
||||
This means advanced workflows should first be explored through:
|
||||
|
||||
- stdlib APIs,
|
||||
- tooling support,
|
||||
- diagnostics,
|
||||
- profiling guidance,
|
||||
- subsystem-specific contracts where needed.
|
||||
|
||||
The language should not absorb explicit lifetime syntax simply because a legacy concept existed before.
|
||||
|
||||
## 5. Migration Narrative
|
||||
|
||||
The official migration narrative is:
|
||||
|
||||
- PBS v1 moves away from RC/HIP-style user-authored lifetime control as the core user model,
|
||||
- GC plus deterministic execution is the baseline,
|
||||
- performance-sensitive reasoning remains important,
|
||||
- but performance and memory control should rise through explicit APIs and tooling before new syntax is considered.
|
||||
|
||||
This is a deliberate simplification, not a temporary placeholder awaiting automatic return to explicit ownership syntax.
|
||||
|
||||
## 6. Future Activation Criteria
|
||||
|
||||
Any future lifetime-oriented language/profile work must satisfy all of the following:
|
||||
|
||||
1. Real implementation and product evidence shows that library/tooling-first approaches are insufficient.
|
||||
2. The proposed feature has a coherent semantic model that does not break the GC baseline by accident.
|
||||
3. The feature can be isolated behind an explicit profile or equivalent opt-in boundary.
|
||||
4. Diagnostics, conformance, and migration obligations are clear.
|
||||
5. The feature does not degrade the beginner-facing default language without strong justification.
|
||||
|
||||
Future activation must be justified by present need and validated design, not by preserving speculative syntax in the current language.
|
||||
|
||||
## 7. Invariants
|
||||
|
||||
- GC remains the default core runtime model.
|
||||
- Core PBS v1 does not promise future activation of legacy lifetime syntax.
|
||||
- Absence of reserved lifetime keywords is a deliberate policy choice.
|
||||
- Future explicit control must be explicit, justified, and profile-gated.
|
||||
|
||||
## 8. Beginner-Facing Model
|
||||
|
||||
The user-facing explanation should be:
|
||||
|
||||
- PBS v1 does not require ownership or lifetime syntax in ordinary code,
|
||||
- advanced control is not removed as a future possibility,
|
||||
- but it will be introduced only if it proves necessary and only through explicit design, not through dormant keywords left in the language.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the exact shape of any future profile mechanism,
|
||||
- the exact syntax of any future explicit lifetime feature,
|
||||
- the future stdlib design for pools, arenas, or weak-reference-like patterns.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
|
||||
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
|
||||
- `docs/pbs/specs/3. Core Syntax Specification.md`
|
||||
|
||||
## 11. Validation Notes
|
||||
|
||||
The intended policy is:
|
||||
|
||||
- no dormant lifetime keywords in core v1,
|
||||
- no nostalgia-based reservation policy,
|
||||
- library/tooling first,
|
||||
- profile-gated language activation only when clearly justified.
|
||||
+168
@@ -0,0 +1,168 @@
|
||||
# Name Resolution - Builtin Shells and Host Owners Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a deterministic rule for how reserved stdlib shells participate in source-level name resolution.
|
||||
|
||||
The open questions were:
|
||||
|
||||
- whether builtin shells and host owners enter lookup as ordinary imported declarations or as special compiler-only names,
|
||||
- whether builtin intrinsic methods participate in free callable lookup,
|
||||
- whether reserved shells receive special collision priority,
|
||||
- whether builtin shells belong under `@core:*` or `@sdk:*` by policy,
|
||||
- and which phase owns failures related to builtin member lookup and canonical identity duplication.
|
||||
|
||||
Important fixed inputs already existed:
|
||||
|
||||
- reserved stdlib project spaces are resolved from the selected stdlib environment,
|
||||
- source-visible builtin names resolve through imported builtin shell declarations,
|
||||
- canonical builtin and host identities come from metadata rather than local spelling,
|
||||
- builtin intrinsic methods are not imported as free functions,
|
||||
- and host-owner namespace remains distinct from type, value, and callable namespaces.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline for builtin shells and host-owner resolution:
|
||||
|
||||
1. Source-visible declarations exposed by reserved builtin shells are imported into their ordinary corresponding namespaces.
|
||||
2. 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.
|
||||
3. `declare builtin type` itself remains a reserved stdlib/toolchain declaration form rather than ordinary user-authored source syntax.
|
||||
4. Reserved-shell metadata exists to drive canonical identity and later lowering, not to create special source-level lookup priority.
|
||||
5. Builtin simple types `int`, `float`, `bool`, and `str` remain separate always-available reserved type names and are not treated as ordinary imported builtin shells.
|
||||
6. Builtin intrinsic methods never participate in free lookup.
|
||||
7. Builtin intrinsic methods are resolved only through member lookup on a receiver already known to have the corresponding builtin type.
|
||||
8. Reserved builtin shells and host owners follow the same collision policy as ordinary imported declarations: same visible name in the same namespace is an error unless another already-closed rule explicitly permits otherwise.
|
||||
9. By policy, builtin shells are preferred under `@core:*`.
|
||||
10. Member lookup failure on an already-typed builtin receiver belongs to static semantics.
|
||||
11. Duplicate canonical builtin identities or duplicate canonical host identities in one resolved environment belong normatively to linking rather than to syntax or ordinary static semantics.
|
||||
|
||||
## 3. Reserved Shells As Imported Declarations
|
||||
|
||||
Reserved shells are source-visible through ordinary import and visibility rules.
|
||||
|
||||
This means:
|
||||
|
||||
- the user imports the shell from a reserved stdlib module,
|
||||
- the imported shell becomes visible in the matching namespace,
|
||||
- and source-level lookup treats that visible declaration like other imported declarations of the same namespace.
|
||||
|
||||
The compiler still recognizes the reserved metadata attached to those declarations, but that metadata does not create a parallel hidden namespace.
|
||||
|
||||
## 4. Builtin Simple Types Versus Imported Builtin Shells
|
||||
|
||||
PBS distinguishes:
|
||||
|
||||
- the tiny predeclared builtin simple-type set: `int`, `float`, `bool`, `str`,
|
||||
- and imported builtin shells such as `Vec2`, `Color`, or similar stdlib-exposed types.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin simple types remain always available without import,
|
||||
- imported builtin shells are not promoted to that same status,
|
||||
- and the two categories must not be conflated in source-level lookup.
|
||||
|
||||
## 5. Intrinsic Member Lookup
|
||||
|
||||
Builtin intrinsic members are resolved only through receiver-member lookup.
|
||||
|
||||
Rules:
|
||||
|
||||
- they do not appear in top-level callable lookup,
|
||||
- they are not introduced by import as free functions,
|
||||
- and aliasing the owner builtin type changes only the local visible owner spelling, not the intrinsic's canonical identity.
|
||||
|
||||
This keeps member semantics uniform and avoids special free-function treatment for reserved surfaces.
|
||||
|
||||
## 6. Collision Policy
|
||||
|
||||
Reserved shells receive no special collision privilege.
|
||||
|
||||
Rules:
|
||||
|
||||
- if an imported builtin shell declaration and another visible declaration produce the same visible name in the same namespace, the program is rejected under the ordinary collision rules already chosen,
|
||||
- if a host owner shares a spelling with a type or value, that alone is not a conflict because host-owner namespace remains distinct,
|
||||
- and reserved-shell status does not authorize silent shadowing.
|
||||
|
||||
## 7. Reserved Project-Space Policy
|
||||
|
||||
For source-level policy:
|
||||
|
||||
- builtin shells are preferred under `@core:*`,
|
||||
- host-facing capability surfaces remain the natural fit for `@sdk:*`.
|
||||
|
||||
This is a policy direction for clarity and separation of concerns.
|
||||
It does not change the underlying ownership model governed by other specs.
|
||||
|
||||
## 8. Failure Ownership Baseline
|
||||
|
||||
The current baseline is:
|
||||
|
||||
- failure to resolve a reserved stdlib module remains manifest/import resolution,
|
||||
- import of a non-exported reserved shell remains linking,
|
||||
- member lookup failure on an already-typed builtin receiver remains static semantics,
|
||||
- duplicate canonical builtin or host identities in one resolved environment remain linking failures.
|
||||
|
||||
Implementations may internally perform some of these checks during environment validation, but the normative external phase ownership is linking where the linking-phase decision assigns it.
|
||||
|
||||
## 9. Invariants
|
||||
|
||||
- Reserved-shell metadata does not create special source-level lookup priority.
|
||||
- Builtin intrinsic methods are never free functions in source-level lookup.
|
||||
- Builtin simple types remain separate from stdlib-delivered builtin shells.
|
||||
- Host owners remain in the host-owner namespace only.
|
||||
- Ordinary collision rules apply to reserved-shell imports unless a later explicit rule says otherwise.
|
||||
- Canonical identity conflicts are linking problems, not syntax problems.
|
||||
|
||||
## 10. Explicit Non-Decisions
|
||||
|
||||
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 `13. Lowering IRBackend Specification.md`.
|
||||
|
||||
## 11. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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/13. Lowering IRBackend Specification.md`
|
||||
|
||||
## 12. Validation Notes
|
||||
|
||||
The intended baseline is:
|
||||
|
||||
- reserved builtin shells are imported like ordinary declarations into the matching namespace,
|
||||
- builtin methods are found only through receiver-member lookup,
|
||||
- builtin simple types remain always available without import,
|
||||
- `@core:*` is the preferred home for builtin shells,
|
||||
- and duplicate canonical builtin or host identities are rejected at linking time.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
```
|
||||
|
||||
`Vec2` becomes an imported visible type declaration with builtin metadata.
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
Vec2.zero()
|
||||
```
|
||||
|
||||
If `zero` is a builtin intrinsic member, it resolves through builtin member lookup on `Vec2`-typed receiver use and not through free callable lookup by the name `zero`.
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
declare const Vec2: int = 1;
|
||||
```
|
||||
|
||||
This is rejected as an ordinary same-namespace collision rather than resolved by reserved-shell priority.
|
||||
+173
@@ -0,0 +1,173 @@
|
||||
# Name Resolution - Callable Sets and Cross-Module Linking Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a deterministic rule for how callable names cross module boundaries.
|
||||
|
||||
The open questions were:
|
||||
|
||||
- what exactly `import { f } from @project:path;` imports when `f` has multiple exported signatures,
|
||||
- whether callable sets from different origins may merge,
|
||||
- whether same-name imported callables from different origins are tolerated until callsite analysis,
|
||||
- whether local and imported callable names may coexist under one visible function name,
|
||||
- and how `mod.barrel` bounds the callable set that becomes importable.
|
||||
|
||||
Earlier closure already fixed important inputs:
|
||||
|
||||
- `mod.barrel` is the single source of module visibility,
|
||||
- only `pub` names may be imported from another module,
|
||||
- local function names and imported function names with the same visible name are already being treated as collisions in this closure pass,
|
||||
- and callable identity is determined by callable shape rather than parameter-label spelling alone.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline for callable sets and cross-module linking:
|
||||
|
||||
1. `import { f } from @project:path;` imports the exported callable set named `f` from the target module.
|
||||
2. The imported callable set for `f` consists only of those overload signatures of `f` that are exported through that module's `mod.barrel`.
|
||||
3. Non-exported overloads in the target module do not participate in the imported callable set.
|
||||
4. Two imports of the same visible callable name are tolerated when they resolve to the same canonical underlying callable-set origin after module resolution.
|
||||
5. Such same-origin duplicate imports are redundant but not errors.
|
||||
6. Two imports of the same visible callable name from different canonical origins are rejected immediately.
|
||||
7. The program must not wait until a callsite to reject different-origin callable-name collisions.
|
||||
8. A module-local function name and an imported function name with the same visible name are rejected immediately.
|
||||
9. Automatic merging of callable sets across different origins is not permitted in this closure pass.
|
||||
10. Ordinary overload resolution occurs only after one unambiguous visible callable set has already been formed.
|
||||
|
||||
## 3. Imported Callable Set
|
||||
|
||||
The meaning of:
|
||||
|
||||
```pbs
|
||||
import { f } from @project:path;
|
||||
```
|
||||
|
||||
is:
|
||||
|
||||
- resolve the target module,
|
||||
- collect the exported callable entries named `f` from that module,
|
||||
- form the callable set consisting only of those exported overloads,
|
||||
- and make that callable set visible locally under the imported visible name.
|
||||
|
||||
This import does not:
|
||||
|
||||
- reach non-exported overloads,
|
||||
- merge with hidden module-internal overloads,
|
||||
- or import one overload at a time independently from the exported callable name.
|
||||
|
||||
## 4. Same-Origin Versus Different-Origin Imports
|
||||
|
||||
### 4.1 Same origin
|
||||
|
||||
If the same visible callable name is imported more than once and both imports resolve to the same canonical underlying callable-set origin:
|
||||
|
||||
- the duplicate import is tolerated,
|
||||
- but it remains redundant.
|
||||
|
||||
### 4.2 Different origin
|
||||
|
||||
If the same visible callable name is imported from different canonical origins:
|
||||
|
||||
- the program is rejected immediately,
|
||||
- and one of the imports must be removed or aliased.
|
||||
|
||||
The implementation must not:
|
||||
|
||||
- merge the callable sets,
|
||||
- defer the conflict to overload resolution,
|
||||
- or allow callsite context to decide which imported origin wins.
|
||||
|
||||
## 5. 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.
|
||||
|
||||
This preserves deterministic visibility and keeps callable origin traceable.
|
||||
|
||||
## 6. Barrel Boundary
|
||||
|
||||
`mod.barrel` defines the exact boundary of the callable set that may cross module boundaries.
|
||||
|
||||
Rules:
|
||||
|
||||
- only overloads exported through `mod.barrel` are part of the importable callable set,
|
||||
- overloads with the same source-level function name but not exported through `mod.barrel` are invisible to importing modules,
|
||||
- and imported callable-set visibility is therefore a direct consequence of the source module's barrel contract.
|
||||
|
||||
## 7. Overload Resolution Boundary
|
||||
|
||||
This decision deliberately separates:
|
||||
|
||||
- callable-set formation,
|
||||
- and overload resolution at a callsite.
|
||||
|
||||
The implementation must first form one unambiguous visible callable set.
|
||||
Only then may ordinary overload resolution operate on the candidate signatures of that set.
|
||||
|
||||
Callsite context must not be used to resolve ambiguity between different imported callable origins.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- Imported callable visibility is bounded by barrel export.
|
||||
- Different callable origins must not merge automatically.
|
||||
- Same-origin duplicate imports may be tolerated as redundancy, not as new callable contributions.
|
||||
- Local and imported function names do not coexist under one merged visible callable name in this closure pass.
|
||||
- Overload resolution happens after visible callable-set formation, not instead of it.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
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 `13. Lowering IRBackend Specification.md`.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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/13. Lowering IRBackend Specification.md`
|
||||
|
||||
## 11. Validation Notes
|
||||
|
||||
The intended baseline is:
|
||||
|
||||
- callable imports operate on exported callable names,
|
||||
- all exported overloads of that name come together from one module,
|
||||
- same-origin duplicate imports are tolerated,
|
||||
- different-origin same-name imports are rejected immediately,
|
||||
- and local/import callable collisions are also rejected immediately.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @a:m;
|
||||
```
|
||||
|
||||
This is tolerated as redundant same-origin duplication.
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @b:n;
|
||||
```
|
||||
|
||||
This is rejected immediately because the visible callable names match but the canonical origins differ.
|
||||
|
||||
```pbs
|
||||
fn f(a: int) -> int { ... }
|
||||
import { f } from @a:m;
|
||||
```
|
||||
|
||||
This is rejected as a local-versus-import callable collision.
|
||||
@@ -0,0 +1,200 @@
|
||||
# Name Resolution - Linking Phase Boundary Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs an explicit phase boundary around source-level name resolution so that:
|
||||
|
||||
- frontend implementation does not invent phase ownership,
|
||||
- diagnostics can attribute failures consistently,
|
||||
- conformance can test rejection classes coherently,
|
||||
- and later lowering work does not have to guess whether a failure belongs to syntax, linking, or typing.
|
||||
|
||||
Earlier closure already established rules for:
|
||||
|
||||
- module scope construction,
|
||||
- import naming and aliasing,
|
||||
- builtin shell visibility,
|
||||
- callable-set visibility across modules.
|
||||
|
||||
The remaining open question was how to classify the failure classes that arise while assembling visible declarations across files and modules.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following normative phase baseline for name resolution and related frontend failures:
|
||||
|
||||
1. `syntax` is a distinct normative phase.
|
||||
2. `manifest/import resolution` is a distinct normative phase.
|
||||
3. `linking` is a distinct normative phase.
|
||||
4. `static semantics` is a distinct normative phase.
|
||||
5. `syntax` owns malformed import grammar and other token-shape or grammar-shape failures.
|
||||
6. `manifest/import resolution` owns failures to resolve project space, reserved stdlib space, dependency graph, module path, or environment source.
|
||||
7. `linking` owns assembly of visible declarations across files and modules.
|
||||
8. `linking` therefore owns:
|
||||
- import of non-exported names,
|
||||
- unresolved barrel entries against module declarations,
|
||||
- collisions between visible imported names from different canonical origins,
|
||||
- local-versus-import visibility collisions,
|
||||
- callable-origin conflicts across module boundaries,
|
||||
- and duplicate canonical builtin or host identities in one resolved environment.
|
||||
9. `static semantics` owns declaration validity, type checking, member lookup once the receiver type is known, and overload resolution within an already-formed visible callable set.
|
||||
10. Member lookup failure on an already-typed builtin receiver belongs to `static semantics`.
|
||||
11. Ambiguity between different imported origins must be rejected in `linking` before any callsite analysis.
|
||||
|
||||
## 3. Phase Roles
|
||||
|
||||
### 3.1 Syntax
|
||||
|
||||
`syntax` owns failures that arise before module or declaration assembly.
|
||||
|
||||
Examples:
|
||||
|
||||
- malformed import declaration shape,
|
||||
- malformed alias syntax,
|
||||
- malformed declaration grammar,
|
||||
- unexpected tokens.
|
||||
|
||||
### 3.2 Manifest and Import Resolution
|
||||
|
||||
`manifest/import resolution` owns failures of locating and loading the source of a module or reserved environment.
|
||||
|
||||
Examples:
|
||||
|
||||
- unresolved `@project:*` dependency target,
|
||||
- unresolved reserved stdlib module,
|
||||
- invalid project-space selection,
|
||||
- failure to load the module source from the selected environment.
|
||||
|
||||
### 3.3 Linking
|
||||
|
||||
`linking` owns the assembly of the visible declaration space after modules have been found and loaded.
|
||||
|
||||
Examples:
|
||||
|
||||
- imported name is not exported by the target module,
|
||||
- `mod.barrel` entry does not resolve against declarations of the module,
|
||||
- two imports expose the same visible name from different canonical origins,
|
||||
- a local visible declaration collides with an imported visible declaration,
|
||||
- callable-origin conflicts across module boundaries,
|
||||
- duplicate canonical builtin identities in one resolved environment,
|
||||
- duplicate canonical host identities in one resolved environment.
|
||||
|
||||
### 3.4 Static Semantics
|
||||
|
||||
`static semantics` owns validation and typing of the already-linked visible program.
|
||||
|
||||
Examples:
|
||||
|
||||
- duplicate local declarations,
|
||||
- invalid declaration validity conditions,
|
||||
- type mismatch,
|
||||
- member lookup on a known receiver type,
|
||||
- overload resolution inside one already-visible callable set.
|
||||
|
||||
## 4. Linking As A Real Normative Phase
|
||||
|
||||
PBS keeps `linking` as a distinct normative phase rather than collapsing it fully into `static semantics`.
|
||||
|
||||
Reasoning:
|
||||
|
||||
- some failures arise only when assembling visible declarations across files and modules,
|
||||
- those failures are neither pure grammar failures nor ordinary local typing failures,
|
||||
- and naming `linking` gives diagnostics and conformance a stable vocabulary for them.
|
||||
|
||||
This does not require every implementation to expose one identical internal compiler pass graph.
|
||||
It only requires the externally visible failure ownership to map back to this normative phase model.
|
||||
|
||||
## 5. Barrel Matching And Visible Assembly
|
||||
|
||||
`mod.barrel` matching belongs to `linking`.
|
||||
|
||||
This means:
|
||||
|
||||
- failure of a barrel item to resolve to a declaration of the module is not merely a syntax issue,
|
||||
- and it is not deferred until later typing or lowering.
|
||||
|
||||
Barrel matching is part of assembling the module's visible declaration contract.
|
||||
|
||||
## 6. Imported-Origin Conflicts
|
||||
|
||||
Conflicts between different imported origins are rejected in `linking` immediately.
|
||||
|
||||
This means:
|
||||
|
||||
- the implementation must not wait for a specific callsite or use-site,
|
||||
- overload resolution is not allowed to rescue ambiguity between different imported origins,
|
||||
- and visible declaration conflicts are resolved structurally before later typing work proceeds.
|
||||
|
||||
## 7. Builtin Receiver Lookup
|
||||
|
||||
Member lookup on a builtin receiver whose type is already known remains `static semantics`.
|
||||
|
||||
The reason is:
|
||||
|
||||
- by that point the relevant shell visibility work has already completed,
|
||||
- and the remaining question is ordinary typed member validity rather than module assembly.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- The phase model exposed to users and conformance must remain deterministic.
|
||||
- `linking` remains the phase for visible declaration assembly across module boundaries.
|
||||
- Callsite analysis must not be used to resolve imported-origin conflicts.
|
||||
- `static semantics` operates on an already-linked visible declaration space.
|
||||
- Syntax and manifest/import resolution remain narrower than linking and do not absorb visible-name conflicts that arise only after module loading.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the full diagnostics-code taxonomy,
|
||||
- whether implementations expose one explicit user-facing `linking` label or a mapped equivalent wording class,
|
||||
- the final artifact-facing phase vocabulary after lowering and verification specs close,
|
||||
- and the exact implementation architecture of one compiler pipeline.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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/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`
|
||||
|
||||
## 11. Validation Notes
|
||||
|
||||
The intended phase split is:
|
||||
|
||||
- `syntax` parses declaration and import shape,
|
||||
- `manifest/import resolution` finds and loads modules,
|
||||
- `linking` assembles visible names across modules and barrels,
|
||||
- `static semantics` validates and types the already-linked visible program.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { Missing } from @a:m;
|
||||
```
|
||||
|
||||
If `@a:m` resolves successfully but does not export `Missing`, this is a `linking` failure.
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @b:n;
|
||||
```
|
||||
|
||||
If the canonical origins differ, this is a `linking` failure and is rejected before any callsite analysis.
|
||||
|
||||
```pbs
|
||||
import { Vec2 } from @core:math;
|
||||
value.zero()
|
||||
```
|
||||
|
||||
If `value` is already known to have builtin type `Vec2` and `.zero` is not a valid member on that receiver type, the failure is `static semantics`.
|
||||
@@ -0,0 +1,270 @@
|
||||
# Name Resolution - Scope, Lookup, and Imports Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial name-resolution closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a deterministic frontend-visible rule for:
|
||||
|
||||
- how module scope is formed,
|
||||
- how lookup works by namespace,
|
||||
- what imports actually introduce into local scope,
|
||||
- how collisions between local and imported names are handled,
|
||||
- and which failures belong to syntax, manifest/import resolution, static semantics, or linking.
|
||||
|
||||
Existing specs already fix important inputs:
|
||||
|
||||
- `mod.barrel` is the single source of module visibility,
|
||||
- imports target modules, not files,
|
||||
- only `pub` names may be imported from another module,
|
||||
- PBS has distinct type, value, callable, and host-owner namespaces,
|
||||
- builtin simple types `int`, `float`, `bool`, and `str` are always available in type position,
|
||||
- and reserved stdlib project spaces resolve only from the selected stdlib environment.
|
||||
|
||||
The remaining goal of this decision is to close the minimum name-resolution baseline needed for normative frontend work around ordinary scope construction, ordinary lookup, and import naming.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following baseline for scope construction, lookup, and imports:
|
||||
|
||||
1. Top-level declarations of a module are collected across all `.pbs` files in the module before visibility filtering is applied.
|
||||
2. `mod.barrel` is a visibility filter over existing module declarations, not the source of declaration existence.
|
||||
3. Module-internal top-level availability does not depend on source-file order.
|
||||
4. Local block scopes nest normally over module scope.
|
||||
5. In value position, lookup prefers the nearest lexical value binding before any module-level or imported value.
|
||||
6. Parameters and local `let` bindings participate in the same nearest lexical value-scope layer for lookup purposes.
|
||||
7. In type position, visible module-local type declarations are considered before imported type declarations, and builtin simple types remain always-available reserved type names outside ordinary import competition.
|
||||
8. In callable position, visible module-local callable declarations are considered before imported callable declarations.
|
||||
9. In host-owner position, visible module-local host owners are considered before imported host owners.
|
||||
10. The local visible name introduced by an import is always the post-alias name when an alias is present.
|
||||
11. `import { X } from @project:path;` introduces the imported exported name `X` into the matching namespace.
|
||||
12. `import { X as Y } from @project:path;` introduces only the local visible name `Y` into the matching namespace.
|
||||
13. Alias spelling changes only the local visible name, never canonical builtin identity or canonical host identity.
|
||||
14. `import { * } from @project:path;` is the whole-module import form for bringing the target module's exported names into local visibility under their exported names.
|
||||
15. A collision between a module-local declaration and an imported visible name in the same namespace is a deterministic error rather than silent shadowing.
|
||||
16. A collision between two imported visible names in the same namespace is not an error only when both imports denote the same canonical underlying declaration after module resolution.
|
||||
17. If two imported visible names in the same namespace come from different canonical underlying declarations, the program is rejected and one of the imports must be aliased or removed.
|
||||
18. `import { * } from @project:path;` does not create a first-class module object, module namespace value, or other source-visible binding by itself; it only introduces the exported names of the target module.
|
||||
19. A module-local function and an imported function with the same visible name produce a deterministic error in this closure pass.
|
||||
20. Non-callable namespaces do not merge by name.
|
||||
|
||||
## 3. Scope Construction
|
||||
|
||||
### 3.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,
|
||||
- then applies `mod.barrel` to determine `mod` and `pub` visibility.
|
||||
|
||||
This means:
|
||||
|
||||
- declaration existence is not derived from barrel entries,
|
||||
- and module-internal declaration availability is not ordered by file traversal.
|
||||
|
||||
### 3.2 Lexical scope
|
||||
|
||||
Inside executable bodies:
|
||||
|
||||
- lexical block scope is nested normally,
|
||||
- nearest local bindings win within value lookup,
|
||||
- and lexical nesting remains independent from cross-module visibility.
|
||||
|
||||
## 4. Lookup By Namespace
|
||||
|
||||
### 4.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 are one nearest lexical value layer.
|
||||
The distinction between them may still matter for diagnostics wording.
|
||||
|
||||
### 4.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 and do not participate in ordinary import competition.
|
||||
|
||||
### 4.3 Callable position
|
||||
|
||||
Callable-position lookup follows this order:
|
||||
|
||||
1. visible module-local callables,
|
||||
2. visible imported callables.
|
||||
|
||||
If a visible module-local function name and a visible imported function name are the same, the program is rejected in this closure pass rather than merged.
|
||||
|
||||
### 4.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.
|
||||
|
||||
## 5. Import Surface
|
||||
|
||||
### 5.1 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.
|
||||
|
||||
### 5.2 Aliased import
|
||||
|
||||
`import { X as Y } from @project:path;`:
|
||||
|
||||
- resolves the same exported declaration as the non-aliased form,
|
||||
- but introduces only `Y` as the local visible name.
|
||||
|
||||
Alias spelling does not change canonical identity governed elsewhere.
|
||||
|
||||
### 5.3 Whole-module import
|
||||
|
||||
`import { * } from @project:path;`:
|
||||
|
||||
- validates and 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 form.
|
||||
|
||||
## 6. Collision Policy
|
||||
|
||||
### 6.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 the imported declaration or the local declaration.
|
||||
|
||||
This includes function names.
|
||||
In this closure pass, a local function and an imported function with the same visible name are rejected rather than merged.
|
||||
|
||||
### 6.2 Imported versus imported
|
||||
|
||||
If two imports produce the same visible name in the same namespace:
|
||||
|
||||
- the program is not rejected if both imports resolve to the same canonical underlying declaration after module resolution,
|
||||
- but the duplicate import is still redundant,
|
||||
- and the program is rejected if the imports resolve to different canonical underlying declarations.
|
||||
|
||||
### 6.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.
|
||||
|
||||
## 7. Relationship To Later Name-Resolution Decisions
|
||||
|
||||
This decision is intentionally limited to:
|
||||
|
||||
- ordinary scope construction,
|
||||
- ordinary namespace lookup,
|
||||
- import naming,
|
||||
- and ordinary collision policy.
|
||||
|
||||
Later name-resolution decisions close:
|
||||
|
||||
- reserved builtin shells and host owners,
|
||||
- callable-set visibility across modules,
|
||||
- and the final phase boundary between syntax, manifest/import resolution, linking, and static semantics.
|
||||
|
||||
## 8. Invariants
|
||||
|
||||
- Name lookup must be deterministic.
|
||||
- Module-internal top-level declaration availability must not depend on file order.
|
||||
- `mod.barrel` remains a visibility mechanism rather than a declaration source.
|
||||
- Imports must not invent first-class module-object semantics accidentally.
|
||||
- The effective visible name of an import is always the post-alias name when an alias is present.
|
||||
- Builtin simple types remain a reserved always-available core type set, distinct from ordinary imported declarations.
|
||||
- Implementations must not assume silent local-over-import shadowing.
|
||||
- Implementations must not merge local and imported function names automatically.
|
||||
|
||||
## 9. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- reserved-shell-specific lookup and collision details,
|
||||
- callable-set import behavior across module boundaries beyond the local-versus-import collision baseline,
|
||||
- and backend-facing lowering consequences of the resolved lookup model.
|
||||
|
||||
## 10. Spec Impact
|
||||
|
||||
This decision should feed at least:
|
||||
|
||||
- `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/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`
|
||||
|
||||
## 11. Validation Notes
|
||||
|
||||
The intended baseline is:
|
||||
|
||||
- all top-level declarations in a module exist before barrel filtering,
|
||||
- lookup is namespace-specific and deterministic,
|
||||
- the effective visible import name is the alias name when an alias is present,
|
||||
- whole-module import through `import { * } from @project:path;` introduces exported names rather than a module object,
|
||||
- local/import collisions are rejected rather than shadowed,
|
||||
- and builtin simple types remain reserved always-available names outside ordinary import competition.
|
||||
|
||||
Illustrative examples:
|
||||
|
||||
```pbs
|
||||
import { Foo } from @a:m;
|
||||
declare const Foo: int = 1;
|
||||
```
|
||||
|
||||
This is rejected as a local-versus-import collision in the value namespace.
|
||||
|
||||
```pbs
|
||||
import { f } from @a:m;
|
||||
import { f } from @b:n;
|
||||
```
|
||||
|
||||
This is rejected because the visible imported names match but the canonical origins differ.
|
||||
|
||||
```pbs
|
||||
fn f(a: int) -> int { ... }
|
||||
import { f } from @a:m;
|
||||
```
|
||||
|
||||
This is rejected as a local-versus-import collision in callable position.
|
||||
|
||||
```pbs
|
||||
import { * } from @a:m;
|
||||
```
|
||||
|
||||
This introduces the exported visible names of `@a:m`, but does not introduce a source-visible module object in v1.
|
||||
|
||||
```pbs
|
||||
import { A as aaa } from @a:m;
|
||||
```
|
||||
|
||||
The visible local declaration name is `aaa`, not `A`.
|
||||
@@ -0,0 +1,44 @@
|
||||
# PBS Decisions
|
||||
|
||||
This directory contains PBS decision records.
|
||||
|
||||
## Purpose
|
||||
|
||||
A decision record is the bridge between agenda discussion and normative spec text.
|
||||
|
||||
Use this directory to capture:
|
||||
|
||||
- what was decided,
|
||||
- why that direction was chosen,
|
||||
- which constraints now apply,
|
||||
- what remains intentionally out of scope,
|
||||
- which specs must be updated.
|
||||
|
||||
Architecture and decisions must be resolved before implementation.
|
||||
|
||||
## Expected Format
|
||||
|
||||
A decision record should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Date or Cycle
|
||||
4. Context
|
||||
5. Decision
|
||||
6. Invariants
|
||||
7. Explicit Non-Decisions
|
||||
8. Spec Impact
|
||||
9. Validation Notes or Examples
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Write in stable, reviewable language.
|
||||
- State the adopted decision first and clearly.
|
||||
- Capture architectural constraints and invariants explicitly.
|
||||
- Record what is still not decided so later implementation does not guess.
|
||||
- Point to the exact specs that need integration.
|
||||
|
||||
## Implementation Rule
|
||||
|
||||
If implementation work exposes a missing decision, do not infer it.
|
||||
Stop, surface the ambiguity, and return it to agenda or decision review.
|
||||
@@ -0,0 +1,41 @@
|
||||
# SPAWN-YIELD v1 Claim Rescope Decision
|
||||
|
||||
Status: Accepted
|
||||
Cycle: Agenda 18 / PR-06.6
|
||||
|
||||
## Context
|
||||
|
||||
Os requisitos `G20-9.4.2` e `G20-9.4.3` estavam em estado `deferred` porque `SPAWN` e `YIELD` ainda nao fazem parte da superficie executavel v1 atualmente claimada pelo backend.
|
||||
|
||||
Sem uma decisao formal, o claim ficava ambiguo para auditoria externa.
|
||||
|
||||
## Decision
|
||||
|
||||
Adotamos oficialmente a **Trilha B**.
|
||||
|
||||
1. `SPAWN` e `YIELD` ficam fora do escopo do claim executavel `core-v1`.
|
||||
2. O backend v1 deve tratar essas formas como nao-suportadas no escopo claimado.
|
||||
3. Invariantes especificas de aridade/stack para `SPAWN` e `YIELD` ficam reservadas para um perfil futuro que as admita explicitamente.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. Nenhum claim `core-v1` pode implicar suporte executavel a `SPAWN`/`YIELD`.
|
||||
2. Se um perfil futuro admitir `SPAWN`/`YIELD`, deve publicar evidencias de conformidade dedicadas antes de claim de suporte.
|
||||
3. Matriz de conformidade deve explicitar o rescope para evitar regressao silenciosa de claim.
|
||||
|
||||
## Spec Impact
|
||||
|
||||
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`:
|
||||
- secao 9.4 passa a declarar `SPAWN`/`YIELD` fora do escopo de `core-v1`.
|
||||
2. `docs/general/specs/17. Compatibility and Evolution Policy.md`:
|
||||
- claims suportados devem explicitar superficies executaveis excluidas.
|
||||
3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`:
|
||||
- linhas `G20-9.4.2` e `G20-9.4.3` saem de `deferred` para status alinhado ao rescope.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Validacao desta decisao e documental/policy:
|
||||
|
||||
1. testes de integridade de spec/matriz para `SPAWN`/`YIELD` claim rescope;
|
||||
2. verificacao explicita de status e notas na matriz;
|
||||
3. rastreabilidade via esta decision record.
|
||||
@@ -0,0 +1,190 @@
|
||||
# Value Representation and Identity Decision
|
||||
|
||||
Status: Accepted (Implemented)
|
||||
Cycle: Initial value-representation closure pass
|
||||
|
||||
## 1. Context
|
||||
|
||||
PBS v1 needs a stable user-visible model for:
|
||||
|
||||
- which values are pure copied payloads,
|
||||
- which values preserve shared runtime identity,
|
||||
- which carriers merely wrap other values,
|
||||
- and how callback values fit into the language without exposing general first-class functions or closures.
|
||||
|
||||
Earlier decisions already fixed important inputs:
|
||||
|
||||
- structs are reference-like in ordinary use,
|
||||
- services are canonical singleton values,
|
||||
- `bind(context, fn_name)` captures the same struct identity without copying it,
|
||||
- `optional` and `result` remain explicit carriers rather than implicit effect-lifting mechanisms.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
PBS v1 adopts the following value-representation baseline:
|
||||
|
||||
1. Pure scalar-like values are copied by value and do not carry user-visible identity.
|
||||
2. Struct values are identity-bearing, heap-backed reference values.
|
||||
3. Service values are identity-bearing canonical singleton values.
|
||||
4. Host-backed resource values are identity-bearing values on the PBS side, even though their backing authority remains host-owned.
|
||||
5. Tuple, `optional`, and `result` carriers do not introduce identity of their own.
|
||||
6. Contract values do not introduce a new user-visible identity distinct from the underlying struct or service value.
|
||||
7. Callback values are first-class callable values in PBS v1, but callback identity is not promoted as a user-visible identity concept.
|
||||
8. Assignment, parameter passing, and return preserve aliasing for identity-bearing values and copy payload for pure value kinds.
|
||||
|
||||
## 3. Value Categories
|
||||
|
||||
### 3.1 Pure copied values
|
||||
|
||||
The following value kinds are pure copied values in the user model:
|
||||
|
||||
- `int`
|
||||
- `float`
|
||||
- `bool`
|
||||
- enum values
|
||||
- canonical `str`
|
||||
|
||||
Assignment, parameter passing, and return of these values copy the value itself.
|
||||
|
||||
### 3.2 Identity-bearing values
|
||||
|
||||
The following value kinds carry stable user-visible identity:
|
||||
|
||||
- struct values
|
||||
- service values
|
||||
- host-backed resource/handle values
|
||||
|
||||
Assignment, parameter passing, and return of these values preserve aliasing to the same runtime entity rather than copying an independent underlying object.
|
||||
|
||||
### 3.3 Carrier-only values
|
||||
|
||||
The following value kinds are carriers and do not create identity of their own:
|
||||
|
||||
- tuples
|
||||
- `optional`
|
||||
- `result`
|
||||
|
||||
They preserve the semantics of the values they contain.
|
||||
|
||||
If a carrier contains an identity-bearing payload, the carrier transports that same payload identity rather than inventing a new one.
|
||||
|
||||
## 4. Structs
|
||||
|
||||
Struct values are always reference-like in PBS v1.
|
||||
|
||||
Rules:
|
||||
|
||||
- `new Struct(...)` produces a fresh struct identity.
|
||||
- Assignment of a struct value copies the reference, not the underlying field storage.
|
||||
- Passing or returning a struct value preserves aliasing to the same struct instance.
|
||||
- Mutation through one alias is observable through other aliases to that same struct instance.
|
||||
|
||||
## 5. Services
|
||||
|
||||
Service values are canonical module-owned singleton values.
|
||||
|
||||
Rules:
|
||||
|
||||
- A service value denotes the same singleton identity wherever it is used in the same resolved program.
|
||||
- Assignment, parameter passing, and return preserve that same singleton identity.
|
||||
- Service use does not create fresh service instances.
|
||||
|
||||
## 6. Contract Values
|
||||
|
||||
Contract values do not introduce a new user-visible entity.
|
||||
|
||||
A contract value is a runtime view over:
|
||||
|
||||
- an underlying struct identity or service singleton identity,
|
||||
- together with the selected contract implementation used for dispatch.
|
||||
|
||||
For user-facing semantics:
|
||||
|
||||
- aliasing is defined by the underlying struct or service value,
|
||||
- not by treating the contract wrapper as a separate identity-bearing object.
|
||||
|
||||
## 7. Callback Values
|
||||
|
||||
Callback values are first-class callable values in PBS v1.
|
||||
|
||||
This means they may be:
|
||||
|
||||
- assigned to variables,
|
||||
- passed as arguments,
|
||||
- and returned from functions.
|
||||
|
||||
However, PBS v1 does not promote callback identity as an explicit user-visible identity concept.
|
||||
|
||||
### 7.1 Plain callback values
|
||||
|
||||
When a callback value is formed from a compatible top-level `fn`, it denotes a callable value over that target function.
|
||||
|
||||
### 7.2 Bound callback values
|
||||
|
||||
When a callback value is formed through `bind(context, fn_name)`:
|
||||
|
||||
- the same struct context identity is captured,
|
||||
- the context is not copied,
|
||||
- the callback retains the target function together with that captured context,
|
||||
- and invoking the callback behaves as if the target function is called with the captured context as its first argument.
|
||||
|
||||
### 7.3 User model
|
||||
|
||||
The language must explain callback behavior without requiring the user to reason about callback identity as if callbacks were ordinary heap objects.
|
||||
|
||||
It is sufficient to state that:
|
||||
|
||||
- callbacks are first-class callable values,
|
||||
- bound callbacks retain their captured context,
|
||||
- and copies of a callback value preserve the same callable meaning and retained context.
|
||||
|
||||
## 8. Copy Versus Aliasing Rule
|
||||
|
||||
The general rule for PBS v1 is:
|
||||
|
||||
- pure value kinds are copied by value,
|
||||
- identity-bearing kinds preserve aliasing,
|
||||
- carrier kinds preserve the semantics of their contained values and do not create identity of their own.
|
||||
|
||||
Examples:
|
||||
|
||||
- assigning an `int` copies the integer value,
|
||||
- assigning a `Struct` value copies the reference to the same struct instance,
|
||||
- assigning an `optional<Player>` that contains `some(player)` preserves the same `Player` identity inside the carrier,
|
||||
- assigning a `result<E> Player` success payload preserves the same `Player` identity inside the carrier.
|
||||
|
||||
## 9. Beginner-Facing Model
|
||||
|
||||
The user-facing explanation should be:
|
||||
|
||||
- some values are plain data, so passing them passes the value,
|
||||
- structs and services are shared entities, so passing them passes access to the same entity,
|
||||
- tuples, `optional`, and `result` only package values and do not become new entities by themselves,
|
||||
- callbacks are callable values, and bound callbacks keep the same captured context rather than copying it.
|
||||
|
||||
This wording is simple enough for beginners while still preserving the performance-relevant truth about aliasing and mutation.
|
||||
|
||||
## 10. Explicit Non-Decisions
|
||||
|
||||
This decision record does not yet close:
|
||||
|
||||
- the exact runtime layout of any heap object,
|
||||
- collection value categories in detail,
|
||||
- the final host-backed handle representation syntax,
|
||||
- the final diagnostics wording for aliasing/copy visibility.
|
||||
|
||||
## 11. Spec Impact
|
||||
|
||||
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/12. Diagnostics Specification.md`
|
||||
|
||||
## 12. Validation Notes
|
||||
|
||||
The intended split is:
|
||||
|
||||
- structs, services, and host-backed resources behave like identity-bearing entities,
|
||||
- tuples, `optional`, and `result` are carriers,
|
||||
- callbacks are first-class callable values without promoted callback identity in the user model.
|
||||
Reference in New Issue
Block a user