# Gate Interface Contract

A gate is a small, independent recognizer that detects whether a particular relation family is likely relevant to the input. Gates are the cheapest component in the pipeline and run first, in parallel.

---

## Design principle

Gates are **high-recall by design**. It is better to activate an unnecessary specialist than to miss a needed one. A false positive costs budget. A false negative corrupts the answer.

Gates do not solve the task. They do not produce objects, facets, or constraints. They only emit a `GateSignal`.

---

## Input

```
GateInput {
  text:          string           -- raw input text
  context:       string?          -- optional prior context
  span_start:    integer?         -- if operating on a specific span
  span_end:      integer?
  gate_id:       string           -- which gate is being invoked
}
```

---

## Output

```
GateSignal {
  gate_id:        string          -- must match the invoking gate_id
  activated:      boolean         -- did this gate fire?
  confidence:     float [0, 1]    -- confidence in the activation decision
  evidence_spans: Span[]?         -- text spans that triggered the gate
  method:         string          -- "regex" | "rule" | "classifier" | "neural" | "hybrid"
}
```

See `schemas/routing.json#/$defs/GateSignal` for the normative schema.

---

## Invariants

Every gate implementation MUST satisfy all of the following:

1. **Bounded output.** A gate emits exactly one `GateSignal`. No additional text, no secondary outputs.

2. **Idempotent.** Calling a gate twice with the same input produces the same output.

3. **No side effects.** A gate does not modify WorldState. It only reads input text.

4. **Declared method.** The `method` field must accurately reflect how the gate works (regex, rule, classifier, neural, hybrid). This is used for diagnostic filtering.

5. **High-recall posture.** When uncertain, a gate should prefer `activated: true` with lower confidence over `activated: false`. A gate should only return `activated: false, confidence: 0.99` if the signal is clearly and definitively absent.

6. **Self-contained.** A gate may not depend on the outputs of other gates. Gates run in parallel with no inter-gate dependencies.

---

## Standard gate IDs

Gates are identified by string IDs. The following IDs are reserved and have defined semantics. Additional domain-specific gates may be added to the registry.

| gate_id | Fires when input probably contains... |
|---|---|
| `is_math` | Numeric computation, arithmetic, algebra |
| `is_code` | Source code, pseudocode, program structures |
| `has_temporal_relation` | Before/after/during/recurring/sequence |
| `has_spatial_relation` | Location, containment, direction, proximity |
| `has_causal_relation` | Cause/effect/enable/block |
| `has_entity_reference` | Named or implied entities |
| `has_coreference` | Pronouns or aliases that refer back |
| `has_quantity` | Counts, amounts, measures, percentages |
| `has_logical_negation` | Not, unless, except, never |
| `has_comparison` | More/less/same/different/equal |
| `has_planning` | Steps, goals, prerequisites, sequencing |
| `has_constraint` | Requirements, restrictions, conditions |
| `has_state_change` | Status transitions, possession changes |
| `has_ownership_transfer` | Give, sell, take, receive, lose |
| `has_social_intent` | Belief, desire, obligation, deception, trust |
| `requires_external_knowledge` | World facts not inferable from input alone |
| `requires_synthesis_only` | Input is direct and needs no decomposition |

---

## Testing a gate implementation

A gate implementation is valid if it passes all of the following test classes:

**Positive recall tests:** Given input known to contain the relation, the gate fires.
**True negative tests:** Given input that clearly lacks the relation, the gate does not fire.
**Confidence calibration tests:** Confidence scores are higher for clear positives than for ambiguous cases.
**Boundary tests:** Very short input, empty input, non-linguistic input (numbers only, code only) produce valid GateSignal objects.
**Idempotency tests:** Same input, same output on repeated calls.

See `tests/contracts/gate_contract_tests.md` for test case templates.

---

## Implementation guide

A gate may be implemented in any language or framework, as long as it satisfies the contract above. Common approaches:

- **Regex / keyword rules:** fast, zero training cost, fragile on unusual phrasing
- **Feature classifier:** small model trained on labeled examples, better generalization
- **Small neural classifier:** ~1M–10M parameter binary classifier, highest recall potential
- **Hybrid:** rules for high-confidence cases, classifier for uncertain cases

The gate registry (`gates/registry.md`) specifies how to register a new gate implementation.