# RAM_SEARCH_LEDGER_RENDER_SPEC -- Render Authority Schema

**Owner:** Epistemic Output Layer (S4) -- RENDER AUTHORITY. **Library:** Private RAM. **Consumers:** S4 only.
**Writers of the underlying state (not rendered):** S1 (Retrieval Router), S2 (Source Integrity Screen), S3 (Multi-Method Orchestrator), S7 (Fitness Adjudicator), S8 (Adversarial Pass Engine).

This spec defines the rendered Search Ledger section inside the Evaluator-ready artifact. The underlying state artifact schema (JSONL records at `state/ram/ram-search-ledger/<run-id>/ledger.jsonl`) is specified in `CROSS_CUTTING_ARTIFACTS.md`; this file specifies how it is rendered. THIS layer owns BOTH schema additions and render -- sign-off required for any schema change.

---

## 1. Record Kinds (four; ALL rendered)

Every record kind in the ledger is rendered in the output. Nothing is summarized away. Nothing is dropped for brevity. The visible-ledger non-negotiable means:

### 1.1 `every-query`
One rendered line per issued query. Fields: `query_id`, `writer` (S1|S2|S3|S7|S8), `pass` (confirmatory|adversarial|integrity|fitness-followup|saturation-check), `query_text`, `corpus_target`, `timestamp_utc`, `rationale` (discipline-specific, non-boilerplate), `claim_id`.

### 1.2 `every-accepted`
One rendered line per source that passed integrity + fitness screens. Fields: `source_id`, `query_id` back-reference, `fitness_verdict_ref`, `integrity_verdict_ref`, `admiralty_input` (A-F / 1-6), `claim_id`, `timestamp_utc`.

### 1.3 `every-rejected`
One rendered line per source rejected by integrity, fitness, or any other gate. Fields: `source_id`, `query_id`, `rejection_reason` (retracted|fabricated-citation|ai-contaminated|pub-bias|fitness-below-threshold|disqualifier-hit|translation-fidelity-fail|care-gate-refused), `reviewer_flag`, `timestamp_utc`.

### 1.4 `every-skipped`
One rendered line per avenue (corpus / query-class / discipline) skipped during the run. Fields: `avenue`, `skip_reason`, `claim_id`, `writer`, `timestamp_utc`.

---

## 2. Rendering Pattern

### 2.1 Top-level section
The Search Ledger is a TOP-LEVEL section of the Evaluator-ready artifact. It is not nested, not abbreviated, not hidden behind a "details" toggle in a way that hides content from the Evaluator.

### 2.2 Per-claim grouping (optional but preferred)
Ledger entries carry `claim_id`. Group entries under claim headings for readability, with a trailing sub-section for ledger entries that have no claim binding (e.g., run-level queries). This grouping does NOT change content; every entry still renders.

### 2.3 Layered disclosure
A per-entry summary line (record_kind + writer + timestamp + short identifier) may be rendered as the default layer, with a details layer exposing full payload. BOTH layers are present; collapsing the details layer out of the artifact is forbidden.

### 2.4 Chronological within group
Render entries in timestamp order within each group. Do NOT reorder to suppress rejections or skips from visibility.

---

## 3. Forbidden Summarizations

All of these throw E3 at validation:
- "Ran N queries, accepted M sources." -- without per-entry rendering.
- "Rejected sources: N; see summary." -- without enumerating each rejection.
- "Avenues skipped: 3." -- without naming each avenue and reason.
- Aggregating `every-rejected` by reason with no per-source back-reference.
- Dropping `every-skipped` because "nothing happened there."

---

## 4. Empty-Ledger Handling

- If Retrieval Router ran but ledger is empty -> upstream defect; emit E3 and escalate to Orchestrator.
- If Retrieval Router was NOT invoked (e.g., the question was resolved from prior run state) -> the absence is legitimate, render a single explanatory row: `{"note": "no retrieval invoked this run", "reason": "<string>"}`. The section still renders; it is never omitted.

---

## 5. Degraded-mode Render

If some writer failed to append (ledger write error), a `ledger-write-incident` stamp is included in the Degraded-Mode section of the artifact AND the Surprise Register AND the partial ledger is rendered with an explicit incomplete marker. Do NOT silently emit a clean ledger when writes failed.

---

## 6. Schema Authority

Additions to record kinds (e.g., a new `coverage-expansion` record) require:
1. This layer's sign-off (render authority).
2. Writer-set update in `CROSS_CUTTING_ARTIFACTS.md`.
3. Validator update in Phase E.
No writer component may unilaterally add a new record kind without the render spec being updated here.
