131 lines
5.9 KiB
Markdown
131 lines
5.9 KiB
Markdown
# Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision
|
|
|
|
Status: Accepted
|
|
Date: 2026-03-22
|
|
Related Agenda: `docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
|
|
|
|
## Context
|
|
|
|
After closing globals and lifecycle semantics, PBS v1 still needed a precise publication contract for executable boot.
|
|
|
|
The remaining problem was no longer how initialization behaves in userland.
|
|
It was how that behavior is published into the artifact and consumed by backend stages and runtime.
|
|
|
|
The open points were:
|
|
|
|
- whether the published entrypoint is still the user `frame()` callable,
|
|
- whether a synthetic wrapper becomes the true physical entrypoint,
|
|
- where `FRAME_RET` must live once lifecycle bootstrap exists,
|
|
- whether `FrontendSpec` continues to hold authority over entrypoint identity,
|
|
- and whether `manifest.json` remains part of entrypoint authority.
|
|
|
|
Important fixed inputs already existed:
|
|
|
|
- `[Frame]` identifies the userland logical frame root,
|
|
- module init and project init are already defined in lifecycle terms,
|
|
- boot is one-shot and fail-fast,
|
|
- and general backend specs already converge on entrypoint function index `0`.
|
|
|
|
## Decision
|
|
|
|
PBS adopts the following publication and ownership policy for executable boot in v1:
|
|
|
|
1. The compiler publishes a synthetic wrapper as the physical executable entrypoint.
|
|
2. The userland callable marked with `[Frame]` remains the logical frame root of user code.
|
|
3. The synthetic wrapper is therefore the physical root, while `[Frame]` remains the logical root.
|
|
4. The wrapper must contain:
|
|
- one-shot boot orchestration,
|
|
- the required init execution exactly once,
|
|
- invocation of the userland `[Frame]` callable,
|
|
- and the final `FRAME_RET`.
|
|
5. `FRAME_RET` no longer belongs at the end of the userland `frame()` body.
|
|
6. `FRAME_RET` belongs to the published wrapper.
|
|
7. The published wrapper must occupy physical entrypoint index `0`.
|
|
|
|
## Entrypoint Authority
|
|
|
|
PBS adopts the following authority model:
|
|
|
|
1. `FrontendSpec` no longer holds authority to decide which callable is the published entrypoint for PBS.
|
|
2. Entrypoint authority is owned exclusively by the PBS compiler.
|
|
3. Source-derived lifecycle semantics determine the logical frame root.
|
|
4. The compiler then publishes the physical wrapper that realizes that lifecycle contract.
|
|
5. Backend handoff must therefore preserve the compiler-selected published wrapper as the effective entrypoint identity.
|
|
|
|
## Manifest and Runtime Protocol
|
|
|
|
PBS adopts the following target protocol direction:
|
|
|
|
1. `entrypoint` must stop being part of the final `manifest.json` contract.
|
|
2. Runtime boot must not depend on nominal entrypoint resolution from the manifest.
|
|
3. Runtime boot must treat physical entrypoint index `0` as protocol.
|
|
4. The compiler guarantees that the published wrapper occupies that index.
|
|
5. Any temporary compatibility line with manifest-declared nominal entrypoint is transitional only and is not the target contract.
|
|
|
|
## Exports Boundary
|
|
|
|
PBS adopts the following boundary for nominal exports:
|
|
|
|
1. Nominal function exports may continue to exist in the emitted artifact.
|
|
2. Those exports are no longer authoritative for loader or boot.
|
|
3. Boot depends exclusively on the published physical entrypoint at index `0`.
|
|
4. Nominal exports remain useful only for tooling, debug, introspection, and related non-boot concerns.
|
|
|
|
## Rationale
|
|
|
|
This decision keeps logical user semantics and physical boot publication clearly separated.
|
|
|
|
That matters because:
|
|
|
|
- the user `frame()` callable should remain the semantic root of frame logic,
|
|
- the one-shot bootstrap sequence must still execute before normal frame work,
|
|
- `FRAME_RET` should mark the true end of the logical published frame,
|
|
- and the compiler must be the single authority that turns source lifecycle into executable publication.
|
|
|
|
The decision also deliberately removes duplicated authority:
|
|
|
|
- not `FrontendSpec`,
|
|
- not manifest nominal metadata,
|
|
- and not PBX nominal exports
|
|
are allowed to compete with the compiler-selected physical wrapper as boot authority.
|
|
|
|
## Invariants
|
|
|
|
1. `[Frame]` remains the userland logical frame root.
|
|
2. The published wrapper remains the physical executable root.
|
|
3. `FRAME_RET` belongs to the published wrapper.
|
|
4. Physical entrypoint index `0` belongs to that wrapper.
|
|
5. Nominal exports are not boot authority.
|
|
6. Entrypoint authority for PBS belongs to the compiler, not to `FrontendSpec` or manifest metadata.
|
|
|
|
## Explicit Non-Decisions
|
|
|
|
1. This decision does not define the final IR encoding of the wrapper body.
|
|
2. This decision does not define the detailed lowering mechanics of globals and lifecycle into IR.
|
|
3. This decision does not define the runtime-side migration implementation plan in detail.
|
|
4. This decision does not define the final diagnostics catalog for backend/runtime structural failures.
|
|
|
|
## Spec Impact
|
|
|
|
This decision should feed at least:
|
|
|
|
1. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
|
|
2. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
|
|
3. `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
|
4. `docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
|
5. `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`
|
|
|
|
It also requires explicit cross-domain propagation to:
|
|
|
|
1. `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
|
|
|
|
## Validation Notes
|
|
|
|
At minimum, validation for this decision should include:
|
|
|
|
1. emitted artifact evidence that the published wrapper occupies function index `0`;
|
|
2. conformance evidence that the userland `[Frame]` callable is invoked by that wrapper rather than being published directly;
|
|
3. evidence that `FRAME_RET` is emitted in the wrapper path;
|
|
4. evidence that nominal exports, when present, do not participate in boot authority;
|
|
5. integration evidence that runtime boot aligns with the fixed physical entrypoint protocol.
|