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

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

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

Interpretation:

• good RSA candidate

Example C: Automatability Routing Tier

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.