codesuture 0.6.0__tar.gz → 0.7.1__tar.gz

codesuture-0.7.1/.gitignore

@@ -0,0 +1,53 @@
+# ---------------------------
+# Python
+# ---------------------------
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# ---------------------------
+# Virtual environments
+# ---------------------------
+.venv/
+env/
+venv/
+
+# ---------------------------
+# IDE / editor
+# ---------------------------
+.vscode/
+.idea/
+*.code-workspace
+
+# ---------------------------
+# CodeSuture runtime artifacts
+# ---------------------------
+.codesuture_store/
+.codesuture_cache/
+.livepatch_cache/
+.codesuture_fingerprints
+.models/
+
+# ---------------------------
+# Test / CI artifacts
+# ---------------------------
+.pytest_cache/
+htmlcov/
+.coverage
+*.log
+
+# ---------------------------
+# Planning & roadmap (local only)
+# ---------------------------
+ROADMAP.md
+implementation_plan.md
+task.md
+walkthrough.md
+
+# ---------------------------
+# Old verification suites (deleted)
+# ---------------------------
+v4test/

codesuture-0.7.1/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.1] - 2026-05-25
+
+### Fixed — Safety Hardening
+- **Index guard no longer returns wrong item:** `index_guard` now returns a
+  type-appropriate default value instead of clamping the index to 0 (which
+  silently returned `list[0]` — a data corruption bug)
+- **Callable guard no longer replaces unknown functions with `lambda: 0`:**
+  Unknown callables are skipped with a warning instead of being silently
+  replaced with a stub that could bypass validation logic
+- **Exception tracebacks shown by default:** `_codesuture_excepthook` now
+  prints a structured summary of self-healed exceptions instead of
+  suppressing all output; use `--silent` to restore old behavior
+- **Rollback restores runtime code:** `codesuture rollback` now restores
+  original bytecode in memory (not just deletes files); original code
+  objects are backed up before patching and saved as `.orig.code` files
+- **Marshal integrity checks:** Persisted `.code` files now include SHA-256
+  checksums in metadata; tampered files are refused on load
+- **Thread safety:** Added locking on `HEALED_FUNCTIONS`,
+  `ANNOUNCED_HEALED_FUNCTIONS`, `_retried_exc_types`, fingerprint registry,
+  and `CodeSutureMetaFinder` recursion guard (now uses `threading.local()`)
+- **`_INLINE_STRATEGIES` set populated:** Try-block detection for inline
+  strategies (`subscript_guard`, `key_guard`, `division_guard`,
+  `chain_subscript_guard`) is now active — previously disabled by empty set
+- **Safe tuple propagation:** Replaced dangerous `ctypes` memory write into
+  tuple `ob_item` array with safe `code.replace(co_consts=...)` approach
+
+### Added — CPython 3.12+ Compatibility
+- **`codesuture/opcodes.py`:** Version-aware opcode abstraction layer
+  providing correct opcode names, instruction builders, and opcode name
+  sets for Python 3.11, 3.12, and 3.13+
+- All guard builders now use `opcodes.py` instead of hardcoded 3.11-only
+  opcode names (`PRECALL`, `POP_JUMP_FORWARD_IF_FALSE`, `LOAD_METHOD`)
+- Pattern matcher uses opcode sets for resilient bytecode analysis across
+  Python versions
+- Frame rewind offset detection is now runtime-detected instead of
+  hardcoded to CPython 3.11 struct layout (`id(frame) + 40`)
+- CLI: added `--silent` flag to `codesuture run`
+
+### Changed
+- Removed old test files, v4test/ verification suite, and heavily-mocked
+  tracer test; replaced with comprehensive new test suite
+
+### Fixed — Audit Round (Post-Release)
+- **`_eval_fix.py`:** Fixed `ImportError` — was importing `apply_fix_with_info`
+  which doesn't exist; changed to `apply_fix`
+- **`_build_subscript_guarded_code`:** No longer calls `.get()` on lists/tuples;
+  now checks `isinstance(container, dict)` before using `.get()`, falls back to
+  direct subscript for non-dict containers
+- **`rollback_runtime`:** Removed dead `gc.get_referrers` loop that had only `pass`
+  in its body
+- **`middleware.py`:** Retry tracking now uses `(exc_type, filename, func_name)`
+  tuple instead of bare exception type — prevents second crash of same type in
+  different function from being silently ignored
+- **`persistence.py`:** Thread name now uses `threading.current_thread().name`
+  instead of hardcoded `"MainThread"`; `datetime.utcnow()` replaced with
+  `datetime.now(timezone.utc)` (Python 3.12 deprecation fix);
+  `_iter_cached_function_names` now excludes `.orig.code` files
+- **`audit.py`:** Unicode box-drawing characters now actually used when terminal
+  supports them (was identical ASCII `|` on both branches);
+  `datetime.utcnow()` deprecation fixed
+- **`rollback.py`:** `datetime.utcnow()` replaced with timezone-aware datetime
+  (was causing `TypeError` when comparing with timezone-aware `patched_at` values)
+- **`tracer.py`:** `--silent` flag now gates ALL 20+ informational print statements
+  (fingerprint hits, patch applied, already healed, etc.); errors/warnings still
+  always print
+- **`opcodes.py`:** Added Python 3.13 compatibility documentation; expanded
+  `SUBSCRIPT_OPCODES` to include `BINARY_SLICE` for 3.13 slice operations
+
+## [0.7.0] - 2026-05-17
+
+### Added
+- Active Shield: after patching, the engine re-invokes the function with
+  original arguments to save the current transaction (eliminates
+  ERR_EMPTY_RESPONSE on first request to patched server endpoints)
+- Python 3.12+ sys.monitoring dual engine: zero baseline overhead,
+  callback fires only on RAISE events instead of line-by-line tracing
+- Transaction fallback: graceful JSON 500 response for network handlers
+  when re-invocation fails, preventing hanging socket connections
+
+## [0.6.0] - 2026-05-12
+
+### Fixed
+- PEP 659: Force de-specialization after `__code__` swap via
+  `ctypes.pythonapi.PyFunction_SetCode` — prevents CPython 3.11+
+  adaptive bytecode cache from ignoring injected patches
+- Thread blindness: Install trace hook on all threads via
+  `threading.settrace` at startup, with `_install_trace_on_all_threads`
+  helper covering existing and future threads; added `threading.Lock`
+  for thread-safe patch store writes
+- Exception table corruption: Guard injection now detects try/except
+  scope via `TryBegin`/`TryEnd` markers and redirects to function
+  entry-point injection to avoid corrupting `co_exceptiontable` offsets
+  in CPython 3.11+
+
+## [0.5.1] - 2026-05-11
+
+### Fixed
+- propagate_patch: skip list/dict/set/generator comprehensions
+  instead of crashing with AttributeError on __code__
+- key_guard, subscript_guard, chain_subscript_guard: infer
+  correct default type from downstream bytecode usage
+  (string methods -> "" default, numeric ops -> 0 default)
+- KeyError on chained subscripts (e.g. request["headers"]["auth"].strip())
+  now produces a chain_subscript_guard instead of a simple key_guard,
+  preventing secondary TypeError from None subscript access
+
+## [0.5.0] - 2026-05-08
+
+### Added
+- Async/await support (CO_COROUTINE frame detection) — automatic `RESUME 0` preservation for coroutine bytecode patching.
+- Watch mode: `codesuture watch --max-restarts N` — subprocess loop with automatic crash-patch-restart cycle.
+- Explain command: `codesuture explain [func_name]` — detailed table of active patches with safety assessment (LIKELY/RISKY/UNKNOWN).
+- WSGI middleware: `CodeSutureMiddleware` — intercepts request handler exceptions, patches, and retries with `X-CodeSuture` response header.
+
+## [0.4.0] - 2026-05-07
+
+### Added
+- `codesuture rollback` command to selectively remove persisted patches (`codesuture rollback <func>`, `--all`, and `--dry-run`).
+- Three new guard types:
+  - `type_coercion_guard` for `TypeError` and `ValueError` during type conversions.
+  - `index_guard` for `IndexError` bounds checking.
+  - `key_guard` for safe dictionary `KeyError` fallbacks.
+- Enhanced `--dry-run` mode with confidence levels (HIGH/MEDIUM/LOW) based on fingerprint registry hits.
+- Full PyPI packaging structure (`pyproject.toml`, complete `README.md`, `CHANGELOG.md`).
+
+### Changed
+- Migrated legacy guards `list_bound_guard` to `index_guard` and `dict_get_guard` to `key_guard` for consistency.
+- Standardized CLI output format and improved error reporting.
+
+## [0.3.0] - 2026-05-06
+
+### Added
+-  Upgrade D1: Semantic diff safety gate to prevent runaway bytecode corruption.
+-  Upgrade D2: Caller-aware patch propagation to automatically fix closures and bound methods in-memory.
+-  Upgrade D3: Shadow execution mode (`--shadow`) to monitor and warn when sentinel defaults leak downstream.
+-  Upgrade D4: Patch expiry TTL warnings to nudge developers toward source-level fixes.
+-  Upgrade D5: Bytecode fingerprint registry for instant cache hits on known crash patterns.
+-  Upgrade D6: `codesuture audit` command for viewing all active patches in a formatted table.
+
+### Fixed
+- Addressed Windows `UnicodeDecodeError` and `cp1252` terminal limitations by enforcing `utf-8` encoding.
+- Resolved a race condition where patch persistence was executing after the code object swap, preventing correct caller identification.
+- Fixed namespace pollution during nested patching.

codesuture-0.7.1/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: codesuture
+Version: 0.7.1
+Summary: Runtime Python bytecode patcher with guard knowledge base, persistence, and self-healing re-execution
+License-Expression: MIT
+Project-URL: Source, https://github.com/codesuture/codesuture
+Keywords: bytecode,runtime,patching,self-healing,debugging,null-safety,resilience
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bytecode>=0.15.1
+Provides-Extra: autonomous
+Requires-Dist: llama-cpp-python; extra == "autonomous"
+Dynamic: license-file
+
+# CodeSuture
+
+![CodeSuture Banner](assets/banner.png)
+
+**Runtime guard synthesis for CPython 3.11+. Catches structural crashes, patches live bytecode, keeps your server running.**
+
+[![Version](https://img.shields.io/badge/version-0.7.1-blue)]()
+[![Python](https://img.shields.io/badge/python-3.11%2B-brightgreen)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-beta-orange)]()
+
+```
+pip install codesuture
+```
+
+---
+
+## What it does
+
+When a Python program crashes, CodeSuture intercepts the exception at the exact bytecode instruction, disassembles the failing function, injects a deterministic guard into its code object in memory, and retries — without touching a single source file.
+
+The patch persists. Next run, it loads before the first function call.
+
+On a live HTTP server, CodeSuture patches the handler mid-request and replays the transaction. The client receives a 200. No restart. No traceback leak.
+
+---
+
+## Quick start — script
+
+```bash
+codesuture run your_script.py
+```
+
+```
+[CodeSuture] Caught AttributeError: 'NoneType' object has no attribute 'bio'
+[CodeSuture] Applying null_guard on 'profile' ...
+[CodeSuture] Patch applied to get_bio().
+[CodeSuture] Re-executing after 1 patch(es)...
+
+Session summary:
+  Patches applied: 1
+```
+
+Run it again:
+
+```
+[CodeSuture] Already healed, skipping: loaded persistent patch for get_bio
+Session summary:
+  Patches applied: 0
+```
+
+---
+
+## Quick start — live server
+
+```bash
+codesuture run server.py --verbose --retries 3
+```
+
+```
+[CodeSuture] Caught AttributeError: 'NoneType' object has no attribute 'get_profile'
+[CodeSuture] Applying null_guard on 'get_profile' ...
+[CodeSuture DEBUG] Diff: +12 -9 instructions (allowed <= 55)
+[CodeSuture] Patch applied to do_GET().
+[CodeSuture] Transaction replay armed for do_GET().
+[CodeSuture] Transaction replay: retrying patched HTTP handler in-place.
+127.0.0.1 - - "GET /user-data HTTP/1.1" 200 -
+```
+
+The client sees:
+
+```http
+HTTP/1.0 200 OK
+Content-type: application/json
+X-CodeSuture: patched=1; guard=null_guard; target=get_profile
+
+{"result": null}
+```
+
+No 500. No traceback. Server process intact.
+
+---
+
+## How it works
+
+1. **Catch** — `sys.settrace` (3.11) or `sys.monitoring` (3.12+) intercepts exceptions at the exact frame and bytecode offset.
+2. **Analyze** — The pattern matcher walks the instruction chain and identifies the failing variable or operation.
+3. **Patch** — The guard synthesizer injects new bytecode into the function's code object. A semantic diff gate rejects patches that change too much logic.
+4. **Rewind** — Execution restarts from the patched function via `f_lineno` setter. The guard prevents recurrence.
+5. **Persist** — The patched code object is serialized to `.codesuture_store/` with SHA-256 integrity checks and JSON metadata. Subsequent runs load it before the first call.
+
+No source files are modified.
+
+---
+
+## Supported guard types
+
+| Guard type | Triggers on | Example |
+|---|---|---|
+| `null_guard` | `AttributeError` on `None` | `user.profile.bio` when `profile` is `None` |
+| `key_guard` | `KeyError` | `cfg["timeout"]` when key is missing |
+| `subscript_guard` | `TypeError` subscripting `None` | `data["key"]` when `data` is `None` |
+| `chain_subscript_guard` | Nested subscript on `None` | `data["user"]["name"]` |
+| `index_guard` | `IndexError` | `items[10]` when `len(items) == 2` |
+| `type_coercion_guard` | `TypeError` on conversion | `int("not_a_number")` |
+| `division_guard` | `ZeroDivisionError` | `x / count` when `count == 0` |
+| `str_coerce_guard` | `TypeError` on string concat | `"age: " + 25` |
+| `file_guard` | `FileNotFoundError` | `open(path)` when file is missing |
+| `callable_guard` | `TypeError` calling `None` | `func()` when `func` is `None` |
+| `return_guard` | `TypeError` on `None` return | Downstream use of a `None` return value |
+
+---
+
+## CLI reference
+
+| Command | Flags | What it does |
+|---|---|---|
+| `codesuture run <script>` | | Run with live patching |
+| | `--verbose` | Show patch diffs and instruction deltas |
+| | `--shadow` | Warn when patched functions return sentinel values |
+| | `--dry-run` | Preview patches without applying |
+| | `--silent` | Suppress all informational output |
+| | `--ttl DAYS` | Set patch expiry (default: 7 days) |
+| | `--retries N` | Max re-execution attempts (default: 3) |
+| `codesuture watch <script>` | `--max-restarts N` | Run continuously, restart after each patch |
+| `codesuture audit` | | Show all active patches in a table |
+| `codesuture explain` | | Plain-language breakdown of every patch |
+| `codesuture explain <name>` | | Explain one function's patch |
+| `codesuture rollback <name>` | | Remove one persisted patch and restore runtime code |
+| `codesuture rollback` | `--all` | Remove all patches and fingerprint registry |
+| `codesuture rollback` | `--dry-run` | Preview what would be removed |
+
+---
+
+## HTTP recovery
+
+CodeSuture patches exceptions inside `http.server` and `socketserver` request handlers. The handler runs in its own thread — CodeSuture installs `threading.settrace` to intercept crashes there.
+
+When a handler crashes and a guard is available, CodeSuture patches the function mid-request and replays the transaction in-place. The client receives a response instead of a socket close.
+
+Every patched response carries:
+
+```
+X-CodeSuture: patched=1; guard=<type>; target=<variable>
+```
+
+### WSGI middleware
+
+```python
+from codesuture.middleware import CodeSutureMiddleware
+
+app = CodeSutureMiddleware(wsgi_app)
+```
+
+See the implementation in [codesuture/middleware.py](codesuture/middleware.py).
+
+---
+
+## Safety features
+
+- **Semantic diff gate** — Patches that modify too many instructions are rejected. The engine never corrupts a complex function to fix a simple crash.
+- **SHA-256 integrity** — Persisted patches are checksummed. Tampered `.code` files are refused on load.
+- **Caller-aware propagation** — After patching, `gc.get_referrers` updates every live reference: closures, bound methods, partials. No stale copy survives.
+- **Patch validation** — Synthesized bytecode is checked for `LOAD_FAST` references to variables not in `co_varnames`. Invalid patches are rejected before application.
+- **Patch expiry (TTL)** — Every patch carries a time-to-live. Aged patches trigger a warning to fix the root cause in source.
+- **Thread safety** — All shared state (fingerprint registry, persistence store, healed function sets) is protected by locks.
+- **Rollback** — `codesuture rollback` removes persisted files AND restores original code in the running process.
+
+---
+
+## What CodeSuture is not
+
+**Not a logger.** It does not record exceptions and move on. It patches the function and retries.
+
+**Not a static analyzer.** It operates at runtime on live bytecode, not on source.
+
+**Not autonomous by default.** All patches are deterministic rule-based guards. An opt-in `--autonomous` flag exists for experimental LLM-powered suggestions via local models, but it is off by default and never auto-applies fixes.
+
+---
+
+## Known limitations
+
+<<<<<<< HEAD
+**Python 3.11+ only.** CodeSuture depends on CPython 3.11 bytecode structures.
+
+**Comprehensions are not patchable.** List, dict, set, and generator comprehensions are anonymous nested code objects. CodeSuture logs a warning and skips them. Refactor into a named function to enable patching.
+
+**Semantic bugs are not patchable.** CodeSuture fixes structural crashes — null access, missing keys, type mismatches, bounds errors. Logic errors that produce wrong results without crashing are out of scope.
+
+**Single-process scope.** Patches apply per-process. Multi-process applications need one instance per worker. `.codesuture_store/` is shared on disk, so patches load correctly on restart.
+
+**Async support is experimental.** Standard `async def` functions are patched. Async generators and deeply nested `await` chains may not be handled correctly in all cases.
+
+**HTTP recovery covers simple server paths.** Validated against `http.server` and `socketserver`. Full ASGI framework support is in progress.
+
+---
+
+## Roadmap
+
+Tracked in [ROADMAP.md](ROADMAP.md). v1.0 themes:
+
+- `sys.monitoring` as the default engine on Python 3.12+ (zero line-tracing overhead on hot paths)
+- Stronger transaction recovery boundaries across web frameworks
+- Verified source-level repair proposals via local LLM
+- Fleet governance, audit lifecycle, and incident export
+- Language-neutral incident protocol for future polyglot adapters
+=======
+- **Python 3.11+ only.** Depends on CPython bytecode structures introduced in 3.11.
+- **3.12+ frame rewind.** The Python-level `f_lineno` setter is used on 3.12+. The ctypes fallback is disabled on 3.12+ to prevent memory corruption from struct layout changes.
+- **Comprehensions are not patchable.** List/dict/set/generator comprehensions are anonymous nested code objects. CodeSuture logs a warning and skips them.
+- **Semantic bugs are out of scope.** CodeSuture fixes structural crashes — null access, missing keys, type mismatches, bounds errors. Logic errors that produce wrong results without crashing cannot be detected.
+- **Single-process scope.** Patches apply per-process. `.codesuture_store/` is shared on disk, so patches persist across restarts.
+- **Async support is experimental.** Standard `async def` functions are patched. Async generators and deeply nested `await` chains may not be handled correctly.
+- **HTTP recovery is validated against `http.server`.** Full ASGI framework support is not yet implemented.
+>>>>>>> 0cedff8 (v0.7.1: safety hardening, audit fixes, 3.12+ compat, 120 tests)
+
+---
+
+## License
+
+<<<<<<< HEAD
+MIT. See [LICENSE](LICENSE) for details. For a detailed history of changes, see the [Changelog](CHANGELOG.md).
+=======
+MIT. See [LICENSE](LICENSE) for details.
+
+For a detailed history of changes, see the [Changelog](CHANGELOG.md).
+>>>>>>> 0cedff8 (v0.7.1: safety hardening, audit fixes, 3.12+ compat, 120 tests)

codesuture-0.7.1/README.md

@@ -0,0 +1,227 @@
+# CodeSuture
+
+![CodeSuture Banner](assets/banner.png)
+
+**Runtime guard synthesis for CPython 3.11+. Catches structural crashes, patches live bytecode, keeps your server running.**
+
+[![Version](https://img.shields.io/badge/version-0.7.1-blue)]()
+[![Python](https://img.shields.io/badge/python-3.11%2B-brightgreen)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-beta-orange)]()
+
+```
+pip install codesuture
+```
+
+---
+
+## What it does
+
+When a Python program crashes, CodeSuture intercepts the exception at the exact bytecode instruction, disassembles the failing function, injects a deterministic guard into its code object in memory, and retries — without touching a single source file.
+
+The patch persists. Next run, it loads before the first function call.
+
+On a live HTTP server, CodeSuture patches the handler mid-request and replays the transaction. The client receives a 200. No restart. No traceback leak.
+
+---
+
+## Quick start — script
+
+```bash
+codesuture run your_script.py
+```
+
+```
+[CodeSuture] Caught AttributeError: 'NoneType' object has no attribute 'bio'
+[CodeSuture] Applying null_guard on 'profile' ...
+[CodeSuture] Patch applied to get_bio().
+[CodeSuture] Re-executing after 1 patch(es)...
+
+Session summary:
+  Patches applied: 1
+```
+
+Run it again:
+
+```
+[CodeSuture] Already healed, skipping: loaded persistent patch for get_bio
+Session summary:
+  Patches applied: 0
+```
+
+---
+
+## Quick start — live server
+
+```bash
+codesuture run server.py --verbose --retries 3
+```
+
+```
+[CodeSuture] Caught AttributeError: 'NoneType' object has no attribute 'get_profile'
+[CodeSuture] Applying null_guard on 'get_profile' ...
+[CodeSuture DEBUG] Diff: +12 -9 instructions (allowed <= 55)
+[CodeSuture] Patch applied to do_GET().
+[CodeSuture] Transaction replay armed for do_GET().
+[CodeSuture] Transaction replay: retrying patched HTTP handler in-place.
+127.0.0.1 - - "GET /user-data HTTP/1.1" 200 -
+```
+
+The client sees:
+
+```http
+HTTP/1.0 200 OK
+Content-type: application/json
+X-CodeSuture: patched=1; guard=null_guard; target=get_profile
+
+{"result": null}
+```
+
+No 500. No traceback. Server process intact.
+
+---
+
+## How it works
+
+1. **Catch** — `sys.settrace` (3.11) or `sys.monitoring` (3.12+) intercepts exceptions at the exact frame and bytecode offset.
+2. **Analyze** — The pattern matcher walks the instruction chain and identifies the failing variable or operation.
+3. **Patch** — The guard synthesizer injects new bytecode into the function's code object. A semantic diff gate rejects patches that change too much logic.
+4. **Rewind** — Execution restarts from the patched function via `f_lineno` setter. The guard prevents recurrence.
+5. **Persist** — The patched code object is serialized to `.codesuture_store/` with SHA-256 integrity checks and JSON metadata. Subsequent runs load it before the first call.
+
+No source files are modified.
+
+---
+
+## Supported guard types
+
+| Guard type | Triggers on | Example |
+|---|---|---|
+| `null_guard` | `AttributeError` on `None` | `user.profile.bio` when `profile` is `None` |
+| `key_guard` | `KeyError` | `cfg["timeout"]` when key is missing |
+| `subscript_guard` | `TypeError` subscripting `None` | `data["key"]` when `data` is `None` |
+| `chain_subscript_guard` | Nested subscript on `None` | `data["user"]["name"]` |
+| `index_guard` | `IndexError` | `items[10]` when `len(items) == 2` |
+| `type_coercion_guard` | `TypeError` on conversion | `int("not_a_number")` |
+| `division_guard` | `ZeroDivisionError` | `x / count` when `count == 0` |
+| `str_coerce_guard` | `TypeError` on string concat | `"age: " + 25` |
+| `file_guard` | `FileNotFoundError` | `open(path)` when file is missing |
+| `callable_guard` | `TypeError` calling `None` | `func()` when `func` is `None` |
+| `return_guard` | `TypeError` on `None` return | Downstream use of a `None` return value |
+
+---
+
+## CLI reference
+
+| Command | Flags | What it does |
+|---|---|---|
+| `codesuture run <script>` | | Run with live patching |
+| | `--verbose` | Show patch diffs and instruction deltas |
+| | `--shadow` | Warn when patched functions return sentinel values |
+| | `--dry-run` | Preview patches without applying |
+| | `--silent` | Suppress all informational output |
+| | `--ttl DAYS` | Set patch expiry (default: 7 days) |
+| | `--retries N` | Max re-execution attempts (default: 3) |
+| `codesuture watch <script>` | `--max-restarts N` | Run continuously, restart after each patch |
+| `codesuture audit` | | Show all active patches in a table |
+| `codesuture explain` | | Plain-language breakdown of every patch |
+| `codesuture explain <name>` | | Explain one function's patch |
+| `codesuture rollback <name>` | | Remove one persisted patch and restore runtime code |
+| `codesuture rollback` | `--all` | Remove all patches and fingerprint registry |
+| `codesuture rollback` | `--dry-run` | Preview what would be removed |
+
+---
+
+## HTTP recovery
+
+CodeSuture patches exceptions inside `http.server` and `socketserver` request handlers. The handler runs in its own thread — CodeSuture installs `threading.settrace` to intercept crashes there.
+
+When a handler crashes and a guard is available, CodeSuture patches the function mid-request and replays the transaction in-place. The client receives a response instead of a socket close.
+
+Every patched response carries:
+
+```
+X-CodeSuture: patched=1; guard=<type>; target=<variable>
+```
+
+### WSGI middleware
+
+```python
+from codesuture.middleware import CodeSutureMiddleware
+
+app = CodeSutureMiddleware(wsgi_app)
+```
+
+See the implementation in [codesuture/middleware.py](codesuture/middleware.py).
+
+---
+
+## Safety features
+
+- **Semantic diff gate** — Patches that modify too many instructions are rejected. The engine never corrupts a complex function to fix a simple crash.
+- **SHA-256 integrity** — Persisted patches are checksummed. Tampered `.code` files are refused on load.
+- **Caller-aware propagation** — After patching, `gc.get_referrers` updates every live reference: closures, bound methods, partials. No stale copy survives.
+- **Patch validation** — Synthesized bytecode is checked for `LOAD_FAST` references to variables not in `co_varnames`. Invalid patches are rejected before application.
+- **Patch expiry (TTL)** — Every patch carries a time-to-live. Aged patches trigger a warning to fix the root cause in source.
+- **Thread safety** — All shared state (fingerprint registry, persistence store, healed function sets) is protected by locks.
+- **Rollback** — `codesuture rollback` removes persisted files AND restores original code in the running process.
+
+---
+
+## What CodeSuture is not
+
+**Not a logger.** It does not record exceptions and move on. It patches the function and retries.
+
+**Not a static analyzer.** It operates at runtime on live bytecode, not on source.
+
+**Not autonomous by default.** All patches are deterministic rule-based guards. An opt-in `--autonomous` flag exists for experimental LLM-powered suggestions via local models, but it is off by default and never auto-applies fixes.
+
+---
+
+## Known limitations
+
+<<<<<<< HEAD
+**Python 3.11+ only.** CodeSuture depends on CPython 3.11 bytecode structures.
+
+**Comprehensions are not patchable.** List, dict, set, and generator comprehensions are anonymous nested code objects. CodeSuture logs a warning and skips them. Refactor into a named function to enable patching.
+
+**Semantic bugs are not patchable.** CodeSuture fixes structural crashes — null access, missing keys, type mismatches, bounds errors. Logic errors that produce wrong results without crashing are out of scope.
+
+**Single-process scope.** Patches apply per-process. Multi-process applications need one instance per worker. `.codesuture_store/` is shared on disk, so patches load correctly on restart.
+
+**Async support is experimental.** Standard `async def` functions are patched. Async generators and deeply nested `await` chains may not be handled correctly in all cases.
+
+**HTTP recovery covers simple server paths.** Validated against `http.server` and `socketserver`. Full ASGI framework support is in progress.
+
+---
+
+## Roadmap
+
+Tracked in [ROADMAP.md](ROADMAP.md). v1.0 themes:
+
+- `sys.monitoring` as the default engine on Python 3.12+ (zero line-tracing overhead on hot paths)
+- Stronger transaction recovery boundaries across web frameworks
+- Verified source-level repair proposals via local LLM
+- Fleet governance, audit lifecycle, and incident export
+- Language-neutral incident protocol for future polyglot adapters
+=======
+- **Python 3.11+ only.** Depends on CPython bytecode structures introduced in 3.11.
+- **3.12+ frame rewind.** The Python-level `f_lineno` setter is used on 3.12+. The ctypes fallback is disabled on 3.12+ to prevent memory corruption from struct layout changes.
+- **Comprehensions are not patchable.** List/dict/set/generator comprehensions are anonymous nested code objects. CodeSuture logs a warning and skips them.
+- **Semantic bugs are out of scope.** CodeSuture fixes structural crashes — null access, missing keys, type mismatches, bounds errors. Logic errors that produce wrong results without crashing cannot be detected.
+- **Single-process scope.** Patches apply per-process. `.codesuture_store/` is shared on disk, so patches persist across restarts.
+- **Async support is experimental.** Standard `async def` functions are patched. Async generators and deeply nested `await` chains may not be handled correctly.
+- **HTTP recovery is validated against `http.server`.** Full ASGI framework support is not yet implemented.
+>>>>>>> 0cedff8 (v0.7.1: safety hardening, audit fixes, 3.12+ compat, 120 tests)
+
+---
+
+## License
+
+<<<<<<< HEAD
+MIT. See [LICENSE](LICENSE) for details. For a detailed history of changes, see the [Changelog](CHANGELOG.md).
+=======
+MIT. See [LICENSE](LICENSE) for details.
+
+For a detailed history of changes, see the [Changelog](CHANGELOG.md).
+>>>>>>> 0cedff8 (v0.7.1: safety hardening, audit fixes, 3.12+ compat, 120 tests)

codesuture-0.7.1/codesuture/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.7.1"
+