docs/rfc/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md

# RFC: Microkernel — extension via Cordis event taxonomy, one concrete loop

Status: implemented

## Problem

The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic workflows, compaction, sandboxing, permissions, UI, persistence, MCP, skills must all be writable as plugins without modifying the core.

## Decision

Pure Cordis event taxonomy. The loop's extension seams are typed events with deliberate dispatch modes:

- **waterfall** (around-middleware) where plugins mutate or veto: `agent/prompt-submit`, `agent/request`, `agent/step-result`, `agent/turn-continuation`, `tools/pre-execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
- **emit** (sync fire-and-forget) for notifications: turn/step boundaries, stream chunks, lifecycle, errors.
- **parallel** (awaited) for the one durability checkpoint: `session/flush`.

The event vocabulary lives in interface packages (dsh-agent declares the agent/* events); `@deepseek-ai/dsh-agent-loop` is the only concrete loop plugin and is itself swappable — nothing outside it may depend on it.

## Alternatives considered

**A purpose-built middleware stack (koa-compose style)** and **an explicit phase state machine plugins insert into** — both would re-implement dispatch, disposal, and reload semantics that Cordis's native event system already provides; as Cordis effects, listeners get HMR and disposal for free.

## Consequences

- Every MVP feature maps to a listener (the [feature → mechanism map](../../../cookbook/extension-cookbook.md#the-feature--mechanism-map) is the proof obligation, kept current).
- HMR and disposal come free: listeners and registrations are Cordis effects.
- Waterfall semantics (call `next()` or short-circuit) are non-obvious and must be taught — documented in AGENTS.md and covered by composition tests.
- The loop must be defensive: plugin exceptions are contained at turn level, steering from any seam is never stranded (regression-tested).
docs: unify ADR/RFC trees into one lifecycle-organized RFC tree 2026-06-18 02:18:24 +08:00			`# RFC: Microkernel — extension via Cordis event taxonomy, one concrete loop`
Backfill architecture decision records 2026-06-11 15:24:14 +08:00
docs(rfc): define and enforce a uniform RFC format; adopt it across the corpus 2026-07-05 22:58:25 +08:00			`Status: implemented`
docs: unify ADR/RFC trees into one lifecycle-organized RFC tree 2026-06-18 02:18:24 +08:00
docs(rfc): define and enforce a uniform RFC format; adopt it across the corpus 2026-07-05 22:58:25 +08:00			`## Problem`
Backfill architecture decision records 2026-06-11 15:24:14 +08:00
docs(rfc): define and enforce a uniform RFC format; adopt it across the corpus 2026-07-05 22:58:25 +08:00			`The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic workflows, compaction, sandboxing, permissions, UI, persistence, MCP, skills must all be writable as plugins without modifying the core.`
Backfill architecture decision records 2026-06-11 15:24:14 +08:00
			`## Decision`

docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			`Pure Cordis event taxonomy. The loop's extension seams are typed events with deliberate dispatch modes:`
Backfill architecture decision records 2026-06-11 15:24:14 +08:00
fix(events): address Codex review — protect post-execute result, purge stale tools/execute refs 2026-06-30 20:25:30 +08:00			- waterfall (around-middleware) where plugins mutate or veto: `agent/prompt-submit`, `agent/request`, `agent/step-result`, `agent/turn-continuation`, `tools/pre-execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			`- emit (sync fire-and-forget) for notifications: turn/step boundaries, stream chunks, lifecycle, errors.`
Backfill architecture decision records 2026-06-11 15:24:14 +08:00			- parallel (awaited) for the one durability checkpoint: `session/flush`.

docs(rfc): record follow-up cleanup seams 2026-06-17 21:26:57 +08:00			The event vocabulary lives in interface packages (dsh-agent declares the agent/* events); `@deepseek-ai/dsh-agent-loop` is the only concrete loop plugin and is itself swappable — nothing outside it may depend on it.
Backfill architecture decision records 2026-06-11 15:24:14 +08:00
docs(rfc): define and enforce a uniform RFC format; adopt it across the corpus 2026-07-05 22:58:25 +08:00			`## Alternatives considered`

			`A purpose-built middleware stack (koa-compose style) and an explicit phase state machine plugins insert into — both would re-implement dispatch, disposal, and reload semantics that Cordis's native event system already provides; as Cordis effects, listeners get HMR and disposal for free.`

Backfill architecture decision records 2026-06-11 15:24:14 +08:00			`## Consequences`

docs(architecture): rewrite the system map to the 1,800-word budget 2026-07-04 14:43:48 +08:00			`- Every MVP feature maps to a listener (the [feature → mechanism map](../../../cookbook/extension-cookbook.md#the-feature--mechanism-map) is the proof obligation, kept current).`
Backfill architecture decision records 2026-06-11 15:24:14 +08:00			`- HMR and disposal come free: listeners and registrations are Cordis effects.`
docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			- Waterfall semantics (call `next()` or short-circuit) are non-obvious and must be taught — documented in AGENTS.md and covered by composition tests.
			`- The loop must be defensive: plugin exceptions are contained at turn level, steering from any seam is never stranded (regression-tested).`