whetstone_RSA/sprints/SPRINT-002-rsa-semantic-bootstrap.md

# Sprint 002: RSA Semantic Bootstrap

## Status

Planned

## Intent

Define the first Whetstone-authored semantic model for `whetstone_RSA` and make it
the new source-of-truth target for future RSA contract evolution.

This sprint exists to stop the project from continuing as a C++-first library by
inertia.

## Problem

`whetstone_RSA` currently has a useful C++ scaffold, but the semantic center of
gravity is still wrong.

The project has already concluded that RSA should be Whetstone-AST-first and that
the C++ layer should be a runtime projection. That conclusion is documented, but it
is not yet operationalized.

Right now:

- the semantic contract is still primarily embodied in `include/whetstone_rsa/types.h`
- diagnosis/runtime interfaces are defined in C++ first
- backend-selection and structured-slot support are planned but not yet represented
  in a semantic-first source model

If that continues, the bootstrap scaffold will become the architecture by default.

## Scope

This sprint is about semantic bootstrap only.

Primary outputs:

- a first concrete RSA semantic model
- a mapping from the existing C++ scaffold into that semantic model
- a projection boundary definition for future C++ runtime types

Supporting documents to update if needed:

- `docs/whetstone_ast_first_integration.md`
- `ROADMAP.md`

This sprint does **not** require immediate deep changes to `whetstone_DSL`
runtime code.

## Architectural Constraint

The semantic source of truth for RSA should live in Whetstone-authored forms.

The C++ code in `whetstone_RSA` should remain:

- runtime implementation
- projected contract types
- diagnosis/runtime execution machinery
- backend adapter surface

It should not remain the primary authoring home of RSA semantics.

## Sprint Goals

### 1. Define the first semantic entity set

Establish the minimum initial semantic model for RSA:

- `DecisionContract`
- `DecisionSurface`
- `DecisionRequestModel`
- `DecisionResultModel`
- `SuitabilityAssessment`
- `DiagnosisModel`
- `ProbeDefinition`
- `BackendSuitability`
- `GatePackage`

### 2. Separate semantic contract from runtime behavior

Classify the current C++ scaffold into:

- semantic contract entities
- runtime-only execution types
- bootstrap/demo code

### 3. Define the first projection boundary

State clearly what will eventually be projected from semantic source into:

- C++ runtime contract structs
- runtime manifests
- schema artifacts
- benchmark configuration artifacts

### 4. Prepare version-0 support for both enum and structured-slot gates

The semantic model must support:

- bounded enum outputs
- bounded structured outputs with slots

from the beginning, even if early runtime examples are enum-dominant.

### 5. Leave RL/bandit as semantic placeholders only

Include `rl_policy` in backend-family semantics now so the contract stays open,
but keep first implementation effort focused on:

- classical ML families
- tiny transformer families

## Concrete Deliverables

### Deliverable A: Semantic model definition

Produce a concrete first semantic model with entity names, field groups, and
relationship rules.

### Deliverable B: C++ scaffold mapping

Map the current public C++ surface into the semantic model, especially:

- `types.h`
- `probe.h`
- `probe_registry.h`
- `diagnosis_engine.h`
- `suitability_assessor.h`

### Deliverable C: Missing-field inventory

Identify what the current scaffold is missing for:

- structured slot outputs
- backend suitability
- deployment packaging
- argument-oriented runtime invocation

### Deliverable D: Projection strategy

Define how future C++ types should be treated:

- temporary projection snapshots
- not semantic source
- updated from semantic-first changes rather than evolved independently

## Acceptance Criteria

- A first semantic model is explicitly documented in RSA docs
- The model supports both enum and structured-slot gates
- The current C++ scaffold is mapped into semantic vs runtime-only layers
- Backend suitability and gate packaging exist in the semantic model even if not
  fully implemented in code
- The roadmap and AST-first integration docs point to the same next step
- A later session could begin implementing semantic-first RSA without re-deriving
  the architecture

## Not In Scope

- full implementation of semantic authoring inside `whetstone_DSL`
- replacing the current C++ runtime scaffold
- immediate automatic projection generation
- training any model
- wiring RSA into `whetstone_DSL` taskitem generation

## Case Study Rule

Use existing RSA C++ types and WhetstoneDSL decision surfaces only as evidence and
bootstrap input.

Do not let any one case study define RSA semantics by itself.

## Recommended Execution Order

1. Inventory the existing C++ public surface.
2. Define the minimum semantic entity set.
3. Map each current C++ field into a semantic or runtime-only bucket.
4. Identify missing fields required by version-0 goals.
5. Define the projection boundary into C++.
6. Record the next implementation step for semantic authoring.

## Exit Condition

This sprint is complete when the project no longer needs to answer:

"What is the first semantic model for RSA, and how does the current C++ scaffold
map into it?"

That question should be settled well enough that implementation can start from the
semantic model instead of revisiting architecture.

## Next Step

Represent the first three RSA semantic entities as Whetstone-authored forms:

- `DecisionContract`
- `DecisionSurface`
- `ProbeDefinition`

Then map `include/whetstone_rsa/types.h` onto those entities as a temporary C++
projection target.