Implement semantic predicate accountability hooks

CLAUDE.md

@@ -37,6 +37,16 @@ cargo run --release --bin antlr4-rust-gen -- \
 The output crate must depend on this runtime (`antlr-rust-runtime = { path = ... }`).
 Both the kotlin-parity dumper and the parse-bench runner are examples.
 
+Every run also writes a `semantics.json` manifest into `--out-dir` listing each
+semantic predicate/action coordinate and its disposition. `--sem-unknown
+error|hook|assume-true|assume-false`, `--sem-patterns`, and
+`--require-full-semantics` control untranslated coordinates (default
+`assume-true`, deprecated; see the README "Semantic Predicates and Actions"
+section and issue #9).
+Generated parsers emit SemIR tables, `with_hooks(tokens, hooks)`, and typed
+hook adapters for bare helper predicates; lexer callers can route closure hooks
+through `LexerSemCtx` and the shared `SemanticHooks` trait.
+
 ## Kotlin parser parity perf benchmark
 
 Reproduces the timings against the Kotlin grammar from `antlr/grammars-v4`.

README.md

@@ -228,6 +228,75 @@ See [docs/kotlin-build.md](docs/kotlin-build.md) for the Kotlin smoke workflow.
 See [docs/runtime-testsuite.md](docs/runtime-testsuite.md) for the upstream
 runtime-testsuite harness.
 
+### Semantic Predicates and Actions: the Compatibility Boundary
+
+ANTLR grammars may embed **target-language** semantic predicates and actions
+(`{isTypeName()}?`, `{this.count++;}`). The serialized ATN records *where*
+they occur, but not executable code, so a metadata-first runtime cannot run
+arbitrary grammar-embedded snippets. The boundary is:
+
+- **Target-agnostic grammars** — no embedded code, or only built-in lexer
+  commands (`skip`, `channel(...)`, `mode(...)`, `type(...)`) — are fully
+  supported.
+- **Recognized predicate/action shapes** — a library of common idioms
+  (constant predicates, lookahead text/type checks, integer member counters,
+  column predicates, and the upstream testsuite's action templates) — are
+  translated into SemIR by `antlr4-rust-gen` when the grammar source is
+  passed via `--grammar`.
+- **User pattern files** — `--sem-patterns file.toml` can add exact predicate
+  rewrites, helper-call rewrites, and per-coordinate `hook` /
+  `assume-true` / `assume-false` / `error` dispositions without changing the
+  generator.
+- **Everything else is not silently guessed.** Each generator run writes a
+  `semantics.json` manifest next to the generated modules listing every
+  predicate/action coordinate with its grammar source span, body, and
+  disposition (`translated`, `hooked`, `assume-true`, `assume-false`,
+  `ignored`, or `error`).
+
+Unknown coordinates are governed by `--sem-unknown`:
+
+```bash
+antlr4-rust-gen --lexer L.interp --parser P.interp --grammar G.g4 \
+    --out-dir src/generated --sem-unknown error
+```
+
+- `assume-true` (current default, deprecated): unknown predicates pass,
+  unknown actions are no-ops — the historical behavior. A future minor
+  release changes the default to `error`.
+- `hook`: unknown parser predicates are routed to `SemanticHooks` and fail if
+  the hook does not handle them.
+- `assume-false`: unknown predicates fail, removing the guarded alternatives.
+- `error`: generation fails, naming each coordinate:
+
+  ```text
+  unsupported semantic predicate: rule=s(0) pred_index=0 at 2:4: {isTypeName()}
+  ```
+
+At runtime the same policy exists as
+`ParserRuntimeOptions::unknown_predicate_policy`
+(`UnknownSemanticPolicy::{AssumeTrue, AssumeFalse, Error}`); under `Error`,
+evaluating an unknown predicate coordinate fails the parse with
+`AntlrError::Unsupported` instead of producing a tree whose shape silently
+depended on a guess.
+
+Generated parsers also expose a parser-side hook escape hatch:
+`MyParser::with_hooks(tokens, hooks)`, where `hooks` implements
+`SemanticHooks`. Unknown parser predicates are offered to
+`SemanticHooks::sempred` before the fallback policy is applied, and unhandled
+parser action events are offered to `SemanticHooks::action` after the committed
+parse path is selected. Predicate hooks may run speculatively during
+prediction, so they must be replay-safe.
+
+For bare helper-call predicates, generated parsers also emit a typed hook
+adapter (`MyParserHooks` plus `MyParserTypedHooks<T>`) that maps stable
+manifest coordinates to named Rust methods. Lexer callers can use
+`LexerSemCtx` with `atn::lexer::next_token_with_semantic_hooks` or the
+compiled-DFA variant to route lexer predicates/actions through the same
+`SemanticHooks` trait.
+
+Use `--require-full-semantics` in CI when every coordinate must be either
+translated or explicitly hooked; policy fallbacks fail generation.
+
 ## Runtime Testsuite
 
 On the maintainer checkout, where the ANTLR jar and upstream runtime-testsuite