transform: add inline rewrite-mode forms (expr: and stmt:)

Adds two inline forms to `mode: rewrite` for patch specifications,
alongside the existing patch-function form. Both are compiled
through clang/clangCIR and spliced at the matched op's site
without going through a library patch module.

`expr:` — single C expression, value substitution
  - Wrapper return type matches the matched op's first result.
  - Captures bind by-reference (`T *__cap_NAME`, `$NAME` →
    `(*__cap_NAME)`); writes to source-storage captures propagate
    to caller storage.
  - Strict parse-time rule: leading control-flow keyword, leading
    `{`, or any top-level `;` is rejected with a "use stmt:" hint.

`stmt:` — C statement body, spliced as CFG
  - Wrapper is always void-returning. Body is preprocessed so each
    `return X;` / `return;` becomes a `__patchestry_return(...)`
    marker call (typed by the enclosing function's return type and
    marked `noreturn`).
  - Inliner clones the wrapper's entry block before the matched op,
    skipping top-level `cir.return` / `cir.br` so fall-through
    becomes natural sequential flow into the matched op's tail.
  - MVP scope: matched op must be 0-result, wrapper must be a
    single function-level block, and surviving `__patchestry_*`
    calls (i.e. user wrote `return X;`) are loud-rejected — the
    marker → CFG rewrite is a follow-up phase.

`patch:` — unchanged, but `mode: replace` keyword retired in favor
of unified `mode: rewrite`. The parser rejects `mode: replace` with
a migration error pointing at `mode: rewrite` + `patch:` +
`arguments:`. `mode: rewrite` requires exactly one of `expr:` /
`stmt:` / `patch:`.

Capture write semantics (shared between expr: and stmt:)
  - Source-storage captures (`cir.load %alloca` / `cir.load
    %global`): wrapper receives `&%alloca`. Writes propagate.
  - Non-storage captures (binop result, constant, unalloca'd block
    arg): wrapper receives the address of a freshly materialised
    `arg_ref` temp. Reads work. Writes are loud-rejected — the
    validator walks transitive uses through `cir.get_member`,
    `cir.ptr_stride`, and `cir.cast` chains rooted at the wrapper
    block-arg, so by-value-struct field writes and array-element
    writes are caught alongside direct `cir.store v, %arg`.
  - The chain stops at `cir.load` so writes through a *loaded*
    pointer (which target real caller storage) stay permitted.

Inliner safety
  - `rewriteWithExpression`'s `fail()` lambda rolls back both the
    cloned ops and the `arg_ref` temps materialised by
    `pass.create_reference`, restoring the "no IR drift on error"
    contract.
  - Both inliners route the matched-op erase through
    `pass.erase_op`, scrubbing `inline_worklists` so chained
    patches (`apply_after` followed by a `mode: rewrite` matching
    the emitted patch call by name) can't leave a dangling pointer
    for the post-pass `inline_call` loop.

Implementation surface
  - YAML schema (`include/patchestry/YAML/PatchSpec.hpp`): add
    `stmt` field to `Action` / `PatchActionObject` / `PatchEntry`;
    three-way mutual-exclusion validation in both surfaces.
  - Fragment compiler (`lib/patchestry/Passes/FragmentCompiler.cpp`,
    `.hpp`): `compile_fragment` + `compile_stmt_fragment` with a
    process-scoped content-keyed cache. Marker preprocessor
    (`preprocess_return_markers`, string-aware over strings/char/
    comments). Strict-expr validator
    (`looks_like_statement`).
  - Inliners (`lib/patchestry/Passes/PatchOperationImpl.{cpp,hpp}`):
    `rewriteWithExpression` (expr-form) and `rewriteWithStatements`
    (stmt-form). Shared `find_capture_source_alloca`,
    `promote_parameter_slots`, `reaches_store_via_addr` storage-
    write validator. `replaceCallWithPatch` /
    `replaceOperationWithPatch` for the `patch:` form.
  - Dispatch (`lib/patchestry/Passes/InstrumentationPass.cpp`):
    function-mode and operation-mode branches both route REWRITE
    to the right inliner based on which inline-form field is set.
  - Documentation (`docs/GettingStarted/patch_specifications.md`):
    three-form rewrite mode documented with examples for each.
  - Test fixtures: `rewrite_emit_*.yaml` for expr-form coverage,
    `rewrite_stmt_*.yaml` for stmt-form (free-and-null, if-guarded
    free, while-with-locals, compound block with declaration).
    Reject fixtures verify storage-write rejection and the
    parser-time three-way exclusion.

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

