whetstone_DSL/sprint46_plan.md

# Sprint 46 Plan: Semantic Core and Porting Contract

## Context

Sprint 46 establishes the non-negotiable foundation for multi-language transpilation:
a shared semantic IR, explicit support tiers, and a hard definition of what "ported"
means. Without this, adding many languages in parallel will produce shallow mappings
that are hard to verify.

This sprint defines the contract used by every later language adapter.

---

## Goals

1. Define a language-agnostic semantic IR for behavior, types, memory, and concurrency
2. Introduce support tiers (`experimental`, `beta`, `stable`) with explicit gates
3. Create a capability matrix per language and paradigm
4. Add migration contract checks (build, tests, safety, perf)

---

## Steps

### Step 689: `SemanticCoreIR` schema (12 tests)

Create `editor/src/SemanticCoreIR.h`.

Core nodes:
- Module, Function, Type, Effect, OwnershipRegion, ConcurrencyRegion
- Intent tags (algorithmic, IO, stateful, pure)
- Contract hooks for preconditions/postconditions/error behavior

Tests (12): schema constructability, node identity stability, roundtrip JSON,
function graph shape, ownership edge validity, effect tags preserved, empty module
valid, invalid edge rejected, deterministic serialization, language metadata
preserved, annotations attach to IR nodes, unknown tag survives passthrough.

### Step 690: Language support tiers + gates (10 tests)

Create `editor/src/LanguageSupportTier.h`.

Introduce:
- `Experimental`: parse + partial projection
- `Beta`: executable equivalence + static checks
- `Stable`: security/perf gates + migration report quality

Tests (10): tier parse, gate mapping, stable implies beta gates,
invalid tier rejected, default tier experimental, serialization,
upgrade path validity, downgrade warnings, deterministic ordering, docs export.

### Step 691: Capability matrix model (10 tests)

Create `editor/src/LanguageCapabilityMatrix.h`.

Track per language:
- Type model, memory model, error model, concurrency model, macro/meta model
- FFI profile, build ecosystem, runtime assumptions

Tests (10): add/read capability rows, paradigm grouping, missing fields flagged,
versioned capability snapshots, diff capability versions, deterministic output,
unknown language allowed in experimental mode, strict mode failure, export to JSON,
import from JSON.

### Step 692: Migration acceptance contract (10 tests)

Create `editor/src/MigrationAcceptanceContract.h`.

Contract checks:
- Build success
- Test parity threshold
- Security findings threshold
- Perf delta bounds
- Manual review checklist completeness

Tests (10): pass path, single gate fail, multiple gate fail, threshold edge cases,
missing benchmark data, missing security report, missing tests, deterministic
result packet, machine-readable reason codes, human-readable summary text.

### Step 693: IR lowering interface and adapter API (10 tests)

Create `editor/src/LanguageToIRAdapter.h` and `editor/src/IRToLanguageAdapter.h`.

Define strict adapter contracts used by every language family sprint.

Tests (10): interface conformance, unsupported feature signaling,
partial lowering packets, confidence propagation, source location mapping,
annotation carry-through, adapter version pinning, registry lookup,
registry fallback behavior, deterministic adapter selection.

### Step 694: `whetstone_get_language_matrix` MCP tool (8 tests)

Expose capability matrix + support tier status via MCP.

Tests (8): tool registration, schema validation, single language query,
all-language query, includes tier field, includes gate status, unknown language
response, deterministic sort order.

### Step 695: `whetstone_get_porting_contract` MCP tool (8 tests)

Returns contract gates and thresholds for a requested source/target pair.

Tests (8): tool registered, pair lookup works, default thresholds,
override thresholds, missing pair fallback, error on invalid payload,
machine-readable gate list, deterministic output.

### Step 696: Baseline docs + examples (8 tests)

Add docs for adapter authors and one end-to-end reference sample.

Tests (8): docs index includes new pages, example compiles in docs build,
example IR valid, example contract packet valid, links resolve,
no broken references, schema snippets current, deterministic examples.

### Step 697: Sprint 46 integration summary (8 tests)

Create `editor/src/Sprint46IntegrationSummary.h`.

Tests (8): struct constructable, all modules reachable, tools listed,
step range correct, files list populated, success flag true, deterministic
summary ordering, regression marker emitted.

### Step 698: Full regression + architecture gate (8 tests)

Run regression for steps 689-697 and existing transpilation steps.

Tests (8): targeted suite pass, legacy suite pass, MCP tools unaffected,
no header exceeds 600 lines, no new dependency, deterministic snapshots,
contract docs generated, sprint gate success.

---

## Architecture Gate (All Steps)

- Header-only C++ for new core metadata modules
- Max 600 lines per header, split with `Extended.h` where needed
- No new runtime dependencies
- All adapter APIs deterministic and side-effect free
- MCP output must be stable and machine-readable