q-runtime-core 0.9.0__py3-none-any.whl

qruntime/cli.py

@@ -0,0 +1,594 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from qruntime.loader import load_workflow
+from qruntime.rails.x402 import (
+    X402DecodeError,
+    as_jsonable,
+    normalize_payment_required,
+    parse_payment_payload,
+    parse_payment_required,
+    parse_settlement_response,
+)
+from qruntime.rails.x402_verify import trace_result_json, trace_result_text, verify_x402_trace
+from qruntime.rails.x402_capture import (
+    X402CaptureError,
+    capture_to_file,
+    compare_capture_quotes,
+)
+from qruntime.rails.x402_external import (
+    ExternalProbeError,
+    audit_x402_list_directory,
+    probe_external,
+    write_external_probe,
+)
+from qruntime.rails.x402_external_suite import run_external_suite
+from qruntime.verify.explorer import verify
+from qruntime.verify.report import to_json, to_text
+from qruntime.rails.x402_fullcycle import (
+    create_testnet_wallet,
+    get_persistent_payment_intent,
+    list_persistent_payment_intents,
+    reconcile_testnet_transaction,
+    fullcycle_result_dict,
+    fullcycle_result_text,
+    run_local_testnet_payment,
+    verify_fullcycle,
+)
+
+
+def _read_x402_input(path: str):
+    raw = Path(path).read_text(encoding="utf-8").strip()
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError:
+        value = raw
+    return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="qruntime")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    verify_p = sub.add_parser("verify", help="verify economic invariants for a QFlow YAML file")
+    verify_p.add_argument("path")
+    verify_p.add_argument("--json", action="store_true", dest="as_json")
+
+    x402_p = sub.add_parser("x402", help="decode and verify x402 v2 economic traces")
+    xsub = x402_p.add_subparsers(dest="x402_command", required=True)
+
+    inspect = xsub.add_parser("inspect", help="decode one x402 v2 wire object")
+    inspect.add_argument("type", choices=["required", "signature", "response"])
+    inspect.add_argument("path")
+
+    normalize = xsub.add_parser("normalize", help="map PAYMENT-REQUIRED to a Q economic event")
+    normalize.add_argument("path")
+    normalize.add_argument("--accept-index", type=int, default=0)
+
+    trace = xsub.add_parser("verify-trace", help="verify a recorded/synthetic x402 event trace")
+    trace.add_argument("path")
+    trace.add_argument("--json", action="store_true", dest="as_json")
+
+    capture = xsub.add_parser("capture-402", help="capture a live HTTP 402/PAYMENT-REQUIRED without paying")
+    capture.add_argument("url")
+    capture.add_argument("--out", required=True)
+    capture.add_argument("--timeout", type=float, default=10.0)
+
+    compare = xsub.add_parser("compare-quotes", help="compare two captured PAYMENT-REQUIRED quotes")
+    compare.add_argument("old_capture")
+    compare.add_argument("new_capture")
+    compare.add_argument("--accept-index", type=int, default=0)
+    compare.add_argument("--json", action="store_true", dest="as_json")
+
+    external = xsub.add_parser("external-audit", help="audit an independent live x402 endpoint without paying")
+    external.add_argument("url")
+    external.add_argument("--method", choices=["GET", "POST", "HEAD"], default="GET")
+    external.add_argument("--json-body", default=None, help="inline JSON body for POST probes")
+    external.add_argument("--out", default=None)
+    external.add_argument("--timeout", type=float, default=10.0)
+    external.add_argument("--mode", choices=["strict", "compatibility"], default="strict")
+    external.add_argument("--json", action="store_true", dest="as_json")
+
+    ext_suite = xsub.add_parser("external-suite", help="cross-implementation checks against independent grug402 endpoints")
+    ext_suite.add_argument("--timeout", type=float, default=10.0)
+    ext_suite.add_argument("--out", default=None)
+    ext_suite.add_argument("--mode", choices=["strict", "compatibility"], default="strict")
+    ext_suite.add_argument("--json", action="store_true", dest="as_json")
+
+    directory = xsub.add_parser("directory-audit", help="safely audit GET endpoints discovered through x402 List")
+    directory.add_argument("--limit", type=int, default=10)
+    directory.add_argument("--timeout", type=float, default=10.0)
+    directory.add_argument("--mode", choices=["strict", "compatibility"], default="compatibility")
+    directory.add_argument("--out", required=True)
+
+    serve = xsub.add_parser("serve-official-demo", help="run a Base-Sepolia demo using the official x402 Python SDK")
+    serve.add_argument("--pay-to", required=True, help="public EVM test-wallet address; private key is never required")
+    serve.add_argument("--price-usd", default="0.01")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=4021)
+    serve.add_argument("--facilitator-url", default="https://x402.org/facilitator")
+
+    fullcycle = xsub.add_parser("verify-fullcycle", help="verify x402 v2 authorization-flow invariants")
+    fullcycle.add_argument("path")
+    fullcycle.add_argument("--json", action="store_true", dest="as_json")
+
+    wallet = xsub.add_parser("create-testnet-wallet", help="create a disposable Base-Sepolia EVM wallet file")
+    wallet.add_argument("--out", required=True)
+
+    live = xsub.add_parser("live-testnet", help="run one capped full-cycle payment against the local Base-Sepolia demo")
+    live.add_argument("url", nargs="?", default="http://127.0.0.1:4021/weather")
+    live.add_argument("--max-amount-atomic", required=True, type=int)
+    live.add_argument(
+        "--intent-id",
+        default=None,
+        help="stable logical operation id; reuse only when retrying the same payment intent",
+    )
+    live.add_argument("--out", required=True)
+    live.add_argument("--key-env", default="Q_RUNTIME_TESTNET_PRIVATE_KEY")
+    live.add_argument("--timeout", type=float, default=30.0)
+
+    reconcile = xsub.add_parser(
+        "reconcile-testnet",
+        help="read-only reconcile an already-broadcast Base-Sepolia transaction",
+    )
+    reconcile.add_argument("transaction")
+    reconcile.add_argument("--out", required=True)
+    reconcile.add_argument("--timeout", type=float, default=15.0)
+    reconcile.add_argument("--json", action="store_true", dest="as_json")
+
+    intents = xsub.add_parser(
+        "intents",
+        help="list persisted x402 payment intents",
+    )
+    intents.add_argument(
+        "--json",
+        action="store_true",
+        dest="as_json",
+    )
+
+    intent_view = intents.add_mutually_exclusive_group()
+
+    intent_view.add_argument(
+        "--state",
+        choices=[
+            "pending",
+            "confirmed",
+            "failed",
+        ],
+        default=None,
+        help="filter intents by economic state",
+    )
+
+    intent_view.add_argument(
+        "--summary",
+        action="store_true",
+        help="show aggregate intent-state counts",
+    )
+
+    intent = xsub.add_parser(
+        "intent",
+        help="inspect one persisted x402 payment intent",
+    )
+    intent.add_argument("intent_id")
+    intent.add_argument(
+        "--json",
+        action="store_true",
+        dest="as_json",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "verify":
+        spec = load_workflow(args.path)
+        result = verify(spec)
+        print(to_json(result) if args.as_json else to_text(result))
+        return 0 if result.passed else 2
+
+    if args.command == "x402":
+        if args.x402_command == "inspect":
+            value = _read_x402_input(args.path)
+            if args.type == "required":
+                parsed = parse_payment_required(value)
+            elif args.type == "signature":
+                parsed = parse_payment_payload(value)
+            else:
+                parsed = parse_settlement_response(value)
+            print(json.dumps(as_jsonable(parsed), indent=2, ensure_ascii=False))
+            return 0
+
+        if args.x402_command == "normalize":
+            value = _read_x402_input(args.path)
+            event = normalize_payment_required(value, args.accept_index)
+            print(json.dumps(as_jsonable(event), indent=2, ensure_ascii=False))
+            return 0
+
+        if args.x402_command == "verify-trace":
+            result = verify_x402_trace(args.path)
+            print(trace_result_json(result) if args.as_json else trace_result_text(result))
+            return 0 if result.passed else 2
+
+        if args.x402_command == "capture-402":
+            try:
+                capture_result = capture_to_file(args.url, args.out, timeout=args.timeout)
+            except X402CaptureError as exc:
+                print(f"CAPTURE FAIL — {exc}")
+                return 2
+            req = capture_result.payment_required.selected(0)
+            print("CAPTURED — LIVE X402 PAYMENT-REQUIRED")
+            print(f"HTTP status: {capture_result.status_code}")
+            print(f"resource: {capture_result.payment_required.resource_url}")
+            print(f"scheme/network: {req.scheme} / {req.network}")
+            print(f"amount atomic: {req.amount_atomic}")
+            print(f"quote fingerprint: {req.fingerprint()}")
+            print(f"trace: {args.out}")
+            return 0
+
+        if args.x402_command == "compare-quotes":
+            try:
+                result = compare_capture_quotes(
+                    args.old_capture, args.new_capture, accept_index=args.accept_index
+                )
+            except (X402CaptureError, ValueError, json.JSONDecodeError) as exc:
+                print(f"COMPARE FAIL — {exc}")
+                return 2
+            if args.as_json:
+                print(json.dumps(result, indent=2, ensure_ascii=False))
+            elif result["stable"]:
+                print("PASS — PaymentRequirementStableForIntent")
+                print("live quote fingerprint unchanged")
+            else:
+                print("FAIL — LIVE_X402_QUOTE_DRIFT")
+                print(f"invariant: {result['invariant']}")
+                if not result["same_resource"]:
+                    print(f"resource: {result['old_resource']} -> {result['new_resource']}")
+                for field, change in result["changes"].items():
+                    print(f"{field}: {change['before']} -> {change['after']}")
+            return 0 if result["stable"] else 2
+
+        if args.x402_command == "external-audit":
+            try:
+                body = None if args.json_body is None else json.loads(args.json_body)
+                result = probe_external(
+                    args.url,
+                    method=args.method,
+                    json_body=body,
+                    timeout=args.timeout,
+                    require_public_https=True,
+                    mode=args.mode,
+                )
+            except (ExternalProbeError, json.JSONDecodeError) as exc:
+                print(f"EXTERNAL AUDIT FAIL — {exc}")
+                return 2
+            if args.out:
+                write_external_probe(result, args.out)
+            data = result.as_dict()
+            if args.as_json:
+                print(json.dumps(data, indent=2, ensure_ascii=False))
+            else:
+                if result.classification == "legacy_x402_v1":
+                    print("FAIL — LEGACY_X402_V1" if args.mode == "strict" else "LEGACY — X402_V1_DETECTED")
+                else:
+                    print("PASS — EXTERNAL X402 AUDIT" if result.passed else "FAIL — EXTERNAL X402 AUDIT")
+                print(f"mode: {args.mode}")
+                print(f"HTTP: {result.status_code} {result.method} {result.final_url}")
+                print(f"challenge source: {result.challenge_source or 'none'}")
+                if result.payment_required is not None:
+                    print(f"resource: {result.payment_required.resource_url}")
+                    print(f"accepts: {len(result.payment_required.accepts)}")
+                    first = result.payment_required.accepts[0]
+                    print(f"first requirement: {first.scheme} / {first.network} / {first.amount_atomic}")
+                    print(f"fingerprint: {first.fingerprint()}")
+                for finding in result.findings:
+                    print(f"{finding.severity.upper()} {finding.invariant}: {finding.reason}")
+                if args.out:
+                    print(f"report: {args.out}")
+            return 0 if result.passed else 2
+
+        if args.x402_command == "external-suite":
+            result = run_external_suite(timeout=args.timeout, mode=args.mode)
+            if args.out:
+                Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+                Path(args.out).write_text(json.dumps(result, indent=2, ensure_ascii=False), encoding="utf-8")
+            if args.as_json:
+                print(json.dumps(result, indent=2, ensure_ascii=False))
+            else:
+                print("PASS — EXTERNAL SUITE" if result["suite_passed"] else "FAIL — EXTERNAL SUITE")
+                for case in result["cases"]:
+                    mark = "PASS" if case.get("matched_expectation") else "FAIL"
+                    print(f"{mark} {case['name']}: {case['url']}")
+                    audit = case.get("audit")
+                    if audit:
+                        for f in audit.get("findings", []):
+                            if f.get("severity") == "error":
+                                print(f"  {f['invariant']}: {f['reason']}")
+                    elif case.get("error"):
+                        print(f"  {case['error']}")
+                if args.out:
+                    print(f"report: {args.out}")
+            return 0 if result["suite_passed"] else 2
+
+        if args.x402_command == "directory-audit":
+            try:
+                result = audit_x402_list_directory(limit=args.limit, timeout=args.timeout, mode=args.mode)
+            except ExternalProbeError as exc:
+                print(f"DIRECTORY AUDIT FAIL — {exc}")
+                return 2
+            Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+            Path(args.out).write_text(json.dumps(result, indent=2, ensure_ascii=False), encoding="utf-8")
+            print("DIRECTORY AUDIT COMPLETE")
+            print(f"services audited: {result['services_audited']}")
+            print(f"errors: {result['errors']}")
+            print(f"warnings: {result['warnings']}")
+            print(f"legacy x402 v1: {result.get('legacy_x402_v1', 0)}")
+            print(f"mode: {args.mode}")
+            print(f"report: {args.out}")
+            return 0 if result["errors"] == 0 and result["services_audited"] > 0 else 2
+
+        if args.x402_command == "verify-fullcycle":
+            result = verify_fullcycle(args.path)
+            print(json.dumps(fullcycle_result_dict(result), indent=2, ensure_ascii=False) if args.as_json else fullcycle_result_text(result))
+            return 0 if result.passed else 2
+
+        if args.x402_command == "create-testnet-wallet":
+            try:
+                result = create_testnet_wallet(args.out)
+            except (RuntimeError, FileExistsError, ValueError) as exc:
+                print(f"WALLET FAIL — {exc}")
+                return 2
+            print("CREATED — DISPOSABLE TESTNET WALLET")
+            print("network: eip155:84532 (Base Sepolia)")
+            print(f"address: {result['address']}")
+            print(f"secret file: {result['path']}")
+            print("WARNING: TESTNET ONLY. Never reuse this key/address for mainnet assets.")
+            return 0
+
+        if args.x402_command == "live-testnet":
+            try:
+                result = run_local_testnet_payment(
+                    args.url,
+                    max_amount_atomic=args.max_amount_atomic,
+                    out=args.out,
+                    intent_id=args.intent_id,
+                    key_env=args.key_env,
+                    timeout=args.timeout,
+                )
+            except (RuntimeError, ValueError, X402DecodeError) as exc:
+                print(f"LIVE TESTNET FAIL — {exc}")
+                return 2
+            print("PASS — LIVE X402 TESTNET SETTLEMENT")
+            print(f"payer: {result['payer']}")
+            print(f"resource: {result['request_url']}")
+            print(f"amount atomic: {result['preflight']['amount_atomic']}")
+            print(f"network: {result['settlement']['network']}")
+            print(f"transaction: {result['settlement']['transaction']}")
+            print(f"report: {args.out}")
+            return 0
+
+        if args.x402_command == "intents":
+            try:
+                entries = list_persistent_payment_intents()
+            except RuntimeError as exc:
+                print(f"INTENT STORE FAIL ? {exc}")
+                return 2
+
+            if args.summary:
+                states = [
+                    str(entry.get("state", ""))
+                    for entry in entries
+                ]
+
+                summary = {
+                    "total": len(entries),
+                    "pending": states.count("pending"),
+                    "confirmed": states.count(
+                        "resolved_confirmed"
+                    ),
+                    "failed": states.count(
+                        "resolved_failed"
+                    ),
+                }
+
+                summary["other"] = (
+                    summary["total"]
+                    - summary["pending"]
+                    - summary["confirmed"]
+                    - summary["failed"]
+                )
+
+                if args.as_json:
+                    print(
+                        json.dumps(
+                            summary,
+                            indent=2,
+                            ensure_ascii=False,
+                        )
+                    )
+                else:
+                    print("X402 INTENT SUMMARY")
+                    print(f"total: {summary['total']}")
+                    print(
+                        f"pending: "
+                        f"{summary['pending']}"
+                    )
+                    print(
+                        f"confirmed: "
+                        f"{summary['confirmed']}"
+                    )
+                    print(
+                        f"failed: "
+                        f"{summary['failed']}"
+                    )
+                    print(
+                        f"other: "
+                        f"{summary['other']}"
+                    )
+
+                return 0
+
+            if args.state:
+                state_map = {
+                    "pending": "pending",
+                    "confirmed": "resolved_confirmed",
+                    "failed": "resolved_failed",
+                }
+
+                wanted = state_map[args.state]
+
+                entries = tuple(
+                    entry
+                    for entry in entries
+                    if str(
+                        entry.get("state", "")
+                    ) == wanted
+                )
+
+            if args.as_json:
+                print(
+                    json.dumps(
+                        list(entries),
+                        indent=2,
+                        ensure_ascii=False,
+                    )
+                )
+                return 0
+
+            if not entries:
+                print("NO PERSISTED X402 INTENTS")
+                return 0
+
+            print(f"PERSISTED X402 INTENTS: {len(entries)}")
+
+            for entry in entries:
+                print(
+                    f"{entry.get('state', 'unknown')}  "
+                    f"{entry.get('intent_id', '')}"
+                )
+                print(
+                    f"  resource: "
+                    f"{entry.get('resource', '')}"
+                )
+                print(
+                    f"  network: "
+                    f"{entry.get('network', '')}"
+                )
+                print(
+                    f"  transaction: "
+                    f"{entry.get('transaction', '')}"
+                )
+                print(
+                    f"  updated_at: "
+                    f"{entry.get('updated_at', '')}"
+                )
+
+            return 0
+
+        if args.x402_command == "intent":
+            try:
+                entry = get_persistent_payment_intent(
+                    args.intent_id
+                )
+            except (RuntimeError, ValueError) as exc:
+                print(f"INTENT LOOKUP FAIL ? {exc}")
+                return 2
+
+            if entry is None:
+                print(
+                    f"INTENT NOT FOUND: "
+                    f"{args.intent_id}"
+                )
+                return 2
+
+            if args.as_json:
+                print(
+                    json.dumps(
+                        entry,
+                        indent=2,
+                        ensure_ascii=False,
+                    )
+                )
+                return 0
+
+            print("X402 INTENT")
+            print(f"intent_id: {entry.get('intent_id', '')}")
+            print(f"state: {entry.get('state', '')}")
+            print(f"resource: {entry.get('resource', '')}")
+            print(f"network: {entry.get('network', '')}")
+            print(
+                f"transaction: "
+                f"{entry.get('transaction', '')}"
+            )
+            print(
+                f"reconciliation: "
+                f"{entry.get('reconciliation_outcome', '')}"
+            )
+            print(
+                f"first_seen_at: "
+                f"{entry.get('first_seen_at', '')}"
+            )
+            print(
+                f"updated_at: "
+                f"{entry.get('updated_at', '')}"
+            )
+
+            return 0
+
+        if args.x402_command == "reconcile-testnet":
+            try:
+                result = reconcile_testnet_transaction(
+                    args.transaction,
+                    out=args.out,
+                    timeout=args.timeout,
+                )
+            except (RuntimeError, ValueError) as exc:
+                print(f"RECONCILIATION FAIL ? {exc}")
+                return 2
+
+            if args.as_json:
+                print(json.dumps(result, indent=2, ensure_ascii=False))
+            else:
+                outcome = result["outcome"]
+                if outcome == "confirmed":
+                    print("RECONCILIATION CONFIRMED")
+                elif outcome == "failed":
+                    print("RECONCILIATION FAILED")
+                else:
+                    print("RECONCILIATION PENDING")
+
+                print(f"network: {result['network']}")
+                print(f"transaction: {result['transaction']}")
+                print(f"outcome: {result['outcome']}")
+                print(f"terminal: {result['terminal']}")
+                print(f"status: {result['chain']['status']}")
+                print(f"block: {result['chain']['block_number']}")
+                print(f"confirmations: {result['chain']['confirmations']}")
+                print(f"method: {result['chain']['method']}")
+                print(f"report: {args.out}")
+
+            # confirmed/failed are terminal reconciliation outcomes.
+            # pending remains fail-closed for automation/retry decisions.
+            return 0 if result["terminal"] else 2
+
+        if args.x402_command == "serve-official-demo":
+            from qruntime.integrations.official_x402_demo import serve as serve_official_x402
+
+            try:
+                serve_official_x402(
+                    pay_to=args.pay_to,
+                    price_usd=args.price_usd,
+                    host=args.host,
+                    port=args.port,
+                    facilitator_url=args.facilitator_url,
+                )
+            except (RuntimeError, ValueError) as exc:
+                print(f"SERVER FAIL — {exc}")
+                return 2
+            return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qruntime/core/invariants.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+
+from .model import RuntimeState, TaskStatus, WorkflowSpec, unresolved_required_cost
+
+
+@dataclass(frozen=True)
+class Violation:
+    invariant: str
+    message: str
+
+
+def check_invariants(spec: WorkflowSpec, state: RuntimeState) -> list[Violation]:
+    violations: list[Violation] = []
+
+    if state.spent + state.reserved > spec.budget:
+        violations.append(Violation(
+            "NoBudgetOversubscription",
+            f"spent({state.spent}) + reserved({state.reserved}) > budget({spec.budget})",
+        ))
+
+    duplicates = [intent for intent, n in Counter(state.settled_intents).items() if n > 1]
+    if duplicates:
+        violations.append(Violation(
+            "NoDuplicateEconomicEffect",
+            f"economic intent settled more than once: {', '.join(sorted(duplicates))}",
+        ))
+
+    if state.ambiguous_intents:
+        violations.append(Violation(
+            "PaymentStateReconciledBeforeRetry",
+            "retry attempted while prior payment outcome remained ambiguous: "
+            + ", ".join(sorted(state.ambiguous_intents)),
+        ))
+
+    if state.evidence_bypasses:
+        violations.append(Violation(
+            "EvidenceBeforeDependentSpend",
+            "economic reservation occurred without required evidence: "
+            + ", ".join(sorted(state.evidence_bypasses)),
+        ))
+
+    if state.unauthorized_effects:
+        violations.append(Violation(
+            "AuthorizedTransitionsOnly",
+            "economic effect attempted by actor outside delegated authority: "
+            + ", ".join(sorted(state.unauthorized_effects)),
+        ))
+
+    required_remaining = unresolved_required_cost(spec, state)
+    if state.spent + state.reserved + required_remaining > spec.budget:
+        violations.append(Violation(
+            "CompletionReservePreserved",
+            "current commitments leave insufficient authorized budget for unresolved required steps",
+        ))
+
+    if state.task_status == TaskStatus.COMPLETED:
+        missing = [s.id for s in spec.steps if s.required and state.status(s.id).value != "DONE"]
+        if missing:
+            violations.append(Violation(
+                "TerminalStateHonesty",
+                f"task completed with unresolved required steps: {', '.join(missing)}",
+            ))
+
+    return violations