patchahead 0.3.0__py3-none-any.whl

patchahead/config.py

@@ -0,0 +1,284 @@
+"""Project configuration.
+
+Read from ``[tool.patchahead]`` in the target repository's ``pyproject.toml``,
+or from a ``.patchahead.toml`` at its root. Every setting has a default that
+works, so a repository with no configuration at all is fully supported.
+
+Configuration belongs to the *repository being analyzed*, not to PatchAhead, so
+it is loaded from the repo path rather than from the current directory.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from patchahead.domain.change import Confidence
+
+try:  # Python >= 3.11
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - exercised on 3.10 only
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ModuleNotFoundError:  # pragma: no cover
+        tomllib = None  # type: ignore[assignment]
+
+log = logging.getLogger(__name__)
+
+CONFIG_FILENAME = ".patchahead.toml"
+PYPROJECT = "pyproject.toml"
+
+#: Directories never walked when discovering source files. Keeps analysis fast
+#: and stops PatchAhead from proposing edits to vendored or generated code.
+DEFAULT_EXCLUDE = (
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "env",
+    "__pycache__",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".nox",
+    "node_modules",
+    "build",
+    "dist",
+    "site-packages",
+    ".eggs",
+    ".patchahead",
+)
+
+
+class ConfigError(Exception):
+    """Raised when a configuration file exists but cannot be used."""
+
+
+@dataclass
+class Config:
+    """Effective configuration for one PatchAhead run."""
+
+    #: Shell command used to run tests inside the isolated workspace.
+    test_command: str = "python -m pytest"
+    #: Directories to analyze, relative to the repo root. Empty means the
+    #: whole repo minus ``exclude``.
+    source_dirs: list[str] = field(default_factory=list)
+    #: Directory names or glob patterns to skip.
+    exclude: list[str] = field(default_factory=lambda: list(DEFAULT_EXCLUDE))
+    #: A proposal touching more files than this fails the scope gate. Guards
+    #: against a runaway rename or an LLM rewriting half the repository.
+    max_changed_files: int = 10
+    #: A proposal larger than this (added + removed lines) fails the scope gate.
+    max_diff_lines: int = 400
+    #: Findings below this confidence are reported but never patched.
+    min_confidence: Confidence = Confidence.MEDIUM
+    #: Whether this repository permits sending source code to an LLM. The CLI's
+    #: ``--use-llm`` cannot override a ``false`` here.
+    allow_llm: bool = True
+    #: Whether test files are migrated too. Tests that call the old API break
+    #: with it, so migrating them is part of the job; a test the patch edited
+    #: is never counted as evidence that the patch worked.
+    migrate_tests: bool = True
+    #: Where artifacts (diff, plan, report) are written, relative to cwd.
+    output_dir: str = ".patchahead"
+    #: Seconds before a test command is killed.
+    test_timeout_seconds: int = 300
+    #: Refuse to copy a repository with more files than this into a workspace.
+    max_workspace_files: int = 20000
+
+    #: Absolute path of the file this config came from, or "" for defaults.
+    source_path: str = ""
+
+    def merged_with_cli(
+        self,
+        *,
+        test_command: str | None = None,
+        output_dir: str | None = None,
+        min_confidence: Confidence | None = None,
+        max_changed_files: int | None = None,
+    ) -> Config:
+        """Apply CLI overrides on top of file configuration.
+
+        Precedence is CLI > config file > defaults, except ``allow_llm``, which
+        the CLI can only narrow (see :meth:`llm_permitted`).
+        """
+        updates: dict[str, Any] = {}
+        if test_command:
+            updates["test_command"] = test_command
+        if output_dir:
+            updates["output_dir"] = output_dir
+        if min_confidence is not None:
+            updates["min_confidence"] = min_confidence
+        if max_changed_files is not None:
+            updates["max_changed_files"] = max_changed_files
+        return replace(self, **updates) if updates else self
+
+    def llm_permitted(self, requested: bool) -> tuple[bool, str]:
+        """Decide whether the LLM path may run, and say why if it may not.
+
+        ``allow_llm = false`` in a repository's config is a policy statement by
+        whoever owns that source code. ``--use-llm`` does not override it.
+        """
+        if not requested:
+            return False, ""
+        if not self.allow_llm:
+            return False, (
+                "LLM mode requested but `allow_llm = false` in this repository's "
+                "PatchAhead configuration; refusing to send source code to an LLM"
+            )
+        return True, ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "test_command": self.test_command,
+            "source_dirs": self.source_dirs,
+            "exclude": self.exclude,
+            "max_changed_files": self.max_changed_files,
+            "max_diff_lines": self.max_diff_lines,
+            "min_confidence": self.min_confidence.value,
+            "allow_llm": self.allow_llm,
+            "migrate_tests": self.migrate_tests,
+            "output_dir": self.output_dir,
+            "test_timeout_seconds": self.test_timeout_seconds,
+            "max_workspace_files": self.max_workspace_files,
+            "source_path": self.source_path,
+        }
+
+
+def _as_str_list(value: Any, key: str) -> list[str]:
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list) and all(isinstance(v, str) for v in value):
+        return list(value)
+    raise ConfigError(f"`{key}` must be a string or a list of strings, got {value!r}")
+
+
+def _as_int(value: Any, key: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ConfigError(f"`{key}` must be an integer, got {value!r}")
+    if value < 0:
+        raise ConfigError(f"`{key}` must not be negative, got {value!r}")
+    return value
+
+
+def _as_bool(value: Any, key: str) -> bool:
+    if not isinstance(value, bool):
+        raise ConfigError(f"`{key}` must be true or false, got {value!r}")
+    return value
+
+
+def from_mapping(data: dict[str, Any], source_path: str = "") -> Config:
+    """Build a :class:`Config` from a parsed ``[tool.patchahead]`` table.
+
+    Unknown keys are a hard error rather than a silent no-op: a typo'd
+    ``max_changed_file`` that quietly does nothing is worse than a message.
+    """
+    config = Config(source_path=source_path)
+    known = {
+        "test_command",
+        "source_dirs",
+        "exclude",
+        "max_changed_files",
+        "max_diff_lines",
+        "min_confidence",
+        "allow_llm",
+        "migrate_tests",
+        "output_dir",
+        "test_timeout_seconds",
+        "max_workspace_files",
+    }
+    unknown = sorted(set(data) - known)
+    if unknown:
+        raise ConfigError(
+            f"unknown PatchAhead config key(s): {', '.join(unknown)}. "
+            f"Valid keys: {', '.join(sorted(known))}"
+        )
+
+    if "test_command" in data:
+        value = data["test_command"]
+        if not isinstance(value, str) or not value.strip():
+            raise ConfigError(f"`test_command` must be a non-empty string, got {value!r}")
+        config.test_command = value.strip()
+    if "source_dirs" in data:
+        config.source_dirs = _as_str_list(data["source_dirs"], "source_dirs")
+    if "exclude" in data:
+        # Additive: a project extending the exclude list should not have to
+        # restate the defaults, which exist to keep analysis correct and fast.
+        extra = _as_str_list(data["exclude"], "exclude")
+        config.exclude = list(DEFAULT_EXCLUDE) + [e for e in extra if e not in DEFAULT_EXCLUDE]
+    if "max_changed_files" in data:
+        config.max_changed_files = _as_int(data["max_changed_files"], "max_changed_files")
+    if "max_diff_lines" in data:
+        config.max_diff_lines = _as_int(data["max_diff_lines"], "max_diff_lines")
+    if "min_confidence" in data:
+        value = data["min_confidence"]
+        try:
+            config.min_confidence = Confidence(str(value).strip().lower())
+        except ValueError:
+            raise ConfigError(
+                f"`min_confidence` must be one of high, medium, low; got {value!r}"
+            ) from None
+    if "allow_llm" in data:
+        config.allow_llm = _as_bool(data["allow_llm"], "allow_llm")
+    if "migrate_tests" in data:
+        config.migrate_tests = _as_bool(data["migrate_tests"], "migrate_tests")
+    if "output_dir" in data:
+        value = data["output_dir"]
+        if not isinstance(value, str) or not value.strip():
+            raise ConfigError(f"`output_dir` must be a non-empty string, got {value!r}")
+        config.output_dir = value.strip()
+    if "test_timeout_seconds" in data:
+        config.test_timeout_seconds = _as_int(data["test_timeout_seconds"], "test_timeout_seconds")
+    if "max_workspace_files" in data:
+        config.max_workspace_files = _as_int(data["max_workspace_files"], "max_workspace_files")
+    return config
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    if tomllib is None:  # pragma: no cover - only on 3.10 without tomli
+        raise ConfigError(
+            f"cannot read {path}: no TOML parser available. "
+            "Install `tomli` (Python 3.10) or use Python 3.11+."
+        )
+    try:
+        with path.open("rb") as handle:
+            return tomllib.load(handle)
+    except OSError as exc:
+        raise ConfigError(f"cannot read {path}: {exc}") from exc
+    except Exception as exc:  # tomllib.TOMLDecodeError and friends
+        raise ConfigError(f"{path} is not valid TOML: {exc}") from exc
+
+
+def load(repo_root: Path) -> Config:
+    """Load configuration for ``repo_root``.
+
+    Looks for ``.patchahead.toml`` first (a dedicated file wins over a shared
+    one), then ``[tool.patchahead]`` in ``pyproject.toml``. Returns defaults if
+    neither exists. Raises :class:`ConfigError` if one exists but is unusable --
+    a broken config is reported, never silently ignored.
+    """
+    repo_root = Path(repo_root)
+
+    dedicated = repo_root / CONFIG_FILENAME
+    if dedicated.is_file():
+        data = _load_toml(dedicated)
+        table = data.get("tool", {}).get("patchahead", data)
+        if not isinstance(table, dict):
+            raise ConfigError(f"{dedicated}: expected a table of settings")
+        log.debug("loaded config from %s", dedicated)
+        return from_mapping(table, source_path=str(dedicated))
+
+    pyproject = repo_root / PYPROJECT
+    if pyproject.is_file():
+        data = _load_toml(pyproject)
+        table = data.get("tool", {}).get("patchahead")
+        if isinstance(table, dict):
+            log.debug("loaded config from %s [tool.patchahead]", pyproject)
+            return from_mapping(table, source_path=f"{pyproject} [tool.patchahead]")
+
+    log.debug("no PatchAhead config found under %s; using defaults", repo_root)
+    return Config()

patchahead/demo/__init__.py

@@ -0,0 +1,256 @@
+"""The bundled demo: fixtures, and the scenarios that narrate them.
+
+``patchahead demo`` exists so that someone who has never seen this project can
+run one command and watch a real migration happen. Everything here is staging --
+*which* repository, *which* change document, and a sentence about what to look
+at. None of it is migration logic: the demo calls
+:func:`patchahead.engine.migrate` exactly as the CLI does, against a real
+directory, running real tests. A demo with its own code path proves nothing
+about the product, which is the mistake the prototype made.
+
+Two things make the staging honest rather than decorative:
+
+* every scenario declares the outcome it expects, and
+  ``tests/test_demo.py`` runs the real engine and asserts reality matches. A
+  scenario whose story stops being true fails the build.
+* the scenario list deliberately includes migrations that do **not** succeed.
+  A demo composed only of green checkmarks would be advertising the opposite of
+  what this tool is for: the interesting claim is not "it rewrites code", it is
+  "it knows when not to, and it will not call a patch verified without
+  evidence".
+
+The fixtures live inside the package (``patchahead/demo/fixtures/``) rather than
+in a top-level ``examples/`` directory, because ``patchahead demo`` has to work
+from an install in an empty directory, not only from a git checkout. The extra
+that carries its dependencies is ``[demo]``: the web UI plus the pytest that
+turns a patch into a verified migration.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = [
+    "DemoError",
+    "Expectation",
+    "Scenario",
+    "SCENARIOS",
+    "changes_root",
+    "find",
+    "fixtures_root",
+    "repo_root",
+    "scenarios",
+]
+
+
+class DemoError(Exception):
+    """The bundled demo data is missing or unreadable."""
+
+
+class Expectation(str, enum.Enum):
+    """What a scenario is expected to demonstrate.
+
+    These are the four states a migration run can end in, and telling them apart
+    is the whole point of the demo. ``VERIFIED`` is the only one that means "this
+    worked"; the other three are the ones a tool that overclaims would blur
+    together.
+    """
+
+    #: Tests failed before the patch and pass after it. The one honest success.
+    VERIFIED = "verified"
+    #: A patch was produced and nothing verified it. Not a success.
+    UNVERIFIED = "patched_unverified"
+    #: Impact was found and PatchAhead declined to rewrite it, with a reason.
+    REFUSED = "refused"
+    #: A patch was produced and the tests rejected it.
+    FAILED = "validation_failed"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+@dataclass(frozen=True)
+class Scenario:
+    """One bundled story: a change document, and what it demonstrates."""
+
+    #: URL-safe identifier, used by ``--scenario`` and by the web UI.
+    id: str
+    #: Short label for the picker.
+    title: str
+    #: Migration family, shown as a chip. Free text, not a ``ChangeKind``: one
+    #: scenario deliberately carries two families in a single document.
+    family: str
+    #: Filename inside ``fixtures/changes``.
+    document: str
+    expect: Expectation
+    #: One sentence: what this scenario is for.
+    headline: str
+    #: One sentence: where to look on screen once it finishes.
+    watch_for: str
+    #: ``False`` runs the migration with test execution disabled, which is the
+    #: only way to reach ``patched_unverified`` on this repository -- its suite
+    #: is red before the patch, so every other path produces evidence one way or
+    #: the other.
+    run_tests: bool = True
+
+    @property
+    def change_path(self) -> Path:
+        path = changes_root() / self.document
+        if not path.is_file():
+            raise DemoError(f"bundled change document is missing: {path}")
+        return path
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "family": self.family,
+            "document": self.document,
+            "expect": self.expect.value,
+            "headline": self.headline,
+            "watch_for": self.watch_for,
+            "run_tests": self.run_tests,
+        }
+
+
+#: Ordered deliberately: the clean red-to-green migration first, because it is
+#: the claim everything else qualifies, then the two harder successes, then the
+#: three ways a run can end without one.
+SCENARIOS: tuple[Scenario, ...] = (
+    Scenario(
+        id="field-rename",
+        title="A renamed field",
+        family="field_rename",
+        document="field-rename.md",
+        expect=Expectation.VERIFIED,
+        headline=(
+            "The upstream `order` object renamed `total` to `amount`. Two reads break; "
+            "a display string that merely contains the word does not."
+        ),
+        watch_for=(
+            '`TOTAL_LABEL = "total"` is untouched in the diff. It is a string, not a '
+            "field access, so it was never a candidate."
+        ),
+    ),
+    Scenario(
+        id="pagination",
+        title="Page numbers to cursors",
+        family="pagination_page_to_cursor",
+        document="pagination-cursor.md",
+        expect=Expectation.VERIFIED,
+        headline=(
+            "The endpoint dropped `page`/`total_pages` for `cursor`/`next_cursor`/"
+            "`has_more`. This is a loop rewrite, not a rename."
+        ),
+        watch_for=(
+            "The function keeps its name, signature, docstring and accumulator. Four "
+            "spans inside one loop change; nothing else does."
+        ),
+    ),
+    Scenario(
+        id="sdk-v2",
+        title="Two changes, one call site",
+        family="method_rename + kwarg_rename",
+        document="sdk-v2.md",
+        expect=Expectation.VERIFIED,
+        headline=(
+            "One release note, two breaking changes, both landing on the same line. "
+            "Neither works alone -- they have to be applied together."
+        ),
+        watch_for=(
+            "Two plans, one workspace, one validation run. Run the `method-rename` "
+            "scenario to see what half of this migration does."
+        ),
+    ),
+    Scenario(
+        id="receiver-mismatch",
+        title="Same field name, different object",
+        family="field_rename",
+        document="invoice-field-rename.md",
+        expect=Expectation.REFUSED,
+        headline=(
+            "A change document about `invoice` objects, run against code that only "
+            "touches `order` objects. The field name matches. Nothing else does."
+        ),
+        watch_for=(
+            "Both sites are found, explained and graded low -- then left alone. This "
+            "is the scenario that matters: a tool that rewrote them would be wrong."
+        ),
+    ),
+    Scenario(
+        id="method-rename",
+        title="Half a migration",
+        family="method_rename",
+        document="method-rename.md",
+        expect=Expectation.FAILED,
+        headline=(
+            "Only the method rename, without the keyword-argument rename that shipped "
+            "with it. The patch is correct and the result still does not work."
+        ),
+        watch_for=(
+            "`targeted_tests` fails, so the run is rejected. PatchAhead does not "
+            "report a migration it cannot stand behind."
+        ),
+    ),
+    Scenario(
+        id="no-evidence",
+        title="The same patch, with the tests switched off",
+        family="field_rename",
+        document="field-rename.md",
+        expect=Expectation.UNVERIFIED,
+        run_tests=False,
+        headline=(
+            "Byte-for-byte the diff from the first scenario, with test execution "
+            "disabled -- the shape of any repository whose tests do not cover a change."
+        ),
+        watch_for=(
+            "Identical diff, different verdict: PATCHED, NOT VERIFIED. Without a test "
+            "that failed before and passes after, there is nothing to verify it."
+        ),
+    ),
+)
+
+
+def fixtures_root() -> Path:
+    """Directory holding the bundled demo data.
+
+    Package data, so it is present in a wheel install and in an editable
+    checkout alike.
+    """
+    root = Path(__file__).resolve().parent / "fixtures"
+    if not root.is_dir():
+        raise DemoError(
+            f"the bundled demo fixtures are missing from the installed package "
+            f"(expected {root}). Reinstall patchahead, or run from a git checkout."
+        )
+    return root
+
+
+def repo_root() -> Path:
+    """The bundled example repository. Read-only as far as the engine is concerned."""
+    repo = fixtures_root() / "orders-service"
+    if not repo.is_dir():
+        raise DemoError(f"the bundled example repository is missing: {repo}")
+    return repo
+
+
+def changes_root() -> Path:
+    changes = fixtures_root() / "changes"
+    if not changes.is_dir():
+        raise DemoError(f"the bundled change documents are missing: {changes}")
+    return changes
+
+
+def scenarios() -> tuple[Scenario, ...]:
+    """Every bundled scenario, in presentation order."""
+    return SCENARIOS
+
+
+def find(scenario_id: str) -> Scenario:
+    for scenario in SCENARIOS:
+        if scenario.id == scenario_id:
+            return scenario
+    known = ", ".join(scenario.id for scenario in SCENARIOS)
+    raise DemoError(f"no such demo scenario: {scenario_id!r}. Available: {known}")

