@spec capturing_identity(keyword()) :: map()

Capturing identity map used to persist and fold a native window.

@spec fallback_reasons() :: [String.t()]

Stable fallback_reason tokens (ADR 0040 Decision 2).

@spec fold_usable?(map(), map()) :: boolean()

Fold-usable predicate for Provider replay.

Returns true when native_replay is present, recorded_usable, still validates, and current Provider/backend/dialect/model match the capturing values. Anthropic fold never consults this predicate.

@spec inspect_native_replay(term()) :: map() | nil

Bounded inspect projection: mode, usability, item ids, fallback reason.

Never includes items or encrypted_content. Accepts either checkpoint data or a native_replay map. Returns nil when no native replay is present.

@spec modes() :: [String.t()]

Accepted native_replay.mode values.

@spec overlay_after_resolve(nil | boolean(), map()) :: {:on, nil} | {:off, String.t()}

Overlay bit after Provider/backend resolve (ADR 0022 late-bound pattern).

preference is nil (no preference), true (request on), or false (explicit off). identity carries string provider, backend, dialect, and optional responses_host from the resolved request.

Overlay on is not standalone C. chatgpt_codex enables D (compact_threshold). Official api.openai.com enables D and may POST C. Other open_responses hosts stay local.

@spec persist_standalone_window(map(), term(), keyword()) ::
  {:ok, map()} | {:error, map()}

Attach a standalone_window native replay from a compact output list.

Persists the entire output array. Reducing that list to cmp_ alone is standalone_window_pruned. Local text checkpoint fields remain mandatory.

@spec persist_threshold_capture(map(), term(), keyword()) ::
  {:ok, map()} | {:error, map()}

Persist a live threshold_item capture without failing the local checkpoint.

Usable singleton cmp_ items are stored as today. Missing, malformed, or forced-fallback captures still return local text plus recorded_usable false.

@spec persist_threshold_item(map(), map() | [map()], keyword()) ::
  {:ok, map()} | {:error, map()}

Attach a threshold_item native replay window to local checkpoint data.

item_or_items must be exactly the latest compaction item (type compaction, id matching cmp_…). A full compact output list is rejected as threshold_item_not_singleton — this helper never drops retained items to invent a singleton.

Local text checkpoint fields remain mandatory on the same Event. This does not call the Provider and does not change live Turn ingest.

@spec project_checkpoint_for_inspect(map()) :: map()

Replace a checkpoint's native_replay with the inspect projection and drop any encrypted_content keys. Used by CLI --json and diagnostics.

@spec project_compact_result_for_inspect(map()) :: map()

Sanitize a compact/complete result so JSON never prints ciphertext.

@spec validate_native_replay(
  term(),
  keyword()
) :: {:ok, map()} | {:error, map()}

Validate a native_replay map for either persist mode.

Returns {:ok, normalized} with recorded_usable set. Unusable windows keep the payload and set fallback_reason. Completely unparseable input returns {:error, structured}.

Pass compact_output: when validating standalone_window so a reduced items list (save-only-cmp_) is standalone_window_pruned.