feat(evaluator): implement indirect offset resolution (#37)

.devcontainer/devcontainer.json

@@ -69,10 +69,7 @@
                     "--all-features"
                 ],
                 "rust-analyzer.cargo.features": "all",
-                "rust-analyzer.rustfmt.extraArgs": [
-                    "--edition",
-                    "2024"
-                ],
+                "rust-analyzer.rustfmt.extraArgs": ["--edition", "2024"],
                 "editor.formatOnSave": true,
                 "editor.codeActionsOnSave": {
                     "source.fixAll": "explicit"

.gemini/settings.json

@@ -1,12 +1,9 @@
 {
-  "mcpServers": {
-    "tessl": {
-      "type": "stdio",
-      "command": "tessl",
-      "args": [
-        "mcp",
-        "start"
-      ]
+    "mcpServers": {
+        "tessl": {
+            "type": "stdio",
+            "command": "tessl",
+            "args": ["mcp", "start"]
+        }
     }
-  }
 }

.mcp.json

@@ -1,12 +1,9 @@
 {
-  "mcpServers": {
-    "tessl": {
-      "type": "stdio",
-      "command": "tessl",
-      "args": [
-        "mcp",
-        "start"
-      ]
+    "mcpServers": {
+        "tessl": {
+            "type": "stdio",
+            "command": "tessl",
+            "args": ["mcp", "start"]
+        }
     }
-  }
 }

.mdformat.toml

@@ -10,20 +10,23 @@ exclude = [
     "megalinter-reports/**",
     "**/*.result",
     "**/*.testfile",
+    "**/SKILL.md",           # AI stuff
+    ".claude/**/*",          # AI stuff
+    ".tessl/**/*",           # AI stuff
 ]
 validate = true
 number = true
 wrap = "no"
 end_of_line = "lf"
-# extensions = [
-#     "gfm",
-#     "frontmatter",
-#     "footnote",
-#     "simple_breaks",
-#     "gfm_alerts",
-#     "toc",
-#     "wikilink",
-# ]
+extensions = [
+    "gfm",
+    "footnote",
+    "front_matters",
+    "simple_breaks",
+    "wikilink",
+    "gfm_alerts",
+    "toc",
+]
 
 [plugin.mkdocs]
 align_semantic_breaks_in_lists = true

.vscode/settings.json

@@ -21,12 +21,8 @@
     "git.rebaseWhenSync": true,
     "git.replaceTagsWhenPull": true,
     "githubPullRequests.codingAgent.uiIntegration": true,
-    "ruff.path": [
-        "${workspaceFolder}/.vscode/mise-tools/ruff"
-    ],
-    "ruff.interpreter": [
-        "${workspaceFolder}/.vscode/mise-tools/python"
-    ],
+    "ruff.path": ["${workspaceFolder}/.vscode/mise-tools/ruff"],
+    "ruff.interpreter": ["${workspaceFolder}/.vscode/mise-tools/python"],
     "python.defaultInterpreterPath": "${workspaceFolder}/.vscode/mise-tools/python",
     "bun.runtime": "${workspaceFolder}/.vscode/mise-tools/bun"
-}
+}

AGENTS.md

@@ -204,7 +204,7 @@ cargo test --doc   # Test documentation examples
 
 ### Currently Implemented (v0.1.0)
 
-- **Offsets**: Absolute and from-end specifications (indirect and relative are parsed but not yet evaluated)
+- **Offsets**: Absolute, from-end, and indirect specifications (relative offsets are parsed but not yet evaluated)
 - **Types**: `byte`, `short`, `long`, `quad`, `float`, `double`, `string`, `pstring` with endianness support; unsigned variants `ubyte`, `ushort`/`ubeshort`/`uleshort`, `ulong`/`ubelong`/`ulelong`, `uquad`/`ubequad`/`ulequad`; float/double endian variants `befloat`/`lefloat`, `bedouble`/`ledouble`; 32-bit date/timestamp types `date`/`ldate`/`bedate`/`beldate`/`ledate`/`leldate`; 64-bit date/timestamp types `qdate`/`qldate`/`beqdate`/`beqldate`/`leqdate`/`leqldate`; `pstring` is a Pascal string (length-prefixed) with support for 1/2/4-byte length prefixes via `/B`, `/H` (2-byte BE), `/h` (2-byte LE), `/L` (4-byte BE), `/l` (4-byte LE) suffixes, and the `/J` flag (stored length includes prefix width, JPEG convention) which is combinable with width suffixes (e.g., `pstring/HJ`); date values formatted as "Www Mmm DD HH:MM:SS YYYY" matching GNU `file` output; types are signed by default (libmagic-compatible)
 - **Operators**: `=` (equal), `!=` (not equal), `<` (less than), `>` (greater than), `<=` (less equal), `>=` (greater equal), `&` (bitwise AND with optional mask), `^` (bitwise XOR), `~` (bitwise NOT), `x` (any value)
 - **Nested Rules**: Hierarchical rule evaluation with proper indentation
@@ -245,9 +245,8 @@ impl BinaryRegex for regex::bytes::Regex {
 
 ### Offset Specifications
 
-- Indirect offsets are parsed into the AST but evaluation is not yet implemented (#37)
+- Indirect offsets are fully implemented (parsing + evaluation) with specifiers: `.b/.B` (byte), `.s/.S` (short), `.l/.L` (long), `.q/.Q` (quad); lowercase = little-endian, uppercase = big-endian (GNU `file` semantics); pointer types signed by default; adjustment after closing paren: `(base.type)+adj`
 - Relative offsets are parsed into the AST but evaluation is not yet implemented (#38)
-- Only absolute and from-end offsets are fully functional
 
 ### Magic File Syntax
 
@@ -570,3 +569,7 @@ This project has the OSSF Best Practices passing badge. Maintain these standards
 - SECURITY.md documents vulnerability reporting with scope, safe harbor, and PGP key
 - AGENTS.md must accurately reflect implemented features (not aspirational)
 - `docs/src/release-verification.md` documents artifact signing for users
+
+## Agent Rules <!-- tessl-managed -->
+
+@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)

AI_POLICY.md

@@ -0,0 +1,31 @@
+# AI Usage Policy
+
+We build operator-focused security tools. AI coding assistants are part of how we do that. This policy is not anti-AI -- it is pro-accountability.
+
+Think of AI assistance like spellcheck. It catches typos, suggests corrections, and speeds up the mechanical parts of writing. But you are still responsible for your words and their consequences.
+
+## The Rule
+
+**You own every line you submit.** You must be able to explain what it does and how it interacts with the rest of the system without asking your AI to explain it back to you.
+
+Everything else follows from that.
+
+## How We Work
+
+- **Disclose your tools.** Note what you used in your PR description -- Claude Code, Copilot, Cursor, whatever. No specific format required.
+
+- **Review AI-generated text before posting.** Issues, discussions, and PR descriptions must reflect your understanding, not a language model's first draft. Read it, cut the filler, make sure it says what you mean.
+
+- **No AI-generated media.** No generated images, logos, audio, or video. Text-based diagrams (ASCII art, Mermaid) and code are acceptable.
+
+- **Unreviewed output gets closed.** Hallucinated APIs, boilerplate that ignores project conventions, suggestions you clearly did not run -- these get closed without review. We are not a QA service for your AI's output.
+
+## Why
+
+Transparent by design means knowing what the code does and why it is there. Tested under pressure means every change was understood by the person who submitted it. AI makes capable engineers faster. It does not replace the understanding that makes contributions trustworthy.
+
+Every pull request is reviewed by a human. Submitting work you do not understand shifts that burden onto maintainers. That is not how we operate.
+
+## New Contributors
+
+Use AI to learn the codebase. Read the code it generates. Run it. Break it. Then submit work that reflects your understanding. We will help you through review -- that deal only works if the code is yours.

GOTCHAS.md

@@ -59,6 +59,18 @@ The nom `tuple` combinator is deprecated. Use bare tuple syntax `(a, b, c)` dire
 
 `type_keyword_to_kind` has `#[allow(clippy::too_many_lines)]` because it exceeds 100 lines with all date keywords.
 
+### 3.5 `parse_number` Does Not Handle `+` Prefix
+
+`parse_number` handles `-` signs but not `+`. When parsing syntax like `+4` (e.g., indirect offset adjustments), consume the `+` character manually before calling `parse_number`.
+
+### 3.6 `parse_value` Requires Quoted Strings
+
+`parse_value()` does not accept bare unquoted strings. String values in magic file rules must be quoted (e.g., `string "MZ"` not `string MZ`). Integration tests writing magic files must use `r#"0 string "MZ" description"#` format.
+
+### 3.7 Indirect Offset Pointer Specifiers Follow GNU `file` Semantics
+
+Lowercase pointer specifiers (`.s`, `.l`, `.q`) map to **little-endian**, not native endian. Uppercase (`.S`, `.L`, `.Q`) map to big-endian. All numeric pointer types are **signed by default** (per S6.3). The adjustment is parsed **after** the closing paren: `(base.type)+adj`, not `(base.type+adj)`.
+
 ## 4. Module Visibility & Re-exports
 
 ### 4.1 Private Engine Module

docs/solutions/integration-issues/indirect-offset-parser-evaluator-sync.md

@@ -0,0 +1,165 @@
+---
+title: Implement indirect offset parsing in magic file grammar
+date: 2026-03-30
+status: resolved
+severity: high
+category: integration-issues
+components:
+  - parser/grammar
+  - evaluator/offset
+  - integration
+tags:
+  - parser
+  - indirect-offset
+  - nom
+  - magic-file-syntax
+  - pointer-specifier
+issue: '#37'
+branch: 37-evaluator-implement-indirect-offset-resolution
+symptoms:
+  - parse_offset("(0x3c.l)") fails with parse error
+  - Magic files containing indirect offset syntax cannot be loaded via MagicDatabase::load_from_file()
+  - resolve_indirect_offset() is unreachable dead code from text-magic loading path
+root_cause: parse_offset() had no branch for '('-prefixed input; always delegated to parse_number() which only handles numeric literals
+solution_files:
+  - src/parser/grammar/mod.rs
+  - src/parser/grammar/tests.rs
+  - tests/indirect_offset_integration.rs
+related_gotchas:
+  - parse_number() handles '-' prefix but not '+'; positive adjustments need manual '+' consumption
+  - parse_value() requires quoted strings; bare string literals cause integration test failures
+---
+
+# Indirect Offset Parser-Evaluator Sync
+
+## Problem
+
+The evaluator for indirect offsets (`resolve_indirect_offset()` in `src/evaluator/offset/indirect.rs`) was fully implemented with 35 unit tests, but the parser in `src/parser/grammar/mod.rs` could not produce `OffsetSpec::Indirect` AST nodes. The `parse_offset()` function only handled absolute numeric offsets and had no branch for `(`-prefixed indirect offset syntax like `(0x3c.l)` or `(0x3c.l+4)`.
+
+This meant the feature was unreachable through the public `MagicDatabase::load_from_file()` API -- the primary way users load text magic files.
+
+## Root Cause
+
+`parse_offset()` unconditionally delegated to `parse_number()`, which only parses numeric literals. Input starting with `(` was rejected as a parse error. The evaluator code was effectively dead code from the text-magic loading path.
+
+## Solution
+
+### 1. Added `pointer_specifier_to_type()` helper
+
+Maps single-character pointer specifiers to `(TypeKind, Endianness)` per libmagic convention:
+
+| Specifier  | Width  | Endianness |
+| ---------- | ------ | ---------- |
+| `.b`, `.B` | 1 byte | Native     |
+| `.s`       | 2 byte | Native     |
+| `.S`       | 2 byte | Big        |
+| `.l`       | 4 byte | Native     |
+| `.L`       | 4 byte | Big        |
+| `.q`       | 8 byte | Native     |
+| `.Q`       | 8 byte | Big        |
+
+All pointer types are unsigned (`signed: false`). Lowercase = native endian, uppercase = big-endian.
+
+### 2. Added `parse_indirect_offset()` function
+
+Parses `(base.type)` and `(base.type+/-adj)` syntax:
+
+1. Consume `(`
+2. Parse base offset via `parse_number()`
+3. Consume `.` and type specifier character
+4. Optionally parse adjustment (see gotcha below)
+5. Consume `)`
+6. Return `OffsetSpec::Indirect { base_offset, pointer_type, adjustment, endian }`
+
+### 3. Updated `parse_offset()` to branch on leading `(`
+
+```rust
+pub fn parse_offset(input: &str) -> IResult<&str, OffsetSpec> {
+    let (input, _) = multispace0(input)?;
+    if input.starts_with('(') {
+        let (input, spec) = parse_indirect_offset(input)?;
+        let (input, _) = multispace0(input)?;
+        Ok((input, spec))
+    } else {
+        let (input, offset_value) = parse_number(input)?;
+        let (input, _) = multispace0(input)?;
+        Ok((input, OffsetSpec::Absolute(offset_value)))
+    }
+}
+```
+
+### 4. No changes needed to `parse_rule_offset()`
+
+It delegates to `parse_offset()`, so hierarchical forms like `>(0x3c.l)` work automatically.
+
+## Gotchas Discovered
+
+### `parse_number()` does not handle `+` prefix
+
+`parse_number()` handles `-` internally but not `+`. For `+N` adjustments, the `+` must be consumed manually:
+
+```rust
+let (input, adjustment) = if input.starts_with('+') {
+    let (input, _) = char('+')(input)?;
+    parse_number(input)?
+} else if input.starts_with('-') {
+    parse_number(input)?
+} else {
+    (input, 0)
+};
+```
+
+Do NOT modify `parse_number()` globally -- it is shared by offset and value parsing, and adding `+` support would change semantics elsewhere.
+
+### `parse_value()` requires quoted strings
+
+Integration tests initially failed because `parse_value()` does not accept bare strings. Magic file string values must be quoted:
+
+```text
+# Correct
+0 string "MZ" DOS executable
+
+# Wrong -- parse_value() rejects bare "MZ"
+0 string MZ DOS executable
+```
+
+### Use big-endian specifiers in cross-platform tests
+
+Prefer `.L` (big-endian long) over `.l` (native) in integration test magic files so byte buffers are deterministic across architectures.
+
+## Prevention Strategies
+
+### Parser-Evaluator Parity Checklist
+
+When adding a new AST variant, ensure:
+
+1. **Parser produces it** -- unit test parses raw syntax, asserts correct AST node
+2. **Evaluator consumes it** -- unit test constructs AST node, asserts evaluation result
+3. **End-to-end test exists** -- integration test through `MagicDatabase::load_from_file()` proves the full pipeline works
+4. **Codegen handles it** -- if it can appear in built-in rules, update `src/parser/codegen.rs`
+5. **Strength calculation covers it** -- update `src/evaluator/strength.rs` if scoring changes
+
+### Integration Test Template
+
+```rust
+#[test]
+fn test_feature_end_to_end() {
+    let temp_dir = TempDir::new().unwrap();
+    let magic_path = temp_dir.path().join("test.magic");
+    let mut f = fs::File::create(&magic_path).unwrap();
+    writeln!(f, r#"0 string "MAGIC" Test match"#).unwrap();
+
+    let db = MagicDatabase::load_from_file(&magic_path).unwrap();
+    let result = db.evaluate_buffer(b"MAGIC\x00data").unwrap();
+    assert!(result.description.contains("Test match"));
+}
+```
+
+## Cross-References
+
+- **Evaluator solution**: `docs/solutions/logic-errors/indirect-offset-resolution.md`
+- **Magic format spec**: `docs/MAGIC_FORMAT.md` (lines 106-126, indirect offset section)
+- **Gotchas**: `GOTCHAS.md` sections 3.5 (`parse_number` `+` limitation) and 3.6 (quoted strings)
+- **Architecture**: `AGENTS.md` offset specifications section
+- **Issue**: #37 (indirect offset resolution)
+- **Related gotchas**: S2 (enum variant checklists), S3 (parser architecture split), S5 (numeric type pitfalls)