# SURPRISE REGISTER ENTRY (Public RAM Template -- shared entry format)

**Purpose:** Canonical entry schema for any component writing to the Surprise Register (S3, S5, S7, S8). One entry = one append line in `state/ram/surprise-register/<run-id>/register.jsonl`.

## Record structure

```json
{
  "entry_id": "<uuid>",
  "run_id": "<run-id>",
  "register_id": "<register-id>",
  "claim_id": "<claim-id-or-null>",
  "entry_kind": "anomaly | contradiction | meta-anomaly | charter-amendment-request",
  "writer_component": "S3 | S5 | S7 | S8",
  "write_timestamp_utc": "<ISO-8601>",
  "source_refs": ["<search-ledger-source-id>", "..."],
  "description": "<<=1000 chars, non-boilerplate>",
  "provenance": {
    "query_ids": ["<ledger-query-id>", "..."],
    "rationale": "<component-specific>"
  },
  "expansion_directive": "sub-inquiry | expand-corpus | defer-to-operator | informational",
  "downstream_effect": {
    "triggers_sub_inquiry_id": "<string-or-null>",
    "charter_amendment_ref": "<string-or-null>"
  },
  "rendered_in_output": false
}
```

## Field rules

- `entry_id`: uuid, writer-generated, unique within the register.
- `claim_id`: null iff `entry_kind == meta-anomaly` and the meta-anomaly is unbound to any specific claim (e.g., an anomaly about inquiry process itself).
- `entry_kind`: CLOSED enum of four. Prohibited values are refused by the write contract (no `tiebreaker-vote`, no `winner-declaration`, no `confidence-delta`).
- `writer_component`: self-identify the skill that wrote the entry.
- `source_refs`: list of RAM Search Ledger source-ids backing the entry; may be empty only for `meta-anomaly` or `charter-amendment-request`.
- `description`: plain text; must describe the anomaly / contradiction without procedural language. No "the winning discipline is X" language.
- `provenance.query_ids`: list of ledger query-ids that surfaced the entry.
- `provenance.rationale`: component-specific, names the detector / rubric / protocol that generated the entry (e.g., "S3 triangulation protocol section 2", "S7 material-admiralty divergence", "S8 inversion defensibility check failed").
- `expansion_directive`: what the entry should trigger downstream; not a routing instruction for S4 but a signal S6 / orchestrator reads.
- `downstream_effect.triggers_sub_inquiry_id`: populated if orchestrator opens a bounded sub-inquiry in response.
- `downstream_effect.charter_amendment_ref`: populated if the entry invites a charter-level change (S5 owns the decision).
- `rendered_in_output`: writers MUST set false. S4 flips to true at emit time. Any writer setting true is a contract violation.

## Writer-specific usage notes

- **S3 Multi-Method Orchestrator** emits `contradiction` entries when triangulation returns CONTRADICTORY convergence class (one entry per contradicting pair; `description` names the disagreeing disciplines and the axis), `anomaly` entries for material PARTIAL_AGREEMENT above threshold, and `charter-amendment-request` entries for CLAIM_TYPE_REVISION candidates.
- **S5 Claim-Typing Engine** emits anomalies for CLAIM_TYPE_AMBIGUITY returns during claim decomposition.
- **S7 Fitness Adjudicator** emits anomalies for disqualifier hits and material Admiralty-vs-fitness divergence.
- **S8 Adversarial Pass Engine** emits contradictions when inversion queries produce defensible findings that disturb a RAM claim.

## Render rules (S4 owns, noted here for clarity)

S4 renders the entries in a top-of-output `Surprise Register` section. Rendering as a footnote is forbidden. `CONTESTED` claims in the triangulation records back-reference their `entry_id` here.

## Invariants

- Append-only. No mutation.
- One entry per contradiction pair, not one entry per CONTRADICTORY claim. A claim with 3 mutually incompatible findings produces 3 pair entries.
- `expansion_directive` must be one of the four listed values -- the register expands inquiry, never resolves it.
