Yanshi Architecture-Lens Evaluation — 2026-06-20
- Status: Complete — validates and refines
docs/RFC_CRATE_ARCHITECTURE.md. - Scope: all 16 workspace crates (15 Rust + 1 TS SPA), architecture / dependency
lens only — complements the security/code-quality lens of
docs/audit/(2026-05-24) rather than repeating it. - Question driving this pass: can the four execution paradigms (static DAG / native loop / harness / dynamic workflow) coexist as one coherent stack, and is the RFC’s contract-kernel crate division the right way to get there?
- Method: ground-truth internal dependency graph parsed from every
Cargo.toml[dependencies](dev-deps excluded — test-only, don’t shape the shipped graph), then per-edge symbol analysis (grep "use yanshi_X::") to learn why each edge exists, not just that it exists. No guesswork.
TL;DR
The RFC is fundamentally sound — direction confirmed, adopt as-is with six refinements (R1–R6 below). The four paradigms already coexist; the only thing keeping them as semi-integrated parallel code paths is that runtimes are fused to concrete capability/tool impls instead of contracts, and the DAG IR is fused with the executor. The narrow-waist contract kernel fixes both. Two findings strengthen the case and one exposes a genuine gap the RFC under-specifies:
- Confirming (de-risks the plan):
agents → coreimports only IR symbols (AsyncNode/Flow/FlowValue/AsyncNodeInputs/YanshiError) and zero executor symbols — so splittinggraphout ofcore(P-A1.3) fully resolves theagents→coreviolation with no residual coupling.coreitself depends on nothing internal — the executor never reaches up. The cleanest possible starting point. - Strengthening:
llmalready has no internal deps (thellm→coreedge the RFC still implies was removed in Q3.6.1). The RFC text should drop it. - Gap:
yanshi-nodesis a fat straddler — a tool-tierAsyncNodelibrary that also consumes capabilities (llm,rag) and a runtime (core). The RFC filesnodesunder “Tools” but its real dependency-set doesn’t fit any single tier. This needs an explicit decomposition decision (R3).
The xtask check-arch gate currently enforces 2 of the 8 laws (runtime- and
surface-isolation) and tracks 4 allow-listed edges. The remaining 7 latent
violations (against laws not yet activatable because the kernel crates don’t
exist) are enumerated below so each kernel-landing PR has its burndown list ready.
Update (T2.4, post-R1.2): the P-A track landed the L0 contract kernel and
xtask check-arch now enforces 3 of the 8 laws — runtime-isolation,
surface-isolation, and kernel-isolation (RFC §7 Law 1: an L0 contract-kernel
crate must not depend on any runtime/capability/tool/ops crate), added in R1.2
(2026-07-28). The rest of this document is left as the 2026-06-20 point-in-time
evaluation; see docs/ARCHITECTURE_DIAGRAM.md and cargo xtask check-arch’s
own output for the current dependency-law count and latent-edge list.
Update (U2.1, 2026-07-30): edge #6’s harness → memory half (row 6 of
§2’s table) is paid down — yanshi-harness’s production code only
ever touched MemoryStore/Message (both plain store-spi re-exports, not
yanshi-memory-specific impls), so [dependencies] now points at
yanshi-store-spi directly; yanshi-memory moved to
[dev-dependencies] for SessionMemory, used only by this crate’s own
tests. ARCH_LATENT_EDGES in xtask/src/main.rs no longer tracks it.
Edge #5’s agents → memory half stays real, not paid down — re-auditing
turned up a materially different reason than this table’s “inject via
agent-spi/store-spi at surfaces” framing assumed: yanshi-agents’s
ReActAgent production code (react/agent.rs) depends on
ProjectMemoryStore/ProjectFact (project-memory feature, landed after
this evaluation’s 2026-06-20 baseline), and neither has a store-spi
contract today — unlike MemoryStore/TaskSummaryStore/Message, which
already do. Closing this edge for real requires first extracting a
ProjectMemoryStore/ProjectFact contract into store-spi (the same
Tool/yanshi-tool split shape T3.3 already used for the tool
contract) — a separate, larger follow-up, not “inject the existing
contract at the surface.” Tracked as a new backlog item rather than left
as a stale “inject via store-spi” resolution note.
Update (U3.3, 2026-07-31): T3.3 (commit b06ce03, 2026-07-30 — one
day after this evaluation’s ground-truth pass) split the Tool
contract out of yanshi-tools into a new, dependency-free
yanshi-tool L0 kernel crate (docs/RFC_TOOL_CONTRACT_SPLIT.md).
§1’s table below still lists yanshi-tools as “Tool contract +
builtins” and §2’s violation map still lists agents/harness → tools
as the latent edge — both accurate as of the 2026-06-20 snapshot,
which predates the split by five weeks, so the table rows are left
as-is per this doc’s own snapshot-preservation convention (see the
T2.4 update above). Post-split, the accurate framing is: yanshi-tool
(L0, zero internal deps) carries the actual Tool contract;
yanshi-agents/yanshi-harness depend on yanshi-tool
directly, not on yanshi-tools; yanshi-tools (L2) depends on
and fully re-exports yanshi-tool, adding the builtin tool impls +
OS-sandbox backends. cargo xtask check-arch’s live edge list and
docs/ARCHITECTURE_DIAGRAM.md (updated alongside this note) are the
sources of truth for the current graph; this file stays a historical
point-in-time evaluation.
Update (U2.5, 2026-07-31): the U2.1 update above tracked
ProjectMemoryStore/ProjectFact as the extraction needed to close
edge #5’s agents → memory half. That extraction is now done —
mirroring the TaskSummaryStore split already in yanshi-store-spi,
ProjectMemoryStore (trait) + ProjectFact (struct) +
project_key_for_path moved to yanshi-store-spi::project;
yanshi-memory::project keeps InMemoryProjectMemoryStore/
SqliteProjectMemoryStore and re-exports the contract types under
their original yanshi_memory::{ProjectFact, ProjectMemoryStore, project_key_for_path} paths, so no call site needed to change. The
edge itself, however, still doesn’t close: re-auditing at the time
of this extraction found yanshi-agents’s ReActAgent also carries
a second, independent concrete-type dependency on yanshi-memory
— Option<Arc<tokio::sync::Mutex<yanshi_memory::SqlitePreferenceStore>>>
yanshi_memory::PreferenceScope(production fields, added by U2.2 after this evaluation’s baseline and after U2.1’s re-audit). UnlikeProjectMemoryStore,PreferenceStore’s write methods are&mut self(U2.2’s own scope decision explicitly left it offstore-spi, since that shape doesn’t fit this crate’sArc<dyn Trait>contracts without first redesigning it to&self+ interior locking). So flippingyanshi-agents/Cargo.toml’s[dependencies]fromyanshi-memorytoyanshi-store-spinow requires that redesign+extraction, not theProjectMemoryStoreone — tracked as a new, still-open backlog item rather than closing this edge prematurely.ARCH_LATENT_EDGESinxtask/src/main.rsdocuments this in full at theagents → memoryrow.
Update (U2.6, 2026-08-01): the PreferenceStore redesign+extraction
U2.5 called for is now done — re-auditing found the &mut self
constraint wasn’t actually load-bearing: SqlitePreferenceStore’s
writes only ever touch &self.pool (sqlx::SqlitePool is internally
Arc-backed and already safe to share), and AgeEncryptedPreferenceStore
just encrypts/forwards to its inner store. PreferenceStore (trait) +
PreferenceScope/PreferenceValue moved to
yanshi-store-spi::preference with &self write methods, matching
ProjectMemoryStore/TaskSummaryStore exactly; ReActAgent’s
preference_store field and RememberPreferenceTool both dropped their
Mutex wrapper for a bare Arc<dyn PreferenceStore>. Despite closing
both of U2.1/U2.5’s tracked reasons, edge #5’s agents → memory half
still doesn’t close: this pass’s re-audit surfaced a third,
different reason — yanshi-agents/src/dynamic.rs’s
DynamicWorkflowAgent constructs a concrete
Box::new(SessionMemory::default_window()) as the default memory
backend for LLM-authored agent plan steps. SessionMemory has no
store-spi contract by design (a deliberate concrete-impl-only type,
not a missing contract like the two above were), so closing this edge
for real needs DynamicWorkflowAgent’s default memory to become
caller-injectable — a materially different, larger change than
“extract one more contract.” Confirmed with the requester and left
un-opened as a new backlog item: this is now understood as an accepted,
load-bearing use of a concrete yanshi-memory type, not a to-do.
ARCH_LATENT_EDGES in xtask/src/main.rs carries the full account at
the agents → memory row.
1. Ground-truth dependency graph (src-confirmed, [dependencies] only)
| Crate | RFC tier (claimed) | Internal deps (real) | Edge reason (imported symbols) |
|---|---|---|---|
yanshi-core | Runtime (executor) + holds IR + FlowValue | — | (depends on nothing internal) |
yanshi-llm | Capability | — | (no internal deps; llm→core removed Q3.6.1) |
yanshi-tools | Tool contract + builtins | — | (no internal deps) |
yanshi-rag | Capability + tool | — | (no internal deps) |
yanshi-db | Ops / persistence leaf | — | (no internal deps) |
yanshi-tracing | Ops | core | events::{EventListener, WorkflowEvent} |
yanshi-mcp | Tool | tracing | context::{current_traceparent, scope} — traceparent ambient only |
yanshi-memory | Capability | rag | embeddings::EmbeddingProvider — SemanticMemory only |
yanshi-nodes | Tool | core, llm, mcp, rag, tools | core=IR; llm=Yanshi/Asr/Tts/Image; rag=retrieval nodes |
yanshi-agents | Runtime (loop) | core, llm, mcp, memory, tools | core=IR-only; llm/memory/tools=concrete impls |
yanshi-skills | Capability | agents, mcp, memory, rag, tools | agents=runtime (builds runnable agent) |
yanshi-harness | Runtime (shell) | agents, llm, memory, tools, tracing | llm=tokenizer only; tracing=redaction/storage/types |
yanshi-server | Surface | agents, cli, core, db, harness, llm, memory, skills, tools, tracing | surface assembly (+ cli edge — allow-listed) |
yanshi-worker | Surface | agents, core, llm, memory, nodes, server, tools | surface (+ server edge — allow-listed) |
yanshi-cli | Surface | agents, core, db, harness, llm, mcp, memory, nodes, rag, server, skills, tools, tracing | top assembly (imports the world — allowed) |
yanshi-ui | Surface (SPA) | — (HTTP client of /v1/*) | n/a |
2. The eight laws vs reality — full violation map
check-arch enforces laws 4/6 (runtime-isolation) and the surface-isolation
corollary today. The table marks [gate] for the 4 edges it already tracks and
[latent] for the 7 it can’t yet, because the target-tier laws (1/2/3/7) only
become checkable once the kernel crates exist. All 11 are real target-state debt.
| # | Edge | Breaks law | Status | Resolution |
|---|---|---|---|---|
| 1 | agents → core | 4/6 runtime-isolation | [gate] allow-listed | P-A1.3 graph split — edge becomes agents→graph (IR-only ✔) |
| 2 | harness → agents | 4/6 runtime-isolation | [gate] allow-listed | P-A2.1 repoint to agent-spi; runtime injected by surfaces |
| 3 | worker → server | surface-isolation | [gate] allow-listed | P-A2.3 extract worker-proto |
| 4 | server → cli | surface-isolation | [gate] allow-listed | P-A2.4 extract shared assembly crate |
| 5 | agents → {llm, mcp, memory, tools} | 4 (runtime fused to impls) | [latent] | inject via agent-spi/store-spi/tool at surfaces |
| 6 | harness → {llm, memory, tools, tracing} | 4 (runtime fused to impls) | [latent] | as above — allowlist under-counts harness debt by 4 edges |
| 7 | nodes → {llm, rag} | 2 (tool crate → capabilities) | [latent] | R3 — decompose nodes |
| 8 | nodes → core | 2 (tool crate → runtime) | [latent] | IR-only → nodes→graph after P-A1.3 |
| 9 | skills → agents | 3 (capability → runtime) | [latent] | P-A4.3 Capability::lower; surface wires the runtime |
| 10 | memory → rag | 3 (capability → capability) | [latent] | route via store-spi embeddings contract (R6) |
| 11 | mcp → tracing | 2 (tool → ops) | [latent] | trace-context contract leaf (R6) |
| — | tracing → core | (ops → runtime) | [latent] | becomes tracing→agent-spi+value once they exist |
Key insight: edges 5–6 are the structural heart of “four parallel paths.”
agents and harness are the two live runtimes; today each hard-wires the
concrete llm/memory/tools it drives. Once those become agent-spi /
store-spi / tool contract edges with injection at the surface, the two
runtimes stop being bespoke stacks and start being interchangeable drivers over
one waist — which is exactly what makes dynamic workflow “free.”
3. Per-crate verdict (architecture lens)
core— Soundest crate in the tree: zero internal deps, executor never reaches up. Its only architectural debt is law 5 (IR ≠ executor):value.rs,async_node.rs,node.rs,flow.rs,expr.rs(IR) live besidescheduler.rs,retry*.rs,timeout.rs,checkpoint.rs,resource_*.rs(executor). Split is mechanical; no consumer imports executor symbols it shouldn’t.llm— Clean leaf. No internal deps. Keep as a capability; its tokenizer sub-module is whatharness/agentsactually reach for (R6).tools— Already theToolcontract + builtins fused. RFC §4 carves the contract intoyanshi-tooland moves builtins toyanshi-tools-builtin; low urgency (no bad inbound edges), do it when convenient.rag— Clean leaf today. Repositions to aKnowledgeBackendcapability (P-A4.1); keep the eval harness as the quality gate.memory— Capability with one capability→capability edge (→ragforEmbeddingProvider). Minor; fold behindstore-spi(R6).tracing— Ops crate;→corefor the workflow event types. Becomes→agent-spi+→value. Theredactionmodule is (correctly) the thingharnessreuses — keep it reusable.mcp— Tool crate; only bad edge is→tracingfor the traceparent ambient (R6). Otherwise a clean tool provider.nodes— The one real crate-division problem (R3). Straddles tool / capability / runtime tiers. Largest cohesion debt in the workspace.agents— Runtime.→coreis IR-only (resolves cleanly viagraph); the→{llm,mcp,memory,tools}edges are the impl-fusion to undo via contracts.skills— Capability that depends on theagentsruntime (inversion). TheCapability::lowerwork (P-A4.3) flips this the right way up.harness— Runtime shell carrying 5 impl edges, only 1 tracked. After P-A2.1, four remain (llmtokenizer,memory,tools,tracing). The governance shell should sit onagent-spi+ the reusableredaction/token contracts, nothing more.db/server/worker/cli/ui— Surfaces (+ db leaf). Allowed to assemble broadly; the two cross-surface edges (3, 4) are the only debt, already tracked.uiis a pure/v1/*HTTP client — correctly outside the Rust graph.
4. RFC validation + six refinements
The RFC’s core decisions are confirmed: refactor-in-place (not rewrite);
narrow-waist contract kernel; Capability-vs-Tool as the two load-bearing traits;
IR ≠ executor; dyn-at-seams / generic-inside; #[non_exhaustive] contract enums.
Refinements (deltas, not reversals):
- R1 — Promote
value; do not defer it. RFC §4 marksyanshi-value“defer (re-export)”. Butgraphdepends onFlowValue, andFlowValue(incore/src/value.rs) is imported by the widest set of crates. Extractvaluefirst in P-A1 as the cheapest, highest-leverage cut and a hard prerequisite of thegraphsplit — not a later nicety. - R2 — Record that
agents→coreis IR-only. Add to RFC §5 / the P-A1.3 task: symbol analysis shows zero executor imports, so the split carries no risk of a hidden executor dependency surviving. De-risks the highest-churn step. - R3 — Give
nodesan explicit decomposition decision (new RFC §9a / P-A task). Options: (a) splitnodesintonodes-core(tool-tier:template/file/http/batch/conditional/while—graph+toolonly) and capability- backed nodes (llm/asr/tts/image*/rag/mcp) that move beside their capability or become thin adapters in a surface/assembly crate; (b) re-tiernodesas an assembly crate (not a leaf tool crate) and exempt it like a surface. Recommended: (a) — it’s the only choice that keeps the tool tier honest and letsworkerdepend on tool-tier nodes without draggingllm/ragin. - R4 — Drop the stale
llm→coreclaim from RFC §1 (seam #2 framing) and §4 (thellmdependent row). Already removed in Q3.6.1. - R5 — Ship the full target-state edge map, not just the 4 gate edges. The
check-archallowlist tracks 4 runtime/surface edges; the kernel migration must also repoint ~7 capability/tool edges (table §2 rows 5–11). Add these as a burndown checklist (P-A0.4) so activating each new law (a “one-line change” per the RFC) lands with its edge list already paid down — and so theharness4-edge under-count (row 6) is visible. - R6 — Decide the three “thin reason, fat dep” edges deliberately.
harness→llm(tokenizer only),mcp→tracing(traceparent only),memory→rag(embeddings only) each pull a whole crate for one small surface. Don’t mint three micro-crates — fold them into kernel crates that already exist in the plan: token-count → a util invalueorstore-spi; trace-context ambient →agent-spi(orvalue);EmbeddingProvider→store-spi. This keeps the kernel at six crates (RFC §12 cap) while killing three latent violations.
5. Crate-count sanity check (no over-splitting)
Applying the RFC’s own rule — a crate exists iff its dependent-set is distinct —
to the proposed end state: value (universal leaf), tool, graph,
store-spi, agent-spi, async-util each have genuinely distinct dependent-sets
(confirmed against §1). store-spi cannot fold into agent-spi without forcing
rag/memory to depend on AgentRuntime; value cannot fold upward. The
six kernel crates are warranted. R3 adds one decomposition inside the
existing nodes crate — net new published crates from this evaluation: the six
kernel + (worker-proto, shared-assembly from P-A2) + nodes-core split. No
god-crates, no ceremony crates.
6. Recommendations → ROADMAP / TODOs
- Adopt the RFC as the architecture of record (it already is). Fold R1–R6 into
docs/RFC_CRATE_ARCHITECTURE.mdand theP-Atrack inTODOs.md. - Refresh
RoadMap.md(stale 2026-05-14, pre-kernel) to name the four paradigms and the contract-kernel direction, demoting “two first-class paths.” - Keep ordering: P-A runs after the Q security/correctness waves — an architecture refactor must never preempt production-blocking fixes.
- Sequence within P-A1:
value(R1) →graph(R2) →agent-spi/store-spi(absorbing R6 contracts) →async-util→ dynamic-workflow spike. - Land the
nodesdecomposition decision (R3) as a short RFC addendum before P-A4 (worker node-coverage and dynamic-workflow node reuse both depend on it).