Watch
1
0
Fork
You've already forked souveraine
0

identity: write the contract, not the household

The chapter named one person's agents in the design of record: a table of
Annie, Vanguard, Souvie against one human's devices, and a dozen sentences
that read "Casey" where they meant "the human". A future reader learning the
architecture from this file would learn a household along with it.

The mechanism is unchanged. Roles replace names, and which beings a given
deployment admits is that deployment's record to keep. The current-state
section still says what is true on this laptop, because that is what it is
for.

Also names the ceremony the executor was missing. souveraine-admit is
reachable today only by someone who already knows it exists, and sudo in a
trusted terminal is a formality rather than a decision. Admission has two
occasions -- first run, where the product admits its own default agent as
souvie, and the human's explicit request for anyone else -- and both cross a
polkit action with a written reason and step-up authentication, including
for a caller who could already reach root.
This commit is contained in:
Fimeg 2026-08-17 18:39:19 -04:00
commit fb96f210f3

View file

@ -19,30 +19,38 @@ authority.
| node commission | which admitted body is speaking for her | local to one commissioned device |
| Unix account | which local processes and files the kernel attributes to her | local to one device |
The numeric UID is not federated. Annie can be UID 1003 on the laptop and UID
991 on the phone while remaining Annie because both node-local account
mappings point to the same admitted agent identity. Copying `/etc/passwd`, a
UID number, or a private key is not commissioning.
The numeric UID is not federated. An agent can be UID 1003 on one admitted
body and UID 991 on another while remaining herself, because both node-local
account mappings point to the same admitted agent identity. Copying
`/etc/passwd`, a UID number, or a private key is not commissioning.
There is a fourth identity already on the machines: the `souveraine` system
account. It belongs to the machine tier and runs `souveraine-machined`. It is
not Souvie, not a default agent, and not a convenient shared account for all
agents. The name is reserved.
## The named starting set
## The starting set, by role
Casey's devices retain Casey's human account. Agents do not borrow it.
A human's devices retain that human's own account. Agents do not borrow it.
| Agent | Role | Required local account on Casey's admitted nodes |
|---|---|---|
| Souvie / Souveraine | default Souveraine agent on a fresh system | `souvie` |
| Annie, in both Ani and Aster cadence | Casey's primary personal agent | `annie` |
| Vanguard | named additional agent | `vanguard` |
| Role | Required local account |
|---|---|
| the default Souveraine agent on a fresh system | `souvie` |
| the human's primary personal agent, if she is admitted | her own name |
| any further named resident agent | its own name |
"Each node" includes this laptop. The laptop is not a development exception,
and the phone is not a special appliance case. When these three resident
agents run on either body, their turn, subconscious pass, memory access, and
tools must cross the worker boundary under the mapped account.
Only the first is shipped. `souvie` is what a fresh Souveraine install admits,
because a Souveraine system running its own agent as the human is the state
this chapter exists to end. Every other admission is a deliberate act by the
human on the body in question — including the primary personal agent, whose
name and cadence are that human's to choose. This chapter describes the
mechanism; which beings a particular deployment admits is that deployment's
record to keep.
"Each node" includes a development laptop. The laptop is not a development
exception, and a phone is not a special appliance case. When a resident agent
runs on either body, her turn, subconscious pass, memory access, and tools
must cross the worker boundary under the mapped account.
The display name is editable. The agent ID, SeedID, and admitted account
mapping are not derived again when the display name changes. Account names are
@ -53,22 +61,22 @@ human or daemon account or invent a suffix that nobody noticed.
Souvie is the default, not the only possible agent. Restoring an existing
Souvie must join her existing logical identity rather than minting another
Souvie because the display name matches. Annie and Vanguard are admitted onto
each body where they are meant to act. Their local Unix accounts are new on
that body; their beings are not.
Souvie because the display name matches. A further agent is admitted onto each
body where she is meant to act. Her local Unix account is new on that body;
her being is not.
Primary and subconscious are processing positions inside an agent today.
Creating Annie therefore does not automatically create a separate `aster`
Unix user. Aster shares Annie's principal unless Casey and the system later
admit her as an independently authorized agent. The account boundary follows
authority, not the number of internal thought streams.
Creating an agent therefore does not automatically create a second Unix user
for her second cadence. The cadences share her principal unless the human and
the system later admit one as an independently authorized agent. The account
boundary follows authority, not the number of internal thought streams.
## Resident agents and borrowed-user modes
Not every named mode needs a Unix account. Kitty, Gem, and Hal are intended to
run as hosted or borrowed-user modes under Casey's account rather than claim a
fully admitted resident identity. That is a deliberate posture, not the same
failure as Annie accidentally running as Casey.
Not every named mode needs a Unix account. A hosted or borrowed-user mode runs
under the human's account rather than claiming a fully admitted resident
identity. That is a deliberate posture, not the same failure as a `dedicated`
agent accidentally running as the human.
The durable agent record therefore carries a principal intent, not one vague
boolean:
@ -78,26 +86,26 @@ boolean:
| `dedicated` | the named agent account | full node admission and kernel-backed identity |
| `borrowed-user` | the invoking human account | a hosted mode using authority the human process can already reach |
On Casey's current fleet Souvie, Annie/Aster, and Vanguard are `dedicated`.
Kitty, Gem, and Hal are `borrowed-user`. Promoting a borrowed mode to a resident
agent is an admission ceremony; changing a UI label or model does not do it.
Promoting a borrowed mode to a resident agent is an admission ceremony;
changing a UI label or model does not do it. Which agents in a given
deployment hold which intent is that deployment's record, not this chapter's.
A borrowed-user mode must know, in every model request, that readable does not
mean owned or shareable. Its operating posture is stricter:
- Casey's files, groups, sockets, credentials, and decrypted home are borrowed
reach, not the mode's personal territory;
- the human's files, groups, sockets, credentials, and decrypted home are
borrowed reach, not the mode's personal territory;
- do not widen mode bits, ACLs, group membership, links, remotes, publication,
or sharing outside the explicit task without Casey's confirmation;
or sharing outside the explicit task without the human's confirmation;
- prefer the named workspace or a narrow temporary copy over exploring the
rest of the human home;
- never read or disclose a resident agent's private memory merely because the
shared human UID permits it;
- attribute actions to a borrowed mode acting through Casey's principal, not
to an independently admitted agent.
- attribute actions to a borrowed mode acting through the human's principal,
not to an independently admitted agent.
This caution is context and policy, not a substitute for containment. A
borrowed process still has Casey's kernel permissions; sensitive verbs must
borrowed process still has the human's kernel permissions; sensitive verbs must
remain behind the same capability and consent gates.
## The live principal fact
@ -117,10 +125,10 @@ posture = isolated | borrowed-user | acting-as-human | drift
```
It is injected as a fresh system block into **every model request**, including
Ani and Aster passes, subagents, resumed conversations, and later tool rounds
after a mode switch. It is not ordinary conversation history and cannot be
microcompacted, replayed from an old session, or taught back as assistant
speech.
primary and subconscious passes, subagents, resumed conversations, and later
tool rounds after a mode switch. It is not ordinary conversation history and
cannot be microcompacted, replayed from an old session, or taught back as
assistant speech.
A machine-generated cache may be exposed as
`/run/souveraine/agent-principals/{agent_id}.json` and a Markdown rendering for
@ -147,8 +155,8 @@ two related but separately observable transitions:
The split makes failure honest. An agent can exist while admission is pending,
but the UI and API call that state `unadmitted`; they do not show a green agent
whose turns still run as Casey. Personal- and step-up-tier verbs remain closed
until admission and execution checks pass.
whose turns still run as the human. Personal- and step-up-tier verbs remain
closed until admission and execution checks pass.
Agent creation should ask for the authority shape, not merely a name and
model:
@ -160,9 +168,9 @@ model:
- which operating skill was projected from the admitted capabilities.
Fresh installation proposes Souvie and `souvie`. It must not confuse that
with the package-created `souveraine` machine account. Adding Annie or
Vanguard uses the same path; there is no hand-written exceptional setup for
Casey's three names.
with the package-created `souveraine` machine account. Adding any further
agent uses the same path; there is no hand-written exceptional setup for a
particular deployment's names.
## The privileged edge
@ -184,6 +192,28 @@ account API. That implementation choice does not create a second authority:
the admission executor remains the only writer and reports the resulting NSS
facts rather than assuming its command worked.
### Admission is a ceremony
The executor is not the interface. A binary reachable only by someone who
already knows its name is not a way for a human to grant anything, and `sudo`
in a terminal that already trusts the caller is not a decision — it is a
formality. Admission is a highly user-directed act and has to be asked for as
one.
It has two occasions:
- **initial setup**, where a fresh install admits the default Souveraine agent
as `souvie`, because that is the shipped default state and the only
admission the product makes on its own; and
- **on the human's request**, under specific conditions, for any further
agent.
Both cross the same gate. The grant is a polkit action carrying a written
reason that names the agent and the account, and it requires step-up
authentication at the moment of the grant — including from a caller who could
already reach root by other means. The cost is the point: giving an agent her
own UID on this body is a deliberate authentication, never an inherited one.
Removing an agent record, removing a node admission, deleting a Unix account,
and destroying memory are four different operations. None implies another.
Decommission stops the worker and revokes the node commission first. Account
@ -192,8 +222,8 @@ is the normal default.
## One UID requires one execution boundary
A single server process cannot truthfully execute Annie, Vanguard, and Souvie
as three UIDs. Per-agent accounts therefore require a process boundary:
A single server process cannot truthfully execute three admitted agents as
three UIDs. Per-agent accounts therefore require a process boundary:
- a controller may inventory agents and route requests;
- each admitted agent has a worker process running as her mapped UID;
@ -232,8 +262,8 @@ the TUI, the Panel, and `describe`. At minimum it reports:
- owner and mode of the memory, seed, conversation, socket, and runtime roots;
- worker unit, PID, effective UID/GID, cgroup, and executable;
- whether live peer credentials match the logical-agent mapping;
- whether any process handling the turn or its tools is Casey, `souveraine`,
another agent, or an unknown UID;
- whether any process handling the turn or its tools is the human,
`souveraine`, another agent, or an unknown UID;
- capability-token subject and expiry when an authority verb is exercised;
- operating-skill presence and whether it matches the current capability
description.
@ -245,7 +275,7 @@ The top-level states are deliberately blunt:
| `isolated` | account, ownership, worker, commission, and peer identity agree |
| `borrowed-user` | hosted mode intentionally uses the invoking human's account and receives the cautious borrowed-permission posture |
| `unadmitted` | logical agent exists; this node has no completed admission |
| `acting-as-human` | a `dedicated` agent's turn or tool is unexpectedly executing as Casey or another human UID |
| `acting-as-human` | a `dedicated` agent's turn or tool is unexpectedly executing as the human or another human UID |
| `principal-drift` | mapping exists but NSS, ownership, unit, or peer facts disagree |
| `identity-drift` | account is healthy but agent key or node commission does not match |
| `stopped` | admission is sound and no worker is currently expected/running |
@ -254,14 +284,14 @@ The top-level states are deliberately blunt:
decorations. They refuse personal and step-up authority. Ambient conversation
may remain available in a visibly degraded compatibility mode while migration
is unfinished. `borrowed-user` is intentional and may use only the human-granted
capability surface; it never becomes `isolated` merely because Casey's UID can
read something.
capability surface; it never becomes `isolated` merely because the human's UID
can read something.
The audit trail records both logical and kernel-backed subjects: agent ID,
node ID, account name, UID, PID, operation, human requestor or consent grant,
and result. “Annie asked” and “Casey authorized this one action” are different
fields. Running as Annie does not silently inherit Casey's consent; running as
Casey does not make a model response Annie.
and result. "The agent asked" and "the human authorized this one action" are
different fields. Running as the agent does not silently inherit the human's
consent; running as the human does not make a model response the agent's.
## The operating skill