Hashline Edit Engine

The Hashline Edit Engine is the core deterministic file manipulation system within the plugsuits project. It is designed to provide stale-safe, surgical modifications to source code by using line-anchored operations combined with cryptographic verification. Unlike traditional text-matching or offset-based editing, the Hashline engine ensures that edits are only applied if the target content remains exactly as the agent last observed it.

The engine facilitates three primary operations—replace, append, and prepend—and utilizes a specific anchor format ({line_number}#{hash_id}) to uniquely identify lines within a file. This architecture allows the agent to maintain high synchronization with the file system, even when files are being modified across multiple turns.
Sources: README.md:14-25, packages/cea/src/tools/modify/AGENTS.md:11-13, packages/cea/src/tools/modify/edit-file.ts:16-20

Core Architecture and Data Flow

The engine operates through a multi-stage pipeline that validates the current state of the file, repairs malformed inputs from the model, and applies deterministic transformations.

The flow above illustrates the safety-first approach where global file hashes are checked before any line-level mutations occur.
Sources: packages/cea/src/tools/modify/edit-file.ts:153-205, packages/cea/src/tools/modify/edit-file-validation.ts:145-162

Hashline Anchors

The system uses a unique anchor format for deterministic targeting:

• Format: {line_number}#{hash_id} (e.g., 42#VK).
• Hash Computation: Each line's hash is derived from its content, allowing the engine to detect if a line has moved or changed since it was last read.
• Noisy Input Handling: The engine is resilient to noisy prefixes (like >>>) and pipe-delimited content (like 12#ZP|content) often generated by models.
  Sources: packages/cea/src/tools/utils/hashline/validation.test.ts:13-52, packages/cea/src/tools/modify/edit-file.test.ts:47-60

Key Components and Logic

1. Verification and Safety

The engine implements multiple layers of protection to prevent data corruption and unauthorized file access.

Sources: packages/cea/src/tools/modify/edit-file.ts:156-180, packages/cea/src/tools/modify/edit-file-validation.ts:158-171, packages/cea/src/tools/modify/edit-file.test.ts:717-750

2. Validation and Auto-Repair

Models occasionally produce malformed tool calls. The engine includes a specialized repair layer to correct common syntax errors.

The repair logic can extract code content from anchors that include XML markup, Python dictionary syntax, or query-string parameters.
Sources: packages/cea/src/tools/modify/edit-file.test.ts:468-580, packages/cea/src/tools/modify/edit-file-validation.ts:114-142

3. Operation Types

The engine supports three fundamental operations, which are applied from the bottom of the file upwards to maintain line number stability during batch edits.

• Replace: Swaps a line or a range of lines (defined by pos and end) with new content. Providing an empty array or null results in deletion.
• Append: Inserts lines after the anchored position.
• Prepend: Inserts lines before the anchored position.
  Sources: packages/cea/src/tools/modify/edit-file.ts:25-45, packages/cea/src/tools/utils/hashline/edit-operations.test.ts:11-30

Implementation Details

Diagnostic Escalation

To assist models that repeatedly fail to provide the correct format, the engine tracks failures and escalates the detail in error messages. After a threshold (e.g., 3 failures), it provides specific hints containing the expected line content. If failures continue (e.g., 6+), it triggers a "soft-reject" suggesting the use of write_file instead.
Sources: packages/cea/src/tools/modify/edit-file.test.ts:600-705, packages/cea/src/tools/modify/edit-file-validation.ts:20-35

Deterministic Application

The engine uses the following internal workflow for applying edits:

1. Canonicalization: Normalizes line endings (CRLF vs LF) before processing.
2. Deduplication: Automatically removes semantically identical edits in a single batch.
3. Conflict Detection: Identifies overlapping range edits and throws errors if multiple operations target the same line segments.
   Sources: packages/cea/src/tools/modify/edit-file.ts:175-190, packages/cea/src/tools/utils/hashline/edit-operations.test.ts:45-55, packages/cea/src/tools/utils/hashline/edit-operations.test.ts:125-145

Conclusion

The Hashline Edit Engine represents a robust solution for AI-driven code modification. By combining line-level hashing with global file verification and a resilient repair layer, it bridges the gap between non-deterministic model outputs and the strict requirements of source code integrity. This system ensures that even complex, multi-line refactors remain safe and accurate across extended agent sessions.