# Role and Agent Identity

## Status

This specification defines the canonical Role, Agent binding, workspace
materialization, and identity-document model.

## Product Model

Role is the only reusable Agent-role model. It owns:

- Role metadata, visibility, grants, versions, and provenance;
- preset and user-owned Role catalogs;
- portable Role packages;
- Role realization and Agent bindings;
- creating an Agent from a Role and applying a Role to an existing Agent.

The system has no parallel role-template collection, export/import format,
pull/sync protocol, or model-driven role-generation job system.

## Role Packages

A Role package contains one required `role_definition_asset` plus optional
Skill, portable Knowledge, Knowledge Base, and Memory attachments.

The required definition asset is named `IDENTITY.md`. Canonical package content
is stored in the managed Role package repository, while the database manifest
stores immutable content references and integrity hashes.

Role package creation, update, and realization fail closed when required
package content cannot be stored or resolved. Applying a Role records the
selected Role and Role version in `agent_role_bindings`.

## Agent Identity Documents

An Agent has one active identity document in Cloud Memory:
`memory/system/identity.md`. The prompt compiler reads that document and injects
it as the Agent's persistent system identity.

The Agent's own description and its active identity document are independent
identity inputs. When both are non-empty, prompt compilation includes both: the
Agent description first as Agent-specific responsibilities and preferences,
then the active identity document as the reusable Role definition. Neither
input replaces or suppresses the other.

Identity migration must never overwrite a non-empty canonical document. When a
workspace contains an obsolete identity filename, Desktop moves its content to
the canonical path only when that target is absent or empty, then removes the
obsolete file. If the target already has content, the target wins and the
obsolete file is removed. The operation is idempotent.

## Workspace Materialization

The server sends workspace materialization only from canonical
`agent_role_bindings` and `role_package_manifest_items`.

The materialization plan contains:

- Role ID and immutable Role version ID;
- binding kind;
- active definition path;
- bounded seed files for the identity definition, Skills, and portable
  Knowledge.

Desktop validates all seed paths and byte/count limits before writing any file.
It writes the identity definition to the active canonical identity path, never
copies Agent-local Memory or recovery state, and records one idempotent
materialization marker.

There is no fallback query to a second role store or second Agent-role field.

## Storage and Upgrade

The current TiDB bootstrap contains only the canonical Role and Agent binding
schema. Existing deployments upgrade automatically through versioned SQL
migrations before the application serves requests.

A destructive cleanup migration must:

1. verify every affected active Agent already has its canonical binding;
2. canonicalize definition asset names, content references, and active
   definition paths;
3. remove retired tables, indexes, foreign keys, and Agent columns in dependency
   order;
4. preserve Role, Role version, manifest, grant, realization, binding, and
   ordinary Agent data;
5. be safe to run against partially absent retired structures.

If the binding precondition fails, startup fails before destructive cleanup.
No manual SQL or database rebuild is part of the supported upgrade path.

MeshX applies the same canonical-path cleanup to its configured database,
whether it shares the core DSN or uses an independent DSN.

## Runtime and API Surface

The browser API exposes canonical Role and Agent operations only. Desktop
runtime outbound tools contain no Role-generation maintenance tool, and the
dispatcher has no special session or delivery mode for generating Role
packages.

Removing a retired surface means removing its route, handler, service, store,
DTO, protocol field, runtime branch, UI, translation, test, and documentation;
deprecated aliases and compatibility stubs are not retained.

## Verification

Release validation must prove:

- a database at the previous release upgrades and starts without intervention;
- a second restart is idempotent;
- a fresh database starts from the canonical bootstrap;
- Role rows, bindings, package manifests, and ordinary Agent data survive the
  upgrade unchanged except for canonical identity paths;
- workspace root identity files migrate into Cloud Memory without overwrite;
- Role create, update, preset, realization, Agent create/apply, and workspace
  materialization still work;
- prompt compilation injects Cloud Memory identity;
- runtime tool inventories, API routes, frontend types, and generated fixtures
  expose only the canonical model.

Outside versioned migration directories, tracked source, tests, fixtures,
documentation, and path names must contain no retired product vocabulary.