Author: kumarak

.claude/rules/patch-development.md

@@ -24,6 +24,10 @@ paths:
 | Add LIT transform test | `test/patchir-transform/` — copy an existing YAML test as template |
 | Modify CIR→LLVM lowering | `tools/patchir-cir2llvm/main.cpp` — CIR to LLVM IR/bitcode with contract metadata |
 | Update spec docs | `docs/GettingStarted/patch_specifications.md` |
+| Update fragment wrapper synthesis | `lib/patchestry/Passes/FragmentCompiler.cpp` — `synthesise_wrapper`, `is_statement_form`, `substitute_metavars`. Captures pass by-reference (`T *__cap_NAME`, `$NAME` → `(*__cap_NAME)`); clang/clangIR is the only parser. |
+| Extend the rewrite inliner — `expr:` form | `lib/patchestry/Passes/PatchOperationImpl.cpp` — `rewriteWithExpression`, `find_rewrite_root_in_wrapper`, `find_capture_source_alloca`, `promote_parameter_slots`. Each wrapper block-arg maps to either the capture's source alloca (writes propagate) or a fresh `arg_ref` temp from `pass.create_reference` (read-only; the post-clang validator rejects `cir.store ..., %arg` against non-storage captures). |
+| Adjust the struct-decl walker (capture types → wrapper-source decls) | `lib/patchestry/Passes/PatchOperationImpl.cpp` — `collect_struct_types_rec`, `topo_order_structs`, `lookup_field_name`, `emit_struct_decls_for_types`. Field names are recovered from module-level `cir::GetMemberOp` ops; `rewriteWithExpression` seeds collection with capture types + the matched op's result type. |
+| Add a C-type spelling for capture-type conversion | `lib/patchestry/Passes/Utils.cpp` — `ConvertCirTypesToCTypes`. If the new spelling needs a typedef for clang to accept it, also extend the prelude in `synthesise_wrapper` (`lib/patchestry/Passes/FragmentCompiler.cpp`). |
 
 ## Adding a New Argument Source
 

docs/GettingStarted/patch_specifications.md

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025, Trail of Bits, Inc.
+ *
+ * This source code is licensed in accordance with the terms specified in
+ * the LICENSE file found in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include <llvm/ADT/ArrayRef.h>
+#include <llvm/ADT/StringRef.h>
+
+namespace patchestry::passes::fragment_expr {
+
+    // `name` is without the leading `$`; `c_type` is the spelling clang
+    // will see in the wrapper's parameter list (e.g. "uint32_t", "int32_t *").
+    struct CaptureBinding
+    {
+        std::string name;
+        std::string c_type;
+    };
+
+    struct FragmentResult
+    {
+        std::string func_name;
+        std::optional< std::string > module_text;
+        std::string error;
+    };
+
+    // Compile a rewrite-mode fragment by wrapping it in a synthesised C
+    // function and invoking clang/clangCIR. `arch` follows the Ghidra
+    // `lang` convention ("ARM:LE:32:default"). Identical inputs hit a
+    // process-scoped content-keyed cache.
+    FragmentResult compile_fragment(
+        llvm::StringRef fragment, llvm::ArrayRef< CaptureBinding > captures,
+        llvm::StringRef arch, llvm::StringRef return_c_type = "int32_t",
+        llvm::StringRef extra_decls = ""
+    );
+
+    // Compile a `stmt:` body: auto-converts `return X;` / `return;`
+    // to `__patchestry_return(...)` markers, substitutes `$NAME`,
+    // and wraps in a void function with a `noreturn`-marked extern
+    // for the marker (typed by `enclosing_return_c_type`). Cache
+    // key includes the enclosing return type.
+    FragmentResult compile_stmt_fragment(
+        llvm::StringRef body, llvm::ArrayRef< CaptureBinding > captures,
+        llvm::StringRef arch, llvm::StringRef enclosing_return_c_type = "void",
+        llvm::StringRef extra_decls = ""
+    );
+
+} // namespace patchestry::passes::fragment_expr

