# PEL/OUTPUT-POLICY/1 — Materialization & Promotion Policy

Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2026-02-21
Tags: [pel, outputs, promotion, retention]

**Document ID:** `PEL/OUTPUT-POLICY/1`
**Layer:** L2 — Output handling policy (no execution semantics)

**Depends on (normative):**

* `PEL/1-CORE` — execution semantics
* `ASL/LOG/1` — visibility and log ordering
* `ASL/1-CORE-INDEX` — visibility and tombstone semantics

**Informative references:**

* `ASL/SYSTEM/1` — promotion/publication/retention separation

---

## 0. Conventions

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are
to be interpreted as in RFC 2119.

This document defines **policy** for handling PEL outputs. It does not change
PEL execution semantics.

---

## 1. Policy Dimensions

Each output produced by PEL is subject to three independent policy decisions:

### 1.1 Materialization

Controls whether output bytes are stored, cached, or virtualized.

* `store` — persist in the content index (authoritative).
* `cache` — persist in materialization cache only (performance hint).
* `virtualize` — compute in-memory only; do not persist.

### 1.2 Promotion

Controls whether an output is promoted from a derived view to **truth**.

* `promote` — output becomes eligible for truth/published workflows.
* `no_promote` — output remains derived and must not be treated as truth.

Promotion is **explicit**; it MUST NOT be inferred from execution.

### 1.3 Publication

Controls visibility (internal vs published) encoded in index metadata.

* `internal` — visible only to the local domain.
* `published` — visible to federation/replay.

Publication is distinct from promotion; a promoted output may still be internal.

---

## 2. Policy Hooks (Normative)

Core implementations MUST expose a policy hook that can be invoked **per
output** to decide the three dimensions above.

The hook MUST be deterministic and MUST depend only on:

* the execution inputs (program, params, inputs, snapshot state)
* explicit policy configuration supplied by the caller

The hook MUST NOT read storage layout or non-snapshot metadata.

---

## 3. Default Policy

If no hook is supplied, the default policy is:

* `materialization = store`
* `promotion = no_promote`
* `publication = internal`

---

## 4. API Layer Mapping (Informative)

API layers should expose explicit controls for:

* promotion (`publish` / `promote` flags)
* visibility (`internal` vs `published`)
* materialization (`store` vs `cache` vs `virtualize`)

The API MUST NOT implicitly promote outputs without an explicit policy choice.