The Ultimate Elastic Patcher v1.60 #
Technical Manual & Operational Guide
1. Core Functional Features #
The Ultimate Elastic Patcher operates as an event-driven system console that interacts with your file system and clipboard.
π Clipboard Monitoring
Trigger:F9
(Arm/Disarm)Behavior: When armed, the system polls the clipboard. If valid patch patterns (such as Aider search/replace blocks, unified diffs, or code snippets) are detected, they are processed. Non-code text or trivial commands are ignored.
π― Tactical Alignment Mode
Trigger:Shift + F9
(Tactical Arm)Behavior: Bypasses automatic placement decisions. For every clipboard transaction, it presents an interactive layout allowing you to manually route the patch, select targets, and shift code positions line-by-line.
π State-Lock (Filelock)
Trigger:F8
Behavior: Locks the patcher to a single target file, skipping codebase-wide search routines. Useful when working with multiple files sharing similar method names.
π Integrated LLM Compose Workspace
Trigger:F7
Behavior: A built-in modal text editor replacing external dialog boxes to compose and format LLM requests.Add File/Dir: Select and attach files/directories directly to the prompt.Log Toggle: Attach console logs of failed patch runs to request corrections from the LLM.Custom Instructions: Edit the custom instruction template appended to clipboard payloads.Restore: Recalls the previous session's text and files in the event of an accidental close.
ποΈ Auditing & History Logging
Behavior: WhenCONF_AUDIT_LOG = True
is set, all write operations are recorded:Flat File Audit Log ( Timestamps, target paths, actions, and unified diff previews.ep_patch.log
):JSON Transaction History ( Tracks exact pre- and post-patch states and backup references.ep_history.json
):
π Session-Wide Undo & Redo
Trigger:Ctrl + Z
/Ctrl + Y
Behavior: Non-destructive state engine. Undoing a patch restores the file to its pre-patch state and pushes the change to a forward-history (Redo) stack. Redoing retrieves files from the.redo/
directory.
π Live Diff Viewer Integration
Trigger:F11
Behavior: Connects with the companion utilityep_diff_viewer.exe
to display live side-by-side visual diffs, tracking files before and after modifications.
2. Technical Mechanics (How It Works) #
2.1. Normalization & Sanity Scrubbing
[Raw Clipboard] β [Purge Unicode Garbage] β [Strip Citations & Line Numbers] β [Heal Line-Wraps] β [Extract Code Block]
Click to expand normalization stages
Garbage Character Purging: Converts non-breaking spaces (\xa0
,\u202f
), mathematical spaces, zero-width spaces (\u200b
), byte order marks (\ufeff
), and line separators (\u2028
,\u2029
) into standard spaces or deletes them.Citation Block Removal: Strips web interface citation markers (e.g.,[cite: 1]
,γ4β sourceγ
) to prevent syntax errors.Line Number Deletion: Parses and removes copied line numbers (e.g.,12 | def my_func():
or45: const x = 1
).Line-Wrap Healing: Merges lines that were wrapped mid-statement by web browsers (e.g., lines ending with an open quote followed by an indented line).Text Extraction: Separates conversational text from code blocks using markdown backticks (```) or structural syntax keywords.
2.2. Language Lexing & Syntax Profiles
The patcher uses semantic language mapping to determine how blocks of code are structured. It classifies languages into three profiles:
Indent-Based Profiles*(e.g., Python, Nim, GDScript)*: Uses visual indents to find scope boundaries. It handles decorators (lines starting with@
) and docstrings without breaking the block.Brace-Based Profiles*(e.g., JavaScript, TypeScript, C++, Java, Rust, Go): Uses bracket-counting to find where classes and methods end, making it less dependent on indentation.Keyword-Based Profiles(e.g., Ruby, Lua, Shell)*: Determines scope using keywords likeend
,then
, orfi
.
The Masking Pipeline
To prevent comments or strings from interfering with scope detection (such as a #
inside a string, or a curly brace in a JS template literal), the engine masks these regions:
print("def fake_function():") # This is a comment containing }
print(" ") #
Python Masking: Tracks single-line quotes, multiline triple quotes ("""
and'''
), and line comments. All text inside strings or comments is replaced with spaces in the parser's memory to avoid incorrect matches on class or function definitions.Brace-Based Masking: Tracks block comments (/* ... */
), inline comments (//
), string literals, and template literals, masking them out before the bracket-matching engine evaluates scope depth.
2.3. The Fuzzy Sequence Matching Engine
When a candidate patch is parsed, the engine locates the target area in the file using a weighted similarity calculation:
1. Line Weight Calculation
Trivial lines (like else:
, }
, or return
) are given low weights (1.0). Complex statements containing unique variables, assignments, or method calls are assigned higher weights:
This helps prevent common structural lines from causing false-positive matches.
2. Fuzzy Ratio Mapping & Gap Penalties
Each line in the file is compared against the normalized candidate line. If the engine has to skip lines in the target file to find a match, it applies a gap penalty:
This penalty ensures that if a search block is matched across a widely dispersed set of lines, it is rejected unless an explicit truncation marker (ellipsis) is present.
3. Multi-Match Resolution
If multiple locations return identical high confidence scores:
- For Structured Diffs(Unified or Aider patches), it clamps the match to the location closest to the expected line number to avoid duplicate modifications. - For Drop-In Patches, it applies the modification to all identical locations in reverse order (bottom-to-top) so that file line offsets stay correct.
2.4. Accordion Stitching (Handling Truncation)
If a patch contains placeholders like // ... rest of code
or # existing logic
, the Accordion Stitcher is activated to merge the new code with the old.
TARGET FILE BLOCK TRUNCATED LLM PATCH
+--------------------+ +--------------------+
| def process(): | | def process(): |
| init_env() | | # ... |
| read_data() | =======> | update_val() |
| write_data() | (Stitcher) | # ... |
| clean_up() | +--------------------+
+--------------------+
Hole Detection: Scans for lines matching common truncation indicators (e.g.,...
,ellipsis
,existing logic
,omitted
). - Dominant Indentation Delta: Calculates the difference in indentation between the matching lines in the target file and the patch, using the most common difference to align the rest of the patch:
$$\Delta_{\text{indent}} = \text{Indent}{\text{patch}} - \text{Indent}{\text{file}}$$ -
Anchor Mapping: Matches the code before (Head Anchor) and after (Tail Anchor) the truncation marker to the target file's code. -
Content Restoration: Replaces the truncation markers by pulling the original lines from the target file, adjusting their indentation by$\Delta_{\text{indent}}$ so they line up correctly. -
Inline Truncation Cleanup: Parses, strips comment markers, and normalizes truncation markers written inline at the end of a line (such asimport os # ...
) to ensure clean syntax.
2.5. Safety, Formatting & Code Hygiene Pipelines
[Raw Patch] β [Bracket Parity Check] β [Tab/NBSP Scrub] β [Dupe Resolution] β [Import Hoisting] β [Disk Write]
Bracket Parity Verification: Counts braces, brackets, and parentheses in the modified buffer, logging a console warning if a mismatch is found to help prevent compilation errors.Duplicate Function Resolution: If a patch introduces a function that already exists in the same scope, the patcher identifies both versions, presents a side-by-side comparison in the console, and prompts you to select which version to keep.Import Hoisting: Hoists imports written inline inside the new method bodies to the top of the file, keeping your import statements organized.Vertical Spacing & Tab Normalization:- Converts hard tabs to 4 spaces (configurable).
- Scrubs stray non-breaking spaces.
- Compresses excessive blank lines (more than two consecutive empty lines).
- Ensures a single blank line separates top-level classes and methods.
3. User Workflows & Operational Guides #
3.1. Standard Mode Workflow (Copy-and-Apply)
The standard workflow is designed for quick, hands-off patching:
Launch the Patcher: Openelastic_patcher.exe
. Ensure the console loads your project paths under "Monitoring folder(s)".Arm the System: PressF9
. The status line will change toARMED - Now Monitoring Clipboard
.Generate the Patch: In your AI assistant, request a modification. Copy the resulting code block or diff output.Automatic Processing: The patcher detects the copy event, normalizes the text, identifies the target file, applies the changes in memory, ru...