prometeu-studio/docs/pbs/decisions/Allocation and Cost Visibility Decision.md

Allocation and Cost Visibility Decision

Status: Accepted Cycle: Initial allocation-and-cost closure pass

1. Context

PBS v1 needs a minimal but explicit contract for which runtime cost facts matter semantically and which belong only to diagnostics/profiling quality.

Earlier decisions already fixed important inputs:

• bind(context, fn_name) has real retention/storage consequences,
• optional, result, handle, !, if, and switch are not intended to hide implicit allocation semantics,
• host/userland interaction is stack-only across the boundary,
• and value categories already distinguish copied payload from preserved aliasing.

2. Decision

PBS v1 adopts the following cost-visibility baseline:

1. The normatively relevant cost facts are:
   • whether an operation may allocate VM-owned runtime storage,
   • whether an operation retains state beyond the current evaluation,
   • whether an operation copies payload versus preserves aliasing,
   • whether an operation crosses the host boundary,
   • and whether an operation may trap.
2. bind(context, fn_name) is normatively retention-bearing and requires runtime storage sufficient to keep the callback target and captured context alive.
3. apply is not allocation-bearing by itself.
4. optional, result, handle, !, if, and switch are not allocation-bearing by themselves.
5. Host-boundary crossing is a normatively relevant cost fact, but concrete host-side allocation details belong to subsystem-specific contracts rather than to a general PBS rule.
6. Quantitative reporting such as exact byte counts, exact object counts, or precise collector timing is not a normative language guarantee in v1.

3. Normatively Relevant Cost Facts

The following cost facts are part of the PBS semantic model and may be relied on by later tooling/spec work:

• VM allocation-bearing versus non-allocation-bearing behavior,
• retention-bearing versus non-retention-bearing behavior,
• copy versus aliasing preservation,
• host-boundary crossing,
• trap possibility.

These facts matter because they affect how advanced tooling, diagnostics, and performance reasoning should interpret a construct.

4. bind

bind(context, fn_name) is the strongest closed cost case in the current PBS core.

Rules:

• bind is not semantically free,
• bind is retention-bearing,
• bind requires runtime storage sufficient to preserve the callback target and captured context,
• the captured context remains alive while the callback value remains alive.

This decision does not require the spec to freeze the exact runtime layout used to implement that storage.

5. Non-Allocation-Bearing Surfaces

The following constructs are not allocation-bearing by themselves in PBS v1:

• optional
• result
• handle
• !
• if
• switch
• apply

If allocation or retention occurs while evaluating one of these constructs, that cost arises from:

• subexpression evaluation,
• called targets,
• payload formation already defined elsewhere,
• or runtime behavior outside the surface itself.

6. Copy Versus Aliasing

Copy versus aliasing is a normatively relevant cost fact.

The language already distinguishes:

• pure values copied by value,
• identity-bearing values passed by preserved aliasing,
• carriers that preserve the semantics of their contained values.

Tooling and later specs may rely on these distinctions even if PBS v1 does not require a warning at every such site.

7. Host Boundary

Crossing the host boundary is a normatively relevant cost fact.

However, this decision does not impose a universal rule for:

• host-side allocation volume,
• host-side object count,
• or host-side retention internals.

Those details belong to subsystem-specific contracts when and if they become relevant.

8. Normative Versus Best-Effort Reporting

8.1 Normative facts

The following facts are normative and may be surfaced by diagnostics/tooling:

• whether a construct is retention-bearing,
• whether a construct crosses the host boundary,
• whether semantics preserve aliasing or copy payload,
• whether a construct may trap.

8.2 Best-effort facts

The following facts are not normative language guarantees in v1:

• exact byte counts,
• exact object counts,
• exact collector timing,
• exact host-side allocation volume,
• precise performance ranking beyond the semantic facts above.

These may be surfaced by implementations as profiling or tooling enrichment, but they are not part of the core language contract.

9. Invariants

• The language must not imply hidden allocation semantics where none were intentionally specified.
• bind remains the canonical retention-bearing callback-forming construct in v1.
• Cost visibility must be strong enough for advanced tooling without forcing exact runtime accounting into the language spec.
• Host-boundary cost reporting must not pretend to know subsystem-specific runtime internals unless those are explicitly specified.

10. Explicit Non-Decisions

This decision record does not yet close:

• the final diagnostics wording for warnings or notes,
• subsystem-specific host cost contracts,
• precise collection/profiling metrics,
• optimizer-facing reporting policy.

11. Spec Impact

This decision should feed at least:

• docs/pbs/specs/10. Memory and Lifetime Specification.md
• docs/pbs/specs/11. Diagnostics Specification.md

12. Validation Notes

The intended split is:

• semantic cost facts are explicit,
• bind is the main retained-storage construct already closed,
• most other core surfaces are not allocation-bearing by themselves,
• and quantitative performance reporting remains tooling-quality rather than normative language behavior.