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:
sam committed 2026-08-31 21:26:06 +10:00
1 parent 806cd75e28
commit b236e8a256
4 files changed
+203 -4

No files matched your search

+6
View File
@@ -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 |
+55 -4
View File
@@ -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:
+100
View File
@@ -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
}
+42
View File
@@ -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")
}
}