@senpi/runtime 3.0.9-dev.feat-strategy-compos.20260722213012 → 3.0.9-dev.feat-strategy-compos.20260723050017

package/dist/composer/verbs/_target.py

@@ -0,0 +1,138 @@
+"""_target — the ONE composer ``<target>`` resolver shared by the graph-consuming verbs (K4).
+
+Before K4 the verbs disagreed about what a ``<target>`` is: ``status`` accepted a strategy NAME,
+``check`` / ``deploy`` demanded a full ``graph.yaml`` PATH. A model that typed
+``composer check my-strat`` (a name) or ``composer deploy ./my-strat/`` (a dir) got a bare
+``[Errno 2] No such file or directory`` / ``[Errno 21] Is a directory`` with NO fix_hint
+(dev-test #7). This module is the single acceptance surface. A ``<target>`` is ANY of:
+
+  * an explicit graph ``.yaml`` FILE path (the pre-K4 contract — resolves to itself, unchanged);
+  * a strategy DIR — a canonical ``<state>/composer/<name>/`` dir, or a ``composer deploy``
+    ``staged/`` tree — holding a ``graph.yaml`` (or ``main/<name>.graph.yaml`` inside a staged tree);
+  * a canonical strategy NAME resolved through the state-root layout
+    (:func:`composer.verbs._layout.canonical_graph_path`).
+
+It resolves to the graph ``.yaml`` :class:`~pathlib.Path` the verb should read, and TEACHES —
+via **CMP256**, the existing "graph file could not be read" class, ENUMERATING the strategies that
+DO exist under the state root — when nothing resolves. It reuses CMP256 rather than minting a
+parallel code: the failure the caller experiences ("I named a graph and it isn't there") is exactly
+CMP256's class; K4 only enriches the fix_hint with what IS available.
+
+Back-compat contract: any target that is already an existing FILE resolves to itself, so every
+currently-working ``check``/``deploy`` invocation is byte-identical. The NAME/DIR branches are new
+capability layered on top; a target that looks like a (missing) path or an empty directory falls
+THROUGH to the verb's own ``read_text`` so its pre-K4 CMP256 (missing file / IsADirectory) is
+preserved verbatim — the enumerating CMP256 fires only for a bare NAME that resolves to nothing.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from composer.validator.errors import Location, TeachingError
+
+from ._layout import COMPOSER_DIR, GRAPH_FILE, canonical_graph_path
+
+
+class TargetError(Exception):
+    """A composer ``<target>`` could not be resolved to a strategy graph. Carries a
+    :class:`TeachingError` (CMP256) the CLI renders exactly like a verb's teaching errors."""
+
+    def __init__(self, error: TeachingError) -> None:
+        super().__init__(error.message)
+        self.error = error
+
+
+def available_strategies(base_state_dir: Optional[str]) -> list[str]:
+    """The canonical strategy NAMES that carry a ``graph.yaml`` under ``<state>/composer/`` (sorted).
+    Empty when the state root is unknown or has no composer dir — the teaching hint degrades to a
+    generic instruction rather than fabricating a list."""
+    if not base_state_dir:
+        return []
+    root = Path(base_state_dir) / COMPOSER_DIR
+    if not root.is_dir():
+        return []
+    out: list[str] = []
+    for child in sorted(root.iterdir()):
+        if child.is_dir() and (child / GRAPH_FILE).is_file():
+            out.append(child.name)
+    return out
+
+
+def available_strategies_hint(base_state_dir: Optional[str]) -> str:
+    """A fix_hint fragment naming the strategies that DO exist (or how to find/create one). Shared by
+    the graph verbs (check/deploy) and the lifecycle verbs (status/update) so a "not found" always
+    points at the real, on-box options rather than repeating the rejected target."""
+    names = available_strategies(base_state_dir)
+    if names:
+        shown = ", ".join(names[:20]) + (", …" if len(names) > 20 else "")
+        return f"Known strategies under the state root: {shown}."
+    return ("No strategy graphs were found under the state root's `composer/` dir — run "
+            "`composer new <id> --archetype …` first, or pass the path to an existing graph .yaml.")
+
+
+def looks_like_path(target: str) -> bool:
+    """True when ``target`` is a PATH attempt (an existing path, a value carrying a path separator,
+    or a ``.yaml``/``.yml`` filename) rather than a bare strategy NAME. A path-like miss is left to
+    the verb's own ``read_text`` so its pre-K4 CMP256 (missing file / IsADirectory) is preserved."""
+    if Path(target).exists():
+        return True
+    if os.sep in target or (os.altsep and os.altsep in target):
+        return True
+    return target.endswith((".yaml", ".yml"))
+
+
+def graph_in_dir(d: Path) -> Optional[Path]:
+    """The graph record inside a strategy / staged DIR: the top-level ``graph.yaml`` snapshot
+    (canonical dir and deploy staged tree both carry it), else the in-unit ``main/<name>.graph.yaml``
+    a staged tree also holds. None when the dir carries no graph record."""
+    direct = d / GRAPH_FILE
+    if direct.is_file():
+        return direct
+    main = d / "main"
+    if main.is_dir():
+        for child in sorted(main.glob("*.graph.yaml")):
+            return child
+    return None
+
+
+def resolve_read_path(target: str, base_state_dir: Optional[str]) -> Path:
+    """Resolve a ``check`` / ``deploy`` ``<target>`` to the graph ``.yaml`` :class:`~pathlib.Path`
+    to read. Accepts a graph file (→ itself), a strategy/staged DIR (→ the graph inside), or a bare
+    strategy NAME (→ its canonical ``composer/<name>/graph.yaml``).
+
+    Returns the path the caller should ``read_text``. For an existing FILE this is the file itself
+    (byte-identical to pre-K4). For a path-like MISS (a missing ``.yaml`` path, or a directory with
+    NO graph inside) it returns the ORIGINAL path so the caller's own ``read_text`` raises the OSError
+    the caller already wraps as CMP256 (preserving the missing-file / IsADirectory teaching). It
+    RAISES :class:`TargetError` (CMP256, enumerating the available strategies) only for a bare NAME
+    that resolves to nothing — the case that previously produced a bare ``[Errno 2]``."""
+    p = Path(target)
+    if p.is_file():
+        return p
+    if p.is_dir():
+        found = graph_in_dir(p)
+        # a dir WITH a graph → that graph; an empty/graph-less dir falls through unchanged so the
+        # caller's read_text raises IsADirectoryError → its own CMP256 (the pre-K4 behaviour).
+        return found if found is not None else p
+    if looks_like_path(target):
+        # a missing FILE path (…/foo.graph.yaml): let the caller's read_text raise → its CMP256.
+        return p
+    # a bare STRATEGY NAME resolved through the canonical layout (needs the state root).
+    if base_state_dir:
+        cg = canonical_graph_path(base_state_dir, target)
+        if cg.is_file():
+            return cg
+    raise TargetError(TeachingError(
+        "CMP256",
+        f"the composer target {target!r} could not be resolved to a strategy graph — it is not an "
+        f"existing graph .yaml file, not a strategy directory, and no canonical "
+        f"`composer/{target}/graph.yaml` record exists under the state root.",
+        "Pass the path to an existing graph .yaml, a strategy directory, or a known strategy name. "
+        + available_strategies_hint(base_state_dir)
+        + (" (Pass `--state-dir <dir>` or set `SENPI_STATE_DIR` so a bare name can be resolved.)"
+           if not base_state_dir else ""),
+        Location(),
+    ))

