intact 0.7.1__py3-none-any.whl

intact-0.7.1.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.3
+Name: intact
+Version: 0.7.1
+Summary: A reconciliation ladder that heals stale or drifted edits instead of failing them, with atomic multi-file transactions, patch ingestion, undo, durable anchors, and an LSP client — as a library, a CLI, and an MCP server.
+Author: Robb Doering
+Author-email: Robb Doering <robb@doering.ai>
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Pydantic :: 2
+Classifier: Typing :: Typed
+Requires-Dist: fastmcp>=3.4.0 ; extra == 'mcp'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://gitlab.com/doering-ai/libs/tact
+Project-URL: Source, https://gitlab.com/doering-ai/libs/tact
+Project-URL: Issues, https://gitlab.com/doering-ai/libs/tact/-/issues
+Project-URL: Documentation, https://intact.readthedocs.io
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# intact: _Self-Healing File Edits for Agents_
+
+![Pipeline Status](https://img.shields.io/gitlab/pipeline-status/doering-ai/libs/tact?branch=main) ![Test Coverage](https://img.shields.io/gitlab/pipeline-coverage/doering-ai/libs/tact?branch=main) [![License](https://img.shields.io/gitlab/license/doering-ai/libs/tact)](/LICENSE) [![Documentation](https://app.readthedocs.org/projects/intact/badge)](https://intact.readthedocs.io) ![Python Version](https://img.shields.io/pypi/pyversions/intact) [![PyPI Wheel](https://img.shields.io/pypi/wheel/intact)](https://pypi.org/project/intact) [![PyPI Types](https://img.shields.io/pypi/types/intact)](https://pypi.org/project/intact)
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![version](https://img.shields.io/badge/version-0.7.1-blue)](https://gitlab.com/doering-ai/corpus/-/blob/main/policies/versioning.md) [![pyrefly](https://img.shields.io/endpoint?url=https://pyrefly.org/badge.json)](https://github.com/facebook/pyrefly) [![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+> A reconciliation ladder that heals stale or drifted edits instead of failing them, with atomic multi-file transactions, patch ingestion, undo, durable anchors, and an LSP client — as a library, a CLI, and an MCP server.
+
+> [!NOTE] **Genesis.** `intact` was designed, built, reviewed, and shipped end-to-end by **Claude (Fable 5)** as an autonomous long-run engineering experiment — from mining two weeks of real agent-session ledgers for the failure class worth killing, through a fleet of builder/critic subagents and adversarial review rounds, to the benchmark, the extraction, and this release.
+> The human operator set the charter, held the release gates, and found the name.
+> The eval numbers below are measured on that same fleet's real failures — this package was built by the population it serves.
+
+______________________________________________________________________
+
+## The problem, measured
+
+An independent audit of two weeks of this fleet's own Claude Code session ledgers found that the single largest *recurring* cost line wasn't a wrong answer or a slow model — it was harness friction: an agent's builtin `Edit` tool failing an exact-string match against text that had drifted underneath it (formatter passes, a stale read, whitespace normalization), 99 instances totaling roughly 190K tokens over the window, each one paid as a full read-diff-retry round trip.
+`tact` exists to kill that class of failure at the source: it heals what's mechanical (whitespace, Unicode punctuation, indentation shift, small textual drift) through a symbolic, self-reporting reconciliation ladder, and it refuses loudly — never silently — the moment a match is genuinely ambiguous or absent, because a wrong guess in a file edit is worse than an honest failure.
+It ships as a library, a CLI, and an MCP server, so the same reconciliation core backs whichever front end a given agent harness actually calls.
+
+## Install
+
+```bash
+pip install intact
+# or
+uv add intact
+```
+
+The CLI and library work with no extras.
+The MCP server needs the `mcp` extra:
+
+```bash
+uv add "intact[mcp]"
+```
+
+## 60-second quickstart
+
+### As a library
+
+```python
+from tact import read_file, apply_edits, Edit
+
+r = read_file('config.py')
+apply_edits(
+    'config.py',
+    [Edit(old='DEBUG = True', new='DEBUG = False')],
+    expected_sha256=r.sha256,  # advisory -- a mismatch heals, it never blocks
+)
+```
+
+### As a CLI
+
+```bash
+# a builtin exact-match Edit just failed -- heal it in one round trip
+uv run tact heal config.py --old "DEBUG = True" --new "DEBUG = False"
+
+# or drive the whole read -> edit cycle through tact directly
+uv run tact --json edit config.py --old "DEBUG = True" --new "DEBUG = False"
+```
+
+### As an MCP server
+
+Register `tact` (adapt the project path for your own install):
+
+```bash
+uv run --extra mcp --project /path/to/tact tact-mcp
+```
+
+Then call `tact_edit`/`tact_heal`/`tact_definition`/… as MCP tools instead of the harness's builtin Read/Edit.
+See `docs/howto.md` for per-harness registration snippets (Claude Code, Droid, Codex, Cursor).
+
+## The reconciliation ladder
+
+`find_block` descends five rungs of mounting tolerance, stopping at the *finest* rung that yields a **unique** match:
+
+| Rung     | What it forgives                                    | Example                                        |
+| -------- | --------------------------------------------------- | ---------------------------------------------- |
+| `EXACT`  | Nothing — verbatim line equality                    | `old_string` matches byte-for-byte             |
+| `CANON`  | Unicode punctuation substitution                    | a curly `"quote"` pasted in for a straight one |
+| `RSTRIP` | Trailing whitespace drift                           | a formatter stripped trailing spaces on save   |
+| `INDENT` | A uniform leading-whitespace shift                  | the block moved one indent level deeper        |
+| `FUZZY`  | Small textual drift, bounded by per-line similarity | a stale line number after a nearby edit landed |
+
+Two or more candidates at any rung is a **structured ambiguity refusal** (every candidate shown, resolved only by a `--near` hint); zero candidates at every rung is a **structured no-match refusal**.
+Rungs 1-4 are true equivalence relations; rung 5 is a similarity ball, not transitive — which is exactly why ambiguity-handling concentrates there.
+See `docs/explanation.md` for the full framing.
+
+## The numbers
+
+Replayed against the fleet's own real edit-failure history (`tact.eval`, ledger-mined, no `near` hint supplied — any multi-candidate rung is a refusal, never a guess):
+
+| Corpus                                     | Cases | Healed | False heals | Correct refusals |
+| ------------------------------------------ | ----- | ------ | ----------- | ---------------- |
+| Public subset (this repo, `tests/`)        | 59    | 43     | 0           | 1                |
+| Full private fleet corpus (eval-of-record) | 111   | 68     | 0           | 1                |
+
+The public subset is a privacy-reviewed 59-fixture slice of the full 121-fixture harvest (62 fixtures held back for operator-stack detail or private prose, not for reconciliation performance — see `tests/fixtures/ledger_eval/README.md` for the curation).
+Cases that don't heal are mostly `no_match`, not misses: a large share are `modified_since_read` failures where the stored file snapshot legitimately predates the real edit, so a refusal there is reality reflected correctly, not a ladder weakness.
+
+## Features
+
+- **`check`/`edit`** — resolve-then-atomically-write a batch of edits, with a dry-run twin (`check_edits`) that previews without touching the file.
+- **`apply_many` transactions** — resolve every file in a batch before writing any of them; any failure blocks the whole transaction, nothing partial is ever written.
+- **`heal`** — fix a failed builtin `Edit(path, old_string, new_string)` in one read-only round trip.
+- **`undo`** — a content-addressed pre-image journal behind every write, with a redoable `undo` verb.
+- **Durable anchors** — capture a block's position so it survives a session/compaction boundary; `resolve_anchor` re-finds it, biased by its own remembered index.
+- **`delta`/`read_since`** — a cheap "what changed since this hash" re-read, backed by the undo journal's blob store.
+- **`rename_symbol`** — LSP-computed cross-file renames, converted into one `apply_many` transaction (the one verb that is not LSP-optional).
+- **`apply_patch`** — ingest a unified diff or a fenced old/new block pair straight into an `Edit` batch.
+- **LSP navigation** — `def`/`refs`/`hover`/`sym`/`diag`, name-first, backed by a persistent, resilient pyrefly/ruff client.
+
+## Honest limits
+
+`tact` matches line-by-line, so a paragraph reflow (a prose formatter that rewraps text across different line boundaries) is not a whitespace/indent variant it heals — expect a no-match refusal and a manual re-read there.
+Ambiguity refusals need a `--near` hint or a more distinctive block; tact will not pick a near-tie for you.
+`rename_symbol` is LSP-backed only — it never falls back to a textual find-replace, since that risks renaming the wrong binding, so it structurally refuses when no live LSP is available.
+The undo journal keeps the newest 32 pre-images per file and is index-pruned, not globally garbage-collected — it is acceptable-loss state, not a full version history.
+
+## Provenance
+
+The reconciliation ladder's canonicalization table and fuzzy-matching primitives in `tact/reconcile.py` are a port, with attribution, of parts of [`dirac`](https://github.com/dirac-run/dirac) (Apache-2.0, version 0.4.11) — see `NOTICE` and `reconcile.py`'s own module docstring for exactly what was ported and how it was adapted.
+
+## License
+
+Apache-2.0.
+See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
+
+______________________________________________________________________
+
+## Versioning
+
+This project follows [workflow-gated semver]: the minor version records the highest-completed `py-workflow` step (`0.1.0`-`0.8.0`), with `0.9.0` (beta) gated on >=9 external users and `1.0.0` on a maintainer social guarantee.
+The current version `0.7.0` means gate `7` is the highest cleared.
+See the [normative rubric](https://gitlab.com/doering-ai/corpus/-/blob/main/policies/versioning.md) and the [overview](https://gitlab.com/doering-ai/corpus/-/blob/main/docs/versioning.md).
+
+[workflow-gated semver]: https://gitlab.com/doering-ai/corpus/-/blob/main/docs/versioning.md

intact-0.7.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+tact/README.md,sha256=FvEdE1mzj9BQ1RM4OvDbnS1Jrv-AuN03aaMeu62y5ss,196
+tact/__init__.py,sha256=SAbEwFKkM1z-ddicxJpg7ZJG8J-ujwxAl-h3CcW2QEQ,4964
+tact/_home.py,sha256=K-Cr4H0YZHLyLjVyGQYxaxuEuf_yPdsH_kGoPYdB4WU,1110
+tact/_io.py,sha256=oNtq0CQ0XedaADSpZEjKgYC6rwcwLZJV4Iyulb5zy78,3418
+tact/_serialize.py,sha256=wwUiYd4dGvmxcl1p1t-yoTzWj9D14ewYJs8Tfd1t2RE,2386
+tact/anchor.py,sha256=8104f9dfCmH2z8C8l7_AiCq0Jd0HjROmy_FrWQXKhNw,12781
+tact/apply.py,sha256=Um2O03iqdACOhPGDvuWlDAL4M6qGnPDg1oPa-YQRcIc,25316
+tact/cli.py,sha256=aYTPFRJ96nkRF8yZ6GPMPk8gj19KkqD-7PJns0dBMtY,24129
+tact/delta.py,sha256=lEGTx_lG36Q8_Jiwy2_aHaaMkByV-W44YjuMpGxZnu4,6930
+tact/eval.py,sha256=y9zMdS4ZjtpVY5BQ7tugyq4yoGRvjeJnBIlgo87WzcM,15967
+tact/heal.py,sha256=-Za29GvQ-wv8_BOLjIiQ2lWcUom9vghwzHdhPq9K_Iw,9297
+tact/lsp.py,sha256=H5Akm7PmDcpMfFTPwvMqEYaBSVKBt1Yuy6QczDnfKYU,38988
+tact/mcp_server.py,sha256=TlHZur2lAbaBZpg5bpodXYBNykHo0QSYBFetbbI6Upw,13994
+tact/patch.py,sha256=ZMXBySncz_357-xDlX1mjVYt1x3yLHwQHRiTt5gbNoE,16108
+tact/read.py,sha256=QoloIxW0IqK5qO07H4eWCS641EUbOcn9fJjnzufT8B8,9494
+tact/reconcile.py,sha256=C8iJcUVJqXTYtEYL8KXCdn2dEBHITmBmQXvahcAjgqA,17560
+tact/rename.py,sha256=RMFQ-QLmQFC-qIC0dx3Xq8ThUp0dRgZUdpzRcV-fjmg,16001
+tact/skeleton.py,sha256=6IUu5bPRe-mHZJaq490e7e0YQ-T-KY8-qf1Qvbmrmgc,4465
+tact/telemetry.py,sha256=040K6DQftWlqUN0jVXJGY6hRA5o2aywIR4oBDtkfJRA,2721
+tact/transact.py,sha256=ovsp_ORG14JKn9cy1oZnLNJhJ28JB5_7a7t7kTydRxg,14543
+tact/undo.py,sha256=qvqZ4xOjIxzAM68dSBnWivLjXGfFLjy--fQZv4G4SVQ,13620
+intact-0.7.1.dist-info/WHEEL,sha256=jK0lbM7sVtq70msNoYotEXYS3OJMDdns2CRgyjhimnE,81
+intact-0.7.1.dist-info/entry_points.txt,sha256=fbx5CMh15qEbCT6yKgk9rdCFs09jZgpEjG6DJxJIC0k,72
+intact-0.7.1.dist-info/METADATA,sha256=yLXQWnQPEA8HEGj3D4at8Xn71EJ6WsbLROoDFg8gC_Y,10582
+intact-0.7.1.dist-info/RECORD,,

intact-0.7.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.25
+Root-Is-Purelib: true
+Tag: py3-none-any

intact-0.7.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+tact = tact.cli:main
+tact-mcp = tact.mcp_server:main
+

tact/README.md

@@ -0,0 +1,3 @@
+# `tact` Python Package
+This document is a high-level overview of the engineering decisions behind the tact Python package. 
+For general project information, see [the root directory](/README.md).

tact/__init__.py

@@ -0,0 +1,133 @@
+"""`tact` (Latin *tactus*, touch) — a self-healing write core for agent file edits.
+
+Agents that read a file, decide on an edit, and write it back are routinely defeated by
+turbulence that has nothing to do with the edit's substance: trailing-whitespace drift,
+curly-quote/dash/NBSP substitutions introduced by a copy-paste, an indentation shift from a
+block moving a level deeper, or a stale line number after a concurrent edit landed first.
+Builtin exact-match editors hard-fail on all of these and hand the turbulence back to the
+model as a diff to re-derive — expensive, and it happens on every file, every day.
+
+`tact` handles this in library, not in every agent's context: `reconcile` finds a target
+block under a fixed, self-reporting ladder of increasing tolerance (exact -> canonicalized ->
+whitespace-insensitive -> indentation-insensitive -> bounded fuzzy match), `apply` turns a
+batch of such finds into one atomic, overlap-checked write, and `telemetry` counts which rung
+actually did the work so a later decision about adding a neural rung is made from data.
+
+Phase 1 shipped the reconciliation core: `reconcile.py`, `apply.py`, `telemetry.py`. Phase 2
+added the read side (`read.py`, `skeleton.py`) and a persistent, stdlib-only pyrefly/ruff LSP
+client (`lsp.py`), wired into `apply_edits` via an optional `lsp_manager` for post-write
+diagnostics deltas. The `tact-02` feature wave rounds out the verb set in the same minimalist
+mold, in two halves. Wave A: `check_edits` (dry-run preview, in `apply.py`), `patch.py`
+(unified-diff / fenced-block ingestion into `Edit` batches), `transact.py` (`apply_many`,
+resolve-everything-then-write-all-or-nothing across files), and `heal.py` (the
+builtin-Edit-failure fixer). Wave B: `undo.py` (a content-addressed pre-image journal, wired
+into every write path, with a redoable `undo` verb), `rename.py` (`textDocument/rename` via
+`LspManager.rename`, converted to a multi-file `apply_many` transaction — the one verb in this
+package that is *not* LSP-optional, since renaming has no honest symbolic fallback),
+`anchor.py` (durable, re-findable block handles surviving a session/compaction boundary), and
+`delta.py` (`read_since`, cheap re-reads that compose with `undo.py`'s journal for a real line
+diff). Later phases (`instruments-03`/`-04` in the task backlog) add a console script and an
+MCP skin — `tact` itself stays the one library both front ends call into (N-32/N-35: policy in
+the skins, mechanism in the library).
+
+**Provenance.** The reconciliation ladder in `reconcile.py` ports, with attribution, parts of
+`dirac` (`github.com/dirac-run/dirac`, Apache-2.0, version 0.4.11) — see the `NOTICE` file at
+the repo root and the provenance block in `reconcile.py`'s own module docstring for exactly
+what was ported and how it was adapted.
+"""
+
+from tact.anchor import (
+    Anchor,
+    AnchorCreateResult,
+    AnchorLoadResult,
+    AnchorResult,
+    AnchorSaveResult,
+    anchor,
+    list_anchors,
+    load_anchor,
+    resolve_anchor,
+    save_anchor,
+)
+from tact.apply import ApplyReport, CheckReport, Edit, EditResult, apply_edits, check_edits
+from tact.delta import DeltaResult, DeltaStatus, read_since
+from tact.heal import HealResult, heal
+from tact.lsp import (
+    Diagnostic,
+    Location,
+    LspManager,
+    LspResult,
+    Position,
+    SymbolInfo,
+    find_project_root,
+)
+from tact.patch import (
+    PatchFileResult,
+    PatchParseResult,
+    parse_fenced_blocks,
+    parse_patch,
+    parse_unified_diff,
+)
+from tact.read import ReadResult, SeenHashes, read_file
+from tact.reconcile import Candidate, MatchResult, Rung, canonicalize, find_block
+from tact.rename import RenameResult, rename_symbol
+from tact.skeleton import SkeletonEntry, SkeletonResult, skeleton
+from tact.transact import ManyFileResult, ManyReport, apply_many
+from tact.undo import HistoryEntry, UndoResult, history, journal_preimage, load_blob, undo
+
+__all__ = [
+    'Anchor',
+    'AnchorCreateResult',
+    'AnchorLoadResult',
+    'AnchorResult',
+    'AnchorSaveResult',
+    'ApplyReport',
+    'Candidate',
+    'CheckReport',
+    'DeltaResult',
+    'DeltaStatus',
+    'Diagnostic',
+    'Edit',
+    'EditResult',
+    'HealResult',
+    'HistoryEntry',
+    'Location',
+    'LspManager',
+    'LspResult',
+    'ManyFileResult',
+    'ManyReport',
+    'MatchResult',
+    'PatchFileResult',
+    'PatchParseResult',
+    'Position',
+    'ReadResult',
+    'RenameResult',
+    'Rung',
+    'SeenHashes',
+    'SkeletonEntry',
+    'SkeletonResult',
+    'SymbolInfo',
+    'UndoResult',
+    'anchor',
+    'apply_edits',
+    'apply_many',
+    'canonicalize',
+    'check_edits',
+    'find_block',
+    'find_project_root',
+    'heal',
+    'history',
+    'journal_preimage',
+    'list_anchors',
+    'load_anchor',
+    'load_blob',
+    'parse_fenced_blocks',
+    'parse_patch',
+    'parse_unified_diff',
+    'read_file',
+    'read_since',
+    'rename_symbol',
+    'resolve_anchor',
+    'save_anchor',
+    'skeleton',
+    'undo',
+]

tact/_home.py

@@ -0,0 +1,35 @@
+"""Vendored agent-home resolver — `$AI_HOME` (else `$AI`, else `~/.ai`).
+
+`tact` must not depend on `corpus`. This is a minimal, stdlib-only port of
+`corpus.ai_home.ai_home()` (see `myCorpus`, `policies/ai_home.md`) — just enough to resolve
+the agent-owned working-state home tact writes into (`undo.py`'s journal, `anchor.py`'s
+saved anchors, `telemetry.py`'s counters). See that module for the full convention,
+bootstrap/CLI, and rationale; this file intentionally carries none of that beyond the
+resolver itself.
+"""
+
+############
+### HEAD ###
+############
+### STANDARD
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+############
+### DATA ###
+############
+_AI_HOME_ENV = 'AI_HOME'
+_AI_ENV = 'AI'
+_DEFAULT_AI_HOME = '~/.ai'
+
+
+############
+### BODY ###
+############
+def ai_home() -> Path:
+    """The agent home: `$AI_HOME`, else `$AI`, else `~/.ai` — an absolute path, never created."""
+    override = os.environ.get(_AI_HOME_ENV) or os.environ.get(_AI_ENV)
+    home = Path(override or _DEFAULT_AI_HOME).expanduser()
+    return home if home.is_absolute() else Path.cwd() / home

tact/_io.py

@@ -0,0 +1,89 @@
+"""Shared atomic-write plumbing for the tact package.
+
+One implementation of the temp-file-then-rename idiom (same-directory temp so the
+:func:`os.replace` stays on one filesystem, flush + fsync before rename, best-effort
+cleanup of the temp file on any failure) — used by the apply path, multi-file transactions,
+and telemetry.
+
+:func:`write_atomic` is the single-file entry point (stage, then commit, in one call) that
+every phase-1/2 caller already uses unchanged. It is composed from two smaller primitives,
+:func:`_stage` and :func:`_commit`, split out for :mod:`tact.transact`'s multi-file
+``apply_many``: a transaction must stage *every* file's content (write + fsync, no rename)
+before committing *any* of them, so it cannot call ``write_atomic`` per file — that would
+rename each file the moment its own content was staged, defeating the all-or-nothing point.
+"""
+
+############
+### HEAD ###
+############
+### STANDARD
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from pathlib import Path
+
+
+############
+### BODY ###
+############
+def _stage(path: Path, content: str) -> Path:
+    """Write ``content`` to a fresh temp file in ``path``'s directory; do not rename it.
+
+    Args:
+        path: The eventual destination — only its parent directory and name are used here
+            (same-directory temp keeps the later rename on one filesystem).
+        content: The full new file content, written UTF-8, flushed and fsynced before return.
+
+    Returns:
+        The temp file's path, unrenamed — the caller owns committing it (:func:`_commit`)
+        or cleaning it up on failure.
+    """
+    fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), prefix=f'.{path.name}-', suffix='.tmp')
+    tmp = Path(tmp_path)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+    except Exception:
+        with contextlib.suppress(OSError):
+            tmp.unlink()
+        raise
+    return tmp
+
+
+def _commit(tmp: Path, path: Path, *, mode: int | None = None) -> None:
+    """Rename a staged temp file onto ``path`` — the point of no return for that file.
+
+    Args:
+        tmp: A temp file previously returned by :func:`_stage`.
+        path: The destination. Must not be a symlink — callers resolve first, so the
+            rename lands on the real file and never materializes a link.
+        mode: Permission bits to apply to the new file, or ``None`` to accept the
+            temp file's default.
+    """
+    tmp.replace(path)
+    if mode is not None:
+        # After the rename: a briefly-too-private final file beats a world-readable temp.
+        path.chmod(mode)
+
+
+def write_atomic(path: Path, content: str, *, mode: int | None = None) -> None:
+    """Write ``content`` to ``path`` atomically (temp file in the same dir, then rename).
+
+    Args:
+        path: The destination. Must not be a symlink — callers resolve first, so the
+            rename lands on the real file and never materializes a link.
+        content: The full new file content, written UTF-8.
+        mode: Permission bits to apply to the new file, or ``None`` to accept the
+            temp file's default.
+    """
+    tmp = _stage(path, content)
+    try:
+        _commit(tmp, path, mode=mode)
+    except Exception:
+        with contextlib.suppress(OSError):
+            tmp.unlink()
+        raise

tact/_serialize.py

@@ -0,0 +1,54 @@
+r"""One JSON-shaping helper, shared by the CLI's ``--json`` and the MCP server.
+
+Every verb in this package returns a frozen dataclass (often nesting other frozen
+dataclasses, enums, ``Path``\\s, and tuples) — exactly the shape a human-facing ``--json``
+flag or an MCP tool's return value needs to become plain JSON-safe data. :func:`to_jsonable`
+is the one place that conversion happens, so the CLI and the MCP server can never disagree
+about what a given result looks like as JSON.
+
+**Enum handling.** :class:`~tact.reconcile.Rung` is an ``IntEnum`` — an ``int``
+subclass — so the ``Enum`` check must run *before* the ``int``/``float``/``bool`` check below,
+or every rung would serialize as a bare integer instead of its name (the spec's own
+"asdict + enum names" contract).
+"""
+
+############
+### HEAD ###
+############
+### STANDARD
+from __future__ import annotations
+
+from dataclasses import fields, is_dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+############
+### BODY ###
+############
+def to_jsonable(obj: Any) -> Any:
+    """Recursively convert ``obj`` into plain JSON-safe data (``dict``/``list``/scalars).
+
+    Handles the shapes every verb in this package actually returns: frozen dataclasses
+    (including nested ones, e.g. :class:`~tact.rename.RenameResult`'s
+    ``many_report``), ``Enum``/``IntEnum`` members (rendered as ``.name``, never ``.value``
+    or the raw int), ``Path`` (rendered as ``str``), and ``tuple``/``list`` (rendered as
+    ``list``). Anything else (``None``, ``bool``, ``int``, ``float``, ``str``, already-plain
+    ``dict``) passes through unchanged — this function never raises on a shape it doesn't
+    recognize; ``json.dumps`` is left to complain if something genuinely unsupported slips
+    through, which nothing in this package's public result types currently does.
+    """
+    if isinstance(obj, Enum):
+        return obj.name
+    if obj is None or isinstance(obj, bool | int | float | str):
+        return obj
+    if isinstance(obj, Path):
+        return str(obj)
+    if is_dataclass(obj) and not isinstance(obj, type):
+        return {f.name: to_jsonable(getattr(obj, f.name)) for f in fields(obj)}
+    if isinstance(obj, list | tuple):
+        return [to_jsonable(item) for item in obj]
+    if isinstance(obj, dict):
+        return {str(k): to_jsonable(v) for k, v in obj.items()}
+    return obj