globals and synthetic inits

This commit is contained in:
2026-03-24 13:42:58 +00:00
parent ecea7e96c0
commit 42255c38d0
4 changed files with 711 additions and 5 deletions
@@ -0,0 +1,210 @@
# Diagnostics, Manifest Propagation, and Conformance Coverage Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
## Context
After closing globals, lifecycle markers, published wrapper ownership, and lowering structure, PBS v1 still needed one final consolidation step for topic `19`.
The remaining work was no longer architectural debate.
It was operational consolidation across the whole line:
- which diagnostics are now mandatory,
- which phase owns each failure surface,
- which specs and cross-domain artifacts must be updated,
- and what minimum conformance evidence is required before execution planning begins.
Important fixed inputs already existed:
- `19.1` closed the source surface and dependency rules for globals;
- `19.2` closed lifecycle markers, init ordering, and init restrictions;
- `19.3` closed published wrapper ownership, physical entrypoint `0`, and manifest protocol direction;
- `19.4` closed explicit lowering structure, synthetic callable classes, hidden boot guard policy, and lowering-side invariants.
## Decision
PBS accepts the following consolidation for topic `19`:
1. The diagnostics line for family `19` is grouped by phase rather than by historical agenda order.
2. The final propagation line for family `19` must name PBS specs, general compiler specs, runtime cross-domain ownership, and `learn`.
3. The conformance line for family `19` must cover positive flow, negative frontend coverage, negative lowering coverage, and runtime integration.
4. Runtime-side work required by entrypoint protocol changes remains explicitly cross-domain and is owned through:
- `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
## Consolidated Diagnostics
PBS adopts the following minimum diagnostics and failure surfaces for family `19`.
### Frontend / Static Semantics
The compiler must provide, at minimum:
1. `global initializer uses unsupported form`
2. `global dependency cycle detected`
3. `imported symbol shadows existing visible symbol; alias required`
4. `global import must resolve through a global barrel entry`
5. `init function must have signature fn name() -> void`
6. `frame function must have signature fn name() -> void`
7. `multiple module init functions detected`
8. `multiple project init functions detected`
9. `multiple frame functions detected`
10. `missing frame function for executable project`
11. `Init attribute target invalid`
12. `project init must be colocated with frame`
13. `InitAllowed is valid only on SDK host methods`
14. `host call not allowed during init`
### Lowering / Structural Validation
The lowering line must enforce, at minimum:
1. `synthetic wrapper entrypoint missing`
2. `published entrypoint is not function index 0`
3. `hidden boot guard is missing`
4. `synthetic callable origin missing`
These may appear as backend diagnostics, validation failures, or invariant violations, as long as the failure is observable and testable.
### Runtime / Boot Failure
The runtime-facing failure surface must distinguish, at minimum:
1. `boot failed during module init`
2. `boot failed during project init`
These belong to operational boot failure reporting rather than to the static compiler diagnostic catalog.
## Propagation Targets
PBS adopts the following minimum propagation line for family `19`.
### PBS Specs
This decision must propagate to at least:
1. `docs/compiler/pbs/specs/3. Core Syntax Specification.md`
2. `docs/compiler/pbs/specs/4. Static Semantics Specification.md`
3. `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
4. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
5. `docs/compiler/pbs/specs/11. AST Specification.md`
6. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
7. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
### General Compiler Specs
This decision must also propagate to at least:
1. `docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md`
2. `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`
### Runtime Cross-Domain Owner
The runtime half of the protocol change remains explicitly cross-domain and must be tracked through:
1. `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
### Learn
PBS must also produce a consolidated `learn` artifact explaining:
1. globals,
2. lifecycle markers,
3. published wrapper composition,
4. fixed entrypoint protocol,
5. and the relationship between source flow and lowered artifacts.
## Conformance Matrix
PBS adopts the following minimum conformance matrix for family `19`.
### Positive Coverage
At minimum, one positive fixture must cover:
1. `declare global`
2. file-level `[Init]`
3. project-level `[Init]`
4. `[Frame]`
That fixture must provide evidence for:
1. accepted globals and ordering,
2. generated wrapper publication,
3. `func_id = 0`,
4. `FRAME_RET` in the wrapper path,
5. and hidden boot guard presence.
### Negative Frontend Coverage
At minimum, negative frontend coverage must include:
1. `global` using `fn` in its initializer
2. `global` using `if` in its initializer
3. cycle between globals
4. symbol collision between imported and visible `const` / `global` / `service` / `fn`
5. invalid `[Init]` signature
6. invalid `[Frame]` signature
7. multiple `[Frame]`
8. multiple project init candidates
9. project init outside the `[Frame]` file
10. host call during init without `[InitAllowed]`
11. invalid `[InitAllowed]` target
### Negative Lowering Coverage
At minimum, negative lowering coverage must include:
1. missing published wrapper
2. published wrapper outside physical index `0`
3. missing hidden boot guard
4. missing synthetic origin metadata
### Runtime Integration Coverage
At minimum, runtime integration coverage must include:
1. artifact boot through physical entrypoint `0`
2. evidence that runtime boot no longer depends on nominal export resolution
3. coherent fail-fast reporting for module init failure
4. coherent fail-fast reporting for project init failure
## Rationale
This decision intentionally turns the last umbrella stage of topic `19` into an execution gate rather than another semantic layer.
That matters because the line is already architecturally closed.
What remained was the discipline required to make implementation safe:
- explicit diagnostics,
- explicit propagation ownership,
- explicit cross-domain runtime ownership,
- and explicit conformance evidence.
Without this consolidation step, execution work would still have room to drift across specs, runtime, and compiler validation.
## Invariants
1. Family `19` diagnostics remain partitioned by phase.
2. Family `19` propagation remains explicit across PBS specs, general specs, runtime, and `learn`.
3. Runtime entrypoint-protocol work remains a named cross-domain dependency rather than an implicit follow-up.
4. Family `19` is not considered implementation-ready without the declared conformance matrix.
## Explicit Non-Decisions
1. This decision does not redefine globals surface semantics.
2. This decision does not redefine lifecycle marker semantics.
3. This decision does not redefine published wrapper ownership.
4. This decision does not redefine lowering structure.
5. This decision does not replace the runtime-domain decision work required outside the PBS domain.
## Execution Readiness
With this decision accepted, family `19` is considered ready to move into `pull-request/plan` decomposition for:
1. spec propagation,
2. compiler implementation,
3. runtime cross-domain coordination,
4. diagnostics integration,
5. and conformance fixture execution.
@@ -0,0 +1,194 @@
# Globals and Lifecycle Lowering to IRBackend and IRVM Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda.md`
## Context
After closing globals, lifecycle markers, and published wrapper ownership, PBS v1 still needed a precise lowering contract for how those decisions appear in executable compiler artifacts.
The remaining problem was not semantic policy anymore.
It was structural representation:
- where globals become explicit,
- how synthetic lifecycle callables are represented,
- how one-shot boot state is materialized,
- how diagnostics and attribution survive synthetic lowering,
- and what minimum backend shape must be preserved before `IRVM`.
Important fixed inputs already existed:
- runtime globals are part of the PBS source model,
- module init and project init are semantically defined,
- the published wrapper is the physical entrypoint,
- `FRAME_RET` belongs to that wrapper,
- and VM-level global access already exists as `GET_GLOBAL` / `SET_GLOBAL`.
## Decision
PBS adopts the following lowering policy in v1:
1. Globals must become explicit structural entities at the `IRBackend` boundary.
2. Globals must not be deferred to an implicit late materialization below that boundary.
3. The lowering pipeline must represent synthetic lifecycle artifacts explicitly as synthetic callables rather than ad hoc emitted fragments.
4. The following synthetic callable classes are mandatory:
- `FILE_INIT_FRAGMENT`
- `MODULE_INIT`
- `PROJECT_INIT`
- `PUBLISHED_FRAME_WRAPPER`
5. The wrapper published as the physical entrypoint must exist explicitly in the lowered graph.
6. The one-shot boot guard must exist explicitly as a hidden global.
7. That hidden global is compiler-owned internal state and is not user-visible.
8. The lowering path must target the already-existing VM global operations:
- `GET_GLOBAL`
- `SET_GLOBAL`
## IRBackend Shape
PBS adopts the following minimum structural shape for `IRBackend`-level representation.
### Globals
Each backend global must preserve, at minimum:
1. `name`
2. `ownerModuleId`
3. `type`
4. `slot`
5. `visibility`
6. `isHidden`
7. `origin`
This applies both to:
- user-authored globals,
- and compiler-generated hidden globals such as the boot guard.
### Callables
The backend must distinguish explicitly between:
1. ordinary userland callables,
2. synthetic compiler-generated callables.
Synthetic callables must carry stable class identity rather than being inferred from naming convention alone.
### Hidden Global Kind
The hidden boot guard must carry explicit structural identity:
1. `BOOT_GUARD`
It must not be modeled merely as an informal hidden symbol name.
## Attribution and Diagnostics
PBS adopts the following attribution policy for synthetic lowering:
1. Synthetic globals and synthetic callables must carry origin metadata sufficient for remapping errors to real userland code where possible.
2. Synthetic origin metadata must preserve, at minimum:
- `derivedFromFile`
- `derivedFromModule`
- `derivedFromUserSymbol`
- `primarySpan`
- `fallbackSyntheticLabel`
3. When an error originates from synthetic lowering but has a defensible real userland origin, diagnostics must prefer the real userland span.
4. Purely synthetic spans should be shown only when no defensible userland origin exists.
## Synthetic Callable Policy
PBS adopts the following architectural rule:
1. Synthetic callables are first-class lowering artifacts.
2. They are not incidental codegen accidents.
3. Their explicit class identity exists to support:
- deterministic ordering,
- attribution,
- debug and tooling,
- conformance tests,
- and future lifecycle extensions without reopening the lowering model.
## Hidden Boot Guard Policy
PBS adopts the following policy for the boot guard:
1. It exists as a hidden program-owned global.
2. Userland cannot name it.
3. Userland cannot read it.
4. Userland cannot mutate it.
5. Its sole role is to enforce one-shot bootstrap semantics in the physical wrapper.
## Rationale
This decision intentionally chooses an explicit backend shape over implicit late-stage magic.
That matters because:
- globals are now part of the language contract,
- lifecycle artifacts now exist as semantically meaningful structure,
- diagnostics must remain attributable to real source even after synthesis,
- and backend conformance becomes much harder if the representation boundary stays implicit.
The chosen model also creates a stable editorial split:
- specs explain the structure normatively,
- and `learn` explains the composition through real source examples.
## Structural Diagnostics and Validation
PBS must provide, at minimum, the following structural checks or equivalent validation evidence:
1. `synthetic wrapper entrypoint missing`
2. `published entrypoint is not function index 0`
3. `hidden boot guard is missing`
4. `synthetic callable origin missing`
These may be implemented as backend diagnostics, validation failures, or conformance assertions, as long as the invariant remains enforced and observable.
## Invariants
1. Globals are explicit at the `IRBackend` boundary.
2. Synthetic lifecycle callables are explicit at the `IRBackend` boundary.
3. Hidden compiler state remains distinguishable from user state.
4. Synthetic lowering must preserve enough origin metadata for defensible remapping.
5. The lowering path to `IRVM` must preserve the previously accepted wrapper and entrypoint protocol.
## Explicit Non-Decisions
1. This decision does not redefine source syntax.
2. This decision does not redefine lifecycle semantics.
3. This decision does not redefine manifest publication.
4. This decision does not freeze one concrete implementation class hierarchy.
## Spec and Learn Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
2. relevant general lowering specs outside the PBS domain, when they need the new explicit shape
3. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
It also requires didactic propagation to PBS `learn`, where the model should be explained with source-level examples showing how:
1. `declare global`
2. file `[Init]`
3. project `[Init]`
4. and `[Frame]`
compose into synthetic lowered artifacts and the published wrapper.
## Validation Notes
At minimum, validation for this decision should include:
1. a fixture combining globals, file init, project init, and frame;
2. evidence of generated:
- file init fragment,
- module init,
- project init,
- published wrapper,
- hidden boot guard;
3. evidence that the wrapper occupies `func_id = 0`;
4. evidence that `FRAME_RET` lives in the wrapper path;
5. evidence that a synthetic-lowering error remaps to real userland span when a defensible origin exists.