# INTERFACE CONTRACTS -- Evaluator Router

**Phase:** 7 -- orchestration-engineering-max
**Scope:** Per-edge input/output schemas and write rules for every router boundary. Zero-overlap with RAM is structural, not narrative; these contracts enforce it.

---

## 1. Boundary Inventory

| ID | Edge | Direction | Authority |
|---|---|---|---|
| C1 | Operator -> Router | IN | Operator via slash command |
| C2 | Router -> E1 Isolation Verifier | OUT | Router |
| C3 | E1 -> Router | IN | E1 report |
| C4 | Router -> E6 Audit Charter Lock | OUT | Router |
| C5 | E6 -> Router | IN | E6 lock record |
| C6 | Router -> E3 Frame Host | OUT | Router |
| C7 | E3 -> Router | IN | E3 loaded_frame_handle + registry write confirm |
| C8 | Router -> E8 Frame Divergence Gate | OUT | Router |
| C9 | E8 -> Router | IN | E8 gate verdict + registry seal confirm |
| C10 | E8 -> Router (runtime) | IN | E8 abort_signal (asynchronous) |
| C11 | Router -> E2 Audit Method Engine | OUT | Router |
| C12 | E2 -> Router | IN | E2 Audit Artifact ref |
| C13 | Router -> E5 Blind-Spot Mapper | OUT | Router |
| C14 | E5 -> Router | IN | E5 findings + diagnostic metadata |
| C15 | Router -> E4 Independent Scoring Layer | OUT | Router |
| C16 | E4 -> Router | IN | E4 Scored Artifact + ledger render |
| C17 | Router -> E9 Self-Audit Resistance Monitor | OUT | Router |
| C18 | E9 -> Router | IN | E9 signals |
| C19 | Router -> E7 Reopen Authority Enforcer | OUT | Router |
| C20 | E7 -> Router | IN | E7 verdict token + composite evidence |
| C21 | Router -> top-level loop (bridge) | OUT | Router; enforcement-only |
| C22 | top-level loop -> Router (bridge) | IN | RAM artifact drop; read-only |
| C23 | Router <-> Frame Registry | IN/OUT | Reads only via the artifact owner E8 |
| C24 | Router <-> Evaluator Search Ledger | IN/OUT | Writes only via E4 render authority |

---

## 2. Per-Edge Schemas

### C1 -- Operator -> Router

```
slash_command := {
  command: "/eval-audit" | "/eval-charter" | "/eval-abort",
  args: {
    ram_output_path?: string,           // /eval-audit; must be inside bridge/ram-to-evaluator-handoff/
    charter_path?: string,              // /eval-charter
    run_id?: UUID,                      // /eval-audit optional; /eval-abort required
    amend?: boolean,                    // /eval-charter
    target_ram_run_id?: string,
    role_divider_ack_path?: string,     // /eval-audit, conditional
    reason?: string                     // /eval-abort
  }
}
```

**Write rule:** the router NEVER reads arguments pointing inside `ram/` or `state/ram/*`. Rejects with `EC-INPUT-MISSING` and surfaces silo-breach reason.

### C2 -- Router -> E1

```
e1_invocation := {
  run_id,
  ram_manifest_path: "ram/manifest.json",
  evaluator_manifest_path: "evaluator/manifest.json",
  peer_manifests: [...],                              // all other plugins present in host
  ram_state_snapshot_metadata: "state/ram/*",         // metadata only; content read refused
  evaluator_state_snapshot: "state/evaluator/*",
  retrieval_capability_catalog,
  tick_handle,
  tick_cadence_spec: "every-skill-invocation + every-state-mutation + periodic-merkle-recompute"
}
```

### C3 -- E1 -> Router

```
isolation_verification_report := {
  report_id: UUID,                                    // becomes isolation_verifier_clearance_id
  run_id,
  phase_a: { boundary_declaration_verdict: PASS | FAIL, per_axis_verdicts: {path, state_key, retrieval, library} },
  phase_b: { baseline_captured: boolean, per_plugin_merkle_roots: map },
  phase_c: { continuous_invariant_log_excerpt: events[] },
  phase_d: { violation_records: [] },
  phase_e: { chaos_experiment_trap_rate: float (0.0..1.0) },
  phase_f: { lock_down_state: { frozen_since, expansion_attempt_log } },
  phase_g: { final_verdict: PASS | FAIL, failing_axes: [] }
}
```

