RFC: Crate Architecture — Contract Kernel + Strangler Evolution
- Status: Proposed — design accepted; execution tracked in
TODOs.md§P-A. - Author: (proposed)
- Created: 2026-06-19
- Related:
docs/RFC_HARNESS_LOOP_OWNERSHIP.md,docs/ARCHITECTURE.md,docs/EXTENSIBILITY_MODEL.md,RoadMap.md,docs/archive/PROJECT_EVALUATION_2026-06-06.md,CLAUDE.md(four-layer model) - Affected crates: workspace-wide (new contract crates + dependency re-pointing).
No public-surface change — CLI commands, workflow YAML schema,
SKILL.md, and HTTP/v1/*contracts are all preserved.
TL;DR
Yanshi today supports four execution paradigms — static DAG workflows, native
agent loops, the harness governance shell, and (next) dynamic workflows (an
agent that generates a Flow at runtime). They mostly coexist, but three
seams keep them as semi-integrated parallel code paths instead of one coherent
stack:
yanshi-harnessdepends on theyanshi-agentscrate (not a contract), so the harness cannot govern anything but an agent loop.- Reliability primitives (retry / timeout / cancellation) are implemented twice
— once in
yanshi-core, once in theyanshi-agentsloop. - The DAG execution IR (
Flow) is fused with the executor, so a runtime cannot construct aFlowwithout depending on the scheduler — which blocks dynamic workflows.
This RFC defines a narrow-waist contract kernel plus eight dependency laws, and reaches it by an in-place strangler-fig migration — explicitly NOT a rewrite. The end-state makes dynamic workflow nearly free (no new sideways dependency) and turns the layering from convention into compiler-enforced structure via Rust’s trait system.
0. Decision — refactor in place, do NOT rewrite
A rewrite is justified only when no incremental path exists. None of the rewrite signals apply here:
| Rewrite signal | Yanshi reality |
|---|---|
| Foundational tech choice is wrong (lang/runtime/data model) | ❌ Edition 2024, Tokio, thiserror, no-unwrap discipline — all sound |
| No incremental path; changing A always breaks B | ❌ Target is reached by extracting contract crates + re-pointing deps |
| Core abstractions cannot carry new requirements | ❌ The IR already carries dynamic workflow once IR≠executor is split |
| No tests, unowned, unchangeable | ❌ ~132K LOC, eval harness, live-LLM CI, actively evolved |
The ~80% of the design that is already correct (dependency-clean core / tools
/ llm foundations, the faithful LoopSession extraction, 6-provider
consistency suite, checkpoint fidelity) is an expensive, hard-won asset. We
evolve in place and keep the tree green and shippable at every step.
1. Guiding principle — unify contracts downward, keep drivers distinct
Unification happens at the contract layer (everything reduces to a small set of narrow interfaces), not at the driver layer. Building one “do-everything” orchestrator over the four paradigms would be the big-and-broad trap. Instead:
- Contract kernel = a narrow waist; everyone depends on it; it depends on no concrete implementation.
- Four drivers = independent; they never import each other; they share only the kernel.
Crate-boundary rule (prevents both god-crates and over-splitting): a crate exists iff its set of dependents is distinct. Merge things with the same dependent-set; split things whose dependent-sets differ.
2. Capability vs Tool — the two load-bearing traits
- Tool (
工具) — an atomic, uniform-signature callable. The only thing a runtime loop directly invokes. Lives in a registry. Heterogeneous, injected. - Capability (
能力) — a packaged unit (persona + tools + knowledge + config) that lowers to tools + context at the runtime boundary.
#![allow(unused)]
fn main() {
// yanshi-tools — atomic action (object-safe SPI)
#[async_trait]
pub trait Tool: Send + Sync {
fn metadata(&self) -> ToolMetadata; // source / idempotency / permissions
async fn call(&self, params: FlowValue) -> Result<ToolOutput, ToolError>;
}
// yanshi-agent-spi — a capability lowers to (tools + context)
pub struct Lowered { pub tools: Vec<Arc<dyn Tool>>, pub context: Vec<ContextFragment> }
#[async_trait]
pub trait Capability: Send + Sync {
async fn lower(&self) -> Result<Lowered, CapabilityError>;
}
}
lower() returns an owned Lowered (not &mut Assembly) so capabilities
compose by flatten and are trivially testable. The surface merges all Lowered
into one ToolRegistry + ContextBuilder and hands it to a runtime. The runtime
forever sees only Tool + Context + AgentRuntime.
Status (P-A4.3): Capability + Lowered { tools, context } +
CapabilityError live in yanshi-agent-spi::capability; Lowered.context
reuses the kernel’s existing ContextItem (so the RFC’s “ContextFragment” is
that type), and Lowered::merge is the flatten primitive. yanshi-skills
ships SkillCapability, which lowers a Skill to its tool registry contents + the
persona as a Critical context fragment. Full surface adoption (merging a
Vec<Box<dyn Capability>> in place of the direct SkillBuilder::build path) is
the remaining follow-up.
Modeling rule: open behavior extension points are traits
(Tool/Capability/AgentRuntime/KnowledgeBackend); closed data sets we own
are enums with #[non_exhaustive] (FlowValue, HarnessEvent kind,
ToolOutputPart). Never an event-as-trait or a tool-as-enum.
3. Target layering
| Tier | Representative crates | Single responsibility | May depend on | Must NOT depend on |
|---|---|---|---|---|
| Surfaces | cli, server, worker, ui | Assembly (DI): import everything, wire capabilities into runtimes | all | — |
| Runtimes | core (executor), agents (loop, can emit Flow), harness (governance) | Drive loop / execute graph / govern | contracts only | each other |
| Capabilities | skills, rag, memory, llm | impl Capability / impl *Backend; lower to tools+context | contracts + wrapped tools | runtimes |
| Tools | tools-builtin, mcp, rag (rag_search), nodes | impl Tool / provide AsyncNode | tool contract (+ backend) | runtimes, other tools |
| Contract kernel | value, tool, graph, store-spi, agent-spi, async-util | The narrow waist | only downward to value | any impl |
4. Contract kernel (the narrow waist)
| Crate | Single responsibility | Dependents | Own deps | Priority |
|---|---|---|---|---|
yanshi-value | Data contract: FlowValue + conversions | almost all | none | defer (re-export) |
yanshi-tool* | Action contract: Tool / ToolRegistry / ToolMetadata | tools, capabilities, runtimes | value | exists today |
yanshi-graph | Execution IR: AsyncNode / GraphNode / Flow / NodeType | core, nodes, agents, worker | value | must (split from core) |
yanshi-store-spi | KnowledgeBackend / MemoryStore | skills, rag, memory, agents | value | must |
yanshi-agent-spi | AgentRuntime / AgentEvent / Capability / HarnessEvent / EventSink / Approval* | agents, harness, tracing, server | value, tool | must |
yanshi-async-util | retry / timeout / cancellation combinators | core, agents | tokio, futures | must (de-dup) |
*yanshi-tool = the Tool contract carved out of today’s yanshi-tools;
the built-in file/http/shell tools move to yanshi-tools-builtin (optional;
may stay feature-gated in place initially).
Safe merges are rare: store-spi cannot fold into agent-spi (that would force
rag to depend on AgentRuntime); value stays a separate universal leaf. The
crate count reflects genuinely distinct dependent-sets — this is evidence of low
coupling, not ceremony.
5. IR ≠ executor
Flow (the DAG type) lives in yanshi-graph; the topological/concurrent
scheduler FlowExecutor lives in yanshi-core. This single split lets
agents depend on graph to construct a Flow (the dynamic-workflow
prerequisite) without ever depending on the executor — preserving “runtimes
never depend on each other.”
6. Rust trait design decisions
- dyn at seams, generic inside. Cross-injection contracts are object-safe
(
Arc<dyn Tool>,Box<dyn Capability>,Box<dyn AgentRuntime>). Internal hot paths use generics/concrete types (monomorphized, zero-cost). - Object-safety discipline. The four SPI traits avoid object-safety killers
(no generic methods, no
Selfreturn, no associated types in signatures);async fnis boxed via#[async_trait]at the seam only. Concrete returns (Vec<Chunk>), nevertype Output— associated types fragment the trait object. (This is the same constraint that produced the existing object-safeTurnDrivenRuntime/LoopSession.) - Core trait +
Exttrait. Keep the object-safe trait minimal; put ergonomic generic helpers in a blanket-impl’d…Ext: …trait (impl<T: Tool + ?Sized> ToolExt for T {}), never called throughdyn. - Orphan rule dictates adapter placement. Every cross-crate adapter needs a
local newtype in the assembling crate (
McpToolAdapter,WorkflowTool,AgentNode). This is why the MCP→Tooladapter lives inyanshi-skills, and it generalizes to all adapters — adapters never pollute contract crates. - Type-state + newtypes eliminate whole bug classes (per the project’s own
“encode invariants in types, don’t
panic” guidance):Session<Active>/Session<Finished>— callingnext_turnon a finished session becomes a compile error (replaces theSessionFinishedguard).Seqnewtype + aSeqAllocator::stamp(event)that couples allocation and dispatch in one critical section — closes the seq-vs-write ordering race.Validated<ModelId>constructible only after a successful build — closes the chat-REPL “stalecur_modelafter failed switch” bug.ByteSafeStr/ only exposing.chars().take(n)— closes the UTF-8 byte-slice panic at the API level.
- Evolution & errors.
#[non_exhaustive]on every contract enum (adding a variant is non-breaking — required for the beta-stableHarnessEventwire); sealed traits for internal-only protocols; each contract crate owns athiserrorboundary error enum that impls map into viaFrom. - Feature flags = compile-time low coupling. Contract crates are
feature-less (always present); optional capabilities (
rag,mcp) are gated by consumers; features must be additive. Combined with the orphan rule, a capability that is not compiled has noimpl Capabilityto wire — zero binary, zero runtime cost.
7. Eight dependency laws (enforced by xtask check-arch)
- Contract crates depend only downward to
value; never on any impl. - A tool crate depends on the
toolcontract only; not on runtimes or other tools. - A capability depends on contracts + the tools it wraps;
impl Capability::lower; never on a runtime. - Runtimes never depend on each other; only on contracts; capabilities/tools are injected by surfaces.
- IR ≠ executor:
Flowingraph, scheduler incore. - The executor depends on
graph/value/async-util; never onagents/harness. - Reliability primitives live once in
async-util;coreandagentsreuse them. - Surfaces are the only tier allowed to import the whole graph.
8. Four execution paradigms on this architecture
| Paradigm | Plan author | Executor | Crates touched (contracts + self) |
|---|---|---|---|
| Static DAG | human (code/YAML) → Flow | core | graph → core |
| Native loop | agents (implicit per-step) | agents | agent-spi, graph, tool |
| Harness | as above + governance | agents + harness shell | harness → agent-spi (not agents) |
| Dynamic workflow | agents generates Flow | core executes; nodes may be AgentNode; harness governs | agents→graph build, core→graph execute, harness→agent-spi govern — all meet only via contracts |
The last row is the payoff: once graph and agent-spi are the waist, dynamic
workflow requires no new sideways dependency.
9. RAG repositioning
RAG is on the capability axis, not a top-level mode. yanshi-rag becomes a
KnowledgeBackend implementation behind a Skill’s knowledge: declaration with
tiered progressive disclosure (frontmatter → bundled files via grep/read → RAG
vector retrieval → structured query). RAG fires only when bundled-file
navigation is insufficient (large / dynamic / multi-tenant corpora). The eval
harness is retained — it is the only quality gate for the cases RAG is still
for. The user-facing rag search/index CLI demotes to ops subcommands.
Status (P-A4.1): the KnowledgeBackend SPI lives in yanshi-store-spi
(alongside MemoryStore); yanshi-rag implements it as Bm25KnowledgeBackend
(bundled-files tier) + VectorStoreKnowledgeBackend (vector tier) and exposes
the rag_search Tool (RagSearchTool).
Status (P-A4.2): a Skill’s [[knowledge]] entries carry a backend field
(files default — inline into the persona; rag — index the bundled files and
expose the rag_search tool). SkillBuilder routes each entry independently.
Status (P-A4.1b): the user-facing rag search / rag index /
rag collections CLI is demoted under an ops group (yanshi rag ops <cmd>); rag eval stays top-level (it is the quality gate). The agent-facing
retrieval path is the rag_search tool a Skill exposes.
10. Migration — strangler fig (no rewrite)
Grow the new kernel inside the existing workspace; re-point crates one at a time
behind pub use re-exports; keep cargo test + clippy -D warnings green per
PR. Execution is tracked as track P-A in TODOs.md:
- P-A0 — Guardrails. Land this RFC; add
xtask check-archwith the eight laws and an allowlist of current violations to burn down. - P-A1 — Contract kernel. Create
agent-spi,store-spi, splitgraphout ofcore, extractasync-util; re-export from old paths. Prove the design with adynamic_workflowvertical-slice spike (value → graph → agent-spi → toy runtime → agent emits Flow → core executes). - P-A2 — Runtime decoupling. Re-point
harnessfromagentstoagent-spi(injection at surfaces); let harness govern aFlowrun (P-A2.2 —HarnessRuntime::run_flowMVP landed: envelope + tool-call governance via a wrapped node registry; node-level events + CLI/server surface are follow-ups); extractworker-protosoworker ⊥ server; extract shared assembly soserver ⊥ cli. - P-A3 — Reliability + type hardening. Consolidate retry/timeout/cancel into
async-util; introduceSession<S>type-state,Seqnewtype,ByteSafeStr,Validated<ModelId>(closes the known bug classes). - P-A4 — Dynamic workflow + RAG repositioning.
rag→KnowledgeBackend;PlanExecuteAgentemits a realFlow; productionize the spike;Capability::lowerwiring inskills.
P-A0+P-A1 are low-risk and do “now”; P-A2/P-A3 are gated behind thickened tests; P-A4 is feature work sitting on the cleaned dependencies.
11. Out of scope / untouched
core IR semantics, tools built-ins, the 6 llm providers, mcp, db,
ui, and all external contracts (CLI / workflow YAML / SKILL.md / HTTP
/v1/*). No crate merges/splits beyond the kernel listed in §4. This is a pure
internal dependency re-arrangement.
12. Risks
- P-A3 touches the hot loop (
react/agent.rs) — gate behind expanded tests; reuse the existing “faithful extraction” discipline. - Re-export churn — mechanical; mitigate with one-crate-per-PR and
xtask check-archregression-proofing. - Kernel over-fragmentation — capped at six single-responsibility crates by the distinct-dependent-set rule; no further splitting without that test.
13. Refinements (2026-06-20 architecture-lens evaluation)
docs/ARCHITECTURE_EVALUATION_2026-06-20.md validated this RFC against the
src-confirmed dependency graph (per-edge symbol analysis, not just crate-level
deps). Verdict: direction confirmed, adopt as-is, with these deltas folded in:
- R1 —
valueis promoted, not deferred. §4 markedyanshi-value“defer (re-export)”; it is in fact a hard prerequisite ofgraph(which depends onFlowValue) and the most widely-imported leaf. Extract it first in P-A1. - R2 — the
agents→coresplit is risk-free. Symbol analysis showsagentsimports only IR symbols fromcore(AsyncNode/Flow/FlowValue/AsyncNodeInputs/YanshiError) and zero executor symbols — so the §5graphsplit resolves the edge with no residual coupling. - R3 —
yanshi-nodesneeds an explicit decomposition decision (the one genuine crate-division gap, tracked as P-A0.5).nodesstraddles tool / capability / runtime tiers; split tool-tier nodes (template/file/http/batch/conditional/arxiv/markmap→graph+toolonly) away from capability-backed nodes (llm/asr/tts/image*/rag/mcp). Decided indocs/RFC_NODES_DECOMPOSITION.md: split intoyanshi-nodes(tool-tier) + a newyanshi-nodes-aiadapter crate; lands in P-A4 after thegraphsplit. - R4 —
llm→coreis already gone (removed Q3.6.1); §1 seam #2 and the §4llmrow overstatellm’s coupling.llmhas no internal deps. - R5 — track the full target-state edge map, not just the 4 gate-enforced
runtime/surface edges. Seven latent capability/tool violations (evaluation §2
rows 5–11) must be repointed as the kernel lands; notably
harnesscarries 5 impl edges, of which the allowlist tracks onlyharness→agents. - R6 — fold three “thin reason, fat dep” edges into existing kernel crates
rather than minting micro-crates:
harness→llm(tokenizer only) andmemory→rag(EmbeddingProvideronly) →store-spi/value;mcp→tracing(traceparent ambient only) →agent-spi/value. Keeps the kernel at six.
Status (U2.1, 2026-07-30): the harness→memory edge R5 flagged is paid
down — yanshi-harness now depends on yanshi-store-spi directly
(production code only ever needed MemoryStore/Message, both plain
store-spi re-exports), leaving harness with 4 impl edges instead of 5.
The parallel agents→memory edge is not paid down and, on closer
inspection, isn’t the same kind of edge R5/R6 describe: yanshi-agents’s
ReActAgent depends on ProjectMemoryStore/ProjectFact
(project-memory feature, added after this RFC’s writing), which have no
store-spi contract yet — this needs a genuine contract extraction (T3.3’s
Tool/yanshi-tool split is the template), not just “inject the
existing contract at the surface.” See docs/ARCHITECTURE_EVALUATION_ 2026-06-20.md’s U2.1 update for the full accounting.
Status (U2.5, 2026-07-31): the ProjectMemoryStore/ProjectFact
contract extraction U2.1 called out is done — both now live in
yanshi-store-spi::project (T3.3-shaped split, yanshi-memory
re-exports the contract types and keeps the concrete stores). The
agents→memory edge still doesn’t close, though: ReActAgent also
depends on the concrete yanshi_memory::SqlitePreferenceStore +
PreferenceScope (added by U2.2, after U2.1’s re-audit), and
PreferenceStore’s &mut self write methods were explicitly left off
store-spi in U2.2’s own scope decision. That redesign+extraction is
now the real remaining prerequisite. See docs/ARCHITECTURE_EVALUATION_ 2026-06-20.md’s U2.5 update for the full accounting.
Status (U2.6, 2026-08-01): the PreferenceStore redesign+extraction
is also done — its &mut self constraint turned out not to be
load-bearing (SqlitePreferenceStore only touches &self.pool), so
the trait moved to yanshi-store-spi::preference as &self,
matching ProjectMemoryStore/TaskSummaryStore. The agents→memory
edge still doesn’t close: a third reason surfaced —
yanshi-agents/src/dynamic.rs’s DynamicWorkflowAgent constructs a
concrete SessionMemory as its default memory backend, which has no
store-spi contract by design (not a gap to extract). Closing this
edge for real now needs DynamicWorkflowAgent’s default memory to be
made caller-injectable — accepted as-is rather than tracked as a new
item. See docs/ARCHITECTURE_EVALUATION_2026-06-20.md’s U2.6 update
for the full accounting.