NODEDC_1C/docs/ARCH/11 - architecture_turnaround/03 - capability_contract_spec.md

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:

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.