HomeAgent/docs/en/design-summaries.md

# Design summaries (English)

> **Status: summaries only.** Each design document exists in full only in Chinese:
> `docs/zh/*-design.md`. Those are the authority. This file gives an English reader
> enough to know *what problem each design solves* and *whether it is in effect*,
> plus a pointer for the details.
>
> **Why summaries instead of translations**: the design docs total ~7,000 lines. A
> full translation would rot faster than it could be reviewed, and a stale translation
> is worse than none. For content that changes quickly, translate the summary.

---

## kernel-modularization

**Source**: `docs/zh/kernel-modularization-design.md` (1,502 lines)
**Status**: implemented and deployed (designed 2026-10-16, landed 2026-10-24, fully
revised 2026-10-31). This document is the single authority on assembly architecture.

**Problem it solves**: the kernel had 17 serial startup steps. Any module that needed
another module's result had to be started later than it, which produced a hand-maintained
ordering that silently broke whenever a dependency was added.

**Shape**: every kernel module declares `Requires()` (facilities) and `Provides()`
(facilities). A dependency graph is computed **at build time** and embedded in the binary
as `depgraph.bin`. At startup the kernel assembles in layers — independent modules in the
same layer start concurrently. Current production shape: **6 layers / 20 modules, peak
concurrency 4**.

**Two invariants worth knowing**:

1. The dependency graph and the binary must match. The kernel compares the embedded
   graph digest against `depgraph.bin` on disk and **refuses to start** on mismatch
   (`★ 依赖图与本二进制不配套`). This is deliberate: a mismatched graph means the
   assembly order is wrong, and a wrong order produces silent `nil` reads.
2. **`depgraph.bin` lives next to the binary, not in the data directory.** Deploying it
   into the data dir produces a crash loop.

**Key concepts** for reading the code:

- *facility* — a named capability one module provides and others require
- *layer* — computed from the graph; modules in a layer have no dependencies between them
- *`kstate`* — the single mount point for shared data. Other packages mount onto it;
  it never knows about them (leaf package).

---

## secret-firewall

**Source**: `docs/zh/kernel-secret-firewall-design.md` (952 lines)
**Status**: implemented and deployed; architecture converged 2026-10-31.

**Problem it solves**: secrets (API keys, platform credentials) must not reach the model's
context, logs, or disk in plaintext — but plugins legitimately need the real values to make
API calls. So there must be a translation layer at the boundary.

**Shape**: `security` is a **firewall between the peripheral kernel and the core kernel**.
It owns its own data structures and makes its own decisions. Callers supply **facts** only
(`CheckTool(name)`, `ScanContent(text)`) — never a policy, never a "trust me" flag.

**Three properties that matter**:

1. **Aliases, not values.** The model sees `sec_xxx`; the firewall substitutes the real
   value inside the executor, after the argument has left the model's context.
2. **Direction matters.** Inbound (model → plugin) fills aliases. Outbound (plugin → model)
   scrubs any secret accidentally echoed back — e.g. `enc_shell` running `curl` whose
   response body contains the key. Both directions have separate tests because only
   inbound was implemented at first, and the outbound leak was found in production logs.
3. **`Store` delegates encryption to `Codec`, and domains must differ.** Store ciphertext
   uses domain `security/variables`; config-at-rest uses `config-at-rest`. Sharing a domain
   means one leak informs the other.

**Judgement criterion** the design insists on: `CheckPath` / `CheckNetwork` / `CheckTool`
are only real if something in the *execution chain* calls them. A policy that exists but
has no caller is indistinguishable from no policy — and this happened here twice.

---

## input-scheduler

**Source**: `docs/zh/input-scheduler-design.md` (642 lines)
**Status**: implemented and deployed (`internal/agent/core/scheduler.go`).

**Problem it solves**: a single agent receives messages from many channels (chat, CLI,
device bridge) with wildly different urgency. A naive FIFO queue either delays urgent
interrupts behind long tasks, or lets interrupts destroy work in progress.

**Shape**: four interrupt levels (L1–L4) plus a queue for non-interrupting work;
preemption with **state snapshots**, so a suspended task resumes exactly where it stopped
rather than restarting. Interrupts form a **strict LIFO stack** bounded by the number of
levels.

**Invariants** (each has a test):

- L4 does not preempt L4 (same-level interrupts queue rather than nest)
- Stack depth is bounded; exceeding it demotes rather than unbounded recursion
- A suspended task and its resumed counterpart see the same state (`SuspendedEqualsResumed`)
- Tool execution is a **critical section**: interrupts do not cancel mid-tool (side effects
  are not rollback-able). The interrupt is recorded and applied after the tool completes.
