fluidfix 0.1.0__py3-none-any.whl

fluidfix/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 devkancheti4-design
+"""fluidfix — zero-token repair decisions for mechanical single-line bugs.
+
+    from fluidfix import Oracle, build_packet, MechanicalObserver, repair
+
+    oracle = Oracle("path/to/project", python="path/to/venv/bin/python")
+    packet = build_packet(oracle, "pkg/module.py")
+    observations = MechanicalObserver().observe([packet])[0]
+    result = repair(oracle, "pkg/module.py", observations)
+    print(result.summary())
+"""
+from .acts import (ACTS, KINDS, WORKED_EXAMPLE, Observation, act_for, apply,
+                   register)
+from .guard import (GuardReport, commit_repair, find_candidate_files,
+                    guard_once, write_refusal)
+from .lanes import ADVANCE, EMIT, HALT, kind_of, mask_of
+from .localize import Packet, build_packet
+from .loop import RepairResult, repair
+from .observers import ClaudeObserver, MechanicalObserver, observer_prompt
+from .oracle import Oracle
+from .router import pack, route, route_packed
+
+__version__ = "0.1.0"
+__all__ = [
+    "route", "route_packed", "pack",
+    "EMIT", "ADVANCE", "HALT", "mask_of", "kind_of",
+    "Observation", "KINDS", "ACTS", "WORKED_EXAMPLE", "act_for", "apply",
+    "register",
+    "Oracle", "Packet", "build_packet",
+    "MechanicalObserver", "ClaudeObserver", "observer_prompt",
+    "repair", "RepairResult",
+    "GuardReport", "guard_once", "find_candidate_files", "commit_repair",
+    "write_refusal",
+]

fluidfix/acts.py

