hash-edit 0.1.0__tar.gz

hash_edit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Siml
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hash_edit-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: hash-edit
+Version: 0.1.0
+Summary: Line-hash anchored read/edit/write for AI coding agents — windowed reads, strict version checks, atomic writes
+Keywords: llm,ai,agent,file-editing,hashline
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/jansiml/hash-edit
+Project-URL: Repository, https://github.com/jansiml/hash-edit
+Description-Content-Type: text/markdown
+
+# hash-edit (Python)
+
+Line-hash anchored read/edit/write for AI coding agents — windowed reads, strict version checks, atomic writes.
+
+## Install
+
+```bash
+pip install hash-edit
+# or
+uv add hash-edit
+```
+
+## Quick start
+
+```python
+from hash_edit import HashEditHarness
+
+h = HashEditHarness("/path/to/project")
+
+# 1. Read — returns rendered lines with hashes and a full-file version digest
+result = h.read("src/app.py")
+# result["version"]  == "4a3f..."
+# result["lines"]    == ["1:ab|import os", "2:cd|", "3:ef|def main(): ..."]
+# result["total_lines"] == 3
+
+# 2. Edit — anchored ops verified against expected_version
+h.edit(
+    "src/app.py",
+    [
+        {"op": "replace", "line": 3, "hash": "ef", "lines": ["def main():", "    pass"]},
+    ],
+    expected_version=result["version"],
+)
+
+# 3. Write — safely create or overwrite; expected_version required when overwriting
+h.write("src/new_file.py", "# new content\n")
+```
+
+## Windowed reads
+
+For large files, pass `start_line` / `end_line` to read only the lines you need (saves 55–87% tokens):
+
+```python
+result = h.read("src/app.py", start_line=100, end_line=150)
+# result["lines"]       — 51 rendered lines, numbered 100–150
+# result["total_lines"] — full file length (e.g. 1 200)
+# result["version"]     — full-file digest, same as a whole-file read
+```
+
+The `version` is always the full-file blake2s digest, so a windowed read still gives you a valid `expected_version` to pass to `edit()`.
+
+## Error classes
+
+| Error | When it is raised |
+|---|---|
+| `VersionConflictError` | The file changed between your last `read()` and the current `edit()` or `write()` |
+| `AnchorMismatchError` | A `hash` field does not match the current line; the error message includes updated rendered context so the agent can retry immediately |
+| `InvalidOperationError` | The edit payload is structurally invalid (missing field, out-of-range line, no-op replace, etc.) |
+| `PathEscapeError` | The requested path resolves outside the configured root directory |
+| `MixedNewlineError` | The file mixes newline styles (`\n`, `\r\n`, `\r`) and is rejected before mutation |
+| `FileEncodingError` | The file cannot be decoded with the configured encoding (UTF-8 by default) |
+
+All six inherit from `HashEditError`.
+
+## Further reading
+
+- [Root README](https://github.com/jansiml/hash-edit#readme) — project overview, TypeScript package, and benchmarks
+- [`docs/spec.md`](https://github.com/jansiml/hash-edit/blob/main/docs/spec.md) — full protocol specification
+- [`docs/INTERFACE_DESIGN.md`](https://github.com/jansiml/hash-edit/blob/main/docs/INTERFACE_DESIGN.md) — design rationale

hash_edit-0.1.0/README.md

@@ -0,0 +1,69 @@
+# hash-edit (Python)
+
+Line-hash anchored read/edit/write for AI coding agents — windowed reads, strict version checks, atomic writes.
+
+## Install
+
+```bash
+pip install hash-edit
+# or
+uv add hash-edit
+```
+
+## Quick start
+
+```python
+from hash_edit import HashEditHarness
+
+h = HashEditHarness("/path/to/project")
+
+# 1. Read — returns rendered lines with hashes and a full-file version digest
+result = h.read("src/app.py")
+# result["version"]  == "4a3f..."
+# result["lines"]    == ["1:ab|import os", "2:cd|", "3:ef|def main(): ..."]
+# result["total_lines"] == 3
+
+# 2. Edit — anchored ops verified against expected_version
+h.edit(
+    "src/app.py",
+    [
+        {"op": "replace", "line": 3, "hash": "ef", "lines": ["def main():", "    pass"]},
+    ],
+    expected_version=result["version"],
+)
+
+# 3. Write — safely create or overwrite; expected_version required when overwriting
+h.write("src/new_file.py", "# new content\n")
+```
+
+## Windowed reads
+
+For large files, pass `start_line` / `end_line` to read only the lines you need (saves 55–87% tokens):
+
+```python
+result = h.read("src/app.py", start_line=100, end_line=150)
+# result["lines"]       — 51 rendered lines, numbered 100–150
+# result["total_lines"] — full file length (e.g. 1 200)
+# result["version"]     — full-file digest, same as a whole-file read
+```
+
+The `version` is always the full-file blake2s digest, so a windowed read still gives you a valid `expected_version` to pass to `edit()`.
+
+## Error classes
+
+| Error | When it is raised |
+|---|---|
+| `VersionConflictError` | The file changed between your last `read()` and the current `edit()` or `write()` |
+| `AnchorMismatchError` | A `hash` field does not match the current line; the error message includes updated rendered context so the agent can retry immediately |
+| `InvalidOperationError` | The edit payload is structurally invalid (missing field, out-of-range line, no-op replace, etc.) |
+| `PathEscapeError` | The requested path resolves outside the configured root directory |
+| `MixedNewlineError` | The file mixes newline styles (`\n`, `\r\n`, `\r`) and is rejected before mutation |
+| `FileEncodingError` | The file cannot be decoded with the configured encoding (UTF-8 by default) |
+
+All six inherit from `HashEditError`.
+
+## Further reading
+
+- [Root README](https://github.com/jansiml/hash-edit#readme) — project overview, TypeScript package, and benchmarks
+- [`docs/spec.md`](https://github.com/jansiml/hash-edit/blob/main/docs/spec.md) — full protocol specification
+- [`docs/INTERFACE_DESIGN.md`](https://github.com/jansiml/hash-edit/blob/main/docs/INTERFACE_DESIGN.md) — design rationale

hash_edit-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "hash-edit"
+version = "0.1.0"
+description = "Line-hash anchored read/edit/write for AI coding agents — windowed reads, strict version checks, atomic writes"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+keywords = ["llm", "ai", "agent", "file-editing", "hashline"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/jansiml/hash-edit"
+Repository = "https://github.com/jansiml/hash-edit"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.4.0",
+  "ruff>=0.12.0",
+  "ty>=0.0.1a6",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["hash_edit"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.ty.environment]
+python-version = "3.11"

hash_edit-0.1.0/src/hash_edit/__init__.py

@@ -0,0 +1,47 @@
+from .core import (
+    DeleteOp,
+    EditOp,
+    EditResult,
+    HashEditHarness,
+    InsertAfterOp,
+    InsertBeforeOp,
+    ReadResult,
+    ReplaceOp,
+    WriteResult,
+    compute_line_hash,
+    render_line,
+    render_lines,
+    strip_render_prefixes,
+)
+from .errors import (
+    AnchorMismatchError,
+    FileEncodingError,
+    HashEditError,
+    InvalidOperationError,
+    MixedNewlineError,
+    PathEscapeError,
+    VersionConflictError,
+)
+
+__all__ = [
+    "AnchorMismatchError",
+    "DeleteOp",
+    "EditOp",
+    "EditResult",
+    "FileEncodingError",
+    "HashEditError",
+    "HashEditHarness",
+    "InsertAfterOp",
+    "InsertBeforeOp",
+    "InvalidOperationError",
+    "MixedNewlineError",
+    "PathEscapeError",
+    "ReadResult",
+    "ReplaceOp",
+    "VersionConflictError",
+    "WriteResult",
+    "compute_line_hash",
+    "render_line",
+    "render_lines",
+    "strip_render_prefixes",
+]

hash_edit-0.1.0/src/hash_edit/core.py

@@ -0,0 +1,532 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import stat
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, NotRequired, TypeAlias, TypedDict, cast
+
+from .errors import (
+    AnchorMismatchError,
+    FileEncodingError,
+    InvalidOperationError,
+    MixedNewlineError,
+    PathEscapeError,
+    VersionConflictError,
+)
+
+DEFAULT_ENCODING = "utf-8"
+DEFAULT_HASH_LENGTH = 2
+UTF8_BOM = b"\xef\xbb\xbf"
+NEWLINE_RE = re.compile(r"\r\n|\n|\r")
+PREFIX_RE = re.compile(r"^\s*\d+:[0-9a-f]{2,}\|")
+
+NewlineStyle = Literal["lf", "crlf", "cr", "none"]
+
+
+class ReplaceOp(TypedDict):
+    op: Literal["replace"]
+    line: int
+    hash: str
+    lines: list[str]
+    end_line: NotRequired[int]
+    end_hash: NotRequired[str]
+
+
+class InsertBeforeOp(TypedDict):
+    op: Literal["insert_before"]
+    line: int
+    hash: str
+    lines: list[str]
+
+
+class InsertAfterOp(TypedDict):
+    op: Literal["insert_after"]
+    line: int
+    hash: str
+    lines: list[str]
+
+
+class DeleteOp(TypedDict):
+    op: Literal["delete"]
+    line: int
+    hash: str
+    end_line: NotRequired[int]
+    end_hash: NotRequired[str]
+
+
+EditOp: TypeAlias = ReplaceOp | InsertBeforeOp | InsertAfterOp | DeleteOp
+
+
+class ReadResult(TypedDict):
+    path: str
+    version: str
+    encoding: str
+    bom: bool
+    newline: NewlineStyle
+    has_final_newline: bool
+    hash_length: int
+    total_lines: int
+    start_line: int
+    end_line: int
+    lines: list[str]
+
+
+class EditResult(TypedDict):
+    path: str
+    version_before: str
+    version_after: str
+    applied: int
+    first_changed_line: int | None
+    encoding: str
+    bom: bool
+    newline: NewlineStyle
+    has_final_newline: bool
+    total_lines: int
+
+
+class WriteResult(TypedDict):
+    path: str
+    version_after: str
+    created: bool
+    encoding: str
+    bom: bool
+    newline: NewlineStyle
+    has_final_newline: bool
+    total_lines: int
+
+
+@dataclass(frozen=True)
+class _Snapshot:
+    path: str
+    version: str
+    encoding: str
+    bom: bool
+    newline: NewlineStyle
+    has_final_newline: bool
+    lines: list[str]
+
+    @property
+    def total_lines(self) -> int:
+        return len(self.lines)
+
+
+def _newline_separator(style: NewlineStyle) -> str:
+    if style == "lf":
+        return "\n"
+    if style == "crlf":
+        return "\r\n"
+    if style == "cr":
+        return "\r"
+    return "\n"
+
+
+def _detect_newline_style(text: str) -> tuple[NewlineStyle, bool, list[str]]:
+    matches = NEWLINE_RE.findall(text)
+    unique = set(matches)
+    if len(unique) > 1:
+        raise MixedNewlineError(f"Mixed newline styles detected: {sorted(unique)}")
+    if not matches:
+        return ("none", False, [] if text == "" else [text])
+    separator = matches[0]
+    _newline_map: dict[str, NewlineStyle] = {"\n": "lf", "\r\n": "crlf", "\r": "cr"}
+    style: NewlineStyle = _newline_map[separator]
+    has_final_newline = text.endswith(separator)
+    lines = text.split(separator)
+    if has_final_newline:
+        lines = lines[:-1]
+    return style, has_final_newline, lines
+
+
+def _join_text(lines: list[str], newline: NewlineStyle, has_final_newline: bool) -> str:
+    if not lines:
+        return ""
+    separator = _newline_separator(newline)
+    text = separator.join(lines)
+    if has_final_newline:
+        text += separator
+    return text
+
+
+def _version_for_bytes(data: bytes) -> str:
+    return hashlib.blake2s(data, digest_size=16).hexdigest()
+
+
+def compute_line_hash(
+    line_number: int, text: str, hash_length: int = DEFAULT_HASH_LENGTH
+) -> str:
+    if hash_length < 2:
+        raise ValueError("hash_length must be >= 2")
+    normalized = text.replace("\r", "").rstrip()
+    material = normalized
+    if not any(character.isalnum() for character in normalized):
+        material = f"{line_number}\0{normalized}"
+    return hashlib.blake2s(
+        material.encode(DEFAULT_ENCODING), digest_size=16
+    ).hexdigest()[:hash_length]
+
+
+def render_line(
+    line_number: int, text: str, hash_length: int = DEFAULT_HASH_LENGTH
+) -> str:
+    return f"{line_number}:{compute_line_hash(line_number, text, hash_length)}|{text}"
+
+
+def render_lines(
+    lines: list[str], start_line: int = 1, hash_length: int = DEFAULT_HASH_LENGTH
+) -> list[str]:
+    return [
+        render_line(start_line + offset, line, hash_length)
+        for offset, line in enumerate(lines)
+    ]
+
+
+def strip_render_prefixes(lines: list[str]) -> list[str]:
+    non_empty = [line for line in lines if line != ""]
+    if non_empty and all(PREFIX_RE.match(line) for line in non_empty):
+        return [PREFIX_RE.sub("", line, count=1) for line in lines]
+    return list(lines)
+
+
+def _message_for_mismatches(
+    path: str,
+    lines: list[str],
+    hash_length: int,
+    mismatches: list[dict[str, str | int]],
+) -> str:
+    display_lines: set[int] = set()
+    for mismatch in mismatches:
+        line_number = int(mismatch["line"])
+        for current in range(
+            max(1, line_number - 2), min(len(lines), line_number + 2) + 1
+        ):
+            display_lines.add(current)
+    rendered: list[str] = [
+        f"Anchors are stale in {path}. Re-read the file and use the updated rendered lines below."
+    ]
+    if not display_lines:
+        return "\n".join(rendered)
+    rendered.append("")
+    mismatch_map = {int(mismatch["line"]): mismatch for mismatch in mismatches}
+    previous = -1
+    for line_number in sorted(display_lines):
+        if previous != -1 and line_number > previous + 1:
+            rendered.append("    ...")
+        prefix = ">>> " if line_number in mismatch_map else "    "
+        rendered.append(
+            prefix + render_line(line_number, lines[line_number - 1], hash_length)
+        )
+        previous = line_number
+    return "\n".join(rendered)
+
+
+class HashEditHarness:
+    def __init__(
+        self,
+        root: str | Path = ".",
+        *,
+        default_encoding: str = DEFAULT_ENCODING,
+        hash_length: int = DEFAULT_HASH_LENGTH,
+    ) -> None:
+        self._root = Path(root).resolve()
+        self._default_encoding = default_encoding
+        self._hash_length = hash_length
+
+    def _resolve_path(self, path: str) -> Path:
+        candidate = Path(path)
+        if not candidate.is_absolute():
+            candidate = self._root / candidate
+        resolved = candidate.resolve()
+        try:
+            resolved.relative_to(self._root)
+        except ValueError as error:
+            raise PathEscapeError(f"{path} escapes root {self._root}") from error
+        return resolved
+
+    def _read_snapshot(self, path: Path) -> _Snapshot:
+        raw = path.read_bytes()
+        version = _version_for_bytes(raw)
+        bom = raw.startswith(UTF8_BOM)
+        payload = raw[len(UTF8_BOM) :] if bom else raw
+        try:
+            text = payload.decode(self._default_encoding, errors="strict")
+        except UnicodeDecodeError as error:
+            raise FileEncodingError(
+                f"{path.name} is not valid {self._default_encoding}"
+            ) from error
+        newline, has_final_newline, lines = _detect_newline_style(text)
+        return _Snapshot(
+            path=str(path.relative_to(self._root)),
+            version=version,
+            encoding=self._default_encoding,
+            bom=bom,
+            newline=newline,
+            has_final_newline=has_final_newline,
+            lines=lines,
+        )
+
+    def _write_snapshot(
+        self,
+        path: Path,
+        *,
+        lines: list[str],
+        bom: bool,
+        newline: NewlineStyle,
+        has_final_newline: bool,
+    ) -> str:
+        text = _join_text(lines, newline, has_final_newline)
+        payload = text.encode(self._default_encoding)
+        if bom:
+            payload = UTF8_BOM + payload
+
+        temporary_path: str | None = None
+        existing_mode = None
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists():
+            existing_mode = stat.S_IMODE(path.stat().st_mode)
+
+        try:
+            handle, temporary_path = tempfile.mkstemp(
+                prefix=f".{path.name}.", dir=path.parent
+            )
+            with os.fdopen(handle, "wb") as file_handle:
+                file_handle.write(payload)
+            if existing_mode is not None:
+                os.chmod(temporary_path, existing_mode)
+            os.replace(temporary_path, path)
+        finally:
+            if temporary_path and os.path.exists(temporary_path):
+                os.unlink(temporary_path)
+
+        return _version_for_bytes(payload)
+
+    def read(
+        self, path: str, *, start_line: int | None = None, end_line: int | None = None
+    ) -> ReadResult:
+        resolved = self._resolve_path(path)
+        snapshot = self._read_snapshot(resolved)
+
+        if snapshot.total_lines == 0:
+            return {
+                "path": snapshot.path,
+                "version": snapshot.version,
+                "encoding": snapshot.encoding,
+                "bom": snapshot.bom,
+                "newline": snapshot.newline,
+                "has_final_newline": snapshot.has_final_newline,
+                "hash_length": self._hash_length,
+                "total_lines": 0,
+                "start_line": 0,
+                "end_line": 0,
+                "lines": [],
+            }
+
+        first = 1 if start_line is None else start_line
+        last = snapshot.total_lines if end_line is None else end_line
+        if first < 1 or last < first or last > snapshot.total_lines:
+            raise InvalidOperationError(
+                f"Invalid read window for {snapshot.path}: start_line={first}, end_line={last}, total_lines={snapshot.total_lines}"
+            )
+        visible = snapshot.lines[first - 1 : last]
+        return {
+            "path": snapshot.path,
+            "version": snapshot.version,
+            "encoding": snapshot.encoding,
+            "bom": snapshot.bom,
+            "newline": snapshot.newline,
+            "has_final_newline": snapshot.has_final_newline,
+            "hash_length": self._hash_length,
+            "total_lines": snapshot.total_lines,
+            "start_line": first,
+            "end_line": last,
+            "lines": render_lines(visible, first, self._hash_length),
+        }
+
+    def edit(
+        self, path: str, ops: EditOp | list[EditOp], *, expected_version: str
+    ) -> EditResult:
+        resolved = self._resolve_path(path)
+        snapshot = self._read_snapshot(resolved)
+        if expected_version != snapshot.version:
+            raise VersionConflictError(
+                snapshot.path, expected_version, snapshot.version
+            )
+
+        operations = [ops] if isinstance(ops, dict) else list(ops)
+        if not operations:
+            raise InvalidOperationError("edit() requires at least one operation")
+
+        lines = list(snapshot.lines)
+        mismatches: list[dict[str, str | int]] = []
+
+        def validate_anchor(line_number: int, expected_hash: str) -> None:
+            if line_number < 1 or line_number > len(lines):
+                raise InvalidOperationError(
+                    f"Line {line_number} is out of range for {snapshot.path} (total_lines={len(lines)})"
+                )
+            actual_hash = compute_line_hash(
+                line_number, lines[line_number - 1], self._hash_length
+            )
+            if actual_hash != expected_hash:
+                mismatches.append(
+                    {
+                        "line": line_number,
+                        "expected": expected_hash,
+                        "actual": actual_hash,
+                    }
+                )
+
+        for operation in operations:
+            validate_anchor(int(operation["line"]), str(operation["hash"]))
+            if "end_line" in operation:
+                range_op = cast("ReplaceOp | DeleteOp", operation)
+                end_line = int(range_op["end_line"])
+                end_hash = str(range_op.get("end_hash", ""))
+                if not end_hash:
+                    raise InvalidOperationError("Range edits require end_hash")
+                validate_anchor(end_line, end_hash)
+                if int(operation["line"]) > end_line:
+                    raise InvalidOperationError("end_line must be >= line")
+
+        if mismatches:
+            raise AnchorMismatchError(
+                _message_for_mismatches(
+                    snapshot.path, lines, self._hash_length, mismatches
+                ),
+                mismatches=mismatches,
+            )
+
+        def sort_key(operation: EditOp) -> tuple[int, int]:
+            range_op = cast("ReplaceOp | DeleteOp", operation)
+            end_line_val = range_op.get("end_line", operation["line"])
+            line_number = int(end_line_val)
+            precedence = {
+                "replace": 0,
+                "delete": 0,
+                "insert_after": 1,
+                "insert_before": 2,
+            }[operation["op"]]
+            return (-line_number, precedence)
+
+        first_changed_line: int | None = None
+        for operation in sorted(operations, key=sort_key):
+            line_number = int(operation["line"])
+            op_name = operation["op"]
+            if op_name == "replace":
+                replace_op = cast("ReplaceOp", operation)
+                replacement = strip_render_prefixes(list(replace_op["lines"]))
+                end_line = int(replace_op.get("end_line", line_number))
+                current = lines[line_number - 1 : end_line]
+                if current == replacement:
+                    raise InvalidOperationError(
+                        f"No changes made to {snapshot.path}. Replacement for {line_number}:{replace_op['hash']} is identical."
+                    )
+                lines[line_number - 1 : end_line] = replacement
+                first_changed_line = (
+                    line_number
+                    if first_changed_line is None
+                    else min(first_changed_line, line_number)
+                )
+            elif op_name == "delete":
+                delete_op = cast("DeleteOp", operation)
+                end_line = int(delete_op.get("end_line", line_number))
+                del lines[line_number - 1 : end_line]
+                first_changed_line = (
+                    line_number
+                    if first_changed_line is None
+                    else min(first_changed_line, line_number)
+                )
+            elif op_name == "insert_before":
+                insert_before_op = cast("InsertBeforeOp", operation)
+                inserted = strip_render_prefixes(list(insert_before_op["lines"]))
+                if not inserted:
+                    inserted = [""]
+                lines[line_number - 1 : line_number - 1] = inserted
+                first_changed_line = (
+                    line_number
+                    if first_changed_line is None
+                    else min(first_changed_line, line_number)
+                )
+            elif op_name == "insert_after":
+                insert_after_op = cast("InsertAfterOp", operation)
+                inserted = strip_render_prefixes(list(insert_after_op["lines"]))
+                if not inserted:
+                    inserted = [""]
+                insertion_line = line_number + 1
+                lines[line_number:line_number] = inserted
+                first_changed_line = (
+                    insertion_line
+                    if first_changed_line is None
+                    else min(first_changed_line, insertion_line)
+                )
+            else:
+                raise InvalidOperationError(f"Unsupported op {op_name}")
+
+        version_after = self._write_snapshot(
+            resolved,
+            lines=lines,
+            bom=snapshot.bom,
+            newline=snapshot.newline,
+            has_final_newline=snapshot.has_final_newline,
+        )
+        return {
+            "path": snapshot.path,
+            "version_before": snapshot.version,
+            "version_after": version_after,
+            "applied": len(operations),
+            "first_changed_line": first_changed_line,
+            "encoding": snapshot.encoding,
+            "bom": snapshot.bom,
+            "newline": snapshot.newline,
+            "has_final_newline": snapshot.has_final_newline,
+            "total_lines": len(lines),
+        }
+
+    def write(
+        self, path: str, text: str, *, expected_version: str | None = None
+    ) -> WriteResult:
+        resolved = self._resolve_path(path)
+        created = not resolved.exists()
+
+        input_newline, input_has_final_newline, input_lines = _detect_newline_style(
+            text
+        )
+        bom = False
+        newline = input_newline
+        if created:
+            version_after = self._write_snapshot(
+                resolved,
+                lines=input_lines,
+                bom=False,
+                newline=input_newline,
+                has_final_newline=input_has_final_newline,
+            )
+        else:
+            snapshot = self._read_snapshot(resolved)
+            if expected_version != snapshot.version:
+                raise VersionConflictError(
+                    snapshot.path, expected_version, snapshot.version
+                )
+            bom = snapshot.bom
+            newline = snapshot.newline if snapshot.newline != "none" else input_newline
+            version_after = self._write_snapshot(
+                resolved,
+                lines=input_lines,
+                bom=bom,
+                newline=newline,
+                has_final_newline=input_has_final_newline,
+            )
+
+        return {
+            "path": str(resolved.relative_to(self._root)),
+            "version_after": version_after,
+            "created": created,
+            "encoding": self._default_encoding,
+            "bom": bom,
+            "newline": newline,
+            "has_final_newline": input_has_final_newline,
+            "total_lines": len(input_lines),
+        }

hash_edit-0.1.0/src/hash_edit/errors.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+
+class HashEditError(Exception):
+    """Base error for hash-edit failures."""
+
+
+class PathEscapeError(HashEditError):
+    """Raised when a requested path escapes the configured root."""
+
+
+class MixedNewlineError(HashEditError):
+    """Raised when a file mixes newline styles."""
+
+
+class FileEncodingError(HashEditError):
+    """Raised when a file cannot be decoded with the configured encoding."""
+
+
+class InvalidOperationError(HashEditError):
+    """Raised when an edit payload is invalid or a no-op."""
+
+
+class VersionConflictError(HashEditError):
+    """Raised when the file version does not match the caller's expectation."""
+
+    def __init__(self, path: str, expected: str | None, actual: str) -> None:
+        if expected is None:
+            message = f"{path} already exists. read() first and pass expected_version to overwrite safely."
+        else:
+            message = f"Version conflict for {path}: expected {expected}, actual {actual}. Re-read the file first."
+        super().__init__(message)
+        self.path = path
+        self.expected = expected
+        self.actual = actual
+
+
+class AnchorMismatchError(HashEditError):
+    """Raised when one or more anchored lines have changed or were copied incorrectly."""
+
+    def __init__(self, message: str, *, mismatches: list[dict[str, str | int]]) -> None:
+        super().__init__(message)
+        self.mismatches = mismatches