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:

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:

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:

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.