# 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.