patchahead/demo/fixtures/changes/field-rename.md

@@ -0,0 +1,14 @@
+# Orders API — v2.0.0 Release Notes (Orders schema)
+
+## Breaking changes
+
+### Order field renamed: `total` → `amount`
+
+The monetary field on each `order` object was renamed.
+
+- **Before:** each order object had a `total` field.
+- **After:** the field is now named `amount`. `total` has been **removed**.
+- **Migration:** read `amount` instead of `total`.
+
+> Risk: HIGH — code reading `order["total"]` will raise `KeyError` and
+> revenue numbers will silently break.

patchahead/demo/fixtures/changes/invoice-field-rename.md

@@ -0,0 +1,21 @@
+# Billing API — v3.0.0 Release Notes
+
+A release note from a *different* upstream service than the rest of the
+documents here. It is bundled so the demo can show what PatchAhead does when a
+change looks applicable and is not.
+
+`orders-service` reads `order["total"]`. This document is about `invoice`
+objects. The field name is identical; the object is not, and no amount of
+string matching can tell the difference.
+
+## Breaking changes
+
+### Invoice field renamed: `total` → `amount`
+
+The monetary field on each `invoice` object was renamed.
+
+- **Before:** each invoice object had a `total` field.
+- **After:** the field is now named `amount`. `total` has been **removed**.
+- **Migration:** read `amount` instead of `total` on invoices.
+
+> Risk: HIGH — billing code reading `invoice["total"]` will raise `KeyError`.

