fix: Restore Z-Machine opcode validation for Zork I compatibility

Fixes critical regression where interpreter incorrectly rejected opcode 0x15
(sub instruction), causing Zork I and other commercial games to fail with
"Invalid Long form opcode 0x15" errors.

Changes:
- Updated src/instruction.rs validation from 0x01-0x14 to 0x01-0x1C
- Added comprehensive opcode documentation (0x14=add, 0x15=sub, etc.)
- Updated unit tests to reflect correct validation ranges
- Documented opcode validation architecture in ARCHITECTURE.md
- Confirmed fix with successful Zork I testing

Root cause: Commit d7dec5c implemented overly restrictive validation that
rejected fundamental Z-Machine arithmetic operations (sub, mul, div, mod).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: skeptomai

.gitignore

@@ -11,3 +11,4 @@ debug.log
 
 # Claude Code settings
 .claude/settings.local.json
+pkg/

docs/ARCHITECTURE.md

@@ -386,6 +386,56 @@ Each opcode module follows a consistent pattern:
 4. **Code Organization**: Related operations are grouped together logically
 5. **Performance**: Direct method calls with minimal routing overhead
 
+### Opcode Validation
+
+The instruction decoder in `src/instruction.rs` performs critical validation of Z-Machine opcodes to ensure only valid instructions are processed. This validation prevents interpreter crashes from malformed or corrupted game files.
+
+#### Valid Opcode Ranges
+
+Z-Machine opcodes are validated based on their instruction form:
+
+```rust
+// Long form (2OP) instructions: opcodes 0x01-0x1C
+if opcode == 0x00 || opcode > 0x1C {
+    return Err(format!(
+        "Invalid Long form opcode 0x{:02x} at address {addr:04x} (valid range: 0x01-0x1C)",
+        opcode
+    ));
+}
+```
+
+**Critical Opcode Mappings:**
+- `0x14` - add (addition)
+- `0x15` - sub (subtraction)
+- `0x16` - mul (multiplication)
+- `0x17` - div (division)
+- `0x18` - mod (modulo)
+- `0x19` - call_2s (call function, store result)
+- `0x1A` - call_2n (call function, no result)
+- `0x1B` - set_colour (set foreground/background colors)
+- `0x1C` - throw (exception handling)
+
+#### Historical Issue: Opcode 0x15 Regression
+
+A critical regression was introduced in commit `d7dec5c` that incorrectly rejected opcode 0x15 (sub instruction), causing Zork I and other commercial games to fail with "Invalid Long form opcode 0x15" errors. The issue was caused by implementing overly restrictive validation that assumed opcodes only went up to 0x14 (add).
+
+**Root Cause:** The Z-Machine specification defines fundamental arithmetic operations in opcodes 0x14-0x18 (add, sub, mul, div, mod), but the validation code incorrectly limited the range to 0x01-0x14.
+
+**Resolution:** Updated validation to accept the correct range 0x01-0x1C, ensuring all fundamental Z-Machine operations are properly supported.
+
+**Testing:** The fix was validated by successfully running Zork I (`/Users/cb/Projects/infocom-testing-old/infocom/resources/test/zork1/DATA/ZORK1.DAT`), confirming compatibility with commercial Infocom games.
+
+#### Validation Architecture
+
+The decoder performs form-specific validation:
+
+1. **Long Form (2OP)**: Validates opcodes 0x01-0x1C
+2. **Short Form (1OP/0OP)**: Uses different opcode spaces
+3. **Variable Form (VAR)**: Extended opcode validation for multi-operand instructions
+4. **Extended Form (EXT)**: v5+ extended instruction set
+
+This layered validation ensures that instruction decoding failures are caught early with descriptive error messages, preventing silent corruption or undefined behavior during game execution.
+
 ## Core Components Deep Dive
 
 ### 1. Game Loading and Version Detection

src/instruction.rs

