whetstone_RSA/docs/adoption_model.md

# Adoption Model

## Purpose

This document explains where `whetstone_RSA` sits in the broader tool ecosystem and
how other systems should decide when to use it.

The key architectural claim is:

`whetstone_RSA` belongs directly above deterministic tooling.

It should be used when a problem is no longer fully deterministic, but the output
contract is still bounded enough that open-ended generation is wasteful.

## Placement In The Stack

The intended execution stack is:

```text
deterministic
    ↓
RSA
    ↓
SLM
    ↓
LLM
    ↓
human
```

This is not just a cost ladder. It is a structural ladder.

- `deterministic`
  - same valid input -> same output
  - formulas, rules, template expansion, exact policies

- `RSA`
  - output contract is bounded
  - inputs may be structured, unstructured, or hybrid
  - confidence, abstain, and escalation matter

- `SLM`
  - output is open-ended but still locally constrained

- `LLM`
  - output is open-ended and requires broader synthesis or reasoning

- `human`
  - problem is not yet formalized enough to automate safely

## Why RSA Sits Right Above Deterministic

RSA is the first non-deterministic layer that still preserves strong structure:

- bounded outputs
- schema validation
- abstain support
- deterministic downstream execution
- easy retraining

That makes it the natural default immediately after deterministic methods stop being
enough.

In many systems, the wrong jump is being made:

```text
deterministic -> LLM
```

The RSA layer exists to fill the large missing middle.

## Two Ways A Project Uses RSA

There are two distinct adoption modes.

### 1. Runtime Consumer

A project calls `whetstone_RSA` during execution to make a bounded decision.

Examples:

- choose a workflow type
- classify a validation tier
- select a bounded CAD operation family
- route a request to a deterministic tool

### 2. Architectural Producer

A project decides that the software it is generating should itself include an RSA
gate.

This is especially relevant for `whetstone_DSL`.

`whetstone_DSL` should not only call RSA for its own internal bounded decisions.
It should also be able to say:

- this decision surface in the generated software is bounded
- deterministic rules are insufficient
- LLM use would be wasteful
- therefore the generated system should contain an RSA gate here

That means RSA is both:

- a runtime library
- a target architectural pattern

## Suitability Assessment

Projects should be able to assess whether a decision surface should become an RSA
gate.

The suitability question is:

Should this decision live in deterministic code, an RSA gate, an SLM, an LLM, or a
human workflow?

## Conditions That Favor RSA

Recommend RSA when most of these are true:

- output vocabulary is finite or can be made finite
- downstream execution is deterministic or template-driven
- input space may be structured or unstructured, but is not rule-complete
- many inputs map into a small number of actions
- confidence matters
- abstain or retry is acceptable
- domain retraining is practical

## Conditions That Disfavor RSA

Do not recommend RSA when:

- the decision is already deterministic
- the output is genuinely open-ended
- the label space is unstable and not yet separable from policy
- the task is synthesis, not selection or routing
- no meaningful abstain or escalation path exists

## Suitability Output

The library should eventually support a structured suitability assessment.

Example conceptual result:

```text
GateSuitability
  recommended
  target_layer
  rationale
  bounded_output_confidence
  deterministic_baseline_available
  label_stability_risk
  suggested_gate_shape
```

Where `target_layer` is one of:

- `deterministic`
- `rsa`
- `slm`
- `llm`
- `human`

And `suggested_gate_shape` might be:

- `binary`
- `multiclass`
- `factorized`
- `hierarchical`

## Contractual Boundary

One of the strongest properties of RSA is that it should remain contractual.

The consuming system should not care exactly which learned mechanism fills the gate,
as long as the contract is preserved:

- bounded schema
- confidence
- abstain behavior
- policy recommendation
- traceability

That means the architecture should remain open to future replacements:

- transformer specialist
- RL policy
- classical ML classifier
- retrieval-backed scorer
- hybrid deterministic + learned controller

The important thing is not the current model family.
The important thing is the gate contract.

## Why This Matters

If the contract is stable, the learning mechanism can improve without forcing
downstream systems to change their architecture.

That gives RSA two important advantages:

- it is light enough to retrain quickly when a domain changes
- it is abstract enough to swap in a different decision engine later

This is a major reason to keep `whetstone_RSA` as a standalone library rather than
embedding it into one project's internal logic.

## Ecosystem Role

In the current tool ecosystem:

- `whetstone_RSA`
  - provides the bounded-decision contract, runtime, diagnosis, and suitability model

- `whetstone_DSL`
  - consumes RSA for its own internal bounded decisions
  - may also generate software that itself contains RSA gates

- `WHIMP`, `constcad`, and similar systems
  - consume RSA where design or modeling decisions are bounded but not deterministic

- `hivemind`
  - can identify high-ROI entropy surfaces where RSA gates are worth creating

This avoids circular abstraction problems because:

- RSA owns the generic bounded-decision mechanism
- each tool owns its domain-specific gates
- no domain project needs to be the conceptual home of RSA

## Design Rule

When a system encounters a decision that is not rule-complete but is still bounded
enough to avoid open-ended generation, the default answer should be:

Try RSA before escalating to SLM or LLM.

## Ontology Note

The preferred contract vocabulary for this library is defined in
`docs/decision_contract_ontology.md`.

RSA should be understood through orthogonal fields such as:

- `input_structure`
- `input_modality`
- `output_topology`
- `output_constraint`
- `policy_stability`

not through vague single-label categories.

Backend family choice is a separate decision layer. See `docs/backend_selection.md`.

## Implication For WhetstoneDSL

`whetstone_DSL` should eventually be able to do both:

- use RSA during generation
- recognize when generated software should include an RSA gate

That second capability is important.

It means Whetstone is not only a consumer of the library. It becomes a producer of
RSA-native architectures in the software it builds.