package/dist/composer/verbs/close.py

@@ -387,7 +387,9 @@ def _resolve_targets(target: str, base_state_dir: str, strategies: list,
                 rec = json.loads(wj_path.read_text(encoding="utf-8"))
             except (OSError, json.JSONDecodeError):
                 rec = {}
-        wallet = str(rec.get("wallet") or "")
+        # K3 follow-up: tolerant address read — a hand-authored marker may use the MCP key spellings.
+        from .fund import _rec_wallet
+        wallet = _rec_wallet(rec)
         rec_sid = rec.get("strategyId")
         s = next((s for s in strategies
                   if (rec_sid and _strat_id(s) == rec_sid) or wallet_match(_strat_wallet(s), wallet)),

package/dist/composer/verbs/fund.py

@@ -242,6 +242,33 @@ def _match_strategy(strategies: list, strategy_id: Optional[str], wallet: Option
     return None
 
 
+# Hand-authored / alternate marker key spellings for the wallet ADDRESS (K3). The canonical writer
+# (_write_wallet_json) always emits ``"wallet"``, but a human (or model) authoring a wallet.json
+# marker by hand often copies the field name MCP ``strategy_list`` uses instead —
+# ``strategyWalletAddress`` / ``walletAddress`` / ``address`` (the exact spellings
+# ``close._strat_wallet`` reads). We accept those unambiguous alternates when resolving a marker so
+# the documented adopt/reuse flow survives a hand-authored marker; a backfill then NORMALIZES the
+# file back to the canonical ``"wallet"`` key.
+_WALLET_KEYS = ("wallet", "walletAddress", "strategyWalletAddress", "address")
+
+
+def _rec_wallet(rec: dict) -> str:
+    """The wallet address a wallet.json marker records, tolerating unambiguous hand-authored key
+    spellings (K3). Prefers the canonical ``wallet`` key, then the MCP-shaped alternates. The KEY
+    match is case-insensitive (a hand-author may write ``Address``); the VALUE is returned as read.
+    Empty string when the marker carries no recognizable address key."""
+    if not isinstance(rec, dict):
+        return ""
+    lower = {str(k).lower(): v for k, v in rec.items()}
+    for key in _WALLET_KEYS:
+        v = rec.get(key)
+        if not v:
+            v = lower.get(key.lower())
+        if v:
+            return str(v)
+    return ""
+
+
 # --------------------------------------------------------------------------- result
 
 @dataclass
@@ -563,12 +590,25 @@ def _verify_existing(target: str, strategy: str, budget: float, rec: dict, wj_pa
                      mcp_fn: McpFn, created_at: Optional[str],
                      kind: Optional[str] = None) -> FundResult:
     """Step (a): a wallet.json already exists — verify it via strategy_list, never re-fund.
-    ``kind`` (the recorded marker) is PRESERVED across any in-place backfill so a manual wallet
-    never loses its marker on a re-run."""
+
+    The marker is resolved by recorded strategyId AND by wallet ADDRESS against the LIVE strategies
+    (K3) — the documented adopt/reuse flow, kept alive for a HAND-AUTHORED marker: an alternate
+    address key spelling (``walletAddress`` / ``strategyWalletAddress`` / ``address``), an
+    address-only marker, or a wrong/stale strategyId sitting next to a live address all still adopt.
+    When the match lands by address, the live strategy's own id is written back (a stale recorded id
+    is corrected, never propagated), and the file is NORMALIZED in place to the canonical ``wallet``
+    key. ``kind`` (the recorded marker), ``created_at`` and ``budget`` are PRESERVED across any
+    in-place backfill so a manual wallet never loses its marker on a re-run. CMP231 remains for the
+    genuinely-stale case: no live strategy holds this wallet."""
     rec_kind = kind if kind is not None else wallet_kind(rec)
     result_kind = rec_kind or KIND_MANAGED
-    rec_wallet = str(rec.get("wallet") or "")
+    # Resolve the recorded address tolerating hand-authored key spellings (K3); keep the raw
+    # canonical-key value separately so we know whether the FILE needs normalizing back to "wallet".
+    rec_wallet = _rec_wallet(rec)
+    rec_wallet_canonical = str(rec.get("wallet") or "")
     rec_sid = rec.get("strategyId")
+    rec_budget = rec.get("budget", budget)                # PRESERVE the funded budget across backfills
+    rec_created = rec.get("created_at") or created_at
     try:
         strategies = _find_list(mcp_fn("strategy_list", status=LIVE_STATUSES), "strategies")
         mcp_ok = True
@@ -578,39 +618,61 @@ def _verify_existing(target: str, strategy: str, budget: float, rec: dict, wj_pa
     except McpError:
         strategies, mcp_ok = [], False
 
+    # Resolve by recorded strategyId FIRST, then fall back to the wallet ADDRESS (this is the adopt/
+    # reuse path K3 must keep alive for a hand-authored marker). When the match lands via the
+    # address fallback, the LIVE strategy's own id is authoritative — a stale-but-truthy recorded
+    # strategyId must be CORRECTED to it, never propagated into the result or the backfilled file.
     s = _match_strategy(strategies, rec_sid, rec_wallet)
     status = str(_strat_status(s) or "").upper() if s else ""
+    live_sid = _strat_id(s) if s else None
+    real_sid = live_sid or rec_sid
     addr = str(_strat_wallet(s) or "") if s else rec_wallet
+    write_addr = addr or rec_wallet
+    # The file drifts from live truth when the canonical "wallet" key is empty/stale (a
+    # created-but-not-yet-ACTIVE mint, or a hand-authored alternate-key/address-only marker) or when
+    # the recorded strategyId is stale. Any drift → backfill in place, normalizing to the "wallet"
+    # key and the correct id while PRESERVING kind/created_at/budget (requirement 3: a legacy-read
+    # marker is rewritten to the SAME path it was read from — never a new canonical file).
+    needs_backfill = bool(write_addr) and (
+        write_addr != rec_wallet_canonical or real_sid != rec_sid
+    )
 
     if status == "ACTIVE":
-        # Backfill the wallet address if the recorded one was empty (created-but-not-yet-ACTIVE run).
-        if addr and addr != rec_wallet:
-            _write_wallet_json(wj_path, strategy=strategy, wallet=addr,
-                               strategy_id=rec_sid or _strat_id(s), budget=budget,
-                               created_at=rec.get("created_at") or created_at, kind=rec_kind)
+        if needs_backfill:
+            _write_wallet_json(wj_path, strategy=strategy, wallet=write_addr,
+                               strategy_id=real_sid, budget=rec_budget,
+                               created_at=rec_created, kind=rec_kind)
         return FundResult(
-            target=target, verdict=FUNDED, strategy=strategy, wallet=addr or rec_wallet,
-            strategy_id=rec_sid or _strat_id(s), budget=rec.get("budget", budget),
+            target=target, verdict=FUNDED, strategy=strategy, wallet=write_addr,
+            strategy_id=real_sid, budget=rec_budget,
             kind=result_kind, message="wallet already funded and ACTIVE (no-op).",
         )
     if s is not None and status and status not in CLOSED_STATUSES:
+        if needs_backfill:
+            _write_wallet_json(wj_path, strategy=strategy, wallet=write_addr,
+                               strategy_id=real_sid, budget=rec_budget,
+                               created_at=rec_created, kind=rec_kind)
         return FundResult(
-            target=target, verdict=PENDING, strategy=strategy, wallet=addr or rec_wallet,
-            strategy_id=rec_sid or _strat_id(s), budget=rec.get("budget", budget),
+            target=target, verdict=PENDING, strategy=strategy, wallet=write_addr,
+            strategy_id=real_sid, budget=rec_budget,
             kind=result_kind, message=f"wallet still initializing (status {status}).",
         )
     if not mcp_ok:
         # Could not reach MCP to confirm — do NOT declare stale; re-run once reachable.
         return FundResult(
             target=target, verdict=PENDING, strategy=strategy, wallet=rec_wallet,
-            strategy_id=rec_sid, budget=rec.get("budget", budget), kind=result_kind,
+            strategy_id=rec_sid, budget=rec_budget, kind=result_kind,
             message="could not reach MCP to verify the recorded wallet — re-run `composer fund`.",
         )
-    # Found closed, or not present in the live set at all → the recorded wallet is stale.
+    # No LIVE strategy carries this strategyId OR this wallet address → genuinely stale. (fund
+    # resolves by wallet address against your active strategies, so "stale" here means no active
+    # strategy holds this wallet — not merely that the recorded strategyId moved on.)
     return _refused(target, strategy, TeachingError(
         "CMP231", f"the recorded wallet ({rec_wallet or 'strategyId ' + str(rec_sid)}) is "
-                  f"{status or 'no longer in your active strategies'} — wallet.json is stale.",
-        f"Its strategy was closed or is gone, so it cannot be installed. To fund a FRESH wallet "
+                  f"{status or 'not held by any of your active strategies'} — wallet.json is stale.",
+        f"fund resolves a marker by its recorded strategyId AND by its wallet address against your "
+        f"active strategies (`strategy_list`), so 'stale' means NO active strategy holds this wallet "
+        f"— its strategy was closed or is gone, and it cannot be installed. To fund a FRESH wallet "
         f"for {strategy!r}, delete the stale marker `{wj_path}` and re-run `composer fund`. If you "
         f"believe it is still open, check MCP `strategy_list` (it may be filtered out as terminal).",
         Location(),

package/dist/composer/verbs/install.py

@@ -295,7 +295,7 @@ def _auto_bind_wallet(target: str, out_dir: Optional[str], base_state_dir: str,
     # Imported lazily to avoid an import cycle (fund/close import install at module load).
     from ._box import LIVE_STATUSES, McpCredsMissing, McpError
     from .close import _find_list, _strat_id, _strat_status, _strat_wallet
-    from .fund import _match_strategy, _read_wallet_json
+    from .fund import _match_strategy, _read_wallet_json, _rec_wallet
 
     def _cmp206(msg: str, fix: str) -> tuple[str, TeachingError]:
         return "", TeachingError("CMP206", msg, fix, Location())
@@ -325,7 +325,9 @@ def _auto_bind_wallet(target: str, out_dir: Optional[str], base_state_dir: str,
             f"writes {canonical_wj}), then re-run `composer install` to auto-bind it — or pass "
             f"`--wallet 0x…` explicitly.",
         )
-    rec_wallet = str(rec.get("wallet") or "")
+    # K3 follow-up: read the address with the SAME tolerant reader fund/update use — a
+    # hand-authored marker records it under address/walletAddress/strategyWalletAddress.
+    rec_wallet = _rec_wallet(rec)
     rec_sid = rec.get("strategyId")
     try:
         strategies = _find_list(mcp_fn("strategy_list", status=LIVE_STATUSES), "strategies")