patchahead/demo/fixtures/changes/kwarg-rename.md

@@ -0,0 +1,14 @@
+# Orders SDK — v2.0.0 Release Notes
+
+## Breaking changes
+
+### Keyword argument renamed: `timeout_seconds` → `timeout`
+
+The `timeout_seconds` keyword argument on `fetch_orders` was renamed to `timeout`.
+The unit is unchanged (seconds); only the parameter name changed.
+
+- **Before:** `client.fetch_orders(limit=10, timeout_seconds=30)`
+- **After:** `client.fetch_orders(limit=10, timeout=30)`
+- **Migration:** rename the `timeout_seconds=` keyword argument to `timeout=`.
+
+> Risk: MEDIUM — calls raise `TypeError: unexpected keyword argument`.

patchahead/demo/fixtures/changes/method-rename.md

@@ -0,0 +1,12 @@
+# Orders SDK — v2.0.0 Release Notes
+
+## Breaking changes
+
+### Client method renamed: `fetch_orders` → `list_orders`
+
+- **Before:** `client.fetch_orders(limit=10)`
+- **After:** `client.list_orders(limit=10)`
+- The deprecated `fetch_orders` method has been **removed**.
+- **Migration:** call `list_orders` instead of `fetch_orders`. The signature is unchanged.
+
+> Risk: MEDIUM — calls raise `AttributeError` at runtime.