@@ -160,18 +160,20 @@ impl Instruction {
                 let opcode = opcode_byte & 0x1F;
 
                 // CRITICAL FIX: Validate opcode per Z-Machine specification
-                // Long form (2OP) opcodes are only valid for 0x01-0x14 (1-20)
+                // Long form (2OP) opcodes are valid for 0x01-0x1C (1-28) in Z-Machine spec
                 // This validation prevents false positives in disassembly where
                 // data regions were incorrectly decoded as instructions
                 // Examples of false positives this prevents:
                 // - Address 33c04 in AMFV: all zeros decoded as Long 0x00
                 // - Addresses caf8, cafc: data incorrectly interpreted as code
-                // - Invalid opcodes above 0x14 that don't exist in Z-Machine spec
-                // ENHANCED VALIDATION: Reject ALL invalid Long form opcodes per Z-Machine spec
-                // 2OP instructions exist for opcodes 1-20 (0x01-0x14), opcode 0 and 0x15+ are invalid
-                if opcode == 0x00 || opcode > 0x14 {
+                //
+                // Valid 2OP opcodes include fundamental arithmetic operations:
+                // 0x14 = add, 0x15 = sub, 0x16 = mul, 0x17 = div, 0x18 = mod
+                // 0x19 = call_2s, 0x1A = call_2n, 0x1B = set_colour, 0x1C = throw
+                // Zork I and other commercial Infocom games legitimately use these opcodes
+                if opcode == 0x00 || opcode > 0x1C {
                     return Err(format!(
-                        "Invalid Long form opcode 0x{:02x} at address {addr:04x} (valid range: 0x01-0x14)",
+                        "Invalid Long form opcode 0x{:02x} at address {addr:04x} (valid range: 0x01-0x1C)",
                         opcode
                     ));
                 }
@@ -696,10 +698,10 @@ mod tests {
     }
 
     #[test]
-    fn test_reject_invalid_long_form_opcode_0x15() {
-        // Test that invalid Long form opcode 0x15 is rejected (above valid range)
+    fn test_reject_invalid_long_form_opcode_0x1d() {
+        // Test that invalid Long form opcode 0x1D is rejected (above valid range)
         let memory = vec![
-            0x35, // Long form, 2OP, opcode 0x15 (INVALID), both small constants
+            0x3D, // Long form, 2OP, opcode 0x1D (INVALID), both small constants
             0x34, // First operand (small constant)
             0x78, // Second operand (small constant)
             0x00, 0x00, // Padding
@@ -708,13 +710,13 @@ mod tests {
         let result = Instruction::decode(&memory, 0, 3);
         assert!(result.is_err());
         let error_msg = result.unwrap_err();
-        assert!(error_msg.contains("Invalid Long form opcode 0x15"));
-        assert!(error_msg.contains("valid range: 0x01-0x14"));
+        assert!(error_msg.contains("Invalid Long form opcode 0x1d"));
+        assert!(error_msg.contains("valid range: 0x01-0x1C"));
     }
 
     #[test]
     fn test_accept_valid_long_form_opcodes() {
-        // Test that valid Long form opcodes 0x01-0x14 are accepted
+        // Test that valid Long form opcodes 0x01-0x1C are accepted
 
         // Test opcode 0x01 (je)
         let memory1 = vec![
@@ -735,5 +737,24 @@ mod tests {
             0x00, // Padding
         ];
         assert!(Instruction::decode(&memory2, 0, 3).is_ok());
+
+        // Test opcode 0x15 (sub) - critical for Zork I compatibility
+        let memory3 = vec![
+            0x35, // Long form, 2OP, opcode 0x15 (sub), both small constants
+            0x0A, // First operand (small constant)
+            0x05, // Second operand (small constant)
+            0x01, // Store variable
+            0x00, // Padding
+        ];
+        assert!(Instruction::decode(&memory3, 0, 3).is_ok());
+
+        // Test opcode 0x1C (throw) - highest valid 2OP opcode
+        let memory4 = vec![
+            0x3C, // Long form, 2OP, opcode 0x1C (throw), both small constants
+            0x01, // First operand (small constant)
+            0x02, // Second operand (small constant)
+            0x00, 0x00, // Padding
+        ];
+        assert!(Instruction::decode(&memory4, 0, 3).is_ok());
     }
 }