# Nw Tdd Cross Language

> Port the state-delta + property-based testing paradigm to languages other than Python. DIY recipes per language; canonical Python ref shipped in nwave_ai.state_delta.

- Skill: `nwave-ai/nw-tdd-cross-language-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nwave-ai/nw-tdd-cross-language-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nwave-ai/nw-tdd-cross-language-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nWave-ai (https://skillmd.com/u/nwave-ai)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nwave-ai/nw-tdd-cross-language-2

---


# Cross-Language State-Delta Porting Guide

This is an implementation guide, not the language/PBT authority. The
language-agnostic law and exact eight-adapter matrix live once in
`nw-test-design-mandates-layered-mechanics`; framework-specific generator,
shrinker/replay, and state-machine guidance lives in the matching
`nw-pbt-*` skill. The recipes below show how to port the same state-delta
observation algebra without making Python syntax normative. A language not
covered by a shipped adapter returns `EVIDENCE_GAP` before PBT authoring; it
never borrows Hypothesis as a substitute.

---

## Canonical Python reference

**API contract** (locked at pilot, see `nwave_ai.state_delta.matcher`):

```python
def assert_state_delta(
    before: Mapping[str, Any],
    after: Mapping[str, Any],
    universe: set[str],
    expected: Mapping[str, Predicate],
    *,
    strict: bool = False,
) -> None: ...

Predicate = Callable[[Any, Any], bool]

# 8 predicate factories:
def prepended_with(prefix: str, sep: str = ":") -> Predicate: ...
def appended_with(suffix: str, sep: str = ":") -> Predicate: ...
def unchanged() -> Predicate: ...
def set_to(value: Any) -> Predicate: ...
def containing(substring: str) -> Predicate: ...
def normalized_to(normalizer: Callable[[Any], Any]) -> Predicate: ...
def idempotent_after(prefix: str, sep: str = ":") -> Predicate: ...
def legacy_healed(detector: Callable[[Any], bool], healed_check: Callable[[Any], bool]) -> Predicate: ...
```

**Semantics**:
- For each key in `universe`:
  - If in `expected`: predicate must return True
  - If NOT in `expected`: implicit-unchanged (`before[k] == after[k]`)
- `strict=True`: keys in `(before|after) - universe` raise `kind=strict_universe_mismatch`
- Multi-violation: ALL violations collected, ONE AssertionError raised

---

## Porting recipe (language-agnostic)

For ANY language, the port is a small shim around the language's PBT library + an `assert_state_delta` function that captures the multi-violation collection semantics. **Keep it small (~70-150 LOC). Do not over-engineer.**

### Step 1 — Translate the API contract

Adapt the function signatures using language-idiomatic types:
- Universe = set/list of strings (`Set<String>`, `string[]`, `&[String]`, etc.)
- Expected = map of string → predicate (`Map<String, Predicate>`, `{[key: string]: Predicate}`, `HashMap<String, Box<dyn Fn>>`)
- Predicate = callable taking `(old, new) → bool`

### Step 2 — Implement the multi-violation collector

```pseudocode
function assert_state_delta(before, after, universe, expected, strict=false):
    violations = []
    for key in universe:
        if key in expected:
            predicate = expected[key]
            if not predicate(before[key], after[key]):
                violations.append(predicate_failed_violation(key, before[key], after[key]))
        else:
            if before[key] != after[key]:
                violations.append(undeclared_change_violation(key, before[key], after[key]))
    if strict:
        for key in (before.keys ∪ after.keys) - universe:
            violations.append(strict_universe_mismatch_violation(key, before.get(key), after.get(key)))
    if violations:
        raise AssertionError(format_multiline_message(violations))
```

### Step 3 — Implement the 8 predicate factories

Each factory closes over its parameters and returns a callable. Use language-idiomatic closure mechanism:
- TypeScript: arrow functions
- Rust: `move` closures returning `impl Fn(...) -> bool`
- F#: partial application
- Java: anonymous inner class or lambda + `Function`/`BiPredicate`
- Go: function returning `func(old, new interface{}) bool`

### Step 4 — Hook to PBT library

Combine with language's PBT library. The PBT library generates inputs; `assert_state_delta` validates the post-action state.

```pseudocode
property "installer preserves user PATH":
    forall(path: gen_realistic_path):
        before = capture_state()
        installer.install(path)
        after = capture_state()
        assert_state_delta(before, after,
                          universe={"PATH", "permissions", "hooks"},
                          expected={"PATH": prepended_with(des_bin)},
                          strict=true)
