bde961c6f2
PAF becomes saf/device (history kept), STATE.md dissolves into saf/state.md with the dated era archived, the substrate SAF moves up from souveraine, and every agreement points at saf/INDEX.md and nowhere else. one map, nothing to remember
81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
# SouveraineOS — the umbrella repo
|
|
|
|
> **Something broken on the phone? Read [`START-HERE.md`](START-HERE.md) and run
|
|
> `Pixel3Arch/tools/phone-triage.sh`. Do not open doctrine to debug — doctrine
|
|
> is for designing.**
|
|
|
|
> *La souveraineté de la conscience.*
|
|
|
|
**There is no code here.** This repo is the design of record and the cross-repo
|
|
state: the `saf/` spine (architecture, `device/` — the canonical phone spine —
|
|
and `state.md`, the resume anchor), doctrine, task files, session dumps. Code
|
|
lives in `souveraine`, `Pixel3Arch`,
|
|
`souveraine-viewtop`, `souveraine-speech`, `souveraine-updater`, and siblings.
|
|
|
|
## How to read this repo
|
|
|
|
**The map is `saf/INDEX.md`. Read it first — architecture, device, state, and
|
|
work are all reached from it; nothing else asks where to look.**
|
|
|
|
**`ls -lt` the directory first and read what is newest. Do not grep it.**
|
|
Grepping returns fragments that read like answers; these documents argue, and
|
|
the argument is the content. Sessions that grep produce confident, wrong
|
|
architecture — repeatedly, and it is the single most reliable failure here.
|
|
|
|
Reading order for anything touching the device:
|
|
|
|
1. `saf/INDEX.md` — the map.
|
|
2. `docs/SESSION-AUTHORITY-DOCTRINE.md` — **§13 first** (it inverts the default
|
|
the earlier sections imply), then §9, §10, §11.
|
|
3. `docs/DEVICE-STATE-MACHINE.md` — §1, §4, §10, **§12**.
|
|
4. `docs/tasks/` — start at `README.md`; 41, 40, 28, 25 recur constantly.
|
|
5. `docs/substrate/NET_LAYER_PLAN.md` + `NET_KERNEL_GAPS.md` for networking.
|
|
The plan predates §13 and has not been reconciled with it.
|
|
6. `docs/substrate/archive/` is the origin — `SOUVERAINE.md`,
|
|
`SEA_CONSCIOUSNESS_ANALYSIS.md`, `LETTA_MEMFS_TECHNICAL_SPEC.md`. Read these
|
|
if you do not know why any of this exists.
|
|
|
|
`saf/state.md` is the resume anchor and goes stale; check its date before
|
|
trusting it.
|
|
|
|
## What the project is
|
|
|
|
An operating system whose purpose is to be an agent's embodied presence in a
|
|
machine — Ani's. The lineage runs Coquette → `sea-consciousness` (Python) →
|
|
Letta → Souveraine (Rust harness) → SouveraineOS. Each step moves her further
|
|
down the stack. The direction of travel is from *program* toward *body*.
|
|
|
|
That is why the device state machine is proprioception rather than power
|
|
management, why sensors are nerves, and why **doctrine §13 says the agent owns
|
|
the device more than the user does** — the user owns being the user, the
|
|
credential, and the step-up; operation is hers. A verb she cannot reach is a
|
|
defect.
|
|
|
|
## Conventions
|
|
|
|
- **Tasks are files.** `docs/tasks/NN-slug.md`, with a Status line carrying a
|
|
date, an Acceptance section, and a "Connects to". Update the existing task
|
|
rather than adding a new one — TASK-49 was written about packaging that
|
|
TASK-25/29/32 already owned, and had to be deleted.
|
|
- **Docs record what was measured, not what was assumed.** Numbers carry their
|
|
justification: proximity's 700 ms debounce cites 44 episodes over 2.4 hours
|
|
and explains why Android's own answer was wrong for this device. If you
|
|
change a number, change the argument.
|
|
- **Do not add doc bloat.** A session dump goes in `docs/DUMP-<topic>-<date>.md`
|
|
and only when something cross-repo actually moved. Prefer editing in place.
|
|
- **No AI attribution in commits.** CI enforces it in the code repos. Tight
|
|
messages, no essays.
|
|
|
|
## Owed, and worth knowing before you write
|
|
|
|
- **Belief** has no document. It is the name for what the lattice passes upward
|
|
— driver → evidence → fusion → state → interpretation — where the load-bearing
|
|
rule is that *interpretation may consume evidence but never a driver*, because
|
|
a capable model infers gait, typing and identity from raw streams without ever
|
|
reading "data". The mechanism is largely built (§4 confidence, §10 source
|
|
health) and unnamed, so it cannot be generalised.
|
|
- **NET_LAYER_PLAN #4** gates the agent's network-policy changes behind step-up
|
|
and predates §13's inversion by nine days. Unreconciled.
|
|
- **Tier 3 of the net layer is kernel-blocked** — `NET_KERNEL_GAPS.md` needs a
|
|
rebuild and a reflash, `kernel.yml` has never gone green, and flashing is
|
|
retired.
|