Ship-ready: examples, docs, production codegen, smarter testgen

Production readiness:
- GenerateProduction() strips test backdoors (unsafeBecomeOwner, etc.)
- Generate() keeps test helpers for development/validation

Validate improvements:
- Fix arc count display (was 0, now shows actual count from schema.Arcs)
- Show individual forge test pass/fail counts
- Cleaner aligned output format

Testgen improvements:
- needsStateSetup: detect guards referencing state variables (>= checks)
  and generate expectRevert tests when prior state can't be auto-setup
- inferZeroParams: use amount=1 when guard has "state >= amount" pattern
  (fixes 0 >= 0 passing when it should fail)
- Works for arbitrary .btw schemas, not just known templates

Examples:
- counter.btw — scalar state, increment/decrement
- erc20.btw — fungible token with nested map allowances
- nft.btw — non-fungible token with ownership
- escrow.btw — multi-step deposit/lock/release workflow
- examples/README.md — full .btw DSL syntax reference

All 4 examples pass: ./bitwrap -validate examples/*.btw

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: stackdump

cmd/bitwrap/main.go

@@ -87,48 +87,46 @@ func main() {
 func runValidate(path string) int {
 	src, err := os.ReadFile(path)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "FAIL: read %s: %v\n", path, err)
+		fmt.Fprintf(os.Stderr, "FAIL read %s: %v\n", path, err)
 		return 1
 	}
 
 	// Step 1: Parse DSL
-	fmt.Printf("● parse %s\n", path)
+	fmt.Printf("  parse    %s\n", path)
 	ast, err := dsl.Parse(string(src))
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "FAIL: parse: %v\n", err)
+		fmt.Fprintf(os.Stderr, "FAIL parse: %v\n", err)
 		return 1
 	}
 
 	// Step 2: Build metamodel schema
-	fmt.Printf("● build schema: %s\n", ast.Name)
 	schema, err := dsl.Build(ast)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "FAIL: build: %v\n", err)
+		fmt.Fprintf(os.Stderr, "FAIL build: %v\n", err)
 		return 1
 	}
-	fmt.Printf("  states: %d, actions: %d, arcs: %d\n",
-		len(schema.States), len(schema.Actions), len(schema.InputArcs(""))+len(schema.OutputArcs("")))
+	fmt.Printf("  schema   %s (%d states, %d actions, %d arcs)\n",
+		ast.Name, len(schema.States), len(schema.Actions), len(schema.Arcs))
 
 	// Step 3: Generate Solidity
 	contractName := solidity.ContractName(schema.Name)
 	contractCode := solidity.Generate(schema)
 	testCode := solidity.GenerateTests(schema)
 	genesisCode := solidity.GenerateGenesis(schema.Name, solidity.GenesisConfig{}, solidity.DefaultAddresses())
-	fmt.Printf("● generate Solidity: %s.sol (%d bytes)\n", contractName, len(contractCode))
-	fmt.Printf("  tests: %sTest.t.sol (%d bytes)\n", contractName, len(testCode))
-	fmt.Printf("  genesis: %sGenesis.s.sol (%d bytes)\n", contractName, len(genesisCode))
+	fmt.Printf("  solidity %s.sol (%d bytes), tests (%d bytes), genesis (%d bytes)\n",
+		contractName, len(contractCode), len(testCode), len(genesisCode))
 
 	// Step 4: Check for forge
 	if _, err := exec.LookPath("forge"); err != nil {
-		fmt.Printf("● forge not installed — skipping compilation and deployment\n")
-		fmt.Printf("PASS (parse + generate only)\n")
+		fmt.Printf("  skip     forge not installed\n")
+		fmt.Printf("PASS (parse + generate)\n")
 		return 0
 	}
 
 	// Step 5: Set up temp Foundry project
 	dir, err := os.MkdirTemp("", "bitwrap-validate-*")
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "FAIL: tmpdir: %v\n", err)
+		fmt.Fprintf(os.Stderr, "FAIL tmpdir: %v\n", err)
 		return 1
 	}
 	defer os.RemoveAll(dir)
@@ -144,33 +142,57 @@ func runValidate(path string) int {
 	os.WriteFile(filepath.Join(dir, "script", contractName+"Genesis.s.sol"), []byte(genesisCode), 0o644)
 
 	// Step 6: Install forge-std
-	if !runStep(dir, "install forge-std", "git", "init") {
+	if !runStep(dir, "deps", "git", "init") {
 		return 1
 	}
-	if !runStep(dir, "install forge-std", "forge", "install", "foundry-rs/forge-std") {
+	if !runStep(dir, "deps", "forge", "install", "foundry-rs/forge-std") {
 		return 1
 	}
 
 	// Step 7: Compile
-	if !runStep(dir, "forge build", "forge", "build") {
+	if !runStep(dir, "compile", "forge", "build") {
 		return 1
 	}
 
-	// Step 8: Test
-	if !runStep(dir, "forge test", "forge", "test", "-vv") {
+	// Step 8: Test — show individual results
+	fmt.Printf("  test     ")
+	cmd := exec.Command("forge", "test", "-vv")
+	cmd.Dir = dir
+	out, testErr := cmd.CombinedOutput()
+	outStr := string(out)
+
+	// Count pass/fail from forge output
+	passed, failed := 0, 0
+	for _, line := range strings.Split(outStr, "\n") {
+		if strings.Contains(line, "[PASS]") {
+			passed++
+		} else if strings.Contains(line, "[FAIL") {
+			failed++
+		}
+	}
+	if testErr != nil {
+		fmt.Printf("%d passed, %d failed\n", passed, failed)
+		// Show failing test names
+		for _, line := range strings.Split(outStr, "\n") {
+			if strings.Contains(line, "[FAIL") {
+				fmt.Printf("           %s\n", strings.TrimSpace(line))
+			}
+		}
+		fmt.Fprintf(os.Stderr, "FAIL forge test\n")
 		return 1
 	}
+	fmt.Printf("%d passed\n", passed)
 
 	// Step 9: Deploy to anvil
 	if _, err := exec.LookPath("anvil"); err != nil {
-		fmt.Printf("● anvil not installed — skipping deployment\n")
+		fmt.Printf("  skip     anvil not installed\n")
 		fmt.Printf("PASS\n")
 		return 0
 	}
 
 	listener, err := net.Listen("tcp", "127.0.0.1:0")
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "FAIL: find free port: %v\n", err)
+		fmt.Fprintf(os.Stderr, "FAIL find free port: %v\n", err)
 		return 1
 	}
 	port := listener.Addr().(*net.TCPAddr).Port
@@ -179,15 +201,14 @@ func runValidate(path string) int {
 	rpcURL := fmt.Sprintf("http://127.0.0.1:%d", port)
 	anvil := exec.Command("anvil", "--port", fmt.Sprintf("%d", port), "--silent")
 	if err := anvil.Start(); err != nil {
-		fmt.Fprintf(os.Stderr, "FAIL: start anvil: %v\n", err)
+		fmt.Fprintf(os.Stderr, "FAIL start anvil: %v\n", err)
 		return 1
 	}
 	defer func() { anvil.Process.Kill(); anvil.Wait() }()
 
-	// Wait for anvil
 	for i := 0; i < 50; i++ {
-		cmd := exec.Command("cast", "chain-id", "--rpc-url", rpcURL)
-		if out, err := cmd.CombinedOutput(); err == nil && strings.TrimSpace(string(out)) == "31337" {
+		c := exec.Command("cast", "chain-id", "--rpc-url", rpcURL)
+		if o, e := c.CombinedOutput(); e == nil && strings.TrimSpace(string(o)) == "31337" {
 			break
 		}
 		time.Sleep(100 * time.Millisecond)
@@ -197,18 +218,21 @@ func runValidate(path string) int {
 	createArgs := []string{"create", fmt.Sprintf("src/%s.sol:%s", contractName, contractName),
 		"--rpc-url", rpcURL, "--private-key", privKey, "--broadcast"}
 
-	cmd := exec.Command("forge", createArgs...)
-	cmd.Dir = dir
-	out, err := cmd.CombinedOutput()
-	if err != nil || !strings.Contains(string(out), "Deployed to:") {
-		fmt.Fprintf(os.Stderr, "● deploy FAIL\n%s\n", out)
+	deployCmd := exec.Command("forge", createArgs...)
+	deployCmd.Dir = dir
+	deployOut, deployErr := deployCmd.CombinedOutput()
+	deployStr := string(deployOut)
+	if deployErr != nil || !strings.Contains(deployStr, "Deployed to:") {
+		fmt.Fprintf(os.Stderr, "FAIL deploy\n%s\n", deployStr)
 		return 1
 	}
 
-	// Extract address
-	for _, line := range strings.Split(string(out), "\n") {
+	for _, line := range strings.Split(deployStr, "\n") {
 		if strings.Contains(line, "Deployed to:") {
-			fmt.Printf("● deploy: %s\n", strings.TrimSpace(line))
+			parts := strings.Fields(line)
+			if len(parts) >= 3 {
+				fmt.Printf("  deploy   %s\n", parts[len(parts)-1])
+			}
 		}
 	}
 
@@ -217,13 +241,15 @@ func runValidate(path string) int {
 }
 
 func runStep(dir, label, name string, args ...string) bool {
-	fmt.Printf("● %s\n", label)
+	fmt.Printf("  %-8s ", label)
 	cmd := exec.Command(name, args...)
 	cmd.Dir = dir
 	out, err := cmd.CombinedOutput()
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "FAIL: %s\n%s\n", label, out)
+		fmt.Printf("FAIL\n")
+		fmt.Fprintf(os.Stderr, "%s\n", out)
 		return false
 	}
+	fmt.Printf("ok\n")
 	return true
 }

examples/README.md

@@ -0,0 +1,126 @@
+# .btw DSL Reference
+
+The `.btw` (bitwrap) DSL describes Petri net models that compile to Solidity smart contracts.
+
+## Quick Start
+
+```bash
+# Validate a .btw file (parse → Solidity → compile → test → deploy)
+./bitwrap -validate examples/erc20.btw
+
+# Just compile to JSON schema
+./bitwrap -compile examples/erc20.btw
+```
+
+## Syntax
+
+### Schema Declaration
+
+```
+schema MyToken {
+  version "1.0.0"
+  domain "custody"       # optional
+  asset "erc20"          # optional
+
+  # ... registers, events, functions
+}
+```
+
+### Registers (State Variables)
+
+Registers declare the contract's state. Scalar types become `uint256` storage. Map types become Solidity `mapping(...)` storage.
+
+```
+register BALANCES map[address]uint256 observable
+register ALLOWANCES map[address]map[address]uint256 observable
+register TOTAL_SUPPLY uint256
+register NEXT_ID uint256
+```
+
+- `observable` makes the variable `public` in Solidity (auto-generates a getter)
+- Supported types: `uint256`, `address`, `bool`, `map[keyType]valueType`
+- Nested maps: `map[address]map[address]uint256` for allowance-style patterns
+
+### Events
+
+```
+event TransferEvent {
+  from: address indexed
+  to: address indexed
+  amount: uint256
+}
+```
+
+Events map to Solidity `event` declarations. `indexed` fields become indexed event parameters.
+
+### Functions (Actions)
+
+Functions are the transitions in the Petri net. They consume tokens from input places and produce tokens at output places.
+
+```
+fn(transfer) {
+  var from address
+  var to address
+  var amount amount
+
+  require(BALANCES[from] >= amount && to != address(0))
+  @event TransferEvent
+
+  BALANCES[from] -|amount|> transfer      # input arc: consume from BALANCES[from]
+  transfer -|amount|> BALANCES[to]        # output arc: produce at BALANCES[to]
+}
+```
+
+#### Variables
+
+`var name type` declares a function parameter. The type `amount` is shorthand for `uint256`.
+
+#### Guards
+
+`require(expr)` adds a Solidity `require(...)` statement. The expression can reference registers, variables, and `caller` (maps to `msg.sender`).
+
+#### Event Reference
+
+`@event EventName` links the function to an event. The event is emitted when the function executes.
+
+#### Arcs
+
+Arcs define token flow using the syntax: `SOURCE -|WEIGHT|> TARGET`
+
+- **Input arc** (consume): `REGISTER[key] -|weight|> functionName`
+- **Output arc** (produce): `functionName -|weight|> REGISTER[key]`
+- **Nested keys**: `ALLOWANCES[owner][spender] -|amount|> approve`
+- **Literal weight**: `transfer -|1|> BALANCES[to]` (for NFTs — always moves exactly 1)
+
+When the weight is a variable name (like `amount`), it becomes a function parameter.
+When the weight is a number (like `1`), it's a literal.
+
+## Examples
+
+| File | Pattern | Description |
+|------|---------|-------------|
+| `counter.btw` | Scalar state | Simple increment/decrement counter |
+| `erc20.btw` | Fungible token | ERC-20 with transfer, approve, transferFrom, mint, burn |
+| `nft.btw` | Non-fungible token | Mint and transfer with ownership tracking |
+| `escrow.btw` | Multi-step workflow | Deposit → lock → release escrow pattern |
+
+## What Gets Generated
+
+For each `.btw` file, `bitwrap -validate` generates:
+
+1. **Contract** (`src/Name.sol`) — Solidity contract with state, functions, events, access control
+2. **Tests** (`test/NameTest.t.sol`) — Foundry tests for each function and guard
+3. **Deploy script** (`script/NameGenesis.s.sol`) — Foundry deployment script
+
+The contract includes:
+- `contractOwner` with `onlyOwner` modifier for privileged functions (mint, etc.)
+- `transferOwnership` and `renounceOwnership` admin functions
+- View functions for exported registers (`balanceOf`, `allowance`, etc.)
+- Epoch counter and event sequencing for on-chain ordering
+
+## Limitations
+
+- `caller` in guards maps to `msg.sender` but can't be used as an arc index yet
+- No array/batch operations (ERC-1155 batch patterns need manual extension)
+- Struct types (VestingSchedule) are supported via templates but not yet in DSL
+- Generated tests handle common patterns; complex multi-step workflows may need manual test setup

examples/counter.btw

@@ -0,0 +1,16 @@
+schema Counter {
+  version "1.0.0"
+
+  register COUNT uint256 observable
+
+  fn(increment) {
+    var amount amount
+    increment -|amount|> COUNT
+  }
+
+  fn(decrement) {
+    var amount amount
+    require(COUNT >= amount)
+    COUNT -|amount|> decrement
+  }
+}

examples/escrow.btw

@@ -0,0 +1,57 @@
+schema Escrow {
+  version "1.0.0"
+  domain "payments"
+
+  register DEPOSITS map[address]uint256 observable
+  register LOCKED map[address]uint256
+  register TOTAL_LOCKED uint256
+
+  event DepositEvent {
+    from: address indexed
+    amount: uint256
+  }
+
+  event LockEvent {
+    from: address indexed
+    amount: uint256
+  }
+
+  event ReleaseEvent {
+    to: address indexed
+    amount: uint256
+  }
+
+  fn(deposit) {
+    var from address
+    var amount amount
+
+    require(amount > 0)
+    @event DepositEvent
+
+    deposit -|amount|> DEPOSITS[from]
+  }
+
+  fn(lock) {
+    var from address
+    var amount amount
+
+    require(DEPOSITS[from] >= amount)
+    @event LockEvent
+
+    DEPOSITS[from] -|amount|> lock
+    lock -|amount|> LOCKED[from]
+    lock -|amount|> TOTAL_LOCKED
+  }
+
+  fn(release) {
+    var to address
+    var amount amount
+
+    require(LOCKED[to] >= amount)
+    @event ReleaseEvent
+
+    LOCKED[to] -|amount|> release
+    TOTAL_LOCKED -|amount|> release
+    release -|amount|> DEPOSITS[to]
+  }
+}