Track Worldtree #196: prepare for end_user_id → subject:{type,id} migration #10

New Issue

2026-05-23T14:25:07-07:00

vh commented

2026-05-23 14:25:07 -07:00

Context

Worldtree #196 (LOCKED design, not yet shipped) will replace end_user_id with a polymorphic subject: {type, id} field on the Conversation API. Worldtree-dev confirmed in althing thread 01KSBARG2B8M8C82H6AJGJWX1B (2026-05-23):

v0.22.0 shipped #197 instead of #196; the substrate change for #196 is not yet implemented. When it lands:

Wire-visible: subject: {type: "end_user", id: "vuong"} replaces end_user_id: "vuong"

v0.22.x intro version accepts BOTH with deprecation warning for legacy; v0.23.0 hard-deprecates

Implemented types at v1: end_user (id required), session_only (no id), stateless (no id)

Reserved types (422 subject_type_not_yet_implemented): room, chamber, service_workflow

Durable key extends to (tenant_namespace, agent_id, subject.type, subject.id) — tenant_namespace is new

Response body will echo subject + continuity_scope + warnings[]

Posture (per worldtree-dev's explicit guidance)

Don't pre-implement. The deprecation-warning mechanism will fire per call as the heads-up; migrate when the substrate change actually ships.

What this issue tracks

Watch for these signals from Worldtree side:

The substrate ships in a Worldtree v0.22.x or v0.23.0 release.
We start seeing deprecation warnings in audit_detail on session-create responses (our existing [create_session] log line should be amended to surface them).
The pinned spec doc (per ratatoskr #9) starts describing the new shape.

What we'll need to do (when migration triggers)

Widen ratatoskr.sessions.create_session to accept subject={type, id} instead of (or in addition to) end_user_id.
Widen ParsedArgs and _parse_args: replace --end-user-id with --subject-type + --subject-id OR keep --end-user-id as a shorthand for subject={type:"end_user", id:"<value>"}.
Amend issues #2, #3, #4, #5 contracts in place.
Consider the tenant_namespace field — what's our value? Likely fixed to a constant for single-operator ratatoskr.
Surface deprecation warnings via stderr label (mirrors the existing [session_api_failed] / [network_error] shape).

Out of scope (this issue)

Implementing anything before Worldtree ships the substrate. Worldtree-dev was explicit.
Discussing whether to keep the --end-user-id shorthand (decide at implementation time).

Why now

Worldtree-dev surfaced this on 2026-05-23. Filing now so we don't lose the heads-up.

## Context Worldtree #196 (LOCKED design, not yet shipped) will replace `end_user_id` with a polymorphic `subject: {type, id}` field on the Conversation API. Worldtree-dev confirmed in althing thread `01KSBARG2B8M8C82H6AJGJWX1B` (2026-05-23): > v0.22.0 shipped #197 instead of #196; the substrate change for #196 is not yet implemented. When it lands: > - Wire-visible: `subject: {type: "end_user", id: "vuong"}` replaces `end_user_id: "vuong"` > - v0.22.x intro version accepts BOTH with deprecation warning for legacy; v0.23.0 hard-deprecates > - Implemented types at v1: `end_user` (id required), `session_only` (no id), `stateless` (no id) > - Reserved types (422 `subject_type_not_yet_implemented`): `room`, `chamber`, `service_workflow` > - Durable key extends to `(tenant_namespace, agent_id, subject.type, subject.id)` — `tenant_namespace` is new > - Response body will echo `subject` + `continuity_scope` + `warnings[]` ## Posture (per worldtree-dev's explicit guidance) **Don't pre-implement.** The deprecation-warning mechanism will fire per call as the heads-up; migrate when the substrate change actually ships. ## What this issue tracks Watch for these signals from Worldtree side: 1. The substrate ships in a Worldtree v0.22.x or v0.23.0 release. 2. We start seeing deprecation warnings in `audit_detail` on session-create responses (our existing `[create_session]` log line should be amended to surface them). 3. The pinned spec doc (per ratatoskr #9) starts describing the new shape. ## What we'll need to do (when migration triggers) 1. Widen `ratatoskr.sessions.create_session` to accept `subject={type, id}` instead of (or in addition to) `end_user_id`. 2. Widen `ParsedArgs` and `_parse_args`: replace `--end-user-id` with `--subject-type` + `--subject-id` OR keep `--end-user-id` as a shorthand for `subject={type:"end_user", id:"<value>"}`. 3. Amend issues #2, #3, #4, #5 contracts in place. 4. Consider the `tenant_namespace` field — what's our value? Likely fixed to a constant for single-operator ratatoskr. 5. Surface deprecation warnings via stderr label (mirrors the existing `[session_api_failed]` / `[network_error]` shape). ## Out of scope (this issue) - Implementing anything before Worldtree ships the substrate. Worldtree-dev was explicit. - Discussing whether to keep the `--end-user-id` shorthand (decide at implementation time). ## Why now Worldtree-dev surfaced this on 2026-05-23. Filing now so we don't lose the heads-up.

vh added the needs-triage documentation task labels 2026-05-23 14:25:07 -07:00

vh referenced this issue from a commit

2026-05-23 14:41:31 -07:00

feat(sessions,cli,tui): issues #5 + #6 + worldtree-dev consumer-API follow-up

vh referenced this issue

2026-05-23 19:27:40 -07:00

TUI layout reshape + Tools pane (§5 v1 entry point) #13

vh referenced this issue from a commit

2026-06-17 21:28:00 -07:00

feat(provider): validate scope_filter against the v0.5 4-axis lattice

vh referenced this issue from a commit

2026-08-01 23:06:38 -07:00