```

---

## Idiomatic mini-examples per language

### TypeScript / fast-check

```typescript
import { fc } from 'fast-check';
import { assertStateDelta, prependedWith } from './state-delta';  // ~80 LOC shim

fc.assert(
  fc.property(pathStrategy(), (userPath) => {
    const before = captureState();
    installShims(userPath);
    const after = captureState();
    assertStateDelta(before, after, {
      universe: ['PATH', 'permissions', 'hooks'],
      expected: { PATH: prependedWith('/des/bin') },
      strict: true,
    });
  })
);
```

### Rust / proptest

```rust
use proptest::prelude::*;
use crate::state_delta::{assert_state_delta, prepended_with};  // ~100 LOC shim

proptest! {
    #[test]
    fn installer_preserves_user_path(user_path in path_strategy()) {
        let before = capture_state();
        install_shims(&user_path);
        let after = capture_state();
        assert_state_delta(
            &before, &after,
            &["PATH", "permissions", "hooks"],
            &[("PATH", prepended_with("/des/bin"))],
            true,  // strict
        ).unwrap();
    }
}
```

### F# / FsCheck

```fsharp
open FsCheck.Xunit
open StateDelta  // ~70 LOC shim

[<Property>]
let ``installer preserves user PATH`` (userPath: PathShape) =
    let before = captureState()
    installShims userPath
    let after = captureState()
    assertStateDelta before after
        [ "PATH"; "permissions"; "hooks" ]
        [ "PATH", prependedWith "/des/bin" ]
        StrictMode.Strict
```

### Java / jqwik

```java
import net.jqwik.api.*;
import org.example.statedelta.StateDelta;  // ~120 LOC shim

class InstallerProperties {
    @Property
    void installerPreservesUserPath(@ForAll("paths") String userPath) {
        var before = captureState();
        installer.install(userPath);
        var after = captureState();
        StateDelta.assertStateDelta(
            before, after,
            Set.of("PATH", "permissions", "hooks"),
            Map.of("PATH", StateDelta.prependedWith("/des/bin")),
            true  // strict
        );
    }
}
```

---

## When to NOT port (use canonical Python via subprocess)

If the SUT (system under test) is a Python service or CLI:
- Skip language port; call Python from your language's test runner
- Spawn the Python service, use Python `assert_state_delta` directly via test fixture
- Cheaper than re-porting the matcher

If the SUT is in your language but you only need state-delta for a few critical surfaces:
- Hand-roll a 30-line minimal version (just `assert_state_delta` + 2-3 predicates you actually need)
- Don't port the full 8-predicate library prematurely

---

## Stage cascade applies cross-language

The 3-stage cascade in `nw-tdd-methodology::Paradigm Mandate` applies regardless of language:

- **Stage 0** (new code, paradigm-from-day-zero): debt never accumulates. Apply paradigm in whatever language as you write tests
- **Stage 1** (legacy bug-prone): state-delta migration captures debt (33-75% yield)
- **Stage 2a** (post Stage 1): PBT amplification ~0% by design
- **Stage 2b** (legacy bug-prone, no Stage 1): PBT amplification ~75%

Stage applicability is independent of language. Language port is enabling infrastructure; the paradigm itself is universal.

---

## Enterprise option

If your organization needs:
- Tested, supported language packages (cross-version stability)
- Cross-language consistency checks (same paradigm everywhere, audited)
- Migration tooling (AI-assisted Stage 1 conversions in your language)

These ship as part of the **nwave-pro** enterprise bundle (deferred — contact the nWave team). Open-source path is sufficient for paradigm validation; enterprise reduces porting effort + adds support.

---

## Quick reference

| Task | Resource |
|---|---|
| Read paradigm mandate | `nw-tdd-methodology::Paradigm Mandate` |
| Read stage cascade | `nw-tdd-methodology::Empirical efficacy framework` |
| Python canonical implementation | `nwave_ai.state_delta` (matcher.py + predicates.py) |
| Python pilot example | `tests/state_delta/integration/test_pilot_bug48.py` (D-12 Part A + B) |
| Design directive (architects) | `nw-design::Development Paradigm Selection` |

For language-specific PBT library docs, see official:
- fast-check: `https://fast-check.dev/`
- proptest: `https://docs.rs/proptest/`
- jqwik: `https://jqwik.net/`
- FsCheck: `https://fscheck.github.io/FsCheck/`
- gopter: `https://github.com/leanovate/gopter`
- ScalaCheck: `https://scalacheck.org/`
- qcheck: `https://github.com/c-cube/qcheck`
- kotest (built-in): `https://kotest.io/docs/proptest/property-based-testing.html`