include/patchestry/Passes/FragmentCompiler.hpp

@@ -108,7 +108,12 @@ namespace patchestry::passes { // NOLINT
      *   entry block, after the alloca + parameter-store prologue. Patch-only — contracts
      *   are static and attach predicates as MLIR attributes, so "entrypoint" has no
      *   meaning for them.
-     * - REPLACE: Replace the matched op with a call to the patch function (patch-only).
+     * - REWRITE: Substitute the matched op's result. Two forms (selected
+     *   per-spec): an inline C expression fragment (`expr:`) compiled
+     *   through the clang/CIR fragment compiler and inlined at the match
+     *   site, or an external patch function (`patch:` + `arguments:`)
+     *   called as a `cir.call`. The legacy REPLACE mode was merged into
+     *   this one (patch-only).
      * - ERASE: Delete the matched op, replacing live results with default values
      *   (patch-only; no patch function invoked).
      *
@@ -163,7 +168,7 @@ namespace patchestry::passes { // NOLINT
          * @brief Erase an operation while keeping `inline_worklists` consistent.
          *
          * The inline worklist stores raw `Operation *` pointers pending
-         * post-pass inlining. A later patch action with `mode: replace` or
+         * post-pass inlining. A later patch action with `mode: rewrite` or
          * `mode: erase` may target a previously-emitted patch call by name
          * (see the intentional no-skip comment in `apply_patch_action_to_targets`).
          * If such an action erases an op that's still in `inline_worklists`,
@@ -332,15 +337,19 @@ namespace patchestry::passes { // NOLINT
             mlir::ModuleOp dest, mlir::ModuleOp src, const std::string &symbol_name
         );
 
+      public:
         /**
          * @brief Creates a cast operation if types differ, otherwise returns the original
-         * value.
+         * value. Public so the rewrite-mode inliner (FragmentCompiler) can
+         * reuse the same cast-kind decision table the rest of the pass uses, rather
+         * than re-deriving it.
          */
         mlir::Value create_cast_if_needed(
             mlir::OpBuilder &builder, mlir::Operation *call_op, mlir::Value value,
             mlir::Type target_type
         );
 
+      private:
         /**
          * @brief Creates a reference (alloca + store) for a given value.
          */

include/patchestry/Passes/InstrumentationPass.hpp

@@ -23,8 +23,8 @@ namespace patchestry::passes {
         APPLY_BEFORE,
         APPLY_AFTER,
         APPLY_AT_ENTRYPOINT, // Insert patch call at caller's entry block
-        REPLACE,
-        ERASE // Delete matched op, no patch function
+        ERASE, // Delete matched op, no patch function
+        REWRITE
     };
 
     enum class ArgumentSourceType : uint8_t {
@@ -45,8 +45,8 @@ namespace patchestry::passes {
     static_assert(static_cast< uint8_t >(InstrumentationMode::APPLY_BEFORE) == 1);
     static_assert(static_cast< uint8_t >(InstrumentationMode::APPLY_AFTER) == 2);
     static_assert(static_cast< uint8_t >(InstrumentationMode::APPLY_AT_ENTRYPOINT) == 3);
-    static_assert(static_cast< uint8_t >(InstrumentationMode::REPLACE) == 4);
-    static_assert(static_cast< uint8_t >(InstrumentationMode::ERASE) == 5);
+    static_assert(static_cast< uint8_t >(InstrumentationMode::ERASE) == 4);
+    static_assert(static_cast< uint8_t >(InstrumentationMode::REWRITE) == 5);
 
     static_assert(static_cast< uint8_t >(ArgumentSourceType::OPERAND) == 0);
     static_assert(static_cast< uint8_t >(ArgumentSourceType::VARIABLE) == 1);