docs(architecture): reconcile domain package map, add domain/messaging types
- migration-decisions.md: confirm curator/mapping/scheduling as legitimate domains that were never added to the confirmed list; document identity/agent/messaging/plugin as approved-but-unmaterialised targets rather than creating dead stub packages. - Resolve the open Session/Messaging decision (section 2): keep internal/gateway as-is rather than risk a big-bang rewrite of live session/compression/approval/branch logic; materialise internal/domain/messaging with the already-settled canonical Message/Conversation/ToolCall/ToolResult types. Actual gateway migration onto these types is tracked as sequenced follow-up bd issues (label messaging-migration). - ARCHITECTURE.md: add internal/gateway, internal/tools, internal/memory, internal/secret, internal/plugin, internal/skill to the Package Map.
This commit is contained in:
1 parent
806cd75e28
commit
b236e8a256
4 files changed
+203
-4
No files matched your search
@@ -34,6 +34,12 @@ See `docs/architecture/organisation.md` for the target structure and
|
||||
| `internal/events/` | In-process event bus: publish/subscribe for observability |
|
||||
| `internal/infrastructure/` | Config loading, eventbus transport, model catalog |
|
||||
| `internal/webui/` | SSE dashboard: live event stream, task status |
|
||||
| `internal/gateway/` (18.7k LOC) | Persistent-connection layer between archie and its users (Telegram, web UI, etc.); shared CommandRouter for dispatch |
|
||||
| `internal/tools/` (20.9k LOC) | Central tool subsystem: built-in tool implementations, approval, execution contract |
|
||||
| `internal/memory/` (7k LOC) | Pluggable memory provider architecture |
|
||||
| `internal/secret/` | Secret reference resolution across named engines (env, vault, etc.) |
|
||||
| `internal/plugin/` | Core plugin interface: Yaegi-interpreted `.go` plugins loaded from `~/.config/archie/plugins/` and registered with the daemon's extension registry |
|
||||
| `internal/skill/` | Parses and discovers agentskills.io `SKILL.md` files |
|
||||
| `ai-sdk/runtime` | External: provider-agnostic LLM runtime |
|
||||
| `ai-sdk/agentloop` | External: gated agent loop with budgets and tool jails |
|
||||
| `ai-sdk/core` | External: tool definitions, generate options |
|
||||
|
||||
@@ -18,12 +18,15 @@ tests, persistence, and runtime wiring.
|
||||
|
||||
```text
|
||||
internal/domain/
|
||||
identity/
|
||||
agent/
|
||||
identity/ (approved, not yet materialised as a package)
|
||||
agent/ (approved, not yet materialised as a package)
|
||||
workflow/
|
||||
messaging/
|
||||
messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)
|
||||
workintake/
|
||||
plugin/
|
||||
plugin/ (approved, not yet materialised as a package)
|
||||
curator/
|
||||
mapping/
|
||||
scheduling/
|
||||
```
|
||||
|
||||
- `identity` owns persistent actors, lifecycle, ownership, attribution, and
|
||||
@@ -43,6 +46,30 @@ internal/domain/
|
||||
- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle
|
||||
mechanics. It remains metadata-only; capability semantics and typed
|
||||
registration belong to the owning domain.
|
||||
- `curator` owns the curator engine family: long-running agent loops that
|
||||
reason over memory and perform maintenance tasks on a declared shape
|
||||
(check-in interval, tool set, attached memory engine). See epic
|
||||
archie-core-yp9.
|
||||
- `mapping` owns the payload field-mapping vocabulary: binding named fields to
|
||||
JSON paths inside a captured webhook payload, and detecting drift. See
|
||||
`docs/prds/payload-field-mapping.md`.
|
||||
- `scheduling` owns the ticker engine: deciding when a scheduled job runs and
|
||||
with what concurrency. It declares `JobSource`/`Runner` contracts and owns
|
||||
no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.
|
||||
|
||||
**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed
|
||||
in the tree without being added to this list when their epics landed. They are
|
||||
confirmed as legitimate, narrowly-scoped domains under the same rules as the
|
||||
original six — each owns one capability family, declares typed contracts, and
|
||||
has no cross-domain reach. This list was out of date, not the tree.
|
||||
|
||||
Conversely, `identity`, `agent`, `messaging`, and `plugin` are approved target
|
||||
domains that do not yet exist as packages. Their behaviour currently lives in
|
||||
pre-migration packages (see "Complete package destination map" below for the
|
||||
full inventory). Do **not** create empty stub packages for them ahead of an
|
||||
actual migration PR — an unused stub is dead code and gives no test coverage.
|
||||
Each materialises when its corresponding migration decision below is resolved
|
||||
and implemented in the same change.
|
||||
|
||||
Memory's final package placement remains undecided pending focused review of the
|
||||
existing implementation.
|
||||
@@ -105,6 +132,30 @@ implementation evidence:
|
||||
- normal scoped-memory behaviour regardless of the originating Conversation;
|
||||
- Messaging and Work Intake ownership.
|
||||
|
||||
**Decision (2026-08-31), resolving the open questions above:**
|
||||
|
||||
`internal/gateway/` is the "parallel gateway session implementation" this
|
||||
section names. It is retained as-is for now — a big-bang rewrite of live
|
||||
session/compression/approval/branch logic across Telegram, web UI, email, and
|
||||
webhook channels in one change is exactly the "convoluted to satisfy edge
|
||||
cases" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would
|
||||
risk silent behavioural regressions in the one path every user-facing message
|
||||
travels through.
|
||||
|
||||
Instead, `internal/domain/messaging/` is materialised now with the pieces
|
||||
that are already decided and don't require touching gateway: the canonical
|
||||
`Message` and `Conversation` types (composite Conversation identity, immutable
|
||||
`MessageID`, typed tool-call/tool-result message variants, branch lineage via
|
||||
`ParentConversationID`/`ForkMessageID`). These are pure domain types with no
|
||||
gateway dependency — a new package, not a rewrite of an existing one.
|
||||
|
||||
Migrating `internal/gateway/`'s session, compression, approval, and branch
|
||||
logic onto these types is real, cross-channel-risk work and is **not** done in
|
||||
this pass. It is tracked as separate, appropriately-scoped bd issues (see
|
||||
`bd list --label messaging-migration`), sequenced channel-by-channel so each
|
||||
lands with its own behavioural verification instead of one large diff no one
|
||||
can safely review.
|
||||
|
||||
### 3. Identity data migration
|
||||
|
||||
The migration must define:
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
// Package messaging owns canonical Messages, Conversations, branches,
|
||||
// channel and source correlation, and typed tool-call/tool-result message
|
||||
// variants.
|
||||
//
|
||||
// This package intentionally contains only the vocabulary already settled
|
||||
// in docs/architecture/migration-decisions.md section 2: the composite
|
||||
// Conversation identity, immutable MessageIDs, typed tool-call and
|
||||
// tool-result messages, and branch lineage through ParentConversationID and
|
||||
// ForkMessageID. Migrating internal/gateway/'s session, compression,
|
||||
// approval, and branch logic onto these types is deliberately out of scope
|
||||
// here — see that section for why, and bd for the tracked follow-up work.
|
||||
package messaging
|
||||
|
||||
import "time"
|
||||
|
||||
// ConversationID is the composite identity of a Conversation: a channel and
|
||||
// the channel-native thread within it. Two conversations with the same
|
||||
// ChannelID but different ThreadID are distinct.
|
||||
type ConversationID struct {
|
||||
ChannelID string
|
||||
ThreadID string
|
||||
}
|
||||
|
||||
// MessageID is the canonical, immutable identifier for a Message. Once
|
||||
// assigned it never changes, including across branch and fork operations —
|
||||
// a forked transcript references the original MessageID it branched from
|
||||
// rather than minting a new one for shared history.
|
||||
type MessageID string
|
||||
|
||||
// Role identifies who or what produced a Message.
|
||||
type Role string
|
||||
|
||||
const (
|
||||
RoleUser Role = "user"
|
||||
RoleAssistant Role = "assistant"
|
||||
RoleTool Role = "tool"
|
||||
RoleSystem Role = "system"
|
||||
)
|
||||
|
||||
// Conversation is a single thread of Messages within a channel, optionally
|
||||
// forked from another Conversation.
|
||||
//
|
||||
// Parent and child transcript isolation is exact: a fork sees the parent's
|
||||
// history up to ForkMessageID, and appends to its own independent
|
||||
// continuation. Nothing appended to the child is visible to the parent, and
|
||||
// nothing appended to the parent after the fork point is visible to the
|
||||
// child.
|
||||
type Conversation struct {
|
||||
ID ConversationID
|
||||
|
||||
// ParentConversationID is the Conversation this one branched from, and
|
||||
// the zero value when this Conversation is not a branch.
|
||||
ParentConversationID ConversationID
|
||||
// ForkMessageID is the last MessageID visible to this Conversation from
|
||||
// its parent's history. Empty when ParentConversationID is empty.
|
||||
ForkMessageID MessageID
|
||||
|
||||
CreatedAt time.Time
|
||||
}
|
||||
|
||||
// IsBranch reports whether this Conversation was forked from another.
|
||||
func (c Conversation) IsBranch() bool {
|
||||
return c.ParentConversationID != ConversationID{}
|
||||
}
|
||||
|
||||
// Message is one immutable, persisted turn in a Conversation.
|
||||
type Message struct {
|
||||
ID MessageID
|
||||
ConversationID ConversationID
|
||||
|
||||
// SourceID is the channel-native identifier (e.g. a Telegram
|
||||
// message_id) this Message correlates to. Empty for messages with no
|
||||
// upstream identity.
|
||||
SourceID string
|
||||
|
||||
Role Role
|
||||
Text string
|
||||
|
||||
// ToolCall and ToolResult are populated instead of Text for their
|
||||
// respective Roles; a Message carries exactly one of Text, ToolCall, or
|
||||
// ToolResult content.
|
||||
ToolCall *ToolCall
|
||||
ToolResult *ToolResult
|
||||
|
||||
At time.Time
|
||||
}
|
||||
|
||||
// ToolCall is a typed request from the assistant to invoke a tool.
|
||||
type ToolCall struct {
|
||||
CallID string
|
||||
ToolName string
|
||||
Arguments string // JSON-encoded arguments, opaque to this package
|
||||
}
|
||||
|
||||
// ToolResult is a typed response to a prior ToolCall, correlated by CallID.
|
||||
type ToolResult struct {
|
||||
CallID string
|
||||
Output string
|
||||
Err string // non-empty when the tool call failed
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
package messaging
|
||||
|
||||
import "testing"
|
||||
|
||||
func TestConversationIsBranch(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
conv Conversation
|
||||
want bool
|
||||
}{
|
||||
{
|
||||
name: "root conversation",
|
||||
conv: Conversation{ID: ConversationID{ChannelID: "chan-1"}},
|
||||
want: false,
|
||||
},
|
||||
{
|
||||
name: "forked conversation",
|
||||
conv: Conversation{
|
||||
ID: ConversationID{ChannelID: "chan-1", ThreadID: "fork-1"},
|
||||
ParentConversationID: ConversationID{ChannelID: "chan-1"},
|
||||
ForkMessageID: "msg-42",
|
||||
},
|
||||
want: true,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
if got := tt.conv.IsBranch(); got != tt.want {
|
||||
t.Fatalf("IsBranch() = %t, want %t", got, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestConversationIDDistinguishesThreads(t *testing.T) {
|
||||
a := ConversationID{ChannelID: "chan-1", ThreadID: "t1"}
|
||||
b := ConversationID{ChannelID: "chan-1", ThreadID: "t2"}
|
||||
if a == b {
|
||||
t.Fatal("distinct ThreadIDs must produce distinct ConversationIDs")
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user