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.