atomadic-forge 0.79.0__tar.gz → 0.80.0__tar.gz

{atomadic_forge-0.79.0 → atomadic_forge-0.80.0}/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## v0.80.0 — 2026-05-08
+
+- feat(forge): v0.80 Monadic Laws — MCB / AHLP / AIOM / IFWC-lite
+
+
 ## v0.79.0 — 2026-05-08
 
 - feat(forge): replay — deterministic golden-recipe execution

{atomadic_forge-0.79.0/src/atomadic_forge.egg-info → atomadic_forge-0.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.79.0
+Version: 0.80.0
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1
@@ -225,8 +225,8 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | MCP tools | **10 tools · 116 actions** |
 | CLI verbs | **59** |
-| Source files | **235** (~47K LOC) |
-| Tests | **1597 passing** across **117 test files** |
+| Source files | **242** (~48K LOC) |
+| Tests | **1608 passing** across **119 test files** |
 | Lean4 formal proofs | **872 theorems** (mathematically verified core logic) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |

{atomadic_forge-0.79.0 → atomadic_forge-0.80.0}/README.md

@@ -193,8 +193,8 @@ Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welco
 
 | MCP tools | **10 tools · 116 actions** |
 | CLI verbs | **59** |
-| Source files | **235** (~47K LOC) |
-| Tests | **1597 passing** across **117 test files** |
+| Source files | **242** (~48K LOC) |
+| Tests | **1608 passing** across **119 test files** |
 | Lean4 formal proofs | **872 theorems** (mathematically verified core logic) |
 | Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
 | Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |

{atomadic_forge-0.79.0 → atomadic_forge-0.80.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.79.0"
+version = "0.80.0"
 description = "Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code."
 readme = "README.md"
 requires-python = ">=3.10"

atomadic_forge-0.80.0/src/atomadic_forge/a1_at_functions/ifwc_fuzz.py

@@ -0,0 +1,158 @@
+"""Tier a1 — IFWC-lite property-based fuzzer.
+
+Any callable carrying an ``__invariants__`` dict is fair game:
+
+    def add(a: int, b: int) -> int:
+        return a + b
+    add.__invariants__ = {
+        "args": {"a": "integers", "b": "integers"},
+        "post": "lambda r, a, b: r == a + b",
+    }
+
+``args`` maps parameter name → hypothesis strategy name (or ``"any"``).
+``post`` is a string lambda evaluated with ``(result, **kwargs)``;
+returning False (or raising) ⇒ falsifying example captured.
+
+Pure stdlib + ``hypothesis`` (already a Forge dev dep). No I/O.
+"""
+from __future__ import annotations
+
+import importlib
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+SCHEMA_VERSION_IFWC_V1 = "atomadic-forge.ifwc/v1"
+
+
+_STRATEGY_MAP: dict[str, str] = {
+    "integers": "integers",
+    "floats": "floats",
+    "text": "text",
+    "booleans": "booleans",
+    "none": "none",
+    "any": "integers",  # default fallback
+}
+
+
+def _build_strategies(args_spec: dict[str, str]) -> dict[str, Any]:
+    """Translate ``{"a": "integers"}`` → ``{"a": st.integers()}``."""
+    try:
+        from hypothesis import strategies as st
+    except ImportError as exc:  # pragma: no cover - dev dep
+        raise RuntimeError(
+            "hypothesis not installed; `pip install hypothesis`"
+        ) from exc
+    out: dict[str, Any] = {}
+    for name, strat_name in args_spec.items():
+        key = _STRATEGY_MAP.get(strat_name, "integers")
+        out[name] = getattr(st, key)()
+    return out
+
+
+def fuzz_callable(
+    fn: Callable[..., Any],
+    *,
+    max_examples: int = 100,
+) -> dict[str, Any]:
+    """Run hypothesis against ``fn`` using its ``__invariants__`` spec.
+
+    Returns ``{verdict, examples_run, falsifying_example|None,
+    error|None, function}``.
+    """
+    spec = getattr(fn, "__invariants__", None)
+    if not spec:
+        return {
+            "schema_version": SCHEMA_VERSION_IFWC_V1,
+            "function": fn.__name__,
+            "verdict": "SKIP",
+            "reason": "no __invariants__ marker",
+            "examples_run": 0,
+        }
+
+    try:
+        from hypothesis import given, settings
+    except ImportError:
+        return {
+            "schema_version": SCHEMA_VERSION_IFWC_V1,
+            "function": fn.__name__,
+            "verdict": "ERROR",
+            "reason": "hypothesis not installed",
+            "examples_run": 0,
+        }
+
+    args_spec = dict(spec.get("args") or {})
+    post = spec.get("post")
+    strategies = _build_strategies(args_spec)
+    counter = {"n": 0}
+    failure = {"example": None, "error": None}
+
+    @settings(max_examples=int(max_examples), deadline=None)
+    @given(**strategies)
+    def _runner(**kwargs: Any) -> None:
+        counter["n"] += 1
+        result = fn(**kwargs)
+        if post:
+            ok = False
+            try:
+                check = eval(post) if isinstance(post, str) else post  # noqa: S307
+                ok = bool(check(result, **kwargs))
+            except Exception as exc:  # noqa: BLE001
+                failure["example"] = kwargs
+                failure["error"] = str(exc)
+                raise AssertionError(
+                    f"post-condition raised: {exc}"
+                ) from exc
+            if not ok:
+                failure["example"] = kwargs
+                raise AssertionError(
+                    f"post-condition False on {kwargs} -> {result!r}",
+                )
+
+    try:
+        _runner()
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "schema_version": SCHEMA_VERSION_IFWC_V1,
+            "function": fn.__name__,
+            "verdict": "FAIL",
+            "examples_run": counter["n"],
+            "falsifying_example": failure["example"],
+            "error": str(exc),
+        }
+    return {
+        "schema_version": SCHEMA_VERSION_IFWC_V1,
+        "function": fn.__name__,
+        "verdict": "PASS",
+        "examples_run": counter["n"],
+        "falsifying_example": None,
+    }
+
+
+def fuzz_module(
+    module_name: str,
+    *,
+    max_examples: int = 100,
+) -> dict[str, Any]:
+    """Import ``module_name`` and fuzz every callable carrying invariants."""
+    mod = importlib.import_module(module_name)
+    results: list[dict[str, Any]] = []
+    for _name, obj in inspect.getmembers(mod):
+        if callable(obj) and hasattr(obj, "__invariants__"):
+            results.append(fuzz_callable(obj, max_examples=max_examples))
+    pass_n = sum(1 for r in results if r["verdict"] == "PASS")
+    fail_n = sum(1 for r in results if r["verdict"] == "FAIL")
+    return {
+        "schema_version": SCHEMA_VERSION_IFWC_V1,
+        "module": module_name,
+        "function_count": len(results),
+        "pass_count": pass_n,
+        "fail_count": fail_n,
+        "verdict": "PASS" if fail_n == 0 and pass_n > 0 else (
+            "FAIL" if fail_n else "EMPTY"
+        ),
+        "results": results,
+    }
+
+
+__all__ = ["SCHEMA_VERSION_IFWC_V1", "fuzz_callable", "fuzz_module"]

atomadic_forge-0.80.0/src/atomadic_forge/a1_at_functions/monadic_laws.py

@@ -0,0 +1,235 @@
+"""Tier a1 — Monadic Laws (v0.80): MCB / AHLP / AIOM checkers.
+
+Three pure deterministic AST scanners that surface the v7.0 blueprint
+laws without breaking existing repos:
+
+* :func:`scan_mcb`  — Monadic Compute Bounding: ban ``while`` and
+  recursion in tier-a1 modules.
+* :func:`fingerprint_a1` — AHLP-style SHA-256 of normalized AST
+  per a1 module. Tamper-evident receipts foundation.
+* :func:`scan_aiom` — Algebraic I/O Monad enforcer: forbid network /
+  process / socket imports from tier-a1 (the pure layer).
+
+All three are pure: AST-in, dict-out, no side effects.
+"""
+from __future__ import annotations
+
+import ast
+import hashlib
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION_MCB_V1 = "atomadic-forge.mcb/v1"
+SCHEMA_VERSION_AHLP_V1 = "atomadic-forge.ahlp.fingerprint/v1"
+SCHEMA_VERSION_AIOM_V1 = "atomadic-forge.aiom/v1"
+
+# Modules forbidden in tier-a1 (the pure mathematical layer).
+# Keep this list conservative — anything that talks to the OS,
+# network, or a subprocess. ``pathlib``/``json`` are allowed:
+# they're stdlib data shapers, not effect carriers.
+_AIOM_FORBIDDEN: frozenset[str] = frozenset({
+    "requests", "urllib", "urllib3", "httpx", "aiohttp",
+    "http", "socket", "smtplib", "ftplib", "telnetlib",
+    "subprocess", "multiprocessing",
+    "os.system", "os.popen", "shutil.move",  # checked via attribute walk
+})
+
+_AIOM_FORBIDDEN_PREFIX: tuple[str, ...] = (
+    "requests", "urllib", "urllib3", "httpx", "aiohttp",
+    "http.", "socket", "smtplib", "ftplib", "telnetlib",
+    "subprocess", "multiprocessing.",
+)
+
+A1_TIER_DIR = "a1_at_functions"
+
+
+# ── MCB ─────────────────────────────────────────────────────────────
+
+
+def _scan_one_for_while_recursion(path: Path) -> list[dict[str, Any]]:
+    """Return MCB violations in one file (empty list ⇒ clean)."""
+    findings: list[dict[str, Any]] = []
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return findings
+    func_names = {
+        n.name for n in ast.walk(tree)
+        if isinstance(n, ast.FunctionDef | ast.AsyncFunctionDef)
+    }
+    for node in ast.walk(tree):
+        if isinstance(node, ast.While):
+            findings.append({
+                "kind": "while_loop",
+                "line": node.lineno,
+                "detail": "unbounded `while` in pure-tier function",
+            })
+        elif isinstance(node, ast.Call):
+            # Direct recursion: `foo(...)` inside `def foo`.
+            f = node.func
+            if isinstance(f, ast.Name) and f.id in func_names:
+                # Walk up: are we inside a function with the same name?
+                # Cheap textual heuristic: only flag when name matches.
+                findings.append({
+                    "kind": "self_call",
+                    "line": node.lineno,
+                    "detail": f"possible recursion via `{f.id}(...)`",
+                })
+    return findings
+
+
+def scan_mcb(package_root: Path) -> dict[str, Any]:
+    """Scan ``<package_root>/a1_at_functions/`` for MCB violations.
+
+    Returns a structured report with verdict PASS / FAIL and the list
+    of files + findings. The report is advisory unless the caller
+    enforces it (e.g. ``forge wire --strict-mcb``).
+    """
+    pkg = Path(package_root)
+    a1_dir = pkg / A1_TIER_DIR
+    files: list[dict[str, Any]] = []
+    if a1_dir.is_dir():
+        for f in sorted(a1_dir.glob("*.py")):
+            if f.name == "__init__.py":
+                continue
+            findings = _scan_one_for_while_recursion(f)
+            if findings:
+                files.append({
+                    "file": str(f.relative_to(pkg)),
+                    "findings": findings,
+                })
+    total = sum(len(it["findings"]) for it in files)
+    return {
+        "schema_version": SCHEMA_VERSION_MCB_V1,
+        "package_root": str(pkg),
+        "violation_count": total,
+        "files": files,
+        "verdict": "PASS" if total == 0 else "FAIL",
+    }
+
+
+# ── AHLP fingerprint ────────────────────────────────────────────────
+
+
+def _normalized_ast_bytes(path: Path) -> bytes:
+    """Return a stable byte representation of the file's AST.
+
+    ``ast.dump`` with ``annotate_fields=True, include_attributes=False``
+    is reproducible across runs and stable to whitespace / comment
+    edits — which is exactly what we want for a tamper-evident
+    fingerprint of *logic*, not formatting.
+    """
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return b""
+    return ast.dump(tree, annotate_fields=True,
+                     include_attributes=False).encode("utf-8")
+
+
+def fingerprint_a1(package_root: Path) -> dict[str, Any]:
+    """SHA-256 every a1 module's normalized AST.
+
+    Returns ``{schema_version, package_root, count, fingerprints[]}``.
+    Each fingerprint entry: ``{file, sha256, ast_bytes_len}``.
+    """
+    pkg = Path(package_root)
+    a1_dir = pkg / A1_TIER_DIR
+    out: list[dict[str, Any]] = []
+    if a1_dir.is_dir():
+        for f in sorted(a1_dir.glob("*.py")):
+            if f.name == "__init__.py":
+                continue
+            ast_bytes = _normalized_ast_bytes(f)
+            if not ast_bytes:
+                continue
+            digest = hashlib.sha256(ast_bytes).hexdigest()
+            out.append({
+                "file": str(f.relative_to(pkg)),
+                "sha256": digest,
+                "ast_bytes_len": len(ast_bytes),
+            })
+    return {
+        "schema_version": SCHEMA_VERSION_AHLP_V1,
+        "package_root": str(pkg),
+        "count": len(out),
+        "fingerprints": out,
+    }
+
+
+# ── AIOM ────────────────────────────────────────────────────────────
+
+
+def _scan_one_for_io_imports(path: Path) -> list[dict[str, Any]]:
+    findings: list[dict[str, Any]] = []
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return findings
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if _is_forbidden(alias.name):
+                    findings.append({
+                        "kind": "import",
+                        "module": alias.name,
+                        "line": node.lineno,
+                    })
+        elif isinstance(node, ast.ImportFrom):
+            mod = node.module or ""
+            if _is_forbidden(mod):
+                findings.append({
+                    "kind": "from_import",
+                    "module": mod,
+                    "line": node.lineno,
+                })
+    return findings
+
+
+def _is_forbidden(modname: str) -> bool:
+    if not modname:
+        return False
+    if modname in _AIOM_FORBIDDEN:
+        return True
+    return any(modname == p.rstrip(".") or modname.startswith(p)
+                for p in _AIOM_FORBIDDEN_PREFIX)
+
+
+def scan_aiom(package_root: Path) -> dict[str, Any]:
+    """Scan ``<package_root>/a1_at_functions/`` for forbidden I/O imports.
+
+    Pure-tier modules cannot reach the network, processes, sockets, or
+    SMTP. The blocklist is conservative — ``pathlib``, ``json``,
+    ``hashlib`` etc. remain allowed because they're data shapers.
+    """
+    pkg = Path(package_root)
+    a1_dir = pkg / A1_TIER_DIR
+    files: list[dict[str, Any]] = []
+    if a1_dir.is_dir():
+        for f in sorted(a1_dir.glob("*.py")):
+            if f.name == "__init__.py":
+                continue
+            findings = _scan_one_for_io_imports(f)
+            if findings:
+                files.append({
+                    "file": str(f.relative_to(pkg)),
+                    "findings": findings,
+                })
+    total = sum(len(it["findings"]) for it in files)
+    return {
+        "schema_version": SCHEMA_VERSION_AIOM_V1,
+        "package_root": str(pkg),
+        "violation_count": total,
+        "files": files,
+        "verdict": "PASS" if total == 0 else "FAIL",
+    }
+
+
+__all__ = [
+    "SCHEMA_VERSION_AHLP_V1",
+    "SCHEMA_VERSION_AIOM_V1",
+    "SCHEMA_VERSION_MCB_V1",
+    "fingerprint_a1",
+    "scan_aiom",
+    "scan_mcb",
+]

{atomadic_forge-0.79.0 → atomadic_forge-0.80.0}/src/atomadic_forge/a4_sy_orchestration/cli.py

@@ -2744,6 +2744,18 @@ def _register_specialty_apps() -> None:
         # otherwise spend planning + dispatching each command.
         ("atomadic_forge.commands.replay", "replay",
          "Replay a golden recipe's validation_gate deterministically."),
+        # v0.80.0 — Monadic Laws (additive, advisory by default).
+        # Four read-only AST scanners that surface the v7.0 blueprint
+        # laws without breaking existing repos. Promote to default
+        # enforcement only after audit.
+        ("atomadic_forge.commands.mcb_check", "mcb-check",
+         "Surface MCB violations: unbounded `while`/recursion in a1."),
+        ("atomadic_forge.commands.aiom_check", "aiom-check",
+         "Surface AIOM violations: forbidden I/O imports in a1."),
+        ("atomadic_forge.commands.fingerprint", "fingerprint",
+         "Emit AHLP SHA-256 of every a1 module's normalized AST."),
+        ("atomadic_forge.commands.fuzz", "fuzz",
+         "IFWC-lite fuzzer: hypothesis cases on a1 __invariants__."),
         ("atomadic_forge.commands.emergent_swarm", "emergent-swarm",
          "Round-5: cross-repo emergent composition discovery."),
         ("atomadic_forge.commands.emergent_swarm", "emergent_swarm",

atomadic_forge-0.80.0/src/atomadic_forge/commands/_monadic_laws_shared.py

@@ -0,0 +1,46 @@
+"""Shared print/ledger helper for v0.80 monadic-law CLI verbs."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from atomadic_forge.a1_at_functions.lifetime_savings import append_savings
+
+TOKENS_SAVED_PER_A1_FILE = 40
+
+
+def emit_report(report: dict, *, json_out: bool, header: str,
+                project: Path, tool: str) -> None:
+    """Print a human or JSON report and log token savings to the ledger."""
+    file_count = (len(report.get("fingerprints") or [])
+                   if "fingerprints" in report
+                   else len(report.get("files") or []))
+    saved = file_count * TOKENS_SAVED_PER_A1_FILE
+    if saved > 0:
+        append_savings(project_root=project, tool=tool, tokens_saved=saved)
+        report["tokens_saved_estimate"] = saved
+    if json_out:
+        typer.echo(json.dumps(report, indent=2, default=str))
+        return
+    typer.echo("")
+    typer.echo(header)
+    typer.echo("-" * 60)
+    if "verdict" in report:
+        typer.echo(f"  verdict:        {report['verdict']}")
+        typer.echo(f"  violations:     {report.get('violation_count', 0)}")
+        for f in report.get("files", [])[:20]:
+            typer.echo(f"  • {f['file']}:")
+            for v in f["findings"][:5]:
+                line = v.get("line", "?")
+                detail = v.get("detail") or v.get("module") or v.get("kind")
+                typer.echo(f"      L{line}  {detail}")
+    else:
+        typer.echo(f"  count:          {report['count']}")
+        for fp in report["fingerprints"][:10]:
+            typer.echo(f"  {fp['sha256'][:16]}…  {fp['file']}")
+        if report["count"] > 10:
+            typer.echo(f"  … and {report['count'] - 10} more")
+    if "tokens_saved_estimate" in report:
+        typer.echo(f"  tokens saved:   ~{report['tokens_saved_estimate']:,}")

atomadic_forge-0.80.0/src/atomadic_forge/commands/aiom_check.py

@@ -0,0 +1,44 @@
+"""Tier a4 — `forge aiom-check` CLI: surface AIOM violations in tier-a1.
+
+Advisory by default; pass ``--fail-on-violations`` to enforce.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a1_at_functions.monadic_laws import scan_aiom
+from atomadic_forge.commands._monadic_laws_shared import emit_report
+
+COMMAND_NAME = "aiom-check"
+COMMAND_HELP = (
+    "Surface AIOM (Algebraic I/O Monad) violations: forbidden network / "
+    "subprocess / socket imports in tier-a1 pure functions."
+)
+
+app = typer.Typer(no_args_is_help=False, help=COMMAND_HELP)
+
+
+@app.callback(invoke_without_command=True)
+def run(
+    project: Annotated[Path, typer.Option(
+        "--project", "-p",
+        exists=True, file_okay=False, dir_okay=True,
+        resolve_path=True)] = Path("."),
+    package: Annotated[str, typer.Option(
+        "--package",
+        help="Importable package under src/.")] = "atomadic_forge",
+    fail_on_violations: Annotated[bool, typer.Option(
+        "--fail-on-violations",
+        help="Exit non-zero when violations exist.")] = False,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Scan tier-a1 for forbidden I/O imports."""
+    pkg_root = project / "src" / package
+    report = scan_aiom(pkg_root)
+    emit_report(report, json_out=json_out, header=f"AIOM — {package}",
+                 project=project, tool="aiom-check")
+    if fail_on_violations and report["verdict"] != "PASS":
+        raise typer.Exit(1)

atomadic_forge-0.80.0/src/atomadic_forge/commands/fingerprint.py

@@ -0,0 +1,39 @@
+"""Tier a4 — `forge fingerprint` CLI: AHLP SHA-256 of every a1 module's
+normalized AST. Tamper-evident receipts foundation.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a1_at_functions.monadic_laws import fingerprint_a1
+from atomadic_forge.commands._monadic_laws_shared import emit_report
+
+COMMAND_NAME = "fingerprint"
+COMMAND_HELP = (
+    "Emit AHLP SHA-256 fingerprints per a1 module's normalized AST. "
+    "Stable across whitespace/comments; sensitive to logic changes."
+)
+
+app = typer.Typer(no_args_is_help=False, help=COMMAND_HELP)
+
+
+@app.callback(invoke_without_command=True)
+def run(
+    project: Annotated[Path, typer.Option(
+        "--project", "-p",
+        exists=True, file_okay=False, dir_okay=True,
+        resolve_path=True)] = Path("."),
+    package: Annotated[str, typer.Option(
+        "--package",
+        help="Importable package under src/.")] = "atomadic_forge",
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Print SHA-256 fingerprints of every a1 module's normalized AST."""
+    pkg_root = project / "src" / package
+    report = fingerprint_a1(pkg_root)
+    emit_report(report, json_out=json_out,
+                 header=f"AHLP fingerprint — {package}",
+                 project=project, tool="fingerprint")

atomadic_forge-0.80.0/src/atomadic_forge/commands/fuzz.py

@@ -0,0 +1,79 @@
+"""Tier a4 — `forge fuzz` CLI: IFWC-lite property-based fuzzer.
+
+Targets any tier-a1 callable carrying ``__invariants__`` metadata.
+Each fuzz pass logs ``examples_run × ~5`` tokens to the lifetime
+ledger as ``fuzz/<module>`` (these are LLM round-trips a manual
+property-test campaign would have spent).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a1_at_functions.ifwc_fuzz import fuzz_module
+from atomadic_forge.a1_at_functions.lifetime_savings import append_savings
+
+COMMAND_NAME = "fuzz"
+COMMAND_HELP = (
+    "Fuzz tier-a1 callables that carry an `__invariants__` marker. "
+    "Pure-stdlib + hypothesis. Opt-in per function."
+)
+
+app = typer.Typer(no_args_is_help=False, help=COMMAND_HELP)
+
+
+@app.callback(invoke_without_command=True)
+def run(
+    module: Annotated[str, typer.Argument(
+        help="Importable module to fuzz, e.g. atomadic_forge.a1_at_functions.foo")],
+    project: Annotated[Path, typer.Option(
+        "--project", "-p",
+        exists=True, file_okay=False, dir_okay=True,
+        resolve_path=True)] = Path("."),
+    max_examples: Annotated[int, typer.Option(
+        "--max-examples", "-n",
+        help="Hypothesis examples per function.")] = 100,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Fuzz every callable in ``module`` that exposes ``__invariants__``."""
+    try:
+        report = fuzz_module(module, max_examples=max_examples)
+    except (ImportError, ModuleNotFoundError) as exc:
+        typer.secho(f"forge fuzz: cannot import {module}: {exc}",
+                     fg="red", err=True)
+        raise typer.Exit(2) from exc
+
+    # Each example survived ≈ 5 tokens of LLM property-reasoning saved.
+    examples_total = sum(int(r.get("examples_run", 0))
+                          for r in report.get("results", []))
+    saved = examples_total * 5
+    if saved > 0:
+        append_savings(project_root=project, tool=f"fuzz/{module}",
+                        tokens_saved=saved)
+        report["tokens_saved_estimate"] = saved
+
+    if json_out:
+        typer.echo(json.dumps(report, indent=2, default=str))
+        if report["verdict"] == "FAIL":
+            raise typer.Exit(1)
+        return
+
+    typer.echo("")
+    typer.echo(f"IFWC fuzz — {module}")
+    typer.echo("-" * 60)
+    typer.echo(f"  verdict:        {report['verdict']}")
+    typer.echo(f"  functions:      {report['function_count']}  "
+               f"(pass {report['pass_count']} / fail {report['fail_count']})")
+    for r in report.get("results", []):
+        line = f"  • {r['function']}  [{r['verdict']}]  ({r.get('examples_run', 0)} cases)"
+        typer.echo(line)
+        if r["verdict"] == "FAIL" and r.get("falsifying_example") is not None:
+            typer.secho(f"      falsifying: {r['falsifying_example']}",
+                          fg="red")
+    if "tokens_saved_estimate" in report:
+        typer.echo(f"  tokens saved:   ~{report['tokens_saved_estimate']:,}")
+    if report["verdict"] == "FAIL":
+        raise typer.Exit(1)