costwright 0.1.0__py3-none-any.whl

costwright/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

costwright/caps.py

@@ -0,0 +1,157 @@
+"""costwright caps — detección de constructores LLM sin cap de tokens + sugerencia por provider.
+
+La tabla provider→parámetro proviene de §3.2 del paper (verificada contra docs primarias jun-2026):
+el cap correcto es PARAMETER-specific, no provider-specific. NUNCA edita archivos: emite hallazgos
+y, con --patch, un unified diff aplicable con `git apply` (decisión del council 002: P0-2).
+"""
+import ast
+import difflib
+from pathlib import Path
+
+# constructor → (provider, kwarg correcto, nota de degradación si aplica)
+# Fuente: paper §3.2, docs primarias accedidas jun-2026.
+PROVIDER_CAPS = {
+    # OpenAI / Azure (langchain + SDKs): chat completions usa max_tokens (no-reasoning) o
+    # max_completion_tokens (reasoning); Responses API usa max_output_tokens.
+    "ChatOpenAI":        ("openai",    "max_tokens",        "reasoning models: usar max_completion_tokens (Chat) / max_output_tokens (Responses)"),
+    "AzureChatOpenAI":   ("azure",     "max_tokens",        "reasoning models: max_completion_tokens — reasoning_tokens ⊆ completion_tokens (cap REAL)"),
+    "OpenAI":            ("openai",    "max_output_tokens", "Responses API: bounds reasoning+output"),
+    # Anthropic
+    "ChatAnthropic":     ("anthropic", "max_tokens",        "standard: budget_tokens < max_tokens ⟹ techo real. interleaved/adaptive thinking: el budget puede EXCEDER max_tokens (cap degrada)"),
+    "Anthropic":         ("anthropic", "max_tokens",        "ídem ChatAnthropic"),
+    # Google
+    "ChatGoogleGenerativeAI": ("gemini", "max_output_tokens", "thinking on: fijar TAMBIÉN thinking_budget — maxOutputTokens NO acota thinking (se factura aparte)"),
+    "ChatVertexAI":      ("gemini",    "max_output_tokens", "ídem Gemini"),
+    # otros (langchain)
+    "ChatBedrock":       ("bedrock",   "max_tokens",        "replica la semántica Anthropic en modelos Claude"),
+    "ChatGroq":          ("groq",      "max_tokens",        None),
+    "ChatMistralAI":     ("mistral",   "max_tokens",        None),
+    "ChatOllama":        ("ollama",    "num_predict",       "Ollama usa num_predict, no max_tokens"),
+    "init_chat_model":   ("generic",   "max_tokens",        "el kwarg efectivo depende del provider resuelto en runtime — verificar"),
+    "LLM":               ("crewai",    "max_tokens",        "CrewAI LLM wrapper"),
+}
+CAP_KWARGS = {"max_tokens", "max_output_tokens", "max_completion_tokens", "budget_tokens",
+              "max_tokens_to_sample", "maxOutputTokens", "num_predict", "thinking_budget"}
+EXCLUDE_DIRS = {".venv", "venv", "node_modules", "site-packages", ".git", "__pycache__"}
+
+
+def call_name(n: ast.Call) -> str:
+    f = n.func
+    if isinstance(f, ast.Name):
+        return f.id
+    if isinstance(f, ast.Attribute):
+        return f.attr
+    return ""
+
+
+def scan_file(path: Path):
+    """Devuelve CapFindings: constructores LLM sin ningún cap kwarg."""
+    try:
+        src = path.read_text(encoding="utf-8", errors="ignore")
+        tree = ast.parse(src)
+    except (SyntaxError, OSError):
+        return [], None
+    findings = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        name = call_name(node)
+        if name not in PROVIDER_CAPS:
+            continue
+        kwargs_present = {k.arg for k in node.keywords if k.arg}
+        provider, kwarg, note = PROVIDER_CAPS[name]
+        # detección best-effort de reasoning model por el kwarg `model` (audit-3 gpt-5.5 P0):
+        # en Chat API los o-series/GPT-5 ignoran max_tokens; el cap real es max_completion_tokens
+        model_val = next((k.value.value for k in node.keywords
+                          if k.arg == "model" and isinstance(k.value, ast.Constant)
+                          and isinstance(k.value.value, str)), "")
+        reasoning = any(model_val.startswith(p) for p in
+                        ("o1", "o3", "o4", "gpt-5")) if model_val else False
+        # SOLO Chat-API constructors (audit-3 R2 gpt-5.5): el constructor `OpenAI` es
+        # Responses API y su cap correcto sigue siendo max_output_tokens, reasoning o no
+        if name in ("ChatOpenAI", "AzureChatOpenAI") and reasoning:
+            kwarg = "max_completion_tokens"
+            note = "reasoning model en Chat API: max_tokens es IGNORADO; usar max_completion_tokens"
+        if kwargs_present & CAP_KWARGS:
+            # tiene algún cap — chequear degradaciones conocidas (§3.2)
+            if provider == "gemini" and "thinking_budget" not in kwargs_present:
+                findings.append({
+                    "kind": "degraded", "constructor": name, "provider": provider,
+                    "line": node.lineno, "have": sorted(kwargs_present & CAP_KWARGS),
+                    "suggest_kwarg": "thinking_budget",
+                    "why": "Gemini: maxOutputTokens NO acota thinking tokens (se facturan como output); fijar thinking_budget",
+                })
+            elif provider in ("anthropic", "bedrock"):
+                # audit-3 (gemini P0): Anthropic con cap igual degrada bajo interleaved/adaptive
+                findings.append({
+                    "kind": "degraded", "constructor": name, "provider": provider,
+                    "line": node.lineno, "have": sorted(kwargs_present & CAP_KWARGS),
+                    "suggest_kwarg": None,
+                    "why": "Anthropic: con interleaved/adaptive thinking el budget puede EXCEDER max_tokens — el techo solo vale en modo standard (budget_tokens < max_tokens)",
+                })
+            elif name in ("ChatOpenAI", "AzureChatOpenAI") and reasoning and "max_completion_tokens" not in kwargs_present:
+                findings.append({
+                    "kind": "degraded", "constructor": name, "provider": provider,
+                    "line": node.lineno, "have": sorted(kwargs_present & CAP_KWARGS),
+                    "suggest_kwarg": "max_completion_tokens",
+                    "why": "reasoning model: max_tokens es ignorado en Chat API; el techo real es max_completion_tokens",
+                })
+            continue
+        findings.append({
+            "kind": "missing", "constructor": name, "provider": provider,
+            "line": node.lineno, "suggest_kwarg": kwarg, "note": note,
+        })
+    return findings, src
+
+
+def make_patch(path: Path, src: str, findings, cap_value: int) -> str:
+    """Unified diff que agrega `kwarg=cap_value` a cada constructor sin cap.
+    Edición textual mínima: insertar el kwarg tras el paréntesis de apertura del call.
+    NUNCA escribe el archivo — solo el diff (council 002 P0-2)."""
+    lines = src.splitlines(keepends=True)
+    new_lines = list(lines)
+    # de abajo hacia arriba para no correr line numbers
+    for f in sorted((f for f in findings if f["kind"] == "missing"),
+                    key=lambda x: -x["line"]):
+        i = f["line"] - 1
+        if i >= len(new_lines):
+            continue
+        line = new_lines[i]
+        ctor = f["constructor"]
+        # audit-3 (gemini P0): si hay >1 ocurrencia del constructor en la línea, NO parchear
+        # (la inserción textual no sabe cuál es cuál) — conservador, el hallazgo igual se reporta
+        if line.count(ctor + "(") != 1:
+            continue
+        idx = line.find(ctor + "(")
+        if idx < 0:
+            continue  # constructor multilínea: skip (conservador)
+        insert_at = idx + len(ctor) + 1
+        rest = line[insert_at:]
+        sep = "" if rest.lstrip().startswith(")") else ", "
+        new_lines[i] = line[:insert_at] + f"{f['suggest_kwarg']}={cap_value}{sep}" + rest
+    if new_lines == lines:
+        return ""
+    rel = str(path)
+    return "".join(difflib.unified_diff(lines, new_lines,
+                                        fromfile=f"a/{rel}", tofile=f"b/{rel}"))
+
+
+def scan_path(root: Path, max_files: int = 5000):
+    """Escanea un árbol; devuelve (findings_por_archivo, n_escaneados)."""
+    out = {}
+    n = 0
+    for py in sorted(root.rglob("*.py")):
+        if any(part in EXCLUDE_DIRS for part in py.parts):
+            continue
+        # NO seguir symlinks — un repo hostil podría apuntar fuera del árbol escaneado
+        # (path traversal del scanner). Mismo guard que cli._find_units y pack.build_tarball.
+        if py.is_symlink() or any(p.is_symlink() for p in py.parents
+                                  if root in p.parents or p == root):
+            continue
+        n += 1
+        if n > max_files:
+            break
+        findings, src = scan_file(py)
+        if findings:
+            out[py] = (findings, src)
+    return out, min(n, max_files)