**Acceptance rule:** `final_verdict == PASS AND per_axis_verdicts all PASS AND chaos_experiment_trap_rate == 1.0 AND no global breaker open`. Anything else: router HALTs.

### C4 -- Router -> E6

```
e6_invocation := {
  mode: "initial-lock" | "amendment",
  audit_id: UUID,
  target_ram_run_id,
  proposed_charter: envelope,                         // conforming to charter-envelope-schema.json
  amendment_request?: diff                            // amendment mode only
}
```

### C5 -- E6 -> Router

```
charter_lock_record := {
  charter_version: int,                               // monotonic
  charter_hash: SHA-256,
  locked_at: ISO-8601,
  audit_id,
  target_ram_run_id,
  victore_declarations: { volitions, implementation, contexts, time, outcomes, rivalry, emergence },
  audit_questions: [{ question_id, question_intent, frame_id, ram_frame_id, theta_q, audit_mode }],
  evidence_classes_admissible: [],
  stakeholders: [],
  reopen_thresholds: { ceiling_N, dwell_time_floor, composite_spec, escalation_receiver_id, materiality_threshold, disagreement_threshold, noise_floor },
  amendment_policy: obj,
  isolation_verifier_clearance_id: string             // back-reference to R1
}
```

Or:

```
charter_refusal := {
  refusal_reason: "charter-intake-incomplete" | "charter-intake-inconsistent" | "victore-dimension-missing" | "ram-charter-content-leaked-into-audit-charter",
  missing_or_invalid_fields: [],
  requires_e1_isolation_reopen_review: boolean
}
```

### C6 -- Router -> E3

```
e3_invocation := {
  run_id,
  question_id,
  frame_id,                                           // required; NEVER defaulted by router
  ram_frame_id,                                       // required
  question_intent: "applied" | "lived" | "stakeholder" | "mechanism" | "historical" | "discursive" | "indigenous",
  audit_target_artifact_ref,
  role_divider_acknowledgment?: structured_token,     // required iff realist_cmo x RAM_S03
  population_flag?: { indigenous_or_non_western: boolean },
  isolation_verifier_clearance_id                     // propagated from R1
}
```

### C7 -- E3 -> Router

```
e3_result := {
  loaded_frame_handle: { retrieve(), score(), terminate?(), compat() },
  compatibility_declaration: { methodological, semantic, ontological, summary: "DISTINCT" | "PARTIAL" },
  role_divider_decision: "NOT_REQUIRED" | "REQUIRED_AND_PRESENT" | "REQUIRED_AND_MISSING_REFUSE",
  chilisa_constraint_state: "NONE" | "OVERLAY_ACTIVE" | "PRIMARY_FRAME",
  frame_registry_write_confirmed: { path, hook_bindings_fingerprint, prior_swap_detected: boolean },
  ledger_seed_confirmed: { entry_id }
}
```

Or refusal:

```
e3_refusal := {
  reason: "UNKNOWN_FRAME" | "MISSING_RAM_FRAME" | "NEEDS_INPUT_FRAME_ID" | "MALFORMED_HOOK" | "REGISTRY_WRITE_FAILURE" | "ROLE_DIVIDER_BREACH"
}
```

### C8 -- Router -> E8

```
e8_invocation := {
  question_artifact: { question_id, question_type, ram_frame_declared_axioms_on_three_dimensions },
  loaded_frame_handle,                                // from C7
  theta_q: { value: float, threshold_source: "calibrated_record_ref" | "default_conservative" },
  e1_cleared: true,                                   // must be true
  error_rate_baseline: float,                         // from E2 baseline
  isolation_verifier_clearance_id
}
```

### C9 -- E8 -> Router

