Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 → core imports only IR symbols (AsyncNode / Flow / FlowValue / AsyncNodeInputs / YanshiError) and zero executor symbols — so splitting graph out of core (P-A1.3) fully resolves the agents→core violation with no residual coupling. core itself depends on nothing internal — the executor never reaches up. The cleanest possible starting point.
  • Strengthening: llm already has no internal deps (the llm→core edge the RFC still implies was removed in Q3.6.1). The RFC text should drop it.
  • Gap: yanshi-nodes is a fat straddler — a tool-tier AsyncNode library that also consumes capabilities (llm, rag) and a runtime (core). The RFC files nodes under “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). Unlike ProjectMemoryStore, PreferenceStore’s write methods are &mut self (U2.2’s own scope decision explicitly left it off store-spi, since that shape doesn’t fit this crate’s Arc<dyn Trait> contracts without first redesigning it to &self + interior locking). So flipping yanshi-agents/Cargo.toml’s [dependencies] from yanshi-memory to yanshi-store-spi now requires that redesign+extraction, not the ProjectMemoryStore one — tracked as a new, still-open backlog item rather than closing this edge prematurely. ARCH_LATENT_EDGES in xtask/src/main.rs documents this in full at the agents → memory row.

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)

CrateRFC tier (claimed)Internal deps (real)Edge reason (imported symbols)
yanshi-coreRuntime (executor) + holds IR + FlowValue—(depends on nothing internal)
yanshi-llmCapability—(no internal deps; llm→core removed Q3.6.1)
yanshi-toolsTool contract + builtins—(no internal deps)
yanshi-ragCapability + tool—(no internal deps)
yanshi-dbOps / persistence leaf—(no internal deps)
yanshi-tracingOpscoreevents::{EventListener, WorkflowEvent}
yanshi-mcpTooltracingcontext::{current_traceparent, scope} — traceparent ambient only
yanshi-memoryCapabilityragembeddings::EmbeddingProvider — SemanticMemory only
yanshi-nodesToolcore, llm, mcp, rag, toolscore=IR; llm=Yanshi/Asr/Tts/Image; rag=retrieval nodes
yanshi-agentsRuntime (loop)core, llm, mcp, memory, toolscore=IR-only; llm/memory/tools=concrete impls
yanshi-skillsCapabilityagents, mcp, memory, rag, toolsagents=runtime (builds runnable agent)
yanshi-harnessRuntime (shell)agents, llm, memory, tools, tracingllm=tokenizer only; tracing=redaction/storage/types
yanshi-serverSurfaceagents, cli, core, db, harness, llm, memory, skills, tools, tracingsurface assembly (+ cli edge — allow-listed)
yanshi-workerSurfaceagents, core, llm, memory, nodes, server, toolssurface (+ server edge — allow-listed)
yanshi-cliSurfaceagents, core, db, harness, llm, mcp, memory, nodes, rag, server, skills, tools, tracingtop assembly (imports the world — allowed)
yanshi-uiSurface (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.

#EdgeBreaks lawStatusResolution
1agents → core4/6 runtime-isolation[gate] allow-listedP-A1.3 graph split — edge becomes agents→graph (IR-only ✔)
2harness → agents4/6 runtime-isolation[gate] allow-listedP-A2.1 repoint to agent-spi; runtime injected by surfaces
3worker → serversurface-isolation[gate] allow-listedP-A2.3 extract worker-proto
4server → clisurface-isolation[gate] allow-listedP-A2.4 extract shared assembly crate
5agents → {llm, mcp, memory, tools}4 (runtime fused to impls)[latent]inject via agent-spi/store-spi/tool at surfaces
6harness → {llm, memory, tools, tracing}4 (runtime fused to impls)[latent]as above — allowlist under-counts harness debt by 4 edges
7nodes → {llm, rag}2 (tool crate → capabilities)[latent]R3 — decompose nodes
8nodes → core2 (tool crate → runtime)[latent]IR-only → nodes→graph after P-A1.3
9skills → agents3 (capability → runtime)[latent]P-A4.3 Capability::lower; surface wires the runtime
10memory → rag3 (capability → capability)[latent]route via store-spi embeddings contract (R6)
11mcp → tracing2 (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 beside scheduler.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 what harness/agents actually reach for (R6).
  • tools — Already the Tool contract + builtins fused. RFC §4 carves the contract into yanshi-tool and moves builtins to yanshi-tools-builtin; low urgency (no bad inbound edges), do it when convenient.
  • rag — Clean leaf today. Repositions to a KnowledgeBackend capability (P-A4.1); keep the eval harness as the quality gate.
  • memory — Capability with one capability→capability edge (→rag for EmbeddingProvider). Minor; fold behind store-spi (R6).
  • tracing — Ops crate; →core for the workflow event types. Becomes →agent-spi + →value. The redaction module is (correctly) the thing harness reuses — keep it reusable.
  • mcp — Tool crate; only bad edge is →tracing for 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. →core is IR-only (resolves cleanly via graph); the →{llm,mcp,memory,tools} edges are the impl-fusion to undo via contracts.
  • skills — Capability that depends on the agents runtime (inversion). The Capability::lower work (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 (llm tokenizer, memory, tools, tracing). The governance shell should sit on agent-spi + the reusable redaction/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. ui is 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 marks yanshi-value “defer (re-export)”. But graph depends on FlowValue, and FlowValue (in core/src/value.rs) is imported by the widest set of crates. Extract value first in P-A1 as the cheapest, highest-leverage cut and a hard prerequisite of the graph split — not a later nicety.
  • R2 — Record that agents→core is 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 nodes an explicit decomposition decision (new RFC §9a / P-A task). Options: (a) split nodes into nodes-core (tool-tier: template/file/ http/batch/conditional/while — graph + tool only) 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-tier nodes as 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 lets worker depend on tool-tier nodes without dragging llm/rag in.
  • R4 — Drop the stale llm→core claim from RFC §1 (seam #2 framing) and §4 (the llm dependent row). Already removed in Q3.6.1.
  • R5 — Ship the full target-state edge map, not just the 4 gate edges. The check-arch allowlist 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 the harness 4-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 in value or store-spi; trace-context ambient → agent-spi (or value); 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

  1. Adopt the RFC as the architecture of record (it already is). Fold R1–R6 into docs/RFC_CRATE_ARCHITECTURE.md and the P-A track in TODOs.md.
  2. Refresh RoadMap.md (stale 2026-05-14, pre-kernel) to name the four paradigms and the contract-kernel direction, demoting “two first-class paths.”
  3. Keep ordering: P-A runs after the Q security/correctness waves — an architecture refactor must never preempt production-blocking fixes.
  4. Sequence within P-A1: value (R1) → graph (R2) → agent-spi/store-spi (absorbing R6 contracts) → async-util → dynamic-workflow spike.
  5. Land the nodes decomposition decision (R3) as a short RFC addendum before P-A4 (worker node-coverage and dynamic-workflow node reuse both depend on it).