costwright/cli.py

@@ -0,0 +1,265 @@
+"""costwright CLI — `costwright check` y `costwright caps`.
+
+Exit codes (council 002 P0-1):
+  0 = el tool corrió (hallazgos = warnings, salvo política)
+  1 = la política --fail-on se violó
+  2 = error de infraestructura (path inválido, crash) — nunca severidad de hallazgo
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from costwright import __version__
+from costwright import caps as caps_mod
+from costwright import report as report_mod
+from costwright.extract import extract_unit
+from costwright.mapper import map_unit
+import ast as _ast
+
+EXCLUDE_DIRS = {".venv", "venv", "node_modules", "site-packages", ".git", "__pycache__"}
+
+
+def _find_units(root: Path, max_files: int):
+    """Detecta graph units (constructores LangGraph/CrewAI/AgentsSDK) en el árbol."""
+    units = []
+    n = 0
+    for py in sorted(root.rglob("*.py")):
+        if any(part in EXCLUDE_DIRS for part in py.parts):
+            continue
+        # audit-3 (deepseek P0): NO seguir symlinks — un repo hostil podría apuntar
+        # fuera del árbol escaneado (path traversal del scanner)
+        if py.is_symlink() or any(p.is_symlink() for p in py.parents
+                                  if root in p.parents or p == root):
+            continue
+        n += 1
+        if n > max_files:
+            break
+        try:
+            src = py.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        # precheck laxo (audit-3: "Crew (" con espacio se perdía con "Crew(")
+        if not any(k in src for k in ("StateGraph", "Crew", "Runner.run")):
+            continue
+        try:
+            tree = _ast.parse(src)
+        except SyntaxError:
+            units.append({"file": py, "kind": "unknown", "line": 0, "syntax_error": True})
+            continue
+        for node in _ast.walk(tree):
+            if not isinstance(node, _ast.Call):
+                continue
+            f = node.func
+            nm = f.id if isinstance(f, _ast.Name) else (
+                f"{f.value.id}.{f.attr}" if isinstance(f, _ast.Attribute)
+                and isinstance(f.value, _ast.Name) else
+                (f.attr if isinstance(f, _ast.Attribute) else ""))
+            kind = None
+            if nm == "StateGraph":
+                kind = "langgraph"
+            elif nm == "Crew":
+                kind = "crewai"
+            elif nm in ("Runner.run", "Runner.run_sync", "Runner.run_streamed"):
+                kind = "agents_sdk"
+            if kind:
+                units.append({"file": py, "kind": kind, "line": node.lineno})
+    return units
+
+
+def cmd_check(args) -> int:
+    root = Path(args.path).resolve()
+    if not root.exists():
+        print(f"costwright: path not found: {root}", file=sys.stderr)
+        return 2
+    try:
+        found = _find_units(root, args.max_files)
+        mapped = []
+        for u in found:
+            rel = str(u["file"].relative_to(root))
+            if u.get("syntax_error"):
+                mapped.append({"category": "extractor-failure", "reason": "syntax",
+                               "kind": u["kind"], "rel_path": rel, "line": 0})
+                continue
+            meta = {"unit_id": rel, "file": u["file"].name, "kind": u["kind"]}
+            ex = extract_unit(u["file"].parent, meta)
+            r = map_unit(ex, meta)
+            r["rel_path"] = rel
+            r["line"] = u["line"]
+            mapped.append(r)
+        rep = report_mod.to_v1(mapped)
+        if args.json:
+            print(report_mod.dumps(rep))
+        else:
+            if not rep["units"]:
+                print("costwright: no graph units found")
+                return 0
+            print(report_mod.pretty(rep, verbose=args.verbose))
+        # política opt-in (council 002 P0-1)
+        s = rep["summary"]
+        viol = {"reject": s["runaway"] > 0,
+                "default-dependent": s["runaway"] > 0 or s["default_dependent"] > 0,
+                "non-certifiable": (s["runaway"] > 0 or s["default_dependent"] > 0
+                                    or s["non_certifiable"] > 0)}
+        if args.fail_on and viol.get(args.fail_on, False):
+            print(f"costwright: policy --fail-on {args.fail_on} violated", file=sys.stderr)
+            return 1
+        return 0
+    except Exception as e:                                    # noqa: BLE001
+        print(f"costwright: internal error: {type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+
+
+def cmd_caps(args) -> int:
+    root = Path(args.path).resolve()
+    if not root.exists():
+        print(f"costwright: path not found: {root}", file=sys.stderr)
+        return 2
+    try:
+        per_file, scanned = caps_mod.scan_path(root, args.max_files)
+        if args.json:
+            out = {"schema": "costwright.caps.v1", "files_scanned": scanned, "findings": [
+                {**f, "file": str(p.relative_to(root))}
+                for p, (fs, _) in sorted(per_file.items()) for f in fs]}
+            print(json.dumps(out, indent=1, ensure_ascii=False, sort_keys=True))
+        else:
+            total = sum(len(fs) for fs, _ in per_file.values())
+            if not total:
+                print(f"costwright caps: all LLM constructors capped ({scanned} files scanned)")
+                return 0
+            for p, (fs, _) in sorted(per_file.items()):
+                rel = p.relative_to(root)
+                for f in fs:
+                    if f["kind"] == "missing":
+                        print(f"  ✗ {rel}:{f['line']}  {f['constructor']}(...) sin cap "
+                              f"→ agregar {f['suggest_kwarg']}=<N>"
+                              + (f"   [{f['note']}]" if f.get("note") else ""))
+                    else:
+                        print(f"  ▲ {rel}:{f['line']}  {f['constructor']}: {f['why']}")
+            print(f"\n  {total} finding(s) in {len(per_file)} file(s) "
+                  f"({scanned} scanned). Use --patch to emit a unified diff.")
+        if args.patch:
+            chunks = []
+            for p, (fs, src) in sorted(per_file.items()):
+                d = caps_mod.make_patch(p.relative_to(root), src, fs, args.cap)
+                if d:
+                    chunks.append(d)
+            patch = "".join(chunks)
+            if args.patch == "-":
+                sys.stdout.write(patch)
+            else:
+                Path(args.patch).write_text(patch)
+                print(f"  patch written to {args.patch} (apply with: git apply {args.patch})")
+        return 0
+    except Exception as e:                                    # noqa: BLE001
+        print(f"costwright: internal error: {type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+
+
+def _load_json(path: str):
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _workflow_digest(path: Path) -> str:
+    """Bind the bundle to the analyzed artifact (anti-substitution). Hash the EXACT file bytes (not
+    decoded text — `errors='ignore'` could let two byte-distinct files collide). A single file →
+    digest its bytes; a directory → a deterministic manifest {rel_path: sha256(bytes)} over the *.py."""
+    from costwright import fusion
+    if path.is_dir():
+        manifest = {}
+        for py in sorted(path.rglob("*.py")):
+            if any(part in EXCLUDE_DIRS for part in py.parts):
+                continue
+            manifest[str(py.relative_to(path))] = fusion.digest_bytes(py.read_bytes())
+        return fusion.digest(manifest)
+    return fusion.digest_bytes(path.read_bytes())
+
+
+def cmd_fuse(args) -> int:
+    from costwright import __version__, fusion
+    try:
+        cost = _load_json(args.cost)
+        risk = _load_json(args.risk)
+    except (OSError, ValueError) as e:   # ValueError covers json.JSONDecodeError
+        print(f"costwright: cannot read input JSON: {type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+    claim = None
+    if args.claim_file:
+        try:
+            claim = Path(args.claim_file).read_text(encoding="utf-8")
+        except OSError as e:
+            print(f"costwright: cannot read --claim-file: {e}", file=sys.stderr)
+            return 2
+    wf_digest = None
+    if args.workflow:
+        try:
+            wf_digest = _workflow_digest(Path(args.workflow))
+        except OSError as e:
+            print(f"costwright: cannot read --workflow: {e}", file=sys.stderr)
+            return 2
+    try:
+        bundle = fusion.fuse(cost, risk, run_id=args.run_id,
+                             costwright_version=args.costwright_version or __version__,
+                             verify_version=args.verify_version,
+                             created_unix=args.created_unix,
+                             workflow_digest=wf_digest,
+                             calibrator_digest=args.calibrator_digest, claim=claim)
+    except ValueError as e:
+        print(f"costwright: invalid certificate input: {e}", file=sys.stderr)
+        return 2
+    print(fusion.dumps(bundle) if args.json else fusion.pretty(bundle))
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="costwright",
+        description="Static budget certificates for LLM-agent workflows "
+                    "(LangGraph / CrewAI / OpenAI Agents SDK). Never executes your code.")
+    p.add_argument("--version", action="version", version=f"costwright {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("check", help="map workflows to the typed-budget calculus and report bounds")
+    c.add_argument("path", nargs="?", default=".")
+    c.add_argument("--json", action="store_true", help="emit costwright.v1 JSON")
+    c.add_argument("--verbose", action="store_true", help="also list certifiable units")
+    c.add_argument("--fail-on", choices=["reject", "default-dependent", "non-certifiable"],
+                   help="severity threshold: exit 1 on findings of this severity OR WORSE "
+                        "(reject ⊂ default-dependent ⊂ non-certifiable). Default: never fail")
+    c.add_argument("--max-files", type=int, default=5000)
+    c.set_defaults(fn=cmd_check)
+
+    k = sub.add_parser("caps", help="find LLM constructors without a token cap; suggest the right kwarg per provider")
+    k.add_argument("path", nargs="?", default=".")
+    k.add_argument("--json", action="store_true")
+    k.add_argument("--patch", metavar="FILE", help="write a unified diff adding caps ('-' = stdout); NEVER edits files")
+    k.add_argument("--cap", type=int, default=1024, help="cap value used in --patch (default 1024)")
+    k.add_argument("--max-files", type=int, default=5000)
+    k.set_defaults(fn=cmd_caps)
+
+    from costwright.pack import cmd_pack
+    pk = sub.add_parser("pack", help="build a deterministic .py-only tarball for server-side certification")
+    pk.add_argument("path", nargs="?", default=".")
+    pk.add_argument("-o", "--output", default="costwright-artifact.tgz")
+    pk.set_defaults(fn=cmd_pack)
+
+    fz = sub.add_parser("fuse", help="bundle a costwright.v1 cost cert + an eleata-verify risk cert into a "
+                                     "costwright.fusion.v1 audit record (the cartesian product — NOT a joint guarantee)")
+    fz.add_argument("--cost", required=True, metavar="FILE", help="costwright.v1 JSON (from `costwright check --json`)")
+    fz.add_argument("--risk", required=True, metavar="FILE", help="eleata-verify VerifyResult.to_dict() JSON")
+    fz.add_argument("--run-id", required=True, help="binds both certificates to the same run")
+    fz.add_argument("--costwright-version", default=None, help="costwright that produced --cost (default: this costwright)")
+    fz.add_argument("--verify-version", default="unknown", help="pinned eleata-verify version that produced --risk")
+    fz.add_argument("--workflow", metavar="PATH", help="file/dir of the analyzed workflow → workflow_digest (binding)")
+    fz.add_argument("--claim-file", metavar="FILE", help="the verified claim text → claim_digest (binding)")
+    fz.add_argument("--calibrator-digest", default=None, help="digest/id of the calibrator used (binding)")
+    fz.add_argument("--created-unix", type=int, default=None, help="caller-stamped run timestamp (optional)")
+    fz.add_argument("--json", action="store_true", help="emit costwright.fusion.v1 JSON")
+    fz.set_defaults(fn=cmd_fuse)
+
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

costwright/extract.py

@@ -0,0 +1,214 @@
+"""F2a — extract: por graph unit, AST → ExtractionResult.
+
+Emite: nodos, edges (static/conditional-literal/conditional-fn/dynamic-goto/send), ciclos,
+bounds con fuente (D2/D8), caps de tokens, features no soportadas. 100% estático (D3).
+"""
+import ast, json
+from pathlib import Path
+
+# D8 — tabla verificada 2026-06-12 (fuentes en spec.md)
+DEFAULTS = {
+    "langgraph_recursion_limit_modern": 1000,   # >=1.0.6
+    "langgraph_recursion_limit_legacy": 25,     # <1.0.6
+    "crewai_max_iter": 20,
+    "agents_sdk_max_turns": 10,
+}
+CAP_KWARGS = {"max_tokens", "max_output_tokens", "max_completion_tokens", "budget_tokens",
+              "max_tokens_to_sample", "maxOutputTokens"}
+
+def call_name(n: ast.Call) -> str:
+    f = n.func
+    if isinstance(f, ast.Name): return f.id
+    if isinstance(f, ast.Attribute):
+        parts = []
+        cur = f
+        while isinstance(cur, ast.Attribute):
+            parts.append(cur.attr); cur = cur.value
+        if isinstance(cur, ast.Name): parts.append(cur.id)
+        return ".".join(reversed(parts))
+    return ""
+
+def const_of(node):
+    if isinstance(node, ast.Constant): return node.value
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub) and isinstance(node.operand, ast.Constant):
+        return -node.operand.value
+    return None
+
+class Extractor(ast.NodeVisitor):
+    def __init__(s, src):
+        s.src = src
+        s.nodes = []          # (name|None, lineno)
+        s.edges = []          # dicts {kind, src, dst, line}
+        s.bounds = []         # {param, value|None, source, line}
+        s.caps = []           # {kwarg, value|None, line}
+        s.features = []       # {feature, line} no-soportadas / señales
+        s.llm_calls = 0       # heurística: invocaciones a modelos dentro del archivo
+        s.while_true_invokes = []
+        s._in_while_true = 0
+
+    def visit_While(s, n):
+        is_true = isinstance(n.test, ast.Constant) and n.test.value is True
+        # REPL interactivo: while True con input() en el cuerpo — el humano es el loop,
+        # NO es un driver runaway autónomo (revisión D5: u082/u229 eran chat-REPLs)
+        if is_true:
+            body_src = ast.dump(n)
+            if "id='input'" in body_src or 'id="input"' in body_src:
+                s.features.append({"feature": "interactive-repl", "line": n.lineno})
+                s.generic_visit(n); return
+        if is_true: s._in_while_true += 1
+        s.generic_visit(n)
+        if is_true: s._in_while_true -= 1
+
+    def visit_Call(s, n):
+        name = call_name(n)
+        last = name.split(".")[-1]
+
+        if last == "add_node":
+            arg0 = n.args[0] if n.args else None
+            nname = const_of(arg0) if arg0 is not None else None
+            if not isinstance(nname, str) and len(n.args) == 1:
+                # LangGraph permite add_node(fn) — 1 SOLO arg: el nombre se infiere de
+                # fn.__name__ → nodo nombrado estáticamente (rev D5). Con 2 args, arg0 variable
+                # = NOMBRE dinámico (string en runtime) → queda None (dinámico).
+                if isinstance(arg0, ast.Name): nname = arg0.id
+                elif isinstance(arg0, ast.Attribute): nname = arg0.attr
+            s.nodes.append((nname if isinstance(nname, str) else None, n.lineno))
+            # subgraph como nodo: add_node(name, X.compile()) — el handler es OTRO grafo;
+            # el costo del nodo no es 1 call (rev D5: u139). delegate() lo cubriría; el
+            # harness v1 no lo implementa → feature medida.
+            for a in list(n.args[1:]) + [k.value for k in n.keywords]:
+                if isinstance(a, ast.Call) and call_name(a).split(".")[-1] == "compile":
+                    s.features.append({"feature": "subgraph-node", "line": n.lineno})
+        elif last == "add_edge":
+            a = const_or_endref(n.args[0]) if len(n.args) > 0 else None
+            b = const_or_endref(n.args[1]) if len(n.args) > 1 else None
+            s.edges.append({"kind": "static", "src": a, "dst": b, "line": n.lineno})
+        elif last == "add_conditional_edges":
+            # dst enumerable si hay dict literal en args/kwargs
+            mapping = None
+            for x in list(n.args) + [k.value for k in n.keywords]:
+                if isinstance(x, ast.Dict): mapping = x
+            if mapping is not None:
+                dsts = [const_or_endref(v) for v in mapping.values]
+                s.edges.append({"kind": "conditional-literal", "src": None, "dsts": dsts, "line": n.lineno})
+            else:
+                s.edges.append({"kind": "conditional-fn", "src": None, "dsts": None, "line": n.lineno})
+        elif last == "Send":
+            s.features.append({"feature": "send-fanout", "line": n.lineno})
+        elif last == "Command":
+            goto = next((k.value for k in n.keywords if k.arg == "goto"), None)
+            if goto is not None and const_of(goto) is None and not isinstance(goto, ast.List):
+                s.features.append({"feature": "dynamic-goto", "line": n.lineno})
+            elif goto is not None:
+                s.edges.append({"kind": "static", "src": None, "dst": const_of(goto), "line": n.lineno})
+        elif (last == "interrupt" or last == "NodeInterrupt"
+              or name.endswith("interrupt_before") or name.endswith("interrupt_after")):
+            s.features.append({"feature": "interrupt-human-in-loop", "line": n.lineno})
+        elif last in ("invoke", "stream", "ainvoke", "astream", "batch", "abatch", "kickoff",
+                      "run", "run_sync", "run_streamed"):
+            s._scan_invoke(n)
+            if s._in_while_true: s.while_true_invokes.append(n.lineno)
+        elif last == "compile":
+            for k in n.keywords:
+                if k.arg in ("interrupt_before", "interrupt_after"):
+                    s.features.append({"feature": "interrupt-human-in-loop", "line": n.lineno})
+        elif last in ("Agent",):
+            mi = next((k for k in n.keywords if k.arg == "max_iter"), None)
+            if mi is not None:
+                s.bounds.append({"param": "max_iter", "value": const_of(mi.value),
+                                 "source": "explicit", "line": n.lineno})
+            # CrewAI Agent sin max_iter → default 20 (lo decide el mapper por-kind)
+        elif last == "Crew":
+            proc = next((k for k in n.keywords if k.arg == "process"), None)
+            if proc is not None and "hierarchical" in ast.dump(proc.value):
+                s.features.append({"feature": "hierarchical-manager", "line": n.lineno})
+
+        # caps de tokens en cualquier call (constructores de modelos, llamadas)
+        for k in n.keywords:
+            if k.arg in CAP_KWARGS:
+                s.caps.append({"kwarg": k.arg, "value": const_of(k.value), "line": n.lineno})
+        # heurística de llamadas a LLM
+        if last in ("ChatOpenAI", "ChatAnthropic", "ChatGoogleGenerativeAI", "ChatBedrock",
+                    "AzureChatOpenAI", "ChatVertexAI", "OpenAI", "Anthropic", "LLM",
+                    "init_chat_model", "ChatGroq", "ChatMistralAI", "ChatOllama"):
+            s.llm_calls += 1
+        s.generic_visit(n)
+
+    def _scan_invoke(s, n):
+        """Busca recursion_limit / max_turns en el config del call-site (D2)."""
+        for k in n.keywords:
+            if k.arg == "max_turns":
+                # distinguir None LITERAL (desactivación deliberada) de expresión no-constante
+                # (bound real irrecuperable estáticamente) — revisión D5: u087 era settings.max_turns
+                none_lit = isinstance(k.value, ast.Constant) and k.value.value is None
+                s.bounds.append({"param": "max_turns", "value": const_of(k.value),
+                                 "none_literal": none_lit,
+                                 "source": "explicit", "line": n.lineno})
+            if k.arg == "config" and isinstance(k.value, ast.Dict):
+                for kk, vv in zip(k.value.keys, k.value.values):
+                    if const_of(kk) == "recursion_limit":
+                        s.bounds.append({"param": "recursion_limit", "value": const_of(vv),
+                                         "source": "explicit", "line": n.lineno})
+
+    def visit_Dict(s, n):
+        # config dicts armados aparte: {"recursion_limit": N, ...}
+        for kk, vv in zip(n.keys, n.values):
+            if const_of(kk) == "recursion_limit":
+                s.bounds.append({"param": "recursion_limit", "value": const_of(vv),
+                                 "source": "explicit", "line": n.lineno})
+        s.generic_visit(n)
+
+def const_or_endref(node):
+    v = const_of(node)
+    if v is not None: return v
+    if isinstance(node, ast.Name) and node.id in ("START", "END"): return node.id
+    if isinstance(node, ast.Attribute) and node.attr in ("START", "END"): return node.attr
+    return None
+
+def find_cycles(nodes, edges):
+    """DFS sobre edges con dst resuelto. Conservador: edges no resueltos no crean ciclo
+    (el mapper los trata como dynamic)."""
+    g = {}
+    for e in edges:
+        if e["kind"] == "static" and e.get("src") and e.get("dst") and e["dst"] != "END":
+            g.setdefault(e["src"], set()).add(e["dst"])
+        elif e["kind"] == "conditional-literal" and e.get("dsts"):
+            # src desconocido en muchos casos; si no hay src, no podemos cerrar ciclo → skip
+            if e.get("src"):
+                for d in e["dsts"]:
+                    if d and d != "END": g.setdefault(e["src"], set()).add(d)
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color = {u: WHITE for u in g}
+    cyc = False
+    def dfs(u):
+        nonlocal cyc
+        color[u] = GRAY
+        for v in g.get(u, ()):
+            if color.get(v, WHITE) == GRAY: cyc = True
+            elif color.get(v, WHITE) == WHITE: dfs(v)
+        color[u] = BLACK
+    for u in list(g):
+        if color[u] == WHITE: dfs(u)
+    return cyc
+
+def extract_unit(unit_dir: Path, meta: dict) -> dict:
+    f = unit_dir / meta["file"]
+    src = f.read_text(encoding="utf-8", errors="ignore")
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return {"unit_id": meta["unit_id"], "status": "extractor-failure", "reason": "syntax"}
+    ex = Extractor(src); ex.visit(tree)
+    has_cycle = find_cycles(ex.nodes, ex.edges)
+    # ciclo "implícito" típico LangGraph: conditional edges que vuelven a un nodo previo —
+    # si hay conditional-literal cuyos dsts incluyen un nodo definido, lo tratamos como posible ciclo
+    cond_back = any(e["kind"] == "conditional-literal" and e.get("dsts") and
+                    any(d for d in e["dsts"] if d and d != "END") for e in ex.edges)
+    return {
+        "unit_id": meta["unit_id"], "kind": meta["kind"], "status": "ok",
+        "n_nodes": len(ex.nodes), "n_nodes_named": sum(1 for n, _ in ex.nodes if n),
+        "n_nodes_dynamic": sum(1 for n, _ in ex.nodes if n is None),
+        "edges": ex.edges, "has_static_cycle": has_cycle, "cond_may_cycle": cond_back,
+        "bounds": ex.bounds, "caps": ex.caps, "features": ex.features,
+        "llm_constructors": ex.llm_calls, "while_true_invokes": ex.while_true_invokes,
+    }