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