100 lines
2.6 KiB
Markdown
100 lines
2.6 KiB
Markdown
|
# 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.
|