WFGY/ProblemMap/Twin_Atlas/runtime/forward-route-contract.md

<!--
AI_NOTE_START

Document role:
This page is the public forward-route contract page for the runtime layer of WFGY 4.0 Twin Atlas Engine.

What this page is for:
1. Explain what the route-first contract is inside the Twin Atlas runtime.
2. Show what the Forward Atlas side must preserve before any stronger governance step happens.
3. Help readers understand why route quality, fit honesty, broken invariant, and misrepair shadow matter so much.
4. Provide a public runtime-facing entry into the route contract without dumping the full raw ontology.

What this page is not:
1. It is not the flagship landing page.
2. It is not the full Troubleshooting Atlas document.
3. It is not the full hidden substrate.
4. It is not the final authorization layer.
5. It is not proof that every future routing subtype is already fully finalized here.

Reading order:
1. Read the Twin Atlas README first.
2. Read the Runtime README and Runtime Constitution second.
3. Read this page when you want to understand the route-first runtime contract.
4. Then move into Bridge, Inverse Governance Contract, and State Machine and Output.

Important boundary:
This page presents the public route-first contract of Twin Atlas.
It does not replace the full Forward Atlas family corpus.
It also does not grant authorization or final repair legality by itself.

AI_NOTE_END
-->

# 🗺️ Forward Route Contract

> Before a system is allowed to speak strongly, it should first prove that it is looking in the right structural region.

This page explains the **forward-route contract** inside the runtime layer of **WFGY 4.0 Twin Atlas Engine**.

If Inverse Atlas asks whether an answer has earned the right to exist that strongly yet, then the forward-route contract asks an earlier question:

**what is the strongest honest structural cut available right now?**

That is the job of the route-first side.

This page exists because Twin Atlas should not treat routing as a vague feeling.

It should treat routing as a visible contract.

---

## 🌍 What this page is really about

Many reasoning failures begin before authorization.

They begin much earlier, when the system cuts into the wrong region.

That first cut matters because a bad first cut often causes:

- a bad first repair
- wasted debugging effort
- false closure around the wrong family
- downstream cleanup before structural contact
- route lock-in under weak evidence

That is why Twin Atlas needs a real route-first contract.

The route contract is the part of the engine that says:

**before we argue about how strongly to speak, we should first state what route we think we are on, how strong that route is, and what uncertainty still remains alive.**

---

## 🧠 What the forward-route contract owns

The forward-route contract owns the route-first side of the runtime.

It is responsible for things like:

- choosing the strongest current route
- preserving the nearest live competitor
- naming the likely broken invariant
- keeping fit honesty
- proposing the safest first repair direction
- preserving the tempting wrong-first-fix
- calibrating confidence
- calibrating evidence sufficiency

In simple language:

**this is the part of the engine that tries to look in the right place first, and to say honestly how stable that first cut really is.**

It does **not** own final authorization.
It does **not** own public ceiling.
It does **not** own final repair legality.

Those belong later in the loop.

---

## 🚫 What this contract is not allowed to do

The forward-route contract is important, but it must stay inside its own boundary.

It must not:

- authorize the final answer
- pretend a plausible route is already settled truth
- erase a live neighboring route for neatness
- upgrade family-level fit into fake subtype precision
- turn a first repair direction into structural repair verdict
- spend more confidence than the evidence actually supports

That matters because route quality and release legality are not the same job.

Twin Atlas keeps them separate on purpose.

---

## 🧱 The minimum forward contract

A healthy forward-route contract should preserve a small group of core fields.

At minimum, it should keep:

- `primary_family`
- `secondary_family`
- `why_primary_not_secondary`
- `broken_invariant`
- `best_current_fit`
- `first_fix_direction`
- `misrepair_risk`
- `confidence`
- `evidence_sufficiency`

It may also preserve:

- `need_more_evidence`
- `overlay`

This matters because Twin Atlas does not want routing to dissolve into loose commentary.

It wants routing to remain structurally legible.

---

## 🧩 What each part is really doing

### 🟦 `primary_family`
This is the strongest current route-first cut.

It does **not** mean eternal truth.
It means:

**this is the best current structural region to work from.**

### 🟨 `secondary_family`
This is the nearest live competitor.

It should only appear when the competing route is materially alive.

It is not decorative nuance.
It is preserved pressure.

### 🧠 `why_primary_not_secondary`
This is the discrimination layer.

It explains why the leading route currently wins, without pretending the competing route is already dead if it is still alive.

### 🧱 `broken_invariant`
This is one of the most important fields in the whole contract.

It names the structural failure condition that appears broken enough to anchor the route.

Without this field, routing becomes vague and repair becomes fake.

### 🛠️ `first_fix_direction`
This is the first repair candidate.

It should point toward the broken invariant.

It should not become a random cleanup suggestion.

### ⚠️ `misrepair_risk`
This is the tempting wrong-first-fix.

It matters because a lot of systems do not only miss the right route.
They also confidently choose the wrong first move.

### 📏 `best_current_fit`
This tells the engine how precise the route has actually earned the right to be.

### 📉 `confidence`
This is route confidence, not performance tone.

### 📉 `evidence_sufficiency`
This tells the system how much structural support it really has.

### 🔍 `need_more_evidence`
This should appear only when missing evidence could materially change the route, fit, or first fix.

### 🫧 `overlay`
This is optional refinement only.
It must never replace the main route.

---

## 🎯 The deepest law of this page

The deepest law of the forward-route contract is simple:

**choose the highest honest route resolution under available evidence**

Not the prettiest route.
Not the most dramatic route.
Not the most marketable route.
Not the most specific-looking route.

The highest **honest** route resolution.

That is why Twin Atlas values:

- honest family-level fit
over
- decorative false precision

That law is one of the core reasons this engine matters.

