ratatoskr/persistent-memory.d/2026-07-18-worldtree-sdk-371-and-sillytavern-app.md

[2026-07-18] Worldtree owns the official Conversation API SDK (#371); the SillyTavern-style app is a fresh TS sibling, NOT a fork of Rata.

The question that started it

Operator: "I want to create an app like SillyTavern that runs on Worldtree. Ratatoskr is already most of the way there, so I'm thinking we fork it." → turned into a structural decision about how a new Worldtree chat product should relate to Rata.

Why NOT fork Rata

Rata splits into three layers: (1) a Worldtree client spine (~1.8k LOC — sse_client.py SSE/resume, sessions.py session/agent/persona clients, tier3.py agent lifecycle); (2) a Bifrost provider layer (provider/*); (3) thin front-ends (debug web console + --send CLI). The reusable part is the client spine; the part that diverges is the front-end — and Rata's front-end is a debug-observability console you'd throw away for a chat product. Forking gives you the wrong 60% and makes you delete it, and muddies Rata's reference-impl identity. The ecosystem norm is already independent spec-pinned siblings (Skaldsong Python, mead-hall TS, Rata) — not forks.

The decision (operator ruled YES 2026-07-17, via worldtree-dev)

• Worldtree owns an official Conversation API client SDK — spec-author-ships-the-SDK (Stripe/GitHub shape), keeps SDK↔spec in lockstep, avoids consumer-depends-on-peer-consumer coupling.
• Dedicated repo (name settled at WT's shape pass), elevated onto Worldtree's pre-v1 work track (NOT parked behind WT's two v1 pillars — agent bus + KB).
• Shape: TS-first (near-term demand); types/CRUD generated from WT's published OpenAPI (worldtree-conversation-api-openapi-v2) + a hand-written SSE/resume/error spine seeded from Rata's sse_client/sessions/tier3. TS+Python same-source keeps them in sync. Internal-registry-only distribution, permanently.
• TS package ships v0 first, Python the following milestone → Rata's own repin rides the Python milestone (not imminent; no schedule pressure on us).
• SillyTavern-style chat app = fresh TS sibling consuming the SDK, NOT a fork of Rata. template-dev stands up the app repo. Its early TS client is the natural seed for the SDK's TS side (Rata seeds Python, the app seeds TS) — so it isn't throwaway.
• Bifrost held OUT of scope: the provider Protocols already ship in the bifrost package; Rata's provider/* is a reference provider (a different, smaller audience). Separate track if ever warranted.

Rata's contributions this session

• Parity-matrix usage inventory shipped to worldtree-dev (18 routes; SSE event/resume/ heartbeat surface; full error-code → typed-exception table; auth scopes; 8 compat hacks that must survive the repin). The load-bearing one: empty-id SSE frames treated as keepalives (a provider emits id-less events mid-stream — re-strictifying id parsing crashes turns on it) → promoted to normative rule B-KA-2 in WT's behavioral spec. W-4 (tier-3 role/model drift) triggered a Worldtree-side spec fixup. Seeded WT docs/sdk/parity-matrix.md (698cfc3), behavioral-spec (c999b5f).
• Fixture-corpus gap caught (verified, then sent): issues/1.contract.md's TESTS predate awaiting_llm_first_token (#201) + affect_update (#204) — its full_event_vocab stops at the 8-event set. WT confirmed and patched the fixture-checklist (87d2569) to seed from _envelope_for_type (authoritative 11-variant parse surface), not #1 alone. WT fixture corpus landed independently: 3019ee6, 66 fixtures, validator clean.
• issue-#1 contract drift fixed our side (4bd9abd) — re-canonicalized the SSE event vocab (added both events to the Event union + TESTS via a dated amendment; docs-only, no bump).
• Personal-WT endpoint shipped for fixture/conformance capture: http://10.250.50.152:8081 (health-checked live; unified error envelope = current-gen deploy). No key provisioning needed (operator env carries instance keys). Capture run waits on explicit operator go + instance choice (demo :8080 vs personal :8081).

Pinned for our eventual repin (SDK diverges from Rata in 3 spots)

• D-1 — unknown SSE event type → skip with a diagnostics hook, vs Rata's current hard ValueError in _envelope_for_type. Adopt only at repin.
• D-2 — open-world enums.
• D-3 — typed eager 410 session_retired.

Resolution (operator, 2026-07-18 evening)

No arbo fork, no SillyTavern-on-Rata — both app products leave Rata to a NEW repo (template-dev standing up). Rata does NOT fork and is NOT the app base; it reverts to its core (Worldtree debug-observability surface + Bifrost reference impl + Conversation-API SDK seed/future-consumer). This retires the 2026-07-17 "fork Rata for arbo" NEXT-MAJOR plan. Rata's only forward stake in the app work is the SDK #371 — as the seed donor and a future consumer that repins on the Python milestone. The "SillyTavern app is a fresh TS sibling" framing above was the decision at the time; the app itself is now the new repo's concern, not Rata's.

Tracking

Worldtree #371 (their tracking issue). Rata-side: contract fix 4bd9abd. Cross-references: 2026-07-18-368-silo-test-passed (the prior arc), the reference-impl posture (auto-memory feedback_ratatoskr_is_a_reference_impl_adopt_canonical).