# 03 - Capability Contract Specification

## Purpose

This document defines what every runtime capability must declare in order to participate safely in the assistant architecture.

The system should stop treating capabilities as partially implicit products of:

- intent detection;
- filter extraction;
- recipe selection;
- wording heuristics.

Instead, each capability must be a first-class contract object.

## Capability Contract Object

Each capability must declare the following fields.

### 1. Identity

- `capability_id`
- `domain_id`
- `runtime_lane`
- `intent_ids`

Purpose:

- stable identification;
- relation between capability, domain and route family.

### 2. Entry Semantics

- `entry_modes`
- `supported_transition_classes`
- `frame_compatibility`

Minimum allowed values:

- `root_entry`
- `root_followup`
- `selected_object_drilldown`
- `meta_reuse`
- `clarification_resume`

Purpose:

- define where the capability may legally be entered from.

### 3. Anchor Contract

- `required_anchors`
- `optional_anchors`
- `anchor_source_priority`
- `anchor_admissibility_rules`

Purpose:

- make anchor requirements explicit;
- prevent garbage anchor extraction from being treated as business input.

### 4. Scope Contract

- `organization_scope_behavior`
- `date_scope_behavior`
- `temporal_ceiling_policy`
- `root_context_compatibility`

Purpose:

- define whether the capability reuses, narrows, widens, or rejects prior scope.

### 5. Selected-Object Contract

- `requires_focus_object`
- `accepted_focus_object_kinds`
- `focus_object_override_policy`
- `bundle_reuse_policy`

Purpose:

- define whether the capability depends on an existing selected object;
- define how object continuity is preserved.

### 6. Execution Contract

- `resolver_owner`
- `recipe_owner`
- `execution_adapter`
- `result_shape`
- `answer_object_shape`

Purpose:

- clearly identify the exact runtime owner of execution and output form.

### 7. Truth Gate Contract

- `minimum_evidence_policy`
- `coverage_gate_behavior`
- `truth_mode_fallbacks`
- `blocked_reason_codes`

Purpose:

- declare what counts as sufficient evidence for this capability;
- prevent answer policy from inventing truth semantics later.

### 8. Clarification Contract

- `clarification_triggers`
- `clarification_questions`
- `resume_policy`

Purpose:

- define when the capability must ask, not guess.

### 9. Failure Contract

- `empty_match_behavior`
- `route_expectation_failure_behavior`
- `execution_error_behavior`

Purpose:

- keep failures truthful and stable.

### 10. Acceptance Contract

- `required_unit_tests`
- `required_transition_tests`
- `required_scenario_families`

Purpose:

- make capability completion measurable.

## Minimal Contract Template

Each capability should be designable in the following shape:

```yaml
capability_id: inventory_purchase_provenance_for_item
domain_id: inventory_stock
runtime_lane: address_exact
intent_ids:
  - inventory_purchase_provenance_for_item
entry_modes:
  - selected_object_drilldown
  - clarification_resume
supported_transition_classes:
  - T3
  - T4
  - T5
frame_compatibility:
  root_frame: required
  selected_object_frame: required
required_anchors:
  - item
optional_anchors:
  - organization
  - date_scope
anchor_admissibility_rules:
  - no_low_quality_item_rewrite
  - no_conversational_noise_as_entity
organization_scope_behavior: reuse_or_clarify
date_scope_behavior: respect_root_temporal_ceiling
temporal_ceiling_policy: must_not_expand_beyond_root_without_reason_code
requires_focus_object: true
accepted_focus_object_kinds:
  - inventory_item
bundle_reuse_policy: provenance_bundle_preferred
minimum_evidence_policy: route_specific_threshold
coverage_gate_behavior: partial_or_blocked_if_evidence_insufficient
empty_match_behavior: truthful_empty_match
required_scenario_families:
  - canonical
  - colloquial
  - ui_selected_object
  - short_action_followup
  - pronoun_followup
```

## Contract Rules

### Rule 1. Capability Must Declare Entry Legality

No capability may be entered only because a heuristic guessed it.

It must declare:

- which transition classes are legal;
- which frames are required;
- which frames are incompatible.

### Rule 2. Capability Must Declare Admissible Anchors

No capability may silently accept low-quality business anchors.

It must declare:

- what entity values are required;
- what counts as an admissible extracted value;
- when clarification is mandatory.

### Rule 3. Capability Must Declare Truth Gate Behavior

No capability may leave truth semantics to answer wording.

It must declare:

- what evidence threshold it needs;
- how it behaves under partial evidence;
- when it becomes blocked.

### Rule 4. Capability Must Declare Selected-Object Compatibility

All selected-object actions must explicitly declare:

- whether they require focus object;
- whether they reuse a bundle from prior steps;
- whether they tolerate short follow-up wording.

### Rule 5. Capability Must Declare Scenario Coverage

A capability is not accepted just because canonical wording works.

At minimum it must declare which of the following wording families are required:

- `canonical`
- `colloquial`
- `ui_selected_object`
- `ui_selected_object_colloquial`
- `short_action_followup`
- `pronoun_followup`
- `followup_date_carryover`

## What This Specification Replaces

This specification is designed to reduce architectural pressure on:

- `assistantService`
- hidden carryover logic
- implicit capability semantics in answer shaping

## Done Criteria

This specification is considered operational only when:

- critical capabilities are represented as explicit contract objects;
- contract fields are sufficient to predict allowed entry, required anchors, truth behavior, and scenario acceptance;
- new capability enablement can be reviewed primarily through contract review and tests, not only by reading large service files.