@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 devkancheti4-design
+# Commercial licensing: see COMMERCIAL.md.
+"""The act vocabulary: fault kinds, repairs, and the observation contract.
+
+One structure defines each kind's meaning; the mechanical observer's regexes,
+the LLM observer's prompt, and the appliers all derive from it. The router
+never sees any of this — it maps kind -> act code from one worked example.
+
+Observations may carry "clear data" pointers that sharpen the applier without
+touching the router:
+
+  literal_value/-occurrence  which numeric literal is wrong (kind 1). On the
+      benchmark corpus this alone took in-vocabulary exact repairs from 17/27
+      (first-literal heuristic) to 26/27.
+  op_occurrence  which additive operator is flipped (kind 3), counting binary
+      " + "/" - " left to right, 1-based. Closes the remaining measured miss:
+      a line carrying both a `+` and the faulty `-`.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+__all__ = ["Observation", "KINDS", "ACTS", "WORKED_EXAMPLE", "apply", "act_for"]
+
+from .router import route
+
+# The single mapping supplied to the router; every other act is inferred.
+WORKED_EXAMPLE = (0, 5)
+
+
+@dataclass
+class Observation:
+    """What an observer reports. Never a fix, never an act code."""
+    lineno: int                      # 1-based line in the defect file
+    kinds: list[int] = field(default_factory=list)   # most specific first; [] = refuse
+    literal_value: str | None = None
+    literal_occurrence: int | None = None
+    op_occurrence: int | None = None
+    note: str = ""
+
+
+# kind -> (name, description used verbatim in observer prompts, line-signal regex)
+KINDS = {
+    0: ("strictness",
+        'a token containing < or > has one "=" too many or too few '
+        '(a ">=" that should be ">", a "<" that should be "<=", an "->" '
+        'corrupted to "->=", including inside strings)',
+        re.compile(r"[<>]=?")),
+    1: ("literal-off-by-one",
+        "a numeric literal on the line is exactly one greater than correct "
+        "(3601 for 3600, [2:] for [1:], group(2) for group(1))",
+        re.compile(r"\d")),
+    2: ("swapped-return-operands",
+        'a "return a OP b" whose two operands are in the wrong order',
+        re.compile(r"^\s*return\s+.*\s(?://|[-+*])\s")),
+    3: ("flipped-additive",
+        'a binary " + " that should be " - ", or a " - " that should be '
+        '" + " (spaces around the operator)',
+        re.compile(r"\s[-+]\s")),
+}
+
+
+def _flip_strictness(line: str, obs: Observation) -> str:
+    for a, b in ((">=", ">"), ("<=", "<")):
+        if a in line:
+            return line.replace(a, b, 1)
+    for a, b in ((">", ">="), ("<", "<=")):
+        if a in line:
+            return line.replace(a, b, 1)
+    return line
+
+
+def _reduce_literal(line: str, obs: Observation) -> str:
+    m = None
+    if obs.literal_value:
+        hits = [h for h in re.finditer(r"\d+", line) if h.group() == str(obs.literal_value)]
+        occ = max(1, obs.literal_occurrence or 1)
+        if len(hits) >= occ:
+            m = hits[occ - 1]
+    if m is None:
+        m = re.search(r"\d+", line)
+    if not m:
+        return line
+    new_lit = str(int(m.group()) - 1)
+    out = line[:m.start()] + new_lit + line[m.end():]
+    # Simplify `x + 1` -> decrement -> `x + 0` -> `x`, but ONLY at the
+    # decrement site, and only when the zero stands alone: a global
+    # unanchored sub was measured to eat an unrelated `-0.5` elsewhere on
+    # the line while the suite still passed.
+    if new_lit == "0" and not re.match(r"[0-9.eEjJxXbBoO_]", line[m.end():m.end() + 1] or " "):
+        pre = re.search(r"\s*[+-]\s*$", line[:m.start()])
+        if pre:
+            out = line[:pre.start()] + line[m.end():]
+    return out
+
+
+def _swap_return_operands(line: str, obs: Observation) -> str:
+    m = re.match(r"^(\s*return\s+)(.*?)(\s(?://|[-+*])\s)(.*)$", line)
+    return line if not m else f"{m.group(1)}{m.group(4)}{m.group(3)}{m.group(2)}"
+
+
+def _flip_additive(line: str, obs: Observation) -> str:
+    # Deliberate divergence from kdebug's substring match: \s admits tabs and
+    # non-overlapping scanning skips a "+" that shares a space with a
+    # preceding "-" (`a - + b`). fluidfix attempts strictly more candidates
+    # on those whitespace edge cases; the suite remains the judge.
+    ops = list(re.finditer(r"\s([+-])\s", line))
+    if not ops:
+        return line
+    if obs.op_occurrence and 1 <= obs.op_occurrence <= len(ops):
+        m = ops[obs.op_occurrence - 1]
+    else:
+        # legacy first-match heuristic, kept for observers with no pointer
+        m = next((o for o in ops if o.group(1) == "+"), ops[0])
+    flipped = "-" if m.group(1) == "+" else "+"
+    return line[:m.start(1)] + flipped + line[m.end(1):]
+
+
+# act code -> applier; codes are one translation of the vocabulary. Renumber
+# them freely — the router recovers the offset from WORKED_EXAMPLE each call.
+ACTS = {
+    5: _flip_strictness,
+    6: _reduce_literal,
+    7: _swap_return_operands,
+    8: _flip_additive,
+}
+
+
+def act_for(kind: int) -> int:
+    """The router's decision: kind -> act code, from the one worked example."""
+    return route(WORKED_EXAMPLE[0], WORKED_EXAMPLE[1], kind)
+
+
+def register(kind: int, name: str, description: str, signal,
+             applier) -> int:
+    """Teach fluidfix a new fault class. One entry, one transform — the router
+    is untouched: it infers this kind's act code from the same single worked
+    example, so a new class costs exactly one registration, once, and every
+    future member of the class is decided for free.
+
+    kind: 0-15 (the kernel's domain — one dictionary holds 16 classes).
+    signal: compiled regex a line must match for the mechanical observer to
+        report this kind (LLM observers receive `description` verbatim).
+    applier(line, observation) -> candidate line.
+    Returns the act code the router assigned.
+    """
+    if not 0 <= kind <= 15:
+        raise ValueError("kind must be 0..15 — the kernel routes mod 16")
+    code = act_for(kind)
+    KINDS[kind] = (name, description, signal)
+    ACTS[code] = applier
+    return code
+
+
+def apply(line: str, act: int, obs: Observation) -> str:
+    """Apply an act to a line. Unknown acts are a no-op (NOPROGRESS upstream)."""
+    fn = ACTS.get(act)
+    return line if fn is None else fn(line, obs)

