diff options
| author | t <t@tjp.lol> | 2026-06-07 14:57:58 -0600 |
|---|---|---|
| committer | t <t@tjp.lol> | 2026-06-07 14:57:58 -0600 |
| commit | 17a985cb41727b8a1bca4d95f334106c09386040 (patch) | |
| tree | 237a7f1e0d45dafb61ace13f5112ecd31170df4c /docs | |
| parent | 1eddee33902757f7e06993825a3ad1011e7ec346 (diff) | |
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.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libpanto-cleanup.md | 18 |
1 files changed, 17 insertions, 1 deletions
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` | |