# FINAL_ARTIFACT_SCHEMA

**Type:** Schema for the user-facing deliverable emitted when the Top-Level Dual-System Loop reaches a TERMINAL state.
**Authority:** RAM Solution Architecture (Phase 2A) deliverables inventory; Evaluator Solution Architecture (Phase 2B) deliverables inventory; Phase 1 Gate frame-independence principles.
**Invocation:** Phase 5 (TERMINAL-PASS) and Phase 6 (TERMINAL-ESCALATED) of `SKILL.md`.

---

## 1. Purpose

Define the single artifact format that every `/research` invocation produces. The artifact combines RAM's output (the research answer), Evaluator's audit (the independent adjudication), loop history (the full trace), and the convergence verdict (PASS or ESCALATED).

One schema. Two variants (PASS and ESCALATED). No variant-specific branching that hides the audit structure.

---

## 2. Schema (Top-Level)

```
{
  artifact_version: "1.0",
  question_id: <id>,
  question: <original natural-language question>,
  convergence_verdict: "PASS" | "ESCALATED",
  terminated_at: <timestamp>,

  ram_final_output: <RAM_OUTPUT_BLOCK>,              // Section 3.1
  evaluator_final_audit: <EVALUATOR_AUDIT_BLOCK>,    // Section 3.2
  loop_history: <LOOP_HISTORY_BLOCK>,                // Section 3.3
  frame_registry: <FRAME_REGISTRY_BLOCK>,            // Section 3.4
  ceremonial_detection?: <CEREMONIAL_BLOCK>,         // Section 3.5 -- present if E9 flagged
  source_page: <SOURCE_PAGE_BLOCK>,                  // Section 3.6 -- kept-source naked link list
  escalation_block?: <ESCALATION_BLOCK>              // Section 4 -- present iff verdict == ESCALATED
}
```

---

## 3. Standard Blocks (present in every artifact)

### 3.1 RAM_OUTPUT_BLOCK (from RAM Router's final cycle artifact)

```
{
  cycle_id: <n>,                       // last RAM cycle that ran
  three_axis_confidence: {
    evidence_axis: { score, reasoning },
    transportability_axis: { score, reasoning },
    decision_axis: { score, reasoning }
  },
  per_discipline_outputs: [...],        // inherited from Librarian 11 disciplines, updated to carry three-axis + surprise
  search_ledger: {
    queries_issued: [...],
    sources_accepted: [...],
    sources_rejected: [...],
    avenues_skipped: [...]
  },
  surprise_register: {
    anomalies: [...],
    contradictions: [...]
  },
  disconfirmation_record: {
    inverted_queries: [...],
    nothing_found_claims: [...],
    contradictions_surfaced: [...]
  },
  warrant_based_stopping: {
    decision: "saturated" | "scope_complete" | "charter_locked",
    marginal_yield_argument: <text>
  },
  claim_decomposition: {
    claim_types: [...],
    stacked_intents: [...]
  }
}
```

Source: RAM Router, per RAM Solution Architecture Section 3.1 deliverables inventory.

### 3.2 EVALUATOR_AUDIT_BLOCK (from Evaluator Router's final cycle artifact)

```
{
  cycle_id: <n>,                       // last Evaluator cycle that ran
  three_axis_audit_in_evaluator_frame: {
    evidence_axis: { score, reasoning },
    transportability_axis: { score, reasoning },
    decision_axis: { score, reasoning }
  },
  disagreement_with_ram: {
    evidence_axis_delta: <n>,
    transportability_axis_delta: <n>,
    decision_axis_delta: <n>,
    per_axis_disagreement_narrative: <text>
  },
  blind_spot_findings: [
    { severity, defect_class, evidence_ref, frame_level_probe, text }, ...
  ],
  e9_signals: {
    over_report: <signal>,
    under_report: <signal>,
    ceremonial_pattern: <signal>,
    calibrated_silence_report: <signal>
  },
  audit_method: "artifact_check" | "replication",
  evaluator_search_ledger: {
    queries_issued: [...],
    sources_accepted: [...],
    sources_rejected: [...]
  },
  isolation_verification: {
    build_time_pass: bool,
    runtime_pass: bool,
    runtime_alarms: [...]
  },
  charter_lock_state: {
    scope: [...],
    scope_creep_detected: bool
  }
}
```

Source: Evaluator Router, per Evaluator Solution Architecture Section 3.1 deliverables inventory.

### 3.3 LOOP_HISTORY_BLOCK

```
{
  total_cycles: <n>,
  reopen_count: <n>,
  sub_dwell_deferral_counter: <n>,
  first_cycle_start_ts: <ts>,
  last_cycle_completed_ts: <ts>,
  cycles: [
    {
      cycle_id: <n>,
      ram_artifact_ref: <ref>,
      ram_cycle_start_ts: <ts>,
      ram_cycle_completed_ts: <ts>,
      evaluator_artifact_ref: <ref>,
      evaluator_cycle_start_ts: <ts>,
      evaluator_cycle_completed_ts: <ts>,
      verdict_token: "REOPEN" | "PASS" | "PASS-DEFERRED" | "ESCALATED",
      verdict_basis_ref: <ref>,
      composite_trigger_state: { P1, P2, P3, P4, P5: bool },
      reopen_interval_from_prior_close?: <duration>   // undefined for cycle 1
    }, ...
  ]
}
```

Every cycle is recorded. Missing cycles are a build defect.

### 3.4 FRAME_REGISTRY_BLOCK

```
{
  ram_frame_id: <id>,
  evaluator_frame_id: <id>,
  divergence_verified: bool,
  divergence_verification_method: <text>,
  verified_at: <ts>
}
```

