whetstone_RSA/docs/decision_contract_ontology.md

# Decision Contract Ontology

## Purpose

This document defines the contract vocabulary for `whetstone_RSA`.

The goal is to describe decision problems using orthogonal fields rather than a
single overloaded label.

This is the right approach because `whetstone_RSA` is an applied data science
library. The ontology should describe:

- input shape
- output shape
- constraint type
- policy stability

instead of relying on vague words like `messy`, `semantic`, or `tacit`.

## Core Rule

Do not classify decision problems with one field if multiple independent dimensions
matter.

In particular:

- `structured` is not the same as `deterministic`
- `bounded` is not the same as `discrete`
- `continuous` is not the same as `open`
- `unstructured` is not the same as `non-deterministic`

## Recommended Axes

### 1. `input_structure`

Describes whether the input arrives in normalized fields or not.

Allowed values:

- `structured`
- `unstructured`
- `hybrid`

Guidance:

- `structured`
  - typed fields, metrics, schemas, vectors, enums, AST packets
- `unstructured`
  - free text, raw documents, rich descriptions, unconstrained traces
- `hybrid`
  - mixed structured and unstructured inputs

### 2. `input_modality`

Describes the representational form of the input.

Allowed values:

- `textual`
- `numeric`
- `symbolic`
- `multimodal`

Guidance:

- `textual`
  - natural language or tokenized text-like input
- `numeric`
  - vectors, metrics, time series, scalar features
- `symbolic`
  - AST nodes, typed graphs, enums, rule packets
- `multimodal`
  - mixtures such as text plus metrics, geometry plus labels, etc.

### 3. `output_topology`

Describes the mathematical form of the output space.

Allowed values:

- `discrete`
- `continuous`
- `hybrid`

Guidance:

- `discrete`
  - classes, enums, branch choices, ranked finite actions
- `continuous`
  - scalar scores, vectors, bounded numeric values
- `hybrid`
  - mixed outputs such as class + score

### 4. `output_constraint`

Describes how tightly the output space is constrained.

Allowed values:

- `deterministic`
- `bounded`
- `open`

Guidance:

- `deterministic`
  - rule-complete; same valid input should produce the same output
- `bounded`
  - output must remain inside a defined contract or finite action space
- `open`
  - output is not contract-limited to a finite or strongly bounded space

### 5. `policy_stability`

Describes whether the target label or routing policy is stable over time.

Allowed values:

- `stable`
- `mixed`
- `drifting`

Guidance:

- `stable`
  - policy meaning is not expected to move much with tooling or context
- `mixed`
  - some output semantics are stable, some depend on deployment choices
- `drifting`
  - label meaning changes materially as tools, policy, or capability change

## Why Multiple Fields Matter

These distinctions are operationally important.

Examples:

- `structured + deterministic`
  - formula engine
  - validation rule
  - exact template expansion

- `structured + bounded + discrete`
  - policy classifier over metrics
  - thresholded routing decision
  - bounded model selection

- `unstructured + bounded + discrete`
  - text classification
  - intent router
  - tool selector

- `hybrid + bounded + discrete`
  - text + metrics -> bounded decision
  - telemetry + state + text -> policy route

- `structured + continuous`
  - score model
  - optimization cost estimate
  - risk surface regression

- `unstructured + open`
  - open-ended generation
  - code drafting
  - narrative synthesis

## RSA In This Ontology

RSA should be defined by contract properties, not by one input adjective.

RSA is most appropriate when:

- `output_constraint = bounded`
- output is not fully `deterministic`
- downstream execution is deterministic or strongly structured
- confidence, abstain, and escalation matter

Typical RSA cases:

- `structured -> bounded`
- `unstructured -> bounded`
- `hybrid -> bounded`

Most RSA outputs will also be:

- `output_topology = discrete`

But that should not be assumed as a universal rule if bounded continuous or hybrid
forms later become useful.

## What RSA Is Not

RSA is not:

- a synonym for transformer
- a synonym for RL
- a synonym for all learned decision-making
- a synonym for all non-deterministic automation

RSA is specifically a bounded decision contract with policy behavior around:

- confidence
- abstain
- retry
- escalation
- deterministic downstream execution

## Example Contract Records

### Example A: Formula Confidence Tier

```text
input_structure   = structured
input_modality    = numeric
output_topology   = discrete
output_constraint = deterministic
policy_stability  = stable
```

Interpretation:

- likely not RSA
- should probably remain deterministic

### Example B: Verification Type From Step Text

```text
input_structure   = unstructured
input_modality    = textual
output_topology   = discrete
output_constraint = bounded
policy_stability  = stable
```

Interpretation:

- good RSA candidate

### Example C: Automatability Routing Tier

```text
input_structure   = hybrid
input_modality    = symbolic
output_topology   = discrete
output_constraint = bounded
policy_stability  = drifting
```

Interpretation:

- possible RSA candidate
- but needs stability analysis before treating it as an ordinary gate

## Design Consequence

Suitability assessment should use these fields directly.

The library should be able to answer:

- should this stay deterministic?
- should this become an RSA gate?
- is the output too open for RSA?
- is the policy too unstable for safe gate deployment?

That assessment becomes much clearer when the contract is described with multiple
orthogonal fields.

## Preferred Vocabulary

Prefer:

- `structured`
- `unstructured`
- `hybrid`
- `discrete`
- `continuous`
- `deterministic`
- `bounded`
- `open`
- `stable`
- `drifting`

Avoid as core ontology terms:

- `messy`
- `semantic`
- `tacit`

Those words may still be useful in prose, but they are too vague for the type
system.