Persona/SOUL text was interpolated raw at the top of archie.md.tpl, so a hostile SOUL could inject its own <core_rules> or <instruction_precedence> tags ahead of the real ones. Render it through the existing xml-escaping helper into a labeled trust="data" <soul> block, and tell instruction_precedence explicitly that the block is reference data, not an authority. Closes archie-core-1786637490097-12-bf415ffb
14 KiB
Identity
Status: Approved foundation; lifecycle details are deferred
Date: 2026-07-28
Tracking issue: #73
Purpose
Identity answers which persistent actor owns or performed an action. It supplies stable cross-domain attribution and lifecycle semantics.
Identity kinds include:
- the Archie system identity, such as
Systemorarchied; - agent or bot identities;
- service-account identities;
- future user identities.
A user is another kind of identity rather than a separate foundation concept.
Ownership
internal/domain/identity owns:
- immutable canonical
IdentityIDvalues; - identity kind;
- lifecycle state;
- ownership and attribution semantics;
- identity-related commands and events.
Domains may record an identity reference on their own state and events when ownership or attribution is required. They MUST NOT receive a complete per-identity application configuration bundle.
Persona and communication style are separate from identity.
Every Agent has its own immutable acting IdentityID. Agent actions use that
identity for ownership and attribution in the same way an organisation records
which user accessed a resource, changed a permission, or performed another
auditable action.
Agent and Identity remain separate aggregates. Identity supplies the stable actor reference; Agent owns assistant behaviour, memory, specialisation, conversations, and capability context.
Agent identities MUST NOT be shared between Agents. Automated WorkflowExecutions MAY eventually act through a dedicated service-account identity when a specific unattended automation requires it. Such use is an explicit execution decision and audit principal, not the default for Agents or a substitute for recording the initiating user when one exists.
A Workflow is owned by an IdentityID and executes as its owner by default.
Future delegated execution MAY explicitly assign a different RunAsIdentityID,
including a user or service-account identity. Ownership, effective execution
identity, initiating identity, and delegation provenance remain distinct audit
facts.
Canonical identity
Every identity has an immutable IdentityID. It is the only value used for
cross-domain ownership, attribution, routing, persistence, commands, and events.
Identity kind is explicit:
- system;
- bot;
- service account;
- user.
Display names are mutable and MUST NOT be used as identifiers. Forge usernames, channel bot names, Git authors, provider account names, and other external identifiers are bindings associated with an identity rather than identity itself.
System is represented by a real identity and IdentityID. The empty string
MUST NOT retain special meaning as a legacy system identity.
Configuration refers to identities by IdentityID and supplies external
bindings and capability settings separately. Renaming an identity or changing an
external account MUST NOT change ownership or historical attribution.
Persistence
Identity records are durable domain state. The Identity domain's repository is the source of truth; infrastructure implements its persistence contract.
Configuration MAY bootstrap a missing identity through an explicit, audited
creation operation and MAY propose runtime capability bindings for an existing
IdentityID. Configuration is not the identity registry.
Omitting an identity from configuration stops assembling the omitted runtime capabilities. It MUST NOT delete the identity record, erase history, or make historical references unresolvable.
Disabling or retiring an identity requires an explicit Identity-domain command. Retired identities remain resolvable for historical attribution. A failed external binding affects capability availability without destroying or silently replacing the identity.
Lifecycle
Identity lifecycle is deliberately small:
active: may participate in runtime composition;suspended: deliberately prevented from initiating new work while ownership and history remain;retired: terminal, unable to initiate work, and permanently retained for attribution.
Allowed transitions are:
create -> active
active -> suspended
suspended -> active
active -> retired
suspended -> retired
retired has no outgoing transition.
Capability health is separate from identity lifecycle. Forge, model, channel, workspace, and other bindings report health independently. An active identity may be partially degraded without becoming suspended or retired. Runtime supervision isolates and restores affected bindings through the safe-change and recovery protocol.
System identity
Archie has exactly one built-in system identity. It is created during initial
store bootstrap, is strictly always active, and cannot be suspended or retired.
Its IdentityID and kind are immutable.
Startup, migration, supervision, remediation, and rollback actions performed by the application use the system identity. The system identity MUST NOT be delegated to individual identities. Every user, bot, service account, or other actor mutation records the identity that actually performed it.
System capabilities may independently become unhealthy or unavailable without changing the system identity.
Target placement and contracts
The Identity domain lives at internal/domain/identity.
It owns:
IdentityID, identity kind, display name, lifecycle, version, and audit timestamps;- create, rename, suspend, reactivate, and retire commands;
- corresponding lifecycle events;
- the repository contract required for durable identity records;
- lookup of current and historical identities.
External account bindings and capability settings remain with the domains that
use them and reference IdentityID.
Migration constraints
Migration from the current string model MUST:
- bootstrap the permanent system identity;
- assign stable IDs to configured identities without losing their names;
- replace empty-string legacy ownership with the system identity;
- migrate tasks and sessions to canonical identity references;
- include identity where task uniqueness and transport deduplication require independent ownership;
- route container RPC through the task owner's capability bindings;
- retain historical resolution after rename, suspension, or retirement;
- remove identity-string equality from authentication or access semantics.
This completes the foundation required to restructure the current Identity behaviour. Exact storage schemas and Go method signatures belong to implementation design, not this architecture review.
Lifecycle
Identity lifecycle is deliberately small:
active: may participate in runtime composition;suspended: deliberately prevented from initiating new work while ownership and history remain;retired: terminal, unable to initiate work, and permanently retained for attribution.
Allowed transitions are:
create -> active
active -> suspended
suspended -> active
active -> retired
suspended -> retired
retired has no outgoing transition.
Capability health is separate from identity lifecycle. Forge, model, channel, workspace, and other bindings report health independently. An active identity may be partially degraded without becoming suspended or retired. Runtime supervision isolates and restores affected bindings through the safe-change and recovery protocol.
Explicit non-responsibilities
Identity is not authentication and is not access control.
The current architecture does not require authentication or authorization. Those capabilities MAY be introduced later if deployment or product needs justify them. They MUST remain separate from the identity model.
An identity reference therefore proves attribution within Archie's trusted system model; it does not by itself prove credentials or permission.
Per-identity configuration
Values selected for an identity remain external configuration values. At composition time they are split into the runtime settings owned by the affected domains and correlated by identity reference.
The existing IdentityConfig aggregate MUST be dissolved. Forge accounts,
repositories, models, providers, workspace behaviour, polling, budgets,
notifications, and transport namespaces retain their respective owners.
Audit
Configuration changes and other state changes are actions attributed to an identity. System-initiated changes use the system identity. Their audit records MUST preserve the acting identity, the target, and the resulting change.
The command ownership and persistence mechanism for configuration changes is a separate configuration-management decision.
Current implementation
Identity is not currently implemented as a domain. It is a collection of string fields and process-local associations:
config.IdentityConfig.Nameis the daemon routing key.config.IdentityConfig.BotUseris the external forge and Git author name.daemon.IdentityRunnerbundles the configured name with a forge client, worktree manager, repository list, configuration subset, logger, and polling goroutine.store.Task.Identitypersists the configured name on tasks.- NATS task messages copy the same configured name.
- gateway routing accepts an identity name and uses it to select a repository profile.
- gateway sessions persist
BotUser, not the configured identity name.
There is no identity registry, identity record, identity lifecycle state, identity persistence, or identity command/event model. Removing an identity from configuration makes existing task ownership unresolvable.
An empty identity string selects the legacy single-identity path. This gives the empty string behavioural meaning rather than representing a real system identity.
Current enforcement and isolation
The current implementation uses identity equality as an authorization check for chat task approval and cancellation. This conflicts with the approved rule that identity is attribution rather than authentication or access control and must be reassigned to an appropriate task-ownership or future access policy.
Focused tests verify that:
- a task resolves the forge client and repository list associated with its configured identity name;
- cross-identity repository profiles do not leak;
- chat task creation propagates the selected identity;
- task persistence retains the identity string;
- chat task control rejects a different identity string.
Current hazards
- SQLite task uniqueness is
(owner, repo, issue_number)and excludes identity. Two identities discovering the same forge issue cannot own distinct task records. - NATS deduplication uses
owner/repo/issueand excludes identity, so discovery by a second identity can be discarded as a duplicate. - Container-mode forge and worktree RPC servers are wired to the root clients, not the task owner's clients. The source documents this as an unresolved identity leak.
- The shared task queue claims the oldest task without identity partitioning and relies on later string lookup to recover the correct runner.
- Sessions use forge bot usernames where tasks use configured identity names, so there is no canonical cross-domain identity reference.
- Identity lifecycle is process lifetime only; there is no disabled, degraded, retired, or unavailable state and no audit history.
The focused identity tests pass. Broader daemon and NATS suites could not open embedded listener ports in the current sandbox; their failures occurred before identity behaviour executed.
Three-layer identity model
Agreed 2026-07-30; the frame for SOUL (#68) and the curator (#435). Recovered 2026-08-09 from the pre-migration issue tracker.
Layer 1 — invariants. Instruction precedence, core rules, and the <tools>
and <env> blocks live in internal/gateway/templates/archie.md.tpl and are
unreachable at runtime by anyone.
Layer 2 — SOUL. User-authored identity: agent name, register, warmth. Editable without a rebuild.
Enforcing the Layer 1 / Layer 2 boundary. SOUL is rendered as the
Persona field of SystemPromptConfig (internal/gateway/prompt.go) into a
<soul purpose="identity_and_style" trust="data"> block, XML-escaped through
the same xml template helper used for tool and env metadata, and placed
before <instruction_precedence> in archie.md.tpl. Escaping means SOUL
text can never forge a live <core_rules>, <instruction_precedence>,
<tools> or <env> tag -- an attempt renders as inert escaped text
(<core_rules>...), and <instruction_precedence> explicitly tells the
model the <soul> block is reference data, not an authority. This is
guarded by TestBuildSystemPromptSoulCannotOverrideInvariants in
internal/gateway/prompt_test.go, which renders a hostile SOUL that attempts
to countermand core_rules and asserts the real invariant tags stay singular
and their text stays intact. Keep this test in sync if the template's escaping
or block structure changes -- do not relax it to make a future SOUL feature
(e.g. curator-proposed edits) fit.
Layer 3 — representation. Curator-derived knowledge about the user. It may only propose changes to SOUL and never apply them. If derived conclusions can silently rewrite tone, personality drifts and the user loses the control SOUL exists to give them. A proposal queue also makes the visibility requirement fall out for free, since pending conclusions are inherently reviewable.
Why SOUL comes first: tone currently lives in Go string constants
(DefaultPersonas in internal/gateway/persona.go), so fixing a rude reply on
2026-07-29 required editing Go and rebuilding. SOUL is small, fixes a real
defect, and defines the boundary the curator must respect.