patchahead/demo/fixtures/changes/pagination-cursor.json

@@ -0,0 +1,24 @@
+{
+  "title": "Pagination is now cursor-based",
+  "kind": "pagination_page_to_cursor",
+  "old_behavior": "get_orders(page=N) returned `page` and `total_pages`",
+  "new_behavior": "get_orders(cursor=C) returns `next_cursor` and `has_more`",
+  "migration_hint": "Iterate with cursor/next_cursor; stop when has_more is false.",
+  "severity": "high",
+  "confidence": "high",
+  "target": {
+    "symbol": "page",
+    "replacement": "cursor",
+    "owner": "get_orders"
+  },
+  "pagination": {
+    "page_param": "page",
+    "total_pages_key": "total_pages",
+    "cursor_param": "cursor",
+    "next_cursor_key": "next_cursor",
+    "has_more_key": "has_more"
+  },
+  "evidence": [
+    "The `page` and `total_pages` response fields have been removed."
+  ]
+}

patchahead/demo/fixtures/changes/pagination-cursor.md

@@ -0,0 +1,20 @@
+# Orders API — v2.0.0 Release Notes
+
+## Breaking changes
+
+### Pagination is now cursor-based
+
+The Orders endpoint no longer uses page-based pagination.
+
+- **Before:** `get_orders(page=1)` returned `page` and `total_pages`.
+- **After:** `get_orders(cursor=<cursor>)` returns `next_cursor` and `has_more`.
+- The `page` and `total_pages` response fields have been **removed**.
+- **Migration:** iterate using `cursor` / `next_cursor` and stop when `has_more` is `false`.
+
+> Risk: HIGH — integrations that read `total_pages` will raise `KeyError`
+> and may silently sync incomplete data.
+
+## Non-breaking changes
+
+- Added `created_at` to each order object.
+- Improved rate-limit headers.