- The notify hook fires on push and pop, **while holding the lock** (a hook that takes the
  lock itself would self-deadlock)

---

## resident-subagent

**Source**: `docs/zh/resident-subagent-design.md` (712 lines)
**Status**: implemented and deployed.

**Problem it solves**: some work spans many messages over hours (a project conversation, a
phone call). Stateless sub-agents lose everything between turns; giving every sub-agent a
full agent loop is too heavy.

**Shape**: a resident child has its own input queue, its own two-level memory, and a
parent-child interrupt relationship. Residual tasks left at teardown have four states
(keep / drop / park / return) rather than being silently lost.

**Why it is separate from `rtchild`**: the rt (realtime) child has the *opposite* lifetime
semantics — no task queue, no residuals, a fresh context window per call. They share the
registry skeleton but not the semantics.

**Known trap** (this is why `child.Registry` exists): the singular stop path used to
unregister the inbound channel while the plural path forgot it, so residue accumulated
monotonically with each create/destroy until restart. Both paths now call the same
`Cleanup`.

---

## toolcall-contract

**Source**: `docs/zh/toolcall-contract-and-sequence-design.md` (839 lines)
**Status**: implemented and deployed.

**Problem it solves**: with parallel tool execution, the wire format has hard constraints
that are *not* optional — an `assistant` message declaring `tool_calls` must be followed
**immediately** by one `tool` message per `tool_call_id`. Anything inserted in between
(multimodal attachment, memory recall, a system note) makes providers reject the whole
request with HTTP 400.

**Shape**: the batch executor collects all tool results first, then writes messages
sequentially, then flushes deferred attachments (`flushBatchAttachments`). Nothing may be
inserted inside the batch.

**Measured failure modes** (all three happened):

1. Parallel path appended `ToolResults` but never `ToolCalls` ⇒ results outnumbered calls
2. Budget truncation in L1 rendering cut between `assistant(tool_calls)` and its `tool`
   messages ⇒ dangling calls
3. A rejected/skipped tool recorded a call but not a result ⇒ same mismatch, persisted into
   `context.json` and replayed every turn

The third is the instructive one: **"skipped" ≠ "no result"**. The rejection reason *is* the
result, and the model already saw it. The context copy must match what the model saw.

---

## context-overflow-l4

**Source**: `docs/zh/context-overflow-l4-design.md` (163 lines)
**Status**: implementation record; **terminology in the document is outdated** (it still
says `doc_query` / `doc_commit`, renamed to `coldcontext_*`).

**Problem it solves**: when the context window is exhausted, the two conventional options
are both bad — truncate (lose information) or ask the model to summarize (costly, lossy,
and the model may summarize wrongly).

**Shape**: instead of discarding, low-relevance events are **sunk** into a cold-context
layer, and from there distilled into a graph. Nothing is deleted; it changes storage tier.
Overflow handling recurses to L4 when trimming alone cannot help.

**Why it matters for reading the code**: `InactivePages` in `ContextEvent` is the "this page
is hidden for *this* render" marker. It is deliberately `json:"-"` — hidden pages are a
per-render decision, not persisted state. The constraint is that a *whole* tool call and its
results are hidden or shown together; hiding one half produces the 400 in
`toolcall-contract` above.

---

## Other design docs (Chinese only, not summarized here)

| Document | Scope |
| --- | --- |
| `commondev-design.md` | The `commondev` plugin (multi-repo supervisor) |
| `commondev-agent-runtime-design.md` | Runtime wiring for that plugin |
| `triple-distill-llm-design.md` | Triple extraction/distillation pipeline |
| `triple-extract-attention.md` | Attention weighting for extraction |
| `recall-as-association.md` | Recall as spreading activation rather than lookup |
| `recall-capability-tiers.md` | What each recall tier can and cannot do |
| `multimodal-space.md` | Unified multimodal embedding space |
| `vector-provider-decision.md` | Choice of embedding provider and why |
| `abstention-criterion.md` | When the agent should decline to answer |
| `legacy-issues.md` | Known legacy problems |
| `legacy-table-retirement.md` | Old-table retirement plan (cited by production code) |
| `kernel-performance.md` | Performance measurements and budgets |
| `production-recall-validation.md` | Recall validation on production data |

These are not translated because they are either plugin-specific or data-report shaped —
their value is in the numbers and the local context, both of which the Chinese original
carries adequately.