prometeu-studio/docs/compiler/pbs/decisions/Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md

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.