boxmaker/docs/plans/M5a/02-proto-memory.md

M5a task 02: proto, the memory tools' arguments and messages

Branch: m5a (run git switch m5a; git status --short must be empty, otherwise stop) Commit subject: proto: memory, the arguments of recall and memory and eight message kinds

Goal

The shared types of M5a (spec, sections 5 and 7): the arguments of recall and memory with their shape checks, and the eight messages memoryd exchanges with loopd, brokerd and bxctl. brokerd's list of message kinds grows to twenty-six.

Files

• Copy: the skeleton crates/proto/src/memory.rs; crates/proto/tests/memory_args.rs, crates/proto/tests/memory_wire.rs, and the eight fixtures crates/proto/tests/fixtures/wire/{memory_block,memory_block_reply,session_updated,memory_call,reindex,reindexed,memory_admin,memory_admin_reply}.json
• Modify: crates/proto/src/lib.rs, crates/proto/src/wire.rs, crates/brokerd/src/broker.rs, docs/implementer-log.md

The skeleton

Written: the constants, every type with its serde attributes, and the message structs. To fill, each with the code in its comment: ConsolidateEntry::action, entry_problem, RecallArgs::check, MemoryArgs::check. Count characters with chars().count(), never len().

The edits, exactly

proto/src/lib.rs: add pub mod memory; after pub mod log;, and after pub use log::{LogRecord, ToolCall, Usage}; add:

pub use memory::{
    ConsolidateEntry, EntryAction, MemoryAdmin, MemoryAdminReply, MemoryArgs, MemoryBlockReply,
    MemoryCall, MemoryCommand, MemoryFile, RecallArgs, Reindexed, SessionUpdated,
};

proto/src/wire.rs: after use crate::gateway::{ApprovalOutcome, ApprovalPosted, ApprovalReply, ApprovalRequest}; add

use crate::memory::{
    MemoryAdmin, MemoryAdminReply, MemoryBlockReply, MemoryCall, Reindexed, SessionUpdated,
};

and in enum Message, after ApprovalOutcome(ApprovalOutcome),, add these eight variants, in this order:

    MemoryBlock(Empty),
    MemoryBlockReply(MemoryBlockReply),
    SessionUpdated(SessionUpdated),
    MemoryCall(MemoryCall),
    Reindex(Empty),
    Reindexed(Reindexed),
    MemoryAdmin(MemoryAdmin),
    MemoryAdminReply(MemoryAdminReply),

brokerd/src/broker.rs, kind: the doc comment's "all eighteen kinds" becomes "all twenty-six kinds", and after Message::ApprovalOutcome(_) => "approval_outcome", add:

        Message::MemoryBlock(_) => "memory_block",
        Message::MemoryBlockReply(_) => "memory_block_reply",
        Message::SessionUpdated(_) => "session_updated",
        Message::MemoryCall(_) => "memory_call",
        Message::Reindex(_) => "reindex",
        Message::Reindexed(_) => "reindexed",
        Message::MemoryAdmin(_) => "memory_admin",
        Message::MemoryAdminReply(_) => "memory_admin_reply",

Steps

• 1. Copy the skeleton, the two tests and the eight fixtures from docs/plans/M5a/files/ to the same paths.
• 2. Make the edits above; cargo check --workspace.
• 3. See it fail. cargo test -p proto --test memory_args --test memory_wire. Expected: memory_wire 2 passed (the types are given); memory_args 4 failed, 2 passed.
• 4. Fill the four functions. cargo fmt --all.
• 5. See it pass. The same command: 6 and 2 passed.
• 6. Run the gate. make gate: gate: ok, with 8 more tests than before (about 862).
• 7. Log and commit. git add -A crates docs/implementer-log.md Cargo.lock && git commit

Done when

• make gate prints gate: ok.

Stop and report if

• A given test or fixture fails after the four functions follow their comments exactly.