# Appendix: Enums & Constants

All enum values used across the API. Definitive source of truth.

## Channel Types

| Value | Description |
|-------|-------------|
| `direct` | Single-user chat (default, backward compatible) |
| `dm` | Human-to-human direct message, AI silent unless @mentioned |
| `group` | Multi-user/multi-model collaborative channel |
| `channel` | Named persistent space, configurable ai_mode |
| `workflow` | Staged channel driven by workflow definitions |
| `service` | Autonomous task execution, no human participant |

## Channel AI Modes

| Value | Description |
|-------|-------------|
| `auto` | AI responds to every message (default) |
| `mention_only` | AI responds only when @mentioned (default for `dm`) |
| `off` | AI disabled entirely |

## Participant Types

| Value | Description |
|-------|-------------|
| `user` | Authenticated user. `participant_id` = `users.id` |
| `persona` | AI persona. `participant_id` = `personas.id` |
| `session` | Anonymous visitor. `participant_id` = session token |

## Participant Roles

| Value | Description |
|-------|-------------|
| `owner` | Full control: add/remove participants, delete channel |
| `member` | Send messages, trigger completions, view history |
| `observer` | Read-only: view messages, no send |
| `visitor` | Anonymous session participant (workflow intake) |

## Presence Statuses

`online`, `away`, `offline`

## Message Roles

`user`, `assistant`, `system`, `tool`

## Scopes

`personal`, `team`, `global`

## Visibility (Model Catalog)

`enabled`, `disabled`, `team`

## User Roles

`admin`, `user`

## Team Member Roles

`admin`, `member`

## Provider Types

`openai`, `anthropic`, `openrouter`, `venice` (extensible via registry)

## Model Types

`chat`, `embedding`, `image`

## Memory Scopes

`user`, `persona`, `persona_user`

## Memory Statuses

`active`, `pending_review`, `archived`

## Workspace Owner Types

`user`, `project`, `channel`, `team`

## Workspace Statuses

`active`, `archived`, `deleting`

## File Index Statuses

`pending`, `indexing`, `ready`, `error`, `skipped`

## KB Document Statuses

`pending`, `chunking`, `embedding`, `ready`, `error`

## Provider Health Statuses

`healthy`, `degraded`, `down`

## Routing Policy Types

| Value | Description |
|-------|-------------|
| `provider_prefer` | Ordered provider fallback list |
| `team_route` | Restrict team to specific providers |
| `cost_limit` | Heuristic cost cap per request |
| `model_alias` | Alias → provider+model rewrite |
| `capability_match` | Match cheapest model with required capabilities |

## Extension Tiers

`browser` (implemented), `starlark` (future), `sidecar` (future)

## Grant Types

| Value | Visibility |
|-------|-----------|
| `team_only` | Only the owning team |
| `global` | All authenticated users |
| `groups` | Members of specified groups |

## Resource Grant Resource Types

`persona`, `knowledge_base`, `project`

## Group Sources

| Value | Description |
|-------|-------------|
| `manual` | Admin-created |
| `oidc` | Synced from IdP groups claim |
| `system` | Platform-seeded (e.g., Everyone group) |

## Auth Sources

| Value | Description |
|-------|-------------|
| `builtin` | Username/password, bcrypt |
| `mtls` | Mutual TLS via reverse proxy |
| `oidc` | OpenID Connect (Keycloak etc.) |

## Workflow Statuses

| Value | Description |
|-------|-------------|
| `active` | Instance is running |
| `completed` | All stages finished |
| `stale` | No activity within threshold |
| `cancelled` | Manually cancelled |

## Workflow Entry Modes

`public_link`, `team_only`

## Workflow History Modes

| Value | Description |
|-------|-------------|
| `full` | Next stage sees complete chat history |
| `summary` | Utility-role summary of previous stages |
| `fresh` | Clean slate — no history carried forward |

## Task Types

`prompt`, `workflow`

## Task Run Statuses

| Value | Description |
|-------|-------------|
| `queued` | Waiting to execute |
| `running` | Currently executing |
| `completed` | Finished successfully |
| `failed` | Error during execution |
| `budget_exceeded` | Hit token/tool/wall-clock limit |
| `cancelled` | Manually killed |

## Task Scopes

`personal`, `team`, `global`

## Task Output Modes

`channel`, `note`, `webhook`

## Assignment Statuses

`unassigned`, `claimed`, `completed`

## Surface Sources

`core`, `extension`

## Notification Types

Convention: `domain.action`. Free-form strings — new types don't
require migration.

| Type | Description |
|------|-------------|
| `role.fallback` | Model role fell back to secondary provider |
| `kb.ready` | Knowledge base finished indexing |
| `kb.error` | Knowledge base indexing failed |
| `grant.changed` | User added to or removed from a group |
| `memory.extracted` | New memories extracted from conversation |
| `user.mentioned` | User was @mentioned in a channel |
| `workflow.assigned` | Workflow stage assigned to team/user |
| `workflow.claimed` | Workflow assignment claimed by a user |
| `task.completed` | Scheduled task finished successfully |
| `task.failed` | Scheduled task failed |
| `task.budget_exceeded` | Task hit token/tool/wall-clock budget |

**Planned (not yet implemented):**
`system.announcement` (v0.28.4 — admin broadcast to all users)

## Git Auth Types

`https_pat`, `https_basic`, `ssh_key`

## File Origins

`user_upload`, `tool_output`, `system`

## File Display Hints

`inline`, `download`, `thumbnail`

## Proxy Modes

`system`, `direct`, `custom`

## Permissions

12 permission constants, `domain.action` convention:

| Permission | Description |
|-----------|-------------|
| `model.use` | Use AI models for completions |
| `kb.read` | Search knowledge bases |
| `kb.create` | Create knowledge bases |
| `kb.write` | Upload documents to KBs |
| `channel.create` | Create new channels |
| `channel.invite` | Add participants to channels |
| `persona.create` | Create personal personas |
| `persona.manage` | Edit/delete own personas |
| `workflow.create` | Create/edit workflow definitions |
| `tasks.create` | Create/manage tasks |
| `tasks.admin` | Manage all tasks (admin) |
| `admin.access` | Access admin panel |

Permissions are granted via groups. The `Everyone` group
(ID `00000000-0000-0000-0000-000000000001`) provides default
permissions to all authenticated users. It is system-seeded
and editable by admins.

## Extension Permissions (v0.29.0+)

7 extension permission constants, `domain.action` convention.
Declared in package manifests, granted by admin review.

| Permission | Module | Since |
|-----------|--------|-------|
| `secrets.read` | `secrets` | v0.29.0 |
| `notifications.send` | `notifications` | v0.29.0 |
| `filters.pre_completion` | — | v0.29.0 |
| `api.http` | `http` | v0.29.0 |
| `provider.complete` | `provider` | v0.29.1 |
| `db.read` | `db` | future |
| `db.write` | `db` | future |

## Policies

| Key | Default | Description |
|-----|---------|-------------|
| `allow_registration` | `"true"` | Allow new user self-registration |
| `allow_user_byok` | `"false"` | Allow users to add personal API keys |
| `allow_user_personas` | `"false"` | Allow users to create personal Personas |
| `allow_team_providers` | `"true"` | Allow team admins to configure team providers |
| `allow_raw_model_access` | `"true"` | Allow raw model selection without persona |
| `kb_direct_access` | `"true"` | Show KB picker in channel (false = strict enterprise) |
| `default_user_active` | `"false"` | New users active immediately (vs admin approval) |