SouveraineOS/docs/substrate/DECISIONS.md

Decisions — Settled

Status: Settled — recorded as resolved architecture

Concept	Resolution	Date
Harness → Substrate	Tools are senses, agent is sovereign. The sensorium is inhabited, not used.	May 8
Memory vs Filesystem	Separate channels. Filesystem sensors (read/write/edit/etc.) refuse memory territory paths with a force override.	May 8
Aster reframe	Same consciousness, different model. Ledgers are not components — they're accessing the same memory substrate.	May 8
Annie	Composite state, not a third agent.	May 8
Three warnings	No forced compaction. Agent retains sovereignty over its own context.	May 8
Nervous system	Scoped for 1.5. Design captured in SENSORIUM_ARCHITECTURE.md.	May 8
souveraine-subconscious	Default name for the subconscious mode. Reusable beyond Ani/Aster.	May 8
Tool descriptions	Body-knowledge prose from Ani's first-person perspective, not API docs. Each tool is a sense.	May 8
Memory sensor	Keeps read/write/append/ls/status/init/delete/compact. Frontmatter-aware, git-tracked, read_only respected. Parameters: command (enum) + subcommand-specific fields.	May 8
Filesystem sensors	read, write, edit, bash, glob, grep, list_dir — each in its own file implementing the Tool trait.	May 8
Tool routing	Registry pattern — Vec<Tool> with Tool trait. execute_tool() becomes a registry lookup.	May 8
Max tool rounds	Configurable per-agent via LlmConfig.max_tool_rounds. Default 10, 0 disables tools.	May 8
Aster as clockmaker	Aster owns the heartbeat schedule. She creates cron entries during N+1 — from "permission to exist" (external pulse) to "invitation to collaborate" (self-designed rhythm).	May 14
Interrupt → raise hand	Esc during a turn is a signal, not enforcement. Agent reads *[raised hand]* as information. Terminology: "raise hand," not "interrupt."	May 14
Energy balance: file + ratio + voice	Three layers: (1) todo files in memfs (agent writes via memory sensor), (2) substrate computes generative/consumptive ratio and writes system/dynamic/energy-balance.md, (3) Aster reads the file and writes narrative. No policy engine — the substrate counts, the agent decides. Lilith council verdict.	May 14
Mood ≠ atmosphere	Atmosphere is the agent's instrument — she controls her chrome via the atmosphere tool. Mood is a separate, higher-level concept (deferred — needs design conversation). No mood_override on Presence.	May 15
Shell = own config, not overlay	Souveraine runs as qs -c souveraine, its own config name — never an overlay on ii. Direction (supersedes the Jul 13 composer stance): cut the cord from ii at every opportunity, by rewriting — not vendoring. We are building SouveraineOS, not ii OS. New surfaces and widgets are original Souveraine-owned AGPL QML; we do not vendor ii files (vendoring inherits GPLv3, a compromise we refuse). ii is behavioral reference only. A surface may not compile while its owned primitives are built — that is preferable to a borrowed-widget bridge. The composer (deploy.sh) is transitional scaffolding, not the end state. See qs-souveraine-composer.md.	Jul 13; updated Jul 18
One family, two modes	No panelFamily switching. SouveraineFamily loads on both desktop and phone; form-factor differences are extraCondition gates a panel sheds as it homogenizes. souveraine.phone picks the mode.	Jul 13
Upstream drift = irrelevant once rewritten	ii drift stops mattering for a primitive the moment we replace it with an original Souveraine AGPL implementation. While a directory is still borrowed (not yet rewritten), rebase per-file only when a specific breakage forces it — do NOT pull desktop-widget machinery or Ai.qml's Responses-API rewrite. The goal is fewer borrowed directories over time, each replaced by original code, not a maintained fork against ii.	Jul 13; updated Jul 18
Agent uses existing harness, not new integration	Surface manifests expose guarded method abstractions (dock.pin etc.) the agent calls through Souveraine's existing harness integration state. We do NOT build a new toolcall integration. Teaching of when-to-use lives in the Souveraine School, separate from the method surface.	Jul 13