patchahead/demo/fixtures/changes/sdk-v2.md

@@ -0,0 +1,31 @@
+# Orders SDK — v2.0.0 Release Notes
+
+Two breaking changes in this release. Both affect the same call site, so they
+have to be migrated together — which is what this document demonstrates:
+PatchAhead applies every change from one document into one workspace, in order.
+
+## Breaking changes
+
+### Client method renamed: `fetch_orders` → `list_orders`
+
+- **Before:** `client.fetch_orders(limit=10)`
+- **After:** `client.list_orders(limit=10)`
+- The deprecated `fetch_orders` method has been **removed**.
+- **Migration:** call `list_orders` instead of `fetch_orders`.
+
+> Risk: MEDIUM — calls raise `AttributeError` at runtime.
+
+### Keyword argument renamed: `timeout_seconds` → `timeout`
+
+The `timeout_seconds` keyword argument on `list_orders` was renamed to `timeout`.
+The unit is unchanged (seconds); only the parameter name changed.
+
+- **Before:** `client.list_orders(limit=10, timeout_seconds=30)`
+- **After:** `client.list_orders(limit=10, timeout=30)`
+- **Migration:** rename the `timeout_seconds=` keyword argument to `timeout=`.
+
+> Risk: MEDIUM — calls raise `TypeError: unexpected keyword argument`.
+
+## Non-breaking changes
+
+- Added `created_at` to each order object.