```
e8_gate_verdict := {
  overall_verdict: "PASS" | "FAIL" | "REFUSED",
  refusal_reason?: "E1_NOT_CLEARED" | "FRAME_HOST_NOT_LOADED" | "RAM_FRAME_UNPARSEABLE" | "MISSING_THETA" | "REGISTRY_WRITE_FAILURE",
  frame_pair_id?: UUID,                               // on PASS only
  stage1_binary_verdict: "PASS" | "FAIL",
  stage1_failing_dimensions: [],
  stage2_divergence_index: float,
  stage2_threshold: float,
  stage2_threshold_source: "calibrated_record_ref" | "default_conservative",
  stage2_verdict: "PASS" | "FAIL",
  frame_registry_record_ref: path
}
```

### C10 -- E8 runtime abort

```
e8_abort_signal := {
  run_id,
  question_id,
  frame_pair_id,
  detector: "ADWIN" | "PH" | "DDM" | "lexical-jaccard" | "prior-KL" | "frame-term-leakage",
  signal_value: float,
  triggered_abort: true,
  timestamp_utc
}
```

**Router behavior:** on receipt, HALT the current R-phase, notify E7 for convergence-failure mode handling, request E8 to flip `overall_verdict` on the Frame Registry record to `REFUSE`.

### C11 -- Router -> E2

```
e2_invocation := {
  run_id,
  question_id,
  frame_pair_id,
  loaded_frame_handle,
  charter_scope,
  isolation_verifier_clearance_id,
  ram_output_artifact_ref,                            // read-only
  ledger_write_handle
}
```

### C12 -- E2 -> Router

```
e2_audit_artifact := {
  run_id, question_id,
  per_claim_findings: [],
  per_source_findings: [],
  per_methodology_findings: [],
  cross_level_tensions: [],
  mode_choice_log_ref,
  inventory_snapshot,
  ambiguity_register_snapshot,
  ledger_write_confirmations: [],
  replication_rate: float,                            // if >30%, triggers E6 + E9 consultation
  isolation_verifier_clearance_id
}
```

Or refusal:

```
e2_refusal := {
  reason: "frame-registry-missing" | "charter-intake-incomplete" | "frame-mismatch" | "role-divider-breach" | "replication-out-of-scope" | "ledger-handle-unavailable" | "e1-clearance-missing"
}
```

### C13 -- Router -> E5

```
e5_invocation := {
  run_id, question_id,
  charter_criterion: { fairness_definition, threshold, claim_type_scope, criterion_hash },
  e2_audit_artifact_ref,
  loaded_frame_handle,
  frame_registry_ref,
  isolation_verifier_clearance_id
}
```

### C14 -- E5 -> Router

```
e5_findings := {
  run_id, claim_id, probes_fired: [], signals_fired: [], severity_max, taxonomy_version, ledger_refs,
  diagnostic_metadata_for_e9: { probes_run_count, probes_fired_count, nulls_emitted, criterion_hash, taxonomy_version, delta_metrics }
}
```

Or halt:

```
e5_halt := {
  reason: "CRITERION_NOT_PRE_REGISTERED" | "CRITERION_MODIFIED_MIDRUN",
  signal: "signal-3-fired",
  escalated_to: "E6"
}
```

### C15 -- Router -> E4

```
e4_invocation := {
  run_id, question_id,
  e5_findings_ref,
  e2_audit_artifact_ref,
  ram_confidence_input,
  loaded_frame_identity, role_divider_state,
  frame_registry_ref,
  evaluator_search_ledger_ref,
  isolation_verifier_clearance_id
}
```

### C16 -- E4 -> Router

