This document maps Mike's specific questions and concerns to what the exploration found, where things actually live in the stack, and what's protocol-required vs. solvable at a higher layer.
Mike's question: Stronger isolation of crypto and security concepts. Make it hard to get wrong. End consumers shouldn't care about nonces, inbox IDs, installations. How close can we get?
Where this stands today:
Over the weekend I ran a structured exploration into whether libxmtp's internals, specifically mls_sync and the groups module, could be made meaningfully more modular without forcing a broad public crate split or breaking downstream consumers. These are the two largest and most complex modules in the codebase, and their size has been making it harder to reason about behavior, isolate bugs, and onboard new contributors.
I used my team of agents (Codex & Claude) to do the heavy lifting: planning milestones, executing the refactors, writing tests, and validating the results. The goal was to answer the modularity question with code, not architecture diagrams. Prove or disprove specific internal boundaries, then make a grounded recommendation. The work followed an incremental milestone plan (M0–M8), where each milestone produced reviewable commits and a retro that informed the next step.
Status: Living draft. Section 1 reflects converged direction from the brainstorm; later sections are placeholders to be filled in as the conversation continues. Do not treat unfilled sections as decided.
Signet today runs as a single daemon: the XMTP node, key vault, policy engine, credential lifecycle, and any agent code that consumes credentials all live in one process. That works for a developer running it on their laptop, but it forecloses two things we want:
PR: #553 (consolidated from earlier stacked PRs #538-#541)
I've been using qmd to index agent instruction files and Obsidian-style notes and noticed chunks landing in weird places. Pulled the thread and it turned into four distinct improvements, shipped as one PR with clean commit-per-change history.
The chunker uses scored "break points" (places where splitting is OK) and "protected regions" (places to never split). Four specific issues:
Comprehensive context for designing the next phase of Trails developer experience. Covers three layers: CLI trailhead primitives, the trails CLI tool, and pattern generators. Written April 5, 2026 after shipping beta.14.
These decisions shape the design across all three layers:
Both agents and curious human developers. An agent operates entirely through flags and JSON. A human who runs trails create without flags gets a guided experience. Neither should feel like a second-class citizen.
Stacked branches unlock something that wasn’t practical before: agents can independently ship large, complex features while keeping every change reviewable.
The confluence looks like this. On the build side, agent teams can now parallelize across a stack — one team on infrastructure, another on business logic, another on docs — and land a big feature as a series of small, scoped PRs instead of one monster diff. On the review side, code review tools like Reptle, Devin, and others are most effective when PRs are tight — small line count, limited file scope, clear intent. Stacks give both sides what they need.
That’s a real improvement over what we had before. Giant PRs that no human (or bot) can meaningfully review. Or the alternative: manually decomposing work into branches that constantly drift and conflict. Stacks make it possible to move fast on big features and enforce correctness at each slice. From a git hygiene pers
Context: Trails has four definition functions —
trail(),service(),event(), andpack()— that produce frozen objects withkinddiscriminants, namespaced IDs, and full participation in survey, warden, and testing. Layers are the exception: plain objects withnameandwrap, no factory, nokind, no topo registration, no governance. This document explores whether layers should be promoted to match the other primitives or subsumed into them.
// Auth: plain object literal
How an attempt to dogfood the Trails framework on its own governance system led to a deeper architectural insight — and made the framework better.
We set out to prove the Trails model by applying it to its own governance tool. The warden has 16 lint rules that check Trails conventions. We wrapped each one as a trail() with typed Zod schemas and examples, composed them into a lintFile hike via ctx.follow(), and made them discoverable through a wardenTopo.
"I'd like to split
blazeup in the CLI to simplycreatefor new repos, adding trails to existing projects, or adding a new package within a workspace. Thenaddfor the other parts of blaze, such astrails add trail 'name'."
This is a product-level restructuring of a 9-trail CLI tool. The old command tree:
trails blaze # scaffold a project (route composing 3 sub-trails)