Initial whetstone_RSA architecture and C++ scaffold
This commit is contained in:
Bill Holcombe
290
docs/decision_contract_ontology.md
Normal file
290
docs/decision_contract_ontology.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user