ratatoskr/persistent-memory.d/2026-07-19-worldtree-sdk-cutover-slice-5-complete.md

# worldtree-sdk cutover — SLICE-5 COMPLETE (characters + me/capabilities/models)

`[2026-07-19]` Slice 5 of 7 of the worldtree-sdk consumer cutover (issue #20;
contract `docs/contracts/worldtree_sdk_cutover.contract.md`). Full House Code
Discipline end-to-end: contract slice-notes → TDD → LIVE smoke → heid-code-review →
fixup → heid-bug-hunt → fixup. Both heid panels cleared. Suite **488 green**.

## Commits (tags v0.21.16–.18, on `main`, not-yet-pushed)

- **`deab762`** feat — the six routes onto `ratatoskr.wt`, hand-rolled deleted.
- **`d86d6df`** fix — heid-code-review fixups (CLI presenter degrade-not-crash).
- **`4e20030`** fix — heid-bug-hunt fixups (CLI open-world container-type hardening).

## What migrated

`get_me` / `get_capabilities` / `list_character_models` / `create_character` /
`get_character_state` / `delete_character` moved off the hand-rolled httpx wrappers
onto `client.me.get()` / `client.capabilities.get()` /
`client.models.available_for_characters()` / `client.characters.create|state|delete`.
All six are **open-world reads/acks returned verbatim**; none carries a discriminated
SDK error, so each maps any `ApiError` → the `SessionApiFailed` default —
**NO new § Error map rows** (exact parity with the retired path, which never
discriminated a status/code on these routes).

**CLI-only rewire** — `--whoami` (me + capabilities) and `--characters`
(models → create → state → delete) build a `wt.build_client` over the injected
`_probe_client` transport and catch `wt.SessionApiFailed` + `ConnectFailed`. **No
web-server caller** for any of these six routes.

Deleted the six hand-rolled `sessions.py` wrappers (net **−5 mypy `no-any-return`**
errors); `endpoint_for_plane` + `get_session_bifrost` (slice-6) + the exception
classes stay. Retired the matching `test_sessions.py` classes (`TestGetMe`,
`TestGetCapabilities`, `TestTransientCharacters`); kept `TestEndpointForPlane` +
`TestGetSessionBifrost`.

## Decisions made at TDD (contract § slice-5 notes)

- **`create_character` omits `state` when None** — SDK-idiomatic inline literal
  (per branch, to type-check against the SDK's `CreateCharacterInput` TypedDict
  without importing its private `_types`); server-equivalent to the retired explicit
  `state: null` (Worldtree's field defaults None either way). The only wire-shape
  change; the sole call-site never sets state.
- **`delete_character` returns the SDK's open ACK verbatim** (`-> Mapping | None`,
  not normalized to the hand-rolled `None`; 204 → None). The CLI ignores it.

## LIVE SMOKE (:8081/b128, `WORLDTREE_API_KEY`, INV-CUT-5 / DEC-4 cleared)

Drove both probes end-to-end through the CLI (`python -c "from ratatoskr.cli import
main; main([...])"` — the `ratatoskr` console script isn't on PATH here; `python -m
ratatoskr.cli` imports without calling `main`, no `__main__` guard). `--whoami`
rendered real identity (user_id ratatoskr, tier user, scopes incl. `character.*`,
key_id c990f0be) + `ephemeral_template echo`. `--characters` drove the full
lifecycle: `char-rp` catalog → `created char_…` → `state pad=[0.234,−0.136,0.065]`
read-back → `deleted`. Observed real success, not merely non-crash.

## heid-code-review (thread 01KXXRN50K…) — 2 fixups

Panel: **Gróa + Regin zero** (adapter/route-map/error-map faithful); **Hulda** flagged
2 source-confirmed CLI open-world-presenter crash holes + a live-smoke test-gap. Both
holes fixed (the null/element layer):
- `_format_whoami` `scopes`: `', '.join(me.get('scopes', []))` crashes on a
  present-null `scopes` (`.get(k, [])` returns None, not the default) or a non-string
  element. The contract names `_format_whoami` the degrade-not-crash exemplar — the
  cited exemplar had an un-hardened line (`allowed_roles` was hardened in slice-4,
  `scopes` was not).
- `_characters_probe` model `items`: the slice-5 `or []` guarded the list-level null
  but not each entry (`[None]`/`["x"]`/`[{"name":123}]`).
Test-gap (live-smoke not in the file set) → accept (it WAS run + recorded).

## heid-bug-hunt (thread 01KXXS9S45…) — 3 fixups + 1 accept + 1 dismiss

Cold spec-free diff-scoped panel over the post-code-review-fixup diff. Adapter +
route-map + `ConnectFailed`-at-call-sites **sound against the declared invariants
(all arms agree)**. 4 real findings, all CLI open-world paths — the **container-type
layer BELOW** the null/element holes the code-review had just fixed (the code
comments cite the CR; the two consults were firewalled from each other and converged
independently):
- **[bug, fixed] non-iterable `scopes`/`allowed_roles`** — `{"scopes": 123}` →
  `123 or [] == 123` → `for s in 123` TypeError. New `_display_seq(value)` helper
  degrades any non-list (scalar / bare string / null / absent) to empty; applied to
  both.
- **[bug, fixed] non-iterable `items`** — `{"items": 123}`, same class. Guard `models`
  is a Mapping AND `items` is a list before iterating.
- **[robustness, fixed] non-mapping top-level `created`/`state`** — a non-mapping SDK
  passthrough (`created=[...]`) → `.get` AttributeError. `isinstance(_, Mapping)`
  guard → clean exit-20 abort / `pad=None`.
- **[robustness, ACCEPTED] the probe leaks its transient character on a mid-lifecycle
  failure** — create → state → delete linear, no `finally`. PRE-EXISTING (retired
  probe had the identical structure — "cutover did not worsen it"), TTL-bounded,
  one-shot diagnostic; a `try/finally` would swallow a happy-path delete-failure
  (delete is both teardown and a tested step). Gróa + Heid concur accept is
  defensible. Documented in contract § slice-5 notes.
- **[DISMISSED] `sessions.py` dropped `get_me`/etc.** (Hulda, caller-contract) — the
  intended DEC-3 no-backwards-compat migration (all in-repo callers rewired
  same-diff); Heid labels it intended-surface-change, not a defect.

**Regin BH calibration note:** Regin (glm-5.2 non-reasoning) found only the leak,
missed the 3 crash paths, and self-graded "0 confirmed" on a control-flow-guaranteed
finding — consistent with the crystallized **Regin-unreliable-on-bug-hunts** pattern
(its code-review work this session was reliable). Gróa was the BH standout.

## The cumulative lesson (foot-gun for slices 6-7)

Open-world SDK reads need degrade-not-crash guarding at **THREE levels**, and the two
heid lenses caught different ones: the CODE-REVIEW (conformance) caught the
null/element layer; the cold BUG-HUNT (robustness) caught the container-type layer
below it. Run BOTH — they are complementary, not redundant. The three levels:
1. **container-type** — the field value may be a truthy non-iterable scalar (`123`) or
   a bare string; `or []` only catches null/absent. Guard `isinstance(_, (list, tuple))`.
2. **element-type** — each entry may be a non-mapping; guard `isinstance(m, dict)`.
3. **top-level-mapping** — the whole read may be a non-mapping passthrough; guard
   `isinstance(_, Mapping)` before any `.get`.

See also [[2026-07-19-worldtree-sdk-cutover-slice-4-complete]] (the slice-4 arc + the
`-m` double-module class-identity foot-gun).