From 17a985cb41727b8a1bca4d95f334106c09386040 Mon Sep 17 00:00:00 2001 From: t Date: Sun, 7 Jun 2026 14:57:58 -0600 Subject: Alias Conversation instead of facading it; merge addAssistantMessage A facade that forwards every method 1:1 is worse than paring the real type down to the intended surface and aliasing it. conversation.Conversation's interface is already the public surface we want (init/deinit, the add*/replace* builders, and messages/allocator as plain data fields), so public.zig now aliases it straight through and Agent.conversation() returns a borrowed *Conversation for in-place surgery. Drops the ConversationData alias and the pointer-wrapper. Merged addAssistantMessageWithUsage into addAssistantMessage(blocks, ?usage) on the real type (separate method deleted), so the alias has the intended one-method shape; all call sites updated. Only Agent and Stream remain true facades -- they have genuinely-internal fields plus API-shaping renames (Stream.phase->state, Phase->State) an alias can't express. --- docs/libpanto-cleanup.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/libpanto-cleanup.md b/docs/libpanto-cleanup.md index a495ff5..bc1e1aa 100644 --- a/docs/libpanto-cleanup.md +++ b/docs/libpanto-cleanup.md @@ -71,9 +71,25 @@ touching `agent.zig`. ### Three buckets — wrap, handle, or alias +> **Updated during implementation:** `Conversation` moved out of the +> behavioral-wrap bucket. Its internal interface was pared down to exactly +> the intended public surface (constructors + the `add*`/`replace*` +> builders; `messages`/`allocator` are fine as public data fields for a Zig +> object), so `public.zig` now **aliases** `conversation.Conversation` +> straight through instead of pointer-wrapping it. `Agent.conversation()` +> returns a borrowed `*Conversation` for in-place surgery. Only `Agent` and +> `Stream` remain true façades — they have genuinely-internal fields +> (`config`/`registry`/`session`/`open_stream_fn`/... and +> `queue`/`response`/`pending_error`/...) plus API-shaping renames +> (`Stream.phase`→`state`, `Phase`→`State`) that an alias can't express. +> `addAssistantMessageWithUsage` was merged into +> `addAssistantMessage(blocks, ?usage)` on the real type (the separate +> method deleted), so the alias already has the intended one-method shape. + | bucket | rule | types | | --- | --- | --- | -| **behavioral** | wrap a **pointer** to a heap-pinned internal | `Agent`, `Stream`, `Conversation` | +| **behavioral** | wrap a **pointer** to a heap-pinned internal | `Agent`, `Stream` | +| **behavioral (pared + aliased)** | trim the real type to the public surface, then alias | `Conversation` | | **data (read/output)** | **alias** straight through; inspected field-by-field | `Event` (+ nested), `Usage`, `Pricing`, `SessionInfo` | | **data (constructed)** | **alias** straight through; Zig users build them with `ArrayList` directly | `ContentBlock`, `Message`, the block types, `Config` family, `ResultPart` | -- cgit v1.3