Mandatory even on PASS. The audit is legitimate only if frames diverged.

### 3.5 CEREMONIAL_BLOCK (present iff E9 ceremonial-pattern signal surfaced during the loop)

```
{
  suppressed: bool,
  e9_signal_trace: [...],
  suppressed_reopen_records: [
    { cycle_id, e9_signal, basis, suppressed_at }
  ],
  override_triggered: bool
}
```

Carried into the final artifact -- never hidden, never converted to silent PASS.

### 3.6 SOURCE_PAGE_BLOCK (kept-source naked link list)

```
{
  file: "source-page.txt",                 // emitted companion file: bare URLs, one per line, nothing else
  kept_source_count: <n>,                  // count of kept (accepted) sources with a resolvable link
  links: [ <url>, ... ],                   // the exact lines of source-page.txt, in emission order
  omitted_nonresolvable?: [                 // kept sources with no resolvable link (transparency; NOT on the page)
    { source_id, reason }
  ]
}
```

Produced by RAM's Epistemic Output Layer (S4) per `skills/ram-epistemic-output-layer/references/SOURCE_PAGE_RENDER_SPEC.md`. Definition of **kept**: final-cycle `ram_final_output.search_ledger.sources_accepted` minus any `auto_block` or `sources_rejected` entry. `links` contains ONLY kept-source URLs -- no rejected or skipped source ever appears. The emitted `source-page.txt` is naked: one bare URL per line, no titles, labels, sections, numbering, or annotations. On ESCALATED, the block is built from the last completed RAM cycle (empty `links` if no cycle produced an accepted set).

---

## 4. ESCALATION_BLOCK (present iff `convergence_verdict == ESCALATED`)

```
{
  reason: "bound_exceeded" | "sub_dwell_cap" | "p4_novelty_fail" | "ceremonial_override" | "frame_convergence" | "isolation_alarm" | "operator_abort" | "enforcement_surface_degraded" | "bound_violation" | "dwell_violation" | "ceremonial_mask_leak" | "advisory_regression",
  originator: "e7" | "coordinator",
  receiver_id: <charter.escalation_receiver_id>,
  history_snapshot: <full_loop_history_block>,       // duplicates 3.3 for reviewer convenience
  composite_trigger_final_state: { P1, P2, P3, P4, P5: bool },
  oscillation_diagnostic?: {
    ogata_mode: "sub_critical_damping" | "gain_margin_breach" | "phase_margin_breach",
    reopen_interval_distribution: [...],
    repeat_evidence_refs: [...]
  },
  charter_snapshot: {
    reopen_ceiling_N, dwell_time_floor, sub_dwell_cap,
    materiality_threshold, disagreement_threshold,
    composite_trigger_spec
  },
  enforcement_surface_attestation: {
    build_time_proof_ref: <ref>,
    runtime_ack_only_verified: bool
  },
  reviewer_paths: [
    "accept_escalation",
    "amend_charter_and_restart",
    "flag_component_defect"
  ]
}
```

The `reviewer_paths` field is a reminder to the human reviewer of the three legitimate dispositions (per `ESCALATION_PROTOCOL.md` Section 5.2). It is not a selector; it is a signpost.

---

## 5. Invariants

| Invariant | Check |
|---|---|
| Every PASS artifact has non-null `ram_final_output` AND non-null `evaluator_final_audit` | Build-time + runtime |
| `loop_history.cycles[*].verdict_token` all present and binary | Runtime |
| `frame_registry.divergence_verified == true` in every PASS artifact | Runtime (false -> ESCALATED instead) |
| Every ESCALATED artifact has non-null `escalation_block` | Runtime |
| Every ESCALATED artifact carries full `loop_history` (no truncation) | Runtime |
| `ceremonial_detection` block present iff any cycle had an E9 ceremonial signal | Runtime |
| `source_page` present in every artifact; `source_page.links` are bare URLs of kept sources only; no `sources_rejected`/`avenues_skipped` source appears | Runtime |
| Artifact is single emission (not multi-part across channels) | Runtime |

---

## 6. Rendering

The schema above is the **transport layer**. User-facing rendering is an orchestration-engineering concern outside this coordinator; the coordinator's job is to produce the schema, not to decide presentation.

Minimum rendering requirements for any downstream renderer:

- Surface `convergence_verdict` prominently.
- Surface `ram_final_output.three_axis_confidence` AND `evaluator_final_audit.three_axis_audit_in_evaluator_frame` side-by-side (dual-system is the point).
- Surface `evaluator_final_audit.disagreement_with_ram` as a first-class display.
- Surface `loop_history.reopen_count` and `total_cycles` (transparency on how many turns it took).
- Surface `ceremonial_detection` block (if present) with explicit explanation.
- Surface `escalation_block` (if present) with full reason, history, and reviewer paths.
- Surface `source_page` as a distinct copy-ready block and emit the companion `source-page.txt` file: the naked kept-source link list the operator can select-all and paste into a notebook in one motion. Render it verbatim -- do NOT add titles, numbering, or annotations to it.

Progressive disclosure is allowed -- but NO non-negotiable block may be hidden behind disclosure that the casual reader cannot discover.

---

## 7. Cross-Reference

- `SKILL.md` Phase 5 (TERMINAL-PASS), Phase 6 (TERMINAL-ESCALATED).
- `LOOP_STATE_MACHINE.md` Sections 2-3 (TERMINAL states).
- `ESCALATION_PROTOCOL.md` Section 3 (escalation package; ESCALATION_BLOCK here duplicates with reviewer-facing structure).
- RAM Solution Architecture Section 3.1 (RAM deliverables).
- Evaluator Solution Architecture Section 3.1 (Evaluator deliverables).