```
e4_scored_artifact := {
  run_id, question_id,
  frame_identity: "PRAG" | "PHEN" | "CONSTR" | "REAL-AC" | "HIST" | "DISC" | "CHILISA",
  frame_role_divider_state,
  disagreement_blocks: [                              // three, at TOP
    { axis: "Evidence-Independent", evaluator_value, formula_id: "PRAG-* | ...", ram_value, delta, rationale },
    { axis: "Transportability-Independent", ... },
    { axis: "Decision-Independent", ... }
  ],
  axis_records: [                                     // three, non-collapsed
    { axis, value, evidence_pointers, rationale, formula_id, non_assertible?: boolean, ram_silent_marker?: boolean },
    ... (three total)
  ],
  calibrated_silence_stamps: [],                      // per zero-delta axis
  ledger_snapshot: { provenance_hash, zero_overlap_verified: true },
  emission_metadata_for_e9: { frame, formula_ids, non_assertible_flags, ram_silent_markers, disagreement_counts_per_axis },
  timestamp
}
```

**Router structural check:**
- `axis_records.length == 3`
- `disagreement_blocks.length == 3`
- No field named `composite` / `overall` / `integrated` / `holistic` anywhere in the schema.
- Every `formula_id` matches one of the seven frame prefixes; NONE match RAM prefix.

### C17 -- Router -> E9

```
e9_invocation := {
  run_id, question_id,
  e5_findings_ref,
  e4_scored_artifact_ref,
  e7_history: [],                                     // empty on first cycle
  ram_artifact_ref,                                   // read-only
  frame_registry_ref,                                 // read-only
  calibration_harness_handle?,                        // required if calibration scheduled
  inter_evaluator_instance_pool_handle,
  isolation_verifier_clearance_id
}
```

### C18 -- E9 -> Router

```
e9_signals := {
  over_report_signal?: { per_finding_verdicts, aggregate_candidates, affordances_fired },
  under_report_signal?: { per_surface_verdict, indistinguishability_verdict, calibration_freshness },
  calibrated_silence_report?: {                       // REQUIRED when silence applies
    bounded_surface_S: [],
    seeded_catch_rate_R: { per_class: map },
    equivalence_test_result: TOST_record,
    residual_ceremonial_risk_note: string,
    taxonomy_completeness_disclaimer: string
  },
  ceremonial_pattern_signal?: { active: boolean, evidence },
  calibration_harness_record?: { per_class_catch_rates, ECE, Brier, reliability_diagram, indistinguishability_verdict, taxonomy_version, residuals },
  architectural_violation_signals: []
}
```

**Router gating check at R7 exit:**
- If calibrated_silence_report applies, verify all FIVE fields present.
- Verify no output contains "positive-nothing-found" as a current affordance (forbidden phrasing).
- Verify reporting surface for calibrated silence equals reporting surface for findings.

### C19 -- Router -> E7

```
e7_invocation := {
  run_id, question_id,
  e5_findings,
  e4_disagreement_artifact,
  e9_signals,                                         // all four channels
  reopen_history,                                     // from Ledger
  charter_parameters: { reopen_ceiling_N, dwell_time_floor, composite_spec, escalation_receiver_id, materiality_threshold, disagreement_threshold, noise_floor },
  frame_registry_ref,
  isolation_verifier_clearance_id
}
```

### C20 -- E7 -> Router

```
e7_reopen_emission := {
  verdict: "REOPEN" | "PASS" | "PASS-DEFERRED" | "ESCALATED",   // EXACTLY ONE
  basis: composite_evidence_record,
  cycle_id,
  suppressed_ceremonial_reopen_record?: { suppressed: true, e9_signal, basis },
  escalation_record?: { escalated: true, reason, history_snapshot, receiver_id },
  reopen_event_log_entry_ref
}
```

**Router refusal checks:**
- `verdict` must be in the four-token set; else `EC-ADVISORY-REGRESSION`.
- For `REOPEN`: `basis.composite_evidence_record` must be present; else `EC-GOODHART-DRIFT`.
- For `PASS` with active ceremonial-pattern: `suppressed_ceremonial_reopen_record` must be present; else `EC-CEREMONIAL-MASK`.

### C21 -- Router -> top-level loop (bridge)

Path: `bridge/evaluator-to-ram-reopen/<run-id>.json`.

```
eval_handoff := {
  verdict_token: "REOPEN" | "PASS" | "PASS-DEFERRED" | "ESCALATED",
  composite_evidence_record,
  scored_artifact_ref,
  blind_spot_findings_ref,
  e9_signals_ref,
  frame_registry_entry_ref,
  evaluator_search_ledger_snapshot_ref,
  isolation_verifier_clearance_id,
  audit_artifact_ref,
  run_id, question_id, target_ram_run_id,
  charter_version, charter_hash,
  sealed_at: ISO-8601
}
```

**Contract:** acknowledgement-only response expected. Any richer reply detected -> `EC-ENFORCEMENT-SURFACE-DEGRADED`.

### C22 -- top-level loop -> Router (bridge)

Path: `bridge/ram-to-evaluator-handoff/<ram-run-id>.json` (read-only to the Evaluator side).

```
ram_artifact_drop := {
  ram_run_id,
  ram_output_artifact: { claim_decomposition, per_claim_findings, three_axis_confidence, ram_search_ledger_rendered, ram_declared_frame_per_question: { RAM_S02 | RAM_S03 | RAM_S08 on three Kuhnian dimensions }, surprise_register_rendered },
  ram_charter_hash,
  dropped_at
}
```

**Router behavior:** read once, never mutate, never write back to this path. Pass artifact reference through to E2/E4/E5/E9 as needed.

### C23 -- Router <-> Frame Registry

- Owner: E8. Router NEVER writes directly.
- Router reads via the record-path `state/evaluator/frame-registry/<run-id>/<question-id>.yaml` to verify write discipline at each R-phase exit.
- Structural checks performed by router:
  - `isolation_verifier_clearance_id` present in `provenance`.
  - `refinement_residue` field present (may be `[]`).
  - `overall_verdict` reflects current gate state.
  - Sealed at R9 (post-seal writes rejected by E8).

### C24 -- Router <-> Evaluator Search Ledger

- Owner: E4 (render). Router NEVER writes directly; router requests writes through E4's delegate at halt paths.
- Router verifies zero-overlap vs RAM's Search Ledger at R6 and R9:
  - Path root `state/evaluator/evaluator-search-ledger/` disjoint from `state/ram/ram-search-ledger/`.
  - Record kinds (audit-query / audit-finding / audit-null / audit-refusal / reopen-event) disjoint from RAM's (every-query / every-accepted / every-rejected / every-skipped).
  - Writer set disjoint ({E3 hook, E2, E5} vs {S1, S2, S3, S7, S8}).

---

## 3. Cross-cutting write rules (orchestration-level)

### 3.1 Frame Registry

| Field | Writer | Phase | Mandatory? |
|---|---|---|---|
| `schema_version` | E8 | R4 | Yes |
| `frame_pair_id` | E8 | R4 | Yes (on PASS) |
| `ram_frame` block | E3 | R3 | Yes |
| `evaluator_frame` block | E3 | R3 | Yes |
| `role_divider` block | E3 | R3 | Yes |
| `divergence_report` | E8 | R4 | Yes |
| `refinement_residue` | E8 | R4 | Yes (may be `[]`) |
| `runtime_log` | E8 | R4..R9 | Yes (append-only) |
| `provenance.sealed_at` | E8 | R9 | Yes at seal |
| `provenance.isolation_verifier_clearance_id` | E8 | R4 | Yes |

**Router structural check at R9:** all mandatory fields present; `sealed_at` set; `overall_verdict` final (PASS or REFUSE).

### 3.2 Evaluator Search Ledger

| Record kind | Writer | Phase | Notes |
|---|---|---|---|
| router-intake seed (alias within `audit-refusal` family) | Router via E4 | R0 | Optional; may defer to R6 when E4 opens ledger |
| `audit-query` | E3 hook | R3 | Seed entry naming bound frame |
| `audit-query` | E2 | R5 | Every audit question |
| `audit-query` | E5 | R6a | Every probe invocation |
| `audit-finding` | E2 | R5 | Per-claim / per-source / per-methodology finding |
| `audit-finding` | E5 | R6a | Per-probe fired finding |
| `audit-null` | E5 | R6a | Per-probe null-run (never silent) |
| `audit-refusal` | E2/E3/E5/E6/E8/Router (via E4) | R0..R9 | Any classified refusal |
| `reopen-event` | E7 via E4 render | R8 | Final verdict event |

**Zero-overlap discipline (router-enforced):**
- No record kind matches RAM's ledger kinds.
- No writer belongs to the RAM writer set {S1, S2, S3, S7, S8}.
- Path root is always `state/evaluator/evaluator-search-ledger/` and never `state/ram/*`.
- Schema fields are disjoint from RAM's; router rejects any write that reads RAM schema keys into an Evaluator record.

---

## 4. Isolation pre-flight HALT gate contract

### 4.1 Router invocation (R1)

Router MUST invoke E1 at R1 for every `/eval-audit` AND every `/eval-charter`. (Abort path R-ABORT also calls E1 post-flight for integrity check.)

### 4.2 Acceptance rule

PASS iff:

1. `phase_g.final_verdict == PASS`.
2. `phase_a.per_axis_verdicts` all PASS (path, state_key, retrieval, library).
3. No global Circuit Breaker open.
4. `phase_e.chaos_experiment_trap_rate == 1.0`.
5. Cross-cutting artifact schema-distinctness check passed.

Anything else: HALT.

### 4.3 Clearance ID propagation

On PASS, router records `isolation_verifier_clearance_id = report.report_id`. This ID propagates into:

- Every Frame Registry record (via `provenance.isolation_verifier_clearance_id`).
- Every Ledger write metadata (E4 renders this in the snapshot).
- Every E2/E5/E4/E9/E7 invocation envelope.
- The final bridge handoff at R9.

**Router contract:** any write that omits this ID is a contract violation -> HALT.

---

## 5. Calibrated-silence gating contract

### 5.1 Trigger

Calibrated silence applies when:

- E5 found no probe fires across all six probes; OR
- E4 computed zero-delta on one or more axes; OR
- E7 is about to emit PASS and the downstream artifact will contain apparent-silence surfaces.

### 5.2 Five-field requirement (router-enforced at R7 exit)

Every `calibrated_silence_report` MUST carry:

1. **Bounded surface S** -- explicit watch-surface list.
2. **Seeded catch rate R** -- per-class from fresh indistinguishability-passing calibration.
3. **Equivalence-test result** -- TOST (Lakens 2016) against pre-registered tolerance band.
4. **Residual ceremonial-risk note** -- explicit statement of what is OUTSIDE S.
5. **Taxonomy-completeness disclaimer** -- Metaxa et al. 2021 grounding.

### 5.3 Forbidden phrasing

Any output containing "positive-nothing-found" as a current affordance -> HALT. Phrasing may appear ONLY in retirement / anti-pattern / forbidden-phrasing context.

### 5.4 Reporting-surface parity

Calibrated-silence reports emit on the SAME surface as findings. No demotion, no bundling, no footnote placement.

---

## 6. Write-discipline errors (router-level)

| Error | Trigger | Router response |
|---|---|---|
| Frame Registry write missing `isolation_verifier_clearance_id` | Any phase | HALT with EC-ROUTER-CONTRACT-VIOLATION |
| Ledger record with RAM schema key | Any phase | HALT with EC-LEDGER-LEAK; alarm to E1 |
| Ledger path inside `state/ram/*` | Any phase | HALT immediate; silo breach |
| Frame Registry `refinement_residue` absent | R4/R9 | HALT; E8 repairs or REFUSE |
| E4 emission with composite field | R6 exit | HALT with EC-COLLAPSE-DETECTED |
| E4 emission with RAM-prefix formula ID | R6 exit | HALT with EC-MIRROR-DETECTED |
| E7 emission outside four-token set | R8 | HALT with EC-ADVISORY-REGRESSION |
| Calibrated silence emission missing field(s) | R7 exit | HALT with EC-SILENCE-UNCALIBRATED |
| "Positive-nothing-found" phrasing as current affordance | Any phase | HALT; repair to calibrated-silence |
| Bridge handoff reply > acknowledgement | R9 | HALT with EC-ENFORCEMENT-SURFACE-DEGRADED |

---

**End of INTERFACE_CONTRACTS.md.**
