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.