nw-tdd-cross-language

name	nw-tdd-cross-language
description	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.
user-invocable	false
disable-model-invocation	true

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):

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

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.

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

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

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

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

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