whetstone_RSA/HANDOFF-2026-03-31.md

# whetstone_RSA — Handoff 2026-03-31

## Status

Foundational architecture, ontology, and C++ runtime scaffold are in place.

This project is now beyond brainstorming. It has:

- a clear bounded-decision contract
- a diagnosis and suitability model
- an AST-first integration direction
- an initial C++ implementation scaffold that builds and runs

## What Was Completed

### 1. Library framing and architecture

Core documents written:

- `README.md`
- `ROADMAP.md`
- `docs/architecture.md`
- `docs/entropy_model_sizing.md`
- `docs/evaluation_policy.md`
- `docs/gate_failure_taxonomy.md`
- `docs/diagnosis_api.md`
- `docs/probe_execution_flow.md`
- `docs/runtime_contract.md`
- `docs/probe_registry.md`

### 2. WhetstoneDSL case study

The library was grounded using `whetstone_DSL/specialists` as a case study, but
without making `whetstone_DSL` the conceptual home of RSA.

Key case-study docs:

- `docs/case_studies/whetstone_dsl.md`
- `docs/gate_rubric.md`

Important architectural conclusion:

- `whetstone_DSL` is a consumer of RSA and also a future producer of RSA-native
  architectures in generated software
- `whetstone_RSA` remains the reusable bounded-decision substrate

### 3. Contract ontology refactor

The ontology was tightened into applied-data-science-style orthogonal fields rather
than vague single-label categories.

Canonical doc:

- `docs/decision_contract_ontology.md`

Current preferred fields:

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

Important conclusion:

- RSA should be defined by bounded output contract and policy behavior
- it should not be defined by one model family or one input adjective

### 4. Adoption and AST-first direction

Documents written:

- `docs/adoption_model.md`
- `docs/whetstone_ast_first_integration.md`

Important conclusion:

- `whetstone_RSA` should be Whetstone-AST-first, not merely AST-first
- the semantic source of truth should eventually live in `whetstone_DSL`
- the C++ layer in this repo is a runtime projection/bootstrap, not the ideal
  permanent semantic source of truth

### 5. Backend-selection placeholder

Document written:

- `docs/backend_selection.md`

Important conclusion:

Three different decisions must stay separate:

1. `Layer suitability`
   - deterministic / rsa / slm / llm / human
2. `Gate shape`
   - binary / multiclass / factorized / hierarchical
3. `Backend selection`
   - transformer / gradient boosting / forest / Bayes / RL / hybrid / etc.

This was written down so the idea is not lost.

### 6. C++ runtime scaffold

A modern C++ scaffold now exists and builds successfully.

Key files:

- `CMakeLists.txt`
- `include/whetstone_rsa/types.h`
- `include/whetstone_rsa/probe.h`
- `include/whetstone_rsa/probe_registry.h`
- `include/whetstone_rsa/diagnosis_engine.h`
- `include/whetstone_rsa/suitability_assessor.h`
- `include/whetstone_rsa/probes/confidence_threshold_probe.h`
- `src/probe_registry.cpp`
- `src/diagnosis_engine.cpp`
- `src/suitability_assessor.cpp`
- `src/probes/confidence_threshold_probe.cpp`
- `examples/diagnose_demo.cpp`

Current implemented concepts:

- ontology enums for contract fields
- `GateDefinition`
- `GateEvidence`
- `GateDiagnosis`
- `GateSuitability`
- `ProbeRegistry`
- `DiagnosisEngine`
- `SuitabilityAssessor`
- one concrete probe: `confidence_threshold_probe`

### 7. Schemas

Schemas currently present:

- `schemas/gate_definition_v0.json`
- `schemas/gate_evidence_v0.json`
- `schemas/gate_diagnosis_v0.json`

Note:

- `gate_definition_v0.json` still needs to be updated to include the new ontology
  fields now present in the C++ types

## Verified Runtime State

The C++ project was configured and built successfully with CMake.

The demo executable:

- `build/whetstone_rsa_demo`

was run successfully and currently demonstrates:

- suitability assessment for a bounded gate
- diagnosis using the registered confidence-threshold probe
- guarded deployment recommendation output

## Current Conceptual Position

The cleanest current definition is:

- RSA is a model-agnostic bounded decision contract
- it sits directly above deterministic tooling
- it is not inherently transformer-based
- it is not inherently RL
- it can be filled by many backend families as long as the contract is preserved

This distinction matters and should be preserved.

## Important Things Not To Lose

### 1. RSA is not the whole decision stack

RSA is one container family, not the entire automation ontology.

It is best thought of as:

- bounded output contract
- confidence / abstain / retry / escalation
- deterministic or strongly structured downstream execution

### 2. The broad selector is separate

There is a broader meta-question:

- should a decision be deterministic, RSA, SLM, LLM, or human?

That is a different layer from RSA itself.

### 3. Backend selection is also separate

Even after something is judged to be an RSA gate, there is a separate decision:

- what backend family should implement it?

Do not collapse this into RSA’s core identity.

### 4. Whetstone AST should eventually own the semantic model

Do not let the hand-authored C++ structs become the permanent semantic source of
truth if the Whetstone semantic representation becomes available.

## Immediate Next Steps

### 1. Bring schemas up to the new ontology

Update:

- `schemas/gate_definition_v0.json`

to include the new contract fields reflected in C++:

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

### 2. Add more probes

Best next probes:

- `factorization_probe`
- `schema_stability_probe`

These are the probes most directly motivated by the WhetstoneDSL case study.

### 3. Add backend-selection types to the C++ core

Likely next types:

- `BackendFamily`
- `BackendSuitability`
- `BackendBenchmarkResult`

This was intentionally documented but not yet implemented.

### 4. Define Whetstone-side semantic entities

Longer-term but important:

Define the RSA domain model in Whetstone semantic terms rather than continuing to
grow the C++ model as if it were the source of truth.

Likely entities:

- `GateDefinition`
- `GateEvidence`
- `GateDiagnosis`
- `GateSuitability`
- `ProbeDefinition`
- policy and diagnosis contracts

## Suggested Commit Boundary

This handoff assumes the current state is one foundational initial commit:

- docs
- schemas
- C++ scaffold
- demo

That is the right scope for an initial baseline.