fluidfix/cli.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 devkancheti4-design
+# Commercial licensing: see COMMERCIAL.md.
+"""fluidfix CLI.
+
+  fluidfix guard ROOT [--interval 900] [--commit] [--observer mechanical|claude]
+  fluidfix repair ROOT --file pkg/mod.py [--python VENV_PY] [--observer mechanical|claude]
+  fluidfix packet ROOT --file pkg/mod.py [--python VENV_PY]
+  fluidfix selfcheck
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _oracle(args):
+    from .oracle import Oracle
+    return Oracle(args.root, python=args.python,
+                  timeout=args.suite_timeout,
+                  per_test_timeout=args.test_timeout)
+
+
+def cmd_repair(args) -> int:
+    from .localize import build_packet
+    from .loop import repair
+    oracle = _oracle(args)
+    packet = build_packet(oracle, args.file, coverage_target=args.cov)
+    if packet is None:
+        print("suite is green — nothing to repair (refusing to search)")
+        return 3
+    if args.observer == "claude":
+        from .observers import ClaudeObserver
+        obs = ClaudeObserver(model=args.model)
+        observations = obs.observe([packet])[0]
+        if obs.last_usage is not None:
+            u = obs.last_usage
+            print(f"observer usage: in={u.input_tokens} out={u.output_tokens}",
+                  file=sys.stderr)
+    else:
+        from .observers import MechanicalObserver
+        observations = MechanicalObserver().observe([packet])[0]
+    result = repair(oracle, args.file, observations,
+                    candidate_timeout=args.candidate_timeout)
+    if args.json:
+        print(json.dumps(result.__dict__, default=str, indent=1))
+    else:
+        print(result.summary())
+    return 0 if result.repaired else 2
+
+
+def _observer(args):
+    if args.observer == "claude":
+        from .observers import ClaudeObserver
+        return ClaudeObserver(model=args.model)
+    from .observers import MechanicalObserver
+    return MechanicalObserver()
+
+
+def cmd_guard(args) -> int:
+    import time as _time
+    from .guard import commit_repair, guard_once, write_refusal
+    oracle = _oracle(args)
+    observer = _observer(args)
+    while True:
+        report = guard_once(oracle, observer, coverage_target=args.cov,
+                            candidate_timeout=args.candidate_timeout)
+        print(f"[{_time.strftime('%H:%M:%S')}] {report.summary()}")
+        if report.status == "repaired" and args.commit:
+            print("  committed" if commit_repair(oracle.root, report)
+                  else "  commit failed — repair left in working tree")
+        if report.status == "refused":
+            print(f"  refusal report: {write_refusal(oracle.root, report)}")
+        if args.interval is None:
+            return 0 if report.status in ("green", "repaired") else 2
+        _time.sleep(args.interval)
+
+
+def cmd_packet(args) -> int:
+    from .localize import build_packet
+    packet = build_packet(_oracle(args), args.file, coverage_target=args.cov)
+    if packet is None:
+        print("suite is green — no packet")
+        return 3
+    print(packet.render())
+    return 0
+
+
+def cmd_selfcheck(args) -> int:
+    """Re-derive the shipped laws from scratch. No network, no dependencies."""
+    from .lanes import ADVANCE, EMIT, HALT
+    from .router import route
+
+    bad = 0
+    for F1 in range(16):
+        for A1 in range(16):
+            for Fq in range(16):
+                want = (Fq + A1 - F1) % 16
+                bad += route(F1, A1, Fq) != want
+    print(f"router vs reference, all 4096 (F1,A1,Fq): {4096 - bad}/4096")
+
+    ident = sum(route(F1, A1, F1) != A1 for F1 in range(16) for A1 in range(16))
+    print(f"identity route(F1,A1,F1)==A1:               {256 - ident}/256")
+
+    comp = sum(route(0, o2, route(0, o1, q)) != (q + o1 + o2) % 16
+               for o1 in range(16) for o2 in range(16) for q in range(16))
+    print(f"composition route(o2, route(o1, q)):        {4096 - comp}/4096")
+
+    lane_bad = 0
+    for m in range(256):
+        if m and EMIT(m) != (m & -m):
+            lane_bad += 1
+        if m and ADVANCE(m) >= m:
+            lane_bad += 1
+        if HALT(m) != (1 if m == 0 else 0):
+            lane_bad += 1
+    print(f"lanes: EMIT/ADVANCE/HALT on 256 states:     {'0 wrong' if not lane_bad else f'{lane_bad} WRONG'}")
+
+    steps = 0
+    for m in range(256):
+        w = m
+        while not HALT(w):
+            w = ADVANCE(w)
+            steps += 1
+            assert steps < 4096, "ADVANCE failed to reduce"
+    print(f"termination: every mask drains ({steps} total steps)")
+    print("SELFCHECK PASS" if not (bad or ident or comp or lane_bad) else "SELFCHECK FAIL")
+    return 0 if not (bad or ident or comp or lane_bad) else 1
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="fluidfix", description=__doc__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp, need_file=True):
+        sp.add_argument("root", help="target project root (where pytest runs)")
+        if need_file:
+            sp.add_argument("--file", required=True,
+                            help="defect file, relative to root")
+        sp.add_argument("--python", default=None,
+                        help="target project's python (default: this one)")
+        sp.add_argument("--cov", default=None,
+                        help="coverage target package (default: inferred)")
+        sp.add_argument("--suite-timeout", type=int, default=300,
+                        help="full-suite budget in seconds (default 300)")
+        sp.add_argument("--test-timeout", type=int, default=60,
+                        help="per-test pytest-timeout in seconds (default 60)")
+
+    sp = sub.add_parser("guard", help="commit-and-forget maintenance: watch "
+                        "the suite, restore what breaks, refuse what is novel")
+    common(sp, need_file=False)
+    sp.add_argument("--observer", choices=["mechanical", "claude"],
+                    default="mechanical")
+    sp.add_argument("--model", default="claude-opus-5")
+    sp.add_argument("--candidate-timeout", type=int, default=None,
+                    help="per-candidate suite budget (default: --suite-timeout)")
+    sp.add_argument("--interval", type=int, default=None,
+                    help="seconds between checks; omit for one pass (CI mode)")
+    sp.add_argument("--commit", action="store_true",
+                    help="git-commit each restoration (only the repaired file)")
+    sp.set_defaults(fn=cmd_guard)
+
+    sp = sub.add_parser("repair", help="localise, observe, and repair one defect")
+    common(sp)
+    sp.add_argument("--observer", choices=["mechanical", "claude"],
+                    default="mechanical")
+    sp.add_argument("--model", default="claude-opus-5")
+    sp.add_argument("--candidate-timeout", type=int, default=None,
+                    help="per-candidate suite budget (default: --suite-timeout)")
+    sp.add_argument("--json", action="store_true")
+    sp.set_defaults(fn=cmd_repair)
+
+    sp = sub.add_parser("packet", help="print the lean observation packet")
+    common(sp)
+    sp.set_defaults(fn=cmd_packet)
+
+    sp = sub.add_parser("selfcheck", help="re-verify the shipped laws exhaustively")
+    sp.set_defaults(fn=cmd_selfcheck)
+
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fluidfix/guard.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 devkancheti4-design
+# Commercial licensing: see COMMERCIAL.md.
+"""The guard: commit-and-forget maintenance.
+
+    green  -> touch nothing, sleep
+    red    -> find the fault file mechanically, localise, observe, route,
+              repair — the repo goes back to what it was meant to be
+    novel  -> refuse LOUDLY (a machine-readable refusal report), tree
+              untouched; teaching the class once (register(), or a compiled
+              dictionary) makes its whole family free from then on
+
+Fault-file discovery is mechanical: source files quoted in the failing
+traceback (deepest frame preferred, test files excluded), falling back to the
+files the failing test executed most, ranked by coverage. No model is needed
+to find the file — only, optionally, to name the fault kind.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass, field
+
+from .localize import build_packet
+from .loop import RepairResult, repair
+from .oracle import Oracle
+
+__all__ = ["GuardReport", "find_candidate_files", "guard_once"]
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+@dataclass
+class GuardReport:
+    status: str                       # "green" | "repaired" | "refused"
+    file: str | None = None
+    result: RepairResult | None = None
+    candidates: list[str] = field(default_factory=list)
+    seconds: float = 0.0
+
+    def summary(self) -> str:
+        if self.status == "green":
+            return "suite green — nothing to do"
+        if self.status == "repaired":
+            return f"{self.file}: {self.result.summary()}"
+        return ("REFUSED: fault is outside the taught vocabulary "
+                f"(candidate files tried: {', '.join(self.candidates) or 'none found'}). "
+                "Teach the class once — register() an observation + transform — "
+                "and its whole family becomes free.")
+
+
+def _is_test_path(rel: str) -> bool:
+    parts = rel.replace("\\", "/").split("/")
+    base = parts[-1]
+    return (base.startswith("test_") or base.endswith("_test.py")
+            or "tests" in parts[:-1] or base == "conftest.py")
+
+
+def find_candidate_files(oracle: Oracle, failing_output: str,
+                         limit: int = 3) -> list[str]:
+    """Project source files implicated by the failure, most suspect first."""
+    clean = _ANSI.sub("", failing_output)
+    ordered: list[str] = []
+    for m in re.finditer(r"([\w./\\-]+\.py)[\":,]", clean):
+        p = m.group(1).replace("\\", "/")
+        full = p if os.path.isabs(p) else os.path.join(oracle.root, p)
+        full = os.path.normpath(full)
+        if not full.startswith(oracle.root + os.sep) or not os.path.isfile(full):
+            continue
+        rel = os.path.relpath(full, oracle.root).replace("\\", "/")
+        if _is_test_path(rel):
+            continue
+        # deepest (latest) traceback frame is closest to the fault
+        if rel in ordered:
+            ordered.remove(rel)
+        ordered.append(rel)
+    ordered.reverse()
+    if ordered:
+        return ordered[:limit]
+    # no source frames (pure assertion failure): rank by the failing test's
+    # own coverage — run recorded by the caller's failing_output(), so --lf
+    # re-runs exactly it. No -x: exit-first suppresses the JSON report.
+    cov_json = os.path.join(oracle.root, "_fluidfix_guard_cov.json")
+    oracle.run(["--lf", "--tb=no", "--cov=.",
+                f"--cov-report=json:{cov_json}"], cache=True)
+    ranked: list[tuple[int, str]] = []
+    if os.path.exists(cov_json):
+        try:
+            cov = json.load(open(cov_json))
+            for f, data in cov.get("files", {}).items():
+                rel = f.replace("\\", "/")
+                if _is_test_path(rel) or not rel.endswith(".py"):
+                    continue
+                ranked.append((len(data.get("executed_lines", [])), rel))
+        finally:
+            os.remove(cov_json)
+    ranked.sort(reverse=True)
+    return [rel for _, rel in ranked[:limit]]
+
+
+def guard_once(oracle: Oracle, observer, files: list[str] | None = None,
+               coverage_target: str | None = None,
+               candidate_timeout: int | None = None) -> GuardReport:
+    t0 = time.time()
+    fails, out = oracle.failing_output()
+    if not fails:
+        return GuardReport(status="green", seconds=time.time() - t0)
+    candidates = files or find_candidate_files(oracle, out)
+    for rel in candidates:
+        packet = build_packet(oracle, rel, coverage_target=coverage_target)
+        if packet is None:
+            continue
+        observations = observer.observe([packet])[0]
+        result = repair(oracle, rel, observations,
+                        candidate_timeout=candidate_timeout)
+        if result.repaired:
+            return GuardReport(status="repaired", file=rel, result=result,
+                               candidates=candidates,
+                               seconds=time.time() - t0)
+    return GuardReport(status="refused", candidates=candidates,
+                       seconds=time.time() - t0)
+
+
+def commit_repair(root: str, report: GuardReport) -> bool:
+    """Opt-in: commit a successful restoration. Only the repaired file."""
+    if report.status != "repaired":
+        return False
+    r = report.result
+    msg = (f"fluidfix: restore {report.file}:{r.lineno}\n\n"
+           f"- {r.old_line.strip()}\n+ {r.new_line.strip()}\n\n"
+           f"Routed by the fluidfix kernel ({r.reason}); accepted by the "
+           f"project's own suite in {r.suite_runs} runs.")
+    try:
+        subprocess.run(["git", "-C", root, "add", "--", report.file],
+                       check=True, capture_output=True, timeout=30)
+        subprocess.run(["git", "-C", root, "commit", "-m", msg],
+                       check=True, capture_output=True, timeout=30)
+        return True
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired,
+            FileNotFoundError):
+        return False
+
+
+def write_refusal(root: str, report: GuardReport) -> str:
+    """A machine-readable teach-me signal, written where CI can pick it up."""
+    d = os.path.join(root, ".fluidfix")
+    os.makedirs(d, exist_ok=True)
+    path = os.path.join(d, "last_refusal.json")
+    json.dump({"status": report.status, "candidates": report.candidates,
+               "seconds": report.seconds,
+               "hint": "fault class is outside the taught vocabulary; "
+                       "register() it once and its family becomes free"},
+              open(path, "w"), indent=1)
+    return path

