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.