niklas/amduat
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat/tier1/pel-output-policy-1.md
Carl Niklas Rydberg 3473b19425 trow AI at it.
2026-02-22 00:25:56 +01:00

2.6 KiB
Raw Blame History

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.