# SEARCH LEDGER WRITE CONTRACT (Public RAM -- shared by all writers)

**Scope:** Defines the write surface of the RAM Search Ledger for every component that writes. Ownership stays with Epistemic Output Layer (S4); writers append continuously throughout the run.

## 1. Ownership invariants

- **Owner / render authority:** S4 Epistemic Output Layer. S4 creates the empty ledger at run open and publishes the write handle.
- **Writers:** S1 Retrieval Router, S2 Source Integrity Screen, S3 Multi-Method Orchestrator, S7 Fitness Adjudicator, S8 Adversarial Pass Engine.
- **Readers:** S6 Warrant & Saturation Governor (reads for yield / saturation signal), S4 (renders at run close).
- **Writer set is CLOSED:** exactly the five skills above. No other skill writes to this ledger.

## 2. Record kinds (CLOSED)

Four record kinds. Writers may emit ONLY these values. Record kinds disjoint from the Evaluator Search Ledger to preserve zero-overlap.

- `every-query` -- any query executed against any corpus, including skipped saturation-check queries
- `every-accepted` -- any source that passed integrity + fitness screens and was accepted for use
- `every-rejected` -- any source rejected by any screen
- `every-skipped` -- any corpus / discipline / query-class consciously skipped

The "every-" prefix is load-bearing. There is no such thing as a silent ledger miss. The ledger is the TRUTH SURFACE.

## 3. Required fields per record

### 3.1 `every-query`

```json
{
  "record_kind": "every-query",
  "query_id": "uuid",
  "run_id": "string",
  "claim_id": "string",
  "writer": "S1 | S2 | S3 | S7 | S8",
  "pass": "confirmatory | adversarial | integrity | fitness-followup | saturation-check",
  "query_text": "string",
  "corpus_target": "english-peer | non-english | practitioner | indigenous | retraction-watch | crossref | ai-contam",
  "timestamp_utc": "ISO-8601",
  "rationale": "string (non-boilerplate, discipline-specific)"
}
```

### 3.2 `every-accepted`

```json
{
  "record_kind": "every-accepted",
  "source_id": "string",
  "query_id": "string (back-ref)",
  "fitness_verdict_ref": "string",
  "integrity_verdict_ref": "string",
  "admiralty_input": "A-F / 1-6",
  "claim_id": "string",
  "timestamp_utc": "ISO-8601"
}
```

### 3.3 `every-rejected`

```json
{
  "record_kind": "every-rejected",
  "source_id": "string",
  "query_id": "string",
  "rejection_reason": "retracted | fabricated-citation | ai-contaminated | pub-bias | fitness-below-threshold | disqualifier-hit | translation-fidelity-fail | care-gate-refused",
  "reviewer_flag": "string | null",
  "timestamp_utc": "ISO-8601"
}
```

### 3.4 `every-skipped`

```json
{
  "record_kind": "every-skipped",
  "avenue": "string (corpus / query-class / discipline)",
  "skip_reason": "string",
  "claim_id": "string",
  "writer": "S1 | S2 | S3 | S7 | S8",
  "timestamp_utc": "ISO-8601"
}
```

## 4. Orchestrator-specific records (S3)

S3 writes `every-query` records for discipline-invocation dispatch with `pass: confirmatory`, plus `every-skipped` records when a discipline is capacity-deferred (`skip_reason: CAPACITY_BOUND`) or when a discipline errored (`skip_reason: DISCIPLINE_FAILED`). S3 additionally writes exception-filing records under `every-skipped` with `skip_reason: SINGLE_METHOD_EXCEPTION:<T1|T2|T3|T4>` naming the discipline NOT invoked.

## 5. Write protocol

1. Writer obtains write handle published by S4 at run open.
2. Writer emits records at the moment the event occurs -- query launched, source accepted, source rejected, avenue skipped. No batching to end-of-run.
3. Each write is a single atomic JSONL append line to `state/ram/ram-search-ledger/<run-id>/ledger.jsonl`.
4. Index updates to `index.json` are S4's responsibility at render time; writers touch only the append log.

## 6. Prohibited writer behaviors

- Batching writes to end-of-run
- Mutating existing records (ledger is append-only)
- Writing a record kind not in the CLOSED list of four
- Writing to the Evaluator Search Ledger (zero-overlap; distinct path under `state/evaluator/`)
- Writing boilerplate rationales (e.g., "searched for X"); rationale must be discipline-specific and query-specific
- Writing after S4 renders at run close

## 7. Degraded mode

- Ledger unavailable at write time: calling skill HALTS. There is no silent ledger miss -- the ledger is the truth surface.
- Ledger available but append fails: classified refusal; incident written to orchestrator alarm channel; calling skill halts.

## 8. Zero-overlap enforcement

RAM Search Ledger path root: `state/ram/ram-search-ledger/`. Evaluator has zero read/write authority on this path. Record kinds are disjoint from the Evaluator's `audit-query / audit-finding / audit-null / audit-refusal / reopen-event`.
