353 lines
15 KiB
Markdown
353 lines
15 KiB
Markdown
# 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. It does not change 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 authorisation. 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
|
|
|
|
## Withheld judgement verbs
|
|
|
|
`approve`, `reject`, `abandon` and `archive` are not exposed to an agent. An agent
|
|
that can approve can approve its own work, and the one control this surface exists
|
|
to keep is a human accepting it.
|
|
|
|
The constraint is attribution, not capability: a task action records the acting
|
|
identity and the authorising principal, so exposing the verbs requires that an
|
|
agent's action be recorded as an agent's and the authority it used recorded
|
|
separately. Until a surface carries both, the verbs stay withheld. This is the
|
|
reason the four verbs are absent from the dashboard's in-browser tools, and it is
|
|
why releasing them is a change to this boundary rather than a change to the tools.
|
|
|
|
The current implementation uses identity equality as an authorisation 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
|
|
|
|
- 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 `<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.
|