prometeu-studio/docs/compiler/pbs/decisions/Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision.md

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.