---

## 🟨 Why honest coarse routing is so important

One of the most common AI failures is fake precision.

The route contract is explicitly designed to resist that.

If the evidence is thin, the engine should prefer:

- family-level truth
- unresolved subtype
- visible neighboring pressure
- lower confidence
- preserved ambiguity

rather than:

- subtype theater
- over-clean stories
- one neat answer that the structure has not really earned

This is why **honest coarse** is not weakness.

It is structural discipline.

---

## 🧭 What “best current fit” really means

The engine uses `best_current_fit` to tell the truth about how narrow the route really is.

A healthy route contract usually lives in one of these states:

### ⬛ `no-fit`
No honest family-level route is defensible yet.

### 🟦 `family-level`
One family is clearly stronger, but narrower precision is not yet honest.

### 🟨 `unresolved_subtype`
The broad family is stable enough, but subtype pressure remains alive.

### 🟩 `node-level`
The route has actually earned narrower structural precision.

This matters because route resolution should not be chosen for aesthetic pleasure.

It should be chosen by evidence.

---

## ⚠️ Why misrepair shadow is so important

Many reasoning systems make two mistakes in a row:

1. they cut into the wrong region  
2. they confidently choose the wrong first fix  

That second failure is often more expensive than the first.

That is why Twin Atlas preserves `misrepair_risk`.

This field exists so the next layer still knows:

- what the seductive wrong-first-fix is
- where wasted effort is most likely to happen
- what “sounds smart” but is structurally premature

Without misrepair shadow, the engine becomes too neat and too fragile.

---

## 🔍 Why neighboring pressure must remain alive

A lot of low-quality systems look clean because they delete competition too early.

Twin Atlas does not want that.

If a nearby competing route remains materially alive, the route contract must preserve it.

That is the job of:

- `secondary_family`
- `why_primary_not_secondary`
- honest `best_current_fit`
- honest `confidence`
- honest `need_more_evidence`

This matters because a route contract should not win by tidiness.

It should win by structural honesty.

---

## 📉 Confidence and evidence must stay tied

The route contract also protects against confidence theater.

That means:

- high confidence should not appear on weak evidence
- medium confidence should not quietly act like strong certainty
- cleaner wording should not act like stronger support

In Twin Atlas, confidence is not style.

It is a calibrated routing signal.

The same is true for evidence sufficiency.

It exists to stop the system from spending more certainty than it actually has.

---

## 🌉 Why this page matters for Bridge

Bridge becomes much stronger when the forward-route contract is strong.

Because Bridge is not supposed to invent route structure.

It is supposed to preserve it.

That means a good forward-route contract gives Bridge exactly the kinds of signals it needs:

- which route leads
- which route still competes
- what structural break seems central
- what first repair move is only a candidate
- what wrong-first-fix remains dangerous
- how much confidence and support really exist

The cleaner this contract is, the less Bridge has to compensate for upstream vagueness.

---

## ⚖️ Why this page still does not authorize anything

This is one of the most important boundaries in the whole engine.

A strong route contract still does **not** mean:

- the answer is now authorized
- node-level certainty is automatically lawful
- the repair is structural
- the competing route is dead
- the public answer may now speak at full strength

Those questions belong later.

That is exactly why Twin Atlas separates:

- route-first discipline
from
- legitimacy-first governance

If those collapse into each other, the engine becomes smoother, but less honest.

---

## ✅ What is already fair to say

At the current stage, these statements are fair:

- Twin Atlas already has a meaningful route-first contract surface
- the route contract already has a clear minimum field structure
- broken invariant, fit honesty, and misrepair shadow already act like core load-bearing ideas
- the route-first side already matters far beyond topic matching or generic classification
- this page already makes the runtime spine more complete and more buildable

These are strong claims.

They are also disciplined claims.

---

## 🚧 What should not yet be claimed

This page should not be used to claim that:

- every future family subtype is already frozen
- every routing ontology detail is already final
- the full Forward Atlas corpus is already reduced to this one page
- the route contract alone proves final answer legality
- the current route page alone proves a fully finished closed-loop engine

This page defines the public runtime-facing route contract.

It does not pretend to be the total final closure of all future routing formalization.

---

## ✨ One-sentence takeaway

> The forward-route contract is the part of Twin Atlas that forces the engine to state where it is looking, how honestly it has earned that cut, and what uncertainty must still remain alive before stronger governance can even begin.

---

## 🧭 Final note

A lot of systems fail because they answer too strongly.

But many of those failures begin even earlier.

They begin when the system never formed an honest route contract in the first place.

That is why this page matters.

It is where Twin Atlas says:

**before you conclude strongly, show me that you actually know what structural region you are standing in.**

---

## 🔗 Quick Links

### 🏠 Main entry
- [Twin Atlas README](../README.md)

### ⚙️ Runtime surfaces
- [Runtime README](./README.md)
- [Twin Atlas Runtime Constitution](./twin-atlas-runtime-constitution.md)
- [Inverse Governance Contract](./inverse-governance-contract.md)
- [State Machine and Output](./state-machine-and-output.md)
- [Seal and Audit](./seal-and-audit.md)

### 🌉 Bridge surfaces
- [Bridge README](../Bridge/README.md)
- [Why Bridge Exists](../Bridge/why-bridge-exists.md)

### 🧭 Family surfaces
- [Troubleshooting Atlas / Forward Atlas](../../wfgy-ai-problem-map-troubleshooting-atlas.md)
- [Status and Boundaries](../status-and-boundaries.md)
- [Related Documents](../related-documents.md)

### 🧪 Evidence surfaces
- [Evidence Hub](../evidence/README.md)
- [Flagship Cases](../evidence/flagship-cases.md)

### 🗺️ Next recommended page
- [Bridge README](../Bridge/README.md)