# Identity **Status:** Approved foundation; lifecycle details are deferred **Date:** 2026-07-28 **Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/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 `System` or `archied`; - 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 `IdentityID` values; - 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. Secret-bearing channel bindings remain configuration concerns rather than identity data. In particular, `[chat.telegram].token` is a `secret.SecretRef` resolved by the application through the configured secret registry; the older `token_env` field remains a compatibility fallback. Neither form changes the identity that owns or performs a chat action. ## 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: ```text 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: ```text 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.Name` is the daemon routing key. - `config.IdentityConfig.BotUser` is the external forge and Git author name. - `daemon.IdentityRunner` bundles the configured name with a forge client, worktree manager, repository list, configuration subset, logger, and polling goroutine. - `store.Task.Identity` persists 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/issue` and 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](https://github.com/samcharles93/archie-core/issues/68)) and the curator ([#435](https://github.com/samcharles93/archie-core/issues/435)). Recovered 2026-08-09 from the pre-migration issue tracker. **Layer 1 — invariants.** Instruction precedence, core rules, and the `` and `` 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 `` block, XML-escaped through the same `xml` template helper used for tool and env metadata, and placed *before* `` in `archie.md.tpl`. Escaping means SOUL text can never forge a live ``, ``, `` or `` tag -- an attempt renders as inert escaped text (`<core_rules>...`), and `` explicitly tells the model the `` 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.