fluidfix/lanes.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 devkancheti4-design
+# Commercial licensing: see COMMERCIAL.md.
+"""Loop discipline — vendored unchanged from fluid-router2
+(https://github.com/devkancheti4-design/fluid-router2).
+
+Three machine-authored expressions drive every repair loop. `ADVANCE` strictly
+reduces a live mask, which is what makes the loop a solver rather than a
+classifier: it terminates on all 256 mask states (verified exhaustively in
+fluid-router2's `verify.c`, re-verified by this package's test suite).
+
+  EMIT     which fault to handle next (the lowest live bit)
+  ADVANCE  clear it and keep going
+  HALT     nothing left — 1 iff the mask is empty
+"""
+
+__all__ = ["EMIT", "ADVANCE", "HALT", "mask_of", "kind_of"]
+
+
+def EMIT(m: int) -> int:
+    return m & (-m)
+
+
+def ADVANCE(m: int) -> int:
+    return m - (m & (-m))
+
+
+def HALT(m: int) -> int:
+    # 32-bit semantics of ((m - (m - 1)) + ((-m) >> 31)): 1 iff m == 0.
+    if m == 0:
+        return 1
+    return (m - (m - 1)) + (-1 if -m < 0 else 0)
+
+
+def mask_of(kinds) -> int:
+    """A live mask with one bit per fault kind."""
+    m = 0
+    for k in kinds:
+        m |= 1 << k
+    return m
+
+
+def kind_of(emitted: int) -> int:
+    """The kind number of an EMITted bit."""
+    return emitted.bit_length() - 1