@unicity-astrid/sdk 0.1.0

package/src/contracts.ts

@@ -0,0 +1,1189 @@
+// Auto-generated by @unicity-astrid/build from a WIT file. Do not edit by hand.
+// Mirror of `astrid_sdk_macros::wit_events!` output.
+
+/** Types generated from the `types` WIT interface. */
+export namespace types {
+  /** A conversation message. */
+  export interface Message {
+    role: MessageRole;
+    content: MessageContent;
+  }
+
+  export type MessageRole = "system" | "user" | "assistant" | "tool";
+
+  /** Message content — text, tool calls, tool results, or mixed. */
+  export type MessageContent =
+    | { tag: "text"; value: string }
+    | { tag: "tool_calls"; value: ToolCall[] }
+    | { tag: "tool_result"; value: ToolCallResult }
+    | { tag: "multi_part"; value: ContentPart[] };
+
+  export type ContentPart =
+    | { tag: "text"; value: string }
+    | { tag: "image"; value: ImageData };
+
+  export interface ImageData {
+    data: string;
+    media_type: string;
+  }
+
+  /** A tool call requested by the model. */
+  export interface ToolCall {
+    /** Tool call identifier. */
+    id: string;
+    /** Name of the tool to invoke. */
+    name: string;
+    /** JSON-encoded arguments (serde_json::Value in Rust). */
+    arguments: string;
+  }
+
+  /** Result of executing a tool call. */
+  export interface ToolCallResult {
+    call_id: string;
+    content: string;
+    is_error: boolean;
+  }
+
+  /** A tool definition provided to the model. */
+  export interface ToolDefinition {
+    name: string;
+    description?: string;
+    input_schema: string;
+  }
+
+  /** Token usage statistics. */
+  export interface Usage {
+    input_tokens: bigint;
+    output_tokens: bigint;
+  }
+
+}
+
+/** Types generated from the `agent` WIT interface. */
+export namespace agent {
+  /** A response generated by the agent for the user. */
+  export interface Response {
+    /** The text output (may be a streaming delta or a complete reply). */
+    text: string;
+    /** True if this is the final response in the turn. */
+    is_final: boolean;
+    /** Session ID for multi-session attribution. */
+    session_id: string;
+  }
+
+  /**
+   * Notification that the active session has changed (e.g. cleared,
+   * branched, restored). Uplinks use this to refresh their view.
+   */
+  export interface SessionChanged {
+    /** The session ID that is now active. */
+    session_id: string;
+    /** Optional ID of the session that was previously active. */
+    previous_session_id?: string;
+    /** Reason for the change (e.g. "clear", "restore", "branch"). */
+    reason: string;
+  }
+
+}
+
+/** Types generated from the `approval` WIT interface. */
+export namespace approval {
+  /** An interceptor or capsule request for human authorization. */
+  export interface Required {
+    /** Correlation ID matching the response. */
+    request_id: string;
+    /** The action being requested (e.g. `"git push"`). */
+    action: string;
+    /** The resource target (e.g. full command string). */
+    target_resource: string;
+    /** Justification shown to the user. */
+    reason: string;
+  }
+
+  /** Response to an approval request. */
+  export interface Response {
+    /** Must match the `request-id` from the originating request. */
+    request_id: string;
+    /**
+     * The user's decision (e.g. `"approve"`, `"deny"`,
+     * `"approve_session"`, `"approve_always"`, `"allowance"`).
+     */
+    decision: string;
+    /** Optional reason for the decision. */
+    reason?: string;
+  }
+
+}
+
+/** Types generated from the `client` WIT interface. */
+export namespace client {
+  /** A client has connected to an uplink. */
+  export interface Connect {
+    /** Optional client identifier (e.g. process name + PID). */
+    client_id?: string;
+  }
+
+  /** A client is disconnecting gracefully. */
+  export interface Disconnect {
+    /** Optional reason for disconnection (e.g. "quit", "timeout"). */
+    reason?: string;
+  }
+
+}
+
+/** Types generated from the `context` WIT interface. */
+export namespace context {
+  /** Request to compact messages within a token budget. */
+  export interface CompactRequest {
+    session_id: string;
+    messages: types.Message[];
+    max_tokens: bigint;
+    target_tokens: bigint;
+  }
+
+  /** Result of compaction. */
+  export interface CompactResponse {
+    messages: types.Message[];
+    compacted: boolean;
+    messages_removed: number;
+    strategy: string;
+  }
+
+  /** Request to estimate token count for messages. */
+  export interface EstimateRequest {
+    messages: types.Message[];
+  }
+
+  /** Token count estimate. */
+  export interface EstimateResponse {
+    estimated_tokens: bigint;
+  }
+
+  /** Hook payload sent before compaction (plugins can influence). */
+  export interface BeforeCompactionHook {
+    session_id: string;
+    messages: types.Message[];
+    message_count: number;
+    estimated_tokens: bigint;
+    max_tokens: bigint;
+    response_topic: string;
+  }
+
+  /** Plugin response to before-compaction hook. */
+  export interface BeforeCompactionHookResponse {
+    skip?: boolean;
+    pinned_message_ids: string[];
+    custom_strategy?: string;
+  }
+
+  /** Notification after compaction completes. */
+  export interface AfterCompactionEvent {
+    session_id: string;
+    messages_before: number;
+    messages_after: number;
+    tokens_before: bigint;
+    tokens_after: bigint;
+    strategy_used: string;
+  }
+
+}
+
+/** Types generated from the `elicit` WIT interface. */
+export namespace elicit {
+  /** A lifecycle hook is requesting user input. */
+  export interface Request {
+    /** Correlation ID matching the response. */
+    request_id: string;
+    /** The capsule requesting input. */
+    capsule_id: string;
+    /** Field descriptor reusing the onboarding schema. */
+    field: onboarding.Field;
+  }
+
+  /** Response to an elicit request. */
+  export interface Response {
+    /** Must match the `request-id` from the originating request. */
+    request_id: string;
+    /** The user's input. Absent if the user cancelled. */
+    value?: string;
+    /** For `array`-type fields, the collected items. */
+    values?: string[];
+  }
+
+}
+
+/** Types generated from the `hook` WIT interface. */
+export namespace hook {
+  /** Lifecycle events emitted by the kernel. */
+  export type LifecycleEvent = "session_created" | "session_ended" | "tool_call_started" | "tool_call_completed" | "tool_result_persisting" | "message_received" | "message_sending" | "message_sent" | "sub_agent_spawned" | "sub_agent_completed" | "sub_agent_failed" | "sub_agent_cancelled" | "context_compaction_started" | "context_compaction_completed" | "kernel_started" | "kernel_shutdown";
+
+  /** Merged result from hook fan-out. */
+  export interface HookResult {
+    /** Whether the operation should be skipped. */
+    skip?: boolean;
+    /** Merged data from interceptor responses (opaque JSON). */
+    data?: string;
+  }
+
+}
+
+/** Types generated from the `llm` WIT interface. */
+export namespace llm {
+  /**
+   * Request asking an LLM-provider capsule to describe itself.
+   * Topic: `llm.v1.request.describe`. The registry capsule fans this
+   * out to discover available providers and their per-provider
+   * request / stream topics.
+   */
+  export interface DescribeRequest {
+    /**
+     * Correlation ID for the response. The provider replies on
+     * `llm.v1.response.describe.<correlation-id>`.
+     */
+    correlation_id: string;
+  }
+
+  /**
+   * Provider self-description response.
+   * Topic: `llm.v1.response.describe.<correlation-id>`.
+   */
+  export interface DescribeResponse {
+    /** Must match the `correlation-id` from the originating request. */
+    correlation_id: string;
+    /**
+     * Provider entries the capsule offers (one capsule may expose
+     * multiple models — e.g. an OpenAI-compatible front-end serving
+     * several model IDs).
+     */
+    providers: registry.ProviderEntry[];
+  }
+
+  /** Request to generate a response. */
+  export interface GenerateRequest {
+    request_id: string;
+    model: string;
+    messages: types.Message[];
+    tools: types.ToolDefinition[];
+    /** System prompt. */
+    system: string;
+  }
+
+  /** A streaming event from the provider. */
+  export type StreamEvent =
+    | { tag: "text_delta"; value: string }
+    | { tag: "tool_call_start"; value: ToolCallStartEvent }
+    | { tag: "tool_call_delta"; value: ToolCallDeltaEvent }
+    | { tag: "tool_call_end"; value: ToolCallEndEvent }
+    | { tag: "reasoning_delta"; value: string }
+    | { tag: "usage"; value: types.Usage }
+    | { tag: "done" }
+    | { tag: "error"; value: string };
+
+  export interface ToolCallStartEvent {
+    id: string;
+    name: string;
+  }
+
+  export interface ToolCallDeltaEvent {
+    id: string;
+    args_delta: string;
+  }
+
+  export interface ToolCallEndEvent {
+    id: string;
+  }
+
+  /** Final (non-streaming) response. */
+  export interface GenerateResponse {
+    message: types.Message;
+    has_tool_calls: boolean;
+    stop_reason: StopReason;
+    usage: types.Usage;
+  }
+
+  export type StopReason = "end_turn" | "max_tokens" | "tool_use" | "stop_sequence";
+
+}
+
+/** Types generated from the `onboarding` WIT interface. */
+export namespace onboarding {
+  /** A capsule needs environment variables to be provided by the user. */
+  export interface Required {
+    /** The ID of the capsule requiring onboarding. */
+    capsule_id: string;
+    /** Rich field descriptors for each missing env var. */
+    fields: Field[];
+  }
+
+  /** A field descriptor for capsule onboarding. */
+  export interface Field {
+    /** The environment variable key. */
+    key: string;
+    /** The prompt shown to the user. */
+    prompt: string;
+    /** Optional description for additional context. */
+    description?: string;
+    /** The input type for this field. */
+    field_type: FieldType;
+    /** Optional default value. */
+    default?: string;
+    /** Placeholder hint text shown when the input is empty (e.g. `"sk-..."`). */
+    placeholder?: string;
+  }
+
+  /** The type of input expected for an onboarding field. */
+  export type FieldType =
+    | { tag: "text" }
+    | { tag: "secret" }
+    | { tag: "choice"; value: string[] }
+    | { tag: "array" };
+
+}
+
+/** Types generated from the `prompt` WIT interface. */
+export namespace prompt {
+  /** Request to assemble a prompt for LLM generation. */
+  export interface AssembleRequest {
+    messages: types.Message[];
+    system_prompt: string;
+    request_id: string;
+    model: string;
+    provider: string;
+    session_id?: string;
+  }
+
+  /** Assembled prompt ready for LLM. */
+  export interface AssembleResponse {
+    system_prompt: string;
+    user_context_prefix: string;
+    request_id: string;
+    session_id?: string;
+    /** Collected tool schemas from tool-providing capsules. */
+    tools: types.ToolDefinition[];
+    /** Session conversation history messages. */
+    messages: types.Message[];
+  }
+
+  /** Hook payload sent before prompt build (plugins inject context). */
+  export interface BeforeBuildHook {
+    messages: types.Message[];
+    system_prompt: string;
+    request_id: string;
+    model: string;
+    provider: string;
+    response_topic: string;
+  }
+
+  /** Plugin response to before-build hook. */
+  export interface BeforeBuildHookResponse {
+    prepend_system_context?: string;
+    append_system_context?: string;
+    system_prompt?: string;
+    prepend_context?: string;
+  }
+
+  /** Notification after prompt is built. */
+  export interface AfterBuildEvent {
+    system_prompt: string;
+    user_context_prefix: string;
+    request_id: string;
+  }
+
+}
+
+/** Types generated from the `registry` WIT interface. */
+export namespace registry {
+  /** An available LLM provider entry. */
+  export interface ProviderEntry {
+    /** Model ID (e.g. "gpt-5.4", "claude-sonnet-4-20250514"). */
+    id: string;
+    /** Human-readable description. */
+    description: string;
+    /** IPC topic to publish LLM requests to. */
+    request_topic: string;
+    /** IPC topic the provider streams responses on. */
+    stream_topic: string;
+    /** Model capabilities (e.g. "text", "vision", "tools"). */
+    capabilities: string[];
+    /** Provider's context window size in tokens. */
+    context_window?: bigint;
+    /** Provider's max output tokens per request. */
+    max_output_tokens?: bigint;
+  }
+
+  /** A single option in a selection picker. */
+  export interface SelectionOption {
+    /** Machine-readable identifier sent back on the callback. */
+    id: string;
+    /** Human-readable label shown in the picker. */
+    label: string;
+    /** Optional description shown alongside the label. */
+    description?: string;
+  }
+
+  /**
+   * Capsule asking the user to choose from a set of options. Used by
+   * the registry to drive the LLM-provider picker UI in the TUI.
+   * Topic: `registry.v1.selection.required`.
+   */
+  export interface SelectionRequired {
+    /** Correlation ID for the callback. */
+    request_id: string;
+    /** Title or prompt shown above the list. */
+    title: string;
+    /** The selectable options. */
+    options: SelectionOption[];
+    /** IPC topic to publish the user's choice back on. */
+    callback_topic: string;
+  }
+
+  /**
+   * User's selection sent back to the requesting capsule.
+   * Topic: `registry.v1.selection.callback` (or the `callback-topic`
+   * declared in the matching `selection-required`).
+   */
+  export interface SelectionCallback {
+    /**
+     * Must match the `request-id` from the originating
+     * `selection-required`.
+     */
+    request_id: string;
+    /** `id` of the chosen `selection-option`. */
+    selected_id: string;
+  }
+
+}
+
+/** Types generated from the `session` WIT interface. */
+export namespace session {
+  /** Request to fetch conversation history. */
+  export interface GetMessagesRequest {
+    session_id: string;
+    correlation_id: string;
+    append_before_read?: types.Message[];
+  }
+
+  /** Response containing conversation history. */
+  export interface GetMessagesResponse {
+    correlation_id: string;
+    messages: types.Message[];
+  }
+
+  /** Request to clear a session and start fresh. */
+  export interface ClearRequest {
+    session_id: string;
+    correlation_id: string;
+  }
+
+  /** Response confirming session cleared. */
+  export interface ClearResponse {
+    correlation_id: string;
+    new_session_id: string;
+    old_session_id: string;
+  }
+
+  /** Fire-and-forget append to conversation history. */
+  export interface AppendRequest {
+    session_id: string;
+    messages: types.Message[];
+  }
+
+  /**
+   * Broadcast notification that a session was cleared. Distinct from
+   * `clear-request`/`clear-response` (the request/response pair the
+   * session capsule handles): this is a fan-out event the agent loop
+   * publishes after a successful clear so unrelated capsules can drop
+   * any per-session ephemeral state. Topic: `session.v1.clear`.
+   */
+  export interface SessionCleared {
+    /** Session ID that was cleared. */
+    session_id: string;
+  }
+
+}
+
+/** Types generated from the `spark` WIT interface. */
+export namespace spark {
+  /** Request to build the agent's system prompt. */
+  export interface BuildRequest {
+    workspace_root: string;
+    session_id?: string;
+  }
+
+  /** Response with the assembled system prompt. */
+  export interface BuildResponse {
+    prompt: string;
+    session_id?: string;
+  }
+
+}
+
+/** Types generated from the `system` WIT interface. */
+export namespace system {
+  /**
+   * Published once after every capsule has reported ready, signalling
+   * that the agent stack is fully online. Topic: `astrid.v1.capsules_loaded`.
+   */
+  export interface CapsulesLoaded {
+    /** IDs of every capsule that successfully loaded. */
+    capsule_ids: string[];
+  }
+
+  /**
+   * Periodic kernel watchdog tick, used by long-lived capsules to age
+   * out stale state (timeouts, abandoned correlations, etc.).
+   * Topic: `astrid.v1.watchdog.tick`.
+   */
+  export interface WatchdogTick {
+    /** Wall-clock time of the tick (UNIX epoch milliseconds). */
+    timestamp_ms: bigint;
+  }
+
+  /**
+   * Warning emitted when a subscriber falls behind and the bus had to
+   * drop messages. Subscribers can use this as a signal to drain or
+   * resubscribe. Topic: `astrid.v1.event_bus.lagged`.
+   */
+  export interface EventBusLagged {
+    /** Topic that lagged. */
+    topic: string;
+    /** Number of messages dropped. */
+    dropped: bigint;
+  }
+
+  /**
+   * Cooperative restart signal — the kernel asks long-lived capsules
+   * to flush ephemeral state and re-arm. Topic: `system.v1.lifecycle.restart`.
+   */
+  export interface LifecycleRestart {
+    /** Reason for the restart (e.g. `"config-reload"`, `"upgrade"`). */
+    reason: string;
+  }
+
+  /**
+   * A slash-command typed by a human in an uplink. The CLI capsule
+   * publishes this when the user enters `/<command> [args]`. Routed
+   * to the capsule that registered the command name via its manifest.
+   * Topic: `cli.v1.command.execute`.
+   */
+  export interface CommandExecute {
+    /** The command name (without the leading slash). */
+    name: string;
+    /** JSON-encoded arguments (parsed by the receiving capsule). */
+    arguments: string;
+    /** Session ID the command was issued in. */
+    session_id: string;
+  }
+
+}
+
+/** Types generated from the `tool` WIT interface. */
+export namespace tool {
+  /** Request to cancel in-flight tool executions. */
+  export interface CancelRequest {
+    call_ids: string[];
+  }
+
+  /**
+   * Request asking a tool-providing capsule to enumerate its tools.
+   * Topic: `tool.v1.request.describe`. Empty payload — every responder
+   * returns its full tool list. Routed by the SDK macro from
+   * `#[astrid::tool(...)]` attributes.
+   */
+  export interface DescribeRequest {
+    /**
+     * Correlation ID for the response. The capsule replies on
+     * `tool.v1.response.describe.<correlation-id>`.
+     */
+    correlation_id: string;
+  }
+
+  /**
+   * Response listing the tools a capsule provides.
+   * Topic: `tool.v1.response.describe.<correlation-id>`.
+   */
+  export interface DescribeResponse {
+    /** Must match the `correlation-id` from the originating request. */
+    correlation_id: string;
+    /** The capsule's exposed tools. */
+    tools: types.ToolDefinition[];
+  }
+
+}
+
+/** Types generated from the `user` WIT interface. */
+export namespace user {
+  /** A prompt typed by a human via an uplink. */
+  export interface Prompt {
+    /** The raw text input. */
+    text: string;
+    /** Session ID for conversation continuity. Defaults to `"default"`. */
+    session_id: string;
+    /**
+     * Optional extra context (JSON-encoded) — e.g. attachments,
+     * metadata, or per-turn flags the uplink wants to forward.
+     */
+    context?: string;
+  }
+
+}
+
+/** Types generated from the `users` WIT interface. */
+export namespace users {
+  /**
+   * Multi-tenant request envelope.
+   * 
+   * Carries provenance ("which uplink, on behalf of which end-user")
+   * and a correlation token so the originating uplink can match the
+   * response back to the inflight request among many concurrent
+   * end-users on a single principal.
+   * 
+   * Pending the broader admin-API correlation convention (kernel
+   * issue #748), `source` lives on this interface; once that
+   * convention formalizes a shared envelope, this record migrates
+   * to the shared location and the records below import it instead.
+   */
+  export interface Source {
+    /**
+     * Originating uplink capsule — e.g. `"cli"`, `"sphere"`,
+     * `"discord"`, `"telegram"`. Identifies the capsule making
+     * the request (for audit and routing); distinct from
+     * `frontend-link.platform`, which identifies the external
+     * service being linked.
+     */
+    uplink: string;
+    /**
+     * AstridUserId of the requester when known. `None` for
+     * system flows or pre-login pairing requests.
+     */
+    user_id?: string;
+    /**
+     * Correlation token. The requester subscribes to the response
+     * topic and filters incoming responses by this string.
+     */
+    correlation_id: string;
+  }
+
+  /**
+   * Canonical Astrid user identity.
+   * 
+   * One record per human within the principal's user directory.
+   * `id` is the stable UUID — every `frontend-link` points at this.
+   */
+  export interface AstridUser {
+    /**
+     * UUID v4 string (lowercase, hyphenated). Stable for the
+     * lifetime of the user; never reused.
+     */
+    id: string;
+    /**
+     * Optional ed25519 public key (32 bytes raw). Set via
+     * `set-public-key`; used by future verification flows.
+     */
+    public_key?: number[];
+    /**
+     * Operator/canonical Astrid-side display name. Mutable via
+     * `set-display-name`. Distinct from any platform-side name.
+     */
+    display_name?: string;
+    /** Creation timestamp, RFC 3339 string. */
+    created_at: string;
+  }
+
+  /**
+   * A platform-to-Astrid-user identity link.
+   * 
+   * Composite key: `(platform, platform-instance?, platform-user-id)`.
+   * Exactly one link may exist per triple; relinking overwrites.
+   */
+  export interface FrontendLink {
+    /**
+     * Normalized platform name (lowercased, trimmed) —
+     * e.g. `"discord"`, `"telegram"`, `"nostr"`, `"slack"`,
+     * `"matrix"`, `"email"`, `"x"`, `"github"`.
+     */
+    platform: string;
+    /**
+     * Optional platform instance for federated / multi-tenant
+     * platforms: Slack workspace, IRC network, XMPP server,
+     * Mattermost instance. `None` for globally-scoped platforms
+     * (Discord, Telegram, X) and for federated platforms whose
+     * identifier already embeds the homeserver in the user-id
+     * (Matrix `@alice:server.org`, Mastodon `@a@server.social`).
+     */
+    platform_instance?: string;
+    /**
+     * Platform-specific stable opaque user identifier
+     * (Discord snowflake, Telegram int64, Slack `U...`, Nostr
+     * npub, email address, E.164 phone). Never the user's
+     * mutable handle.
+     */
+    platform_user_id: string;
+    /** The Astrid user UUID this platform identity maps to. */
+    astrid_user_id: string;
+    /**
+     * When this link was created (RFC 3339). Refreshed on
+     * upsert relink.
+     */
+    linked_at: string;
+    /**
+     * How this link was established — `"admin"`, `"system"`,
+     * `"chat_command"`, `"passkey"`, `"self_declared"`, etc.
+     * Recorded for audit. Free-form string.
+     */
+    method: string;
+    /**
+     * Platform's *global* display name at link time —
+     * e.g. Discord global username `"alice"`, Telegram
+     * `@alice`, X handle. Mutable: re-link to refresh.
+     * Distinct from any per-context override
+     * (see `context-identity`) and from `astrid-user.display-name`
+     * (the operator-set canonical Astrid name).
+     */
+    display_name?: string;
+  }
+
+  /**
+   * Per-context display-name overlay on a `frontend-link`.
+   * 
+   * One row per `(platform, platform-instance?, platform-user-id, context-id)`
+   * tuple. The capsule does NOT parse `context-id`; uplinks define
+   * per-platform schemes. Common conventions:
+   * 
+   *   - Discord per-guild nickname:        `context-id = "guild:{guild-id}"`
+   *   - Matrix per-room display name:      `context-id = "room:{room-id}"`
+   *   - Slack per-channel profile:         `context-id = "channel:{channel-id}"`
+   *                                         (workspace lives in `platform-instance`)
+   *   - Mattermost per-team:               `context-id = "team:{team-id}"`
+   *   - Single-context platforms (X, SMS): no rows ever created
+   * 
+   * Per-context attributes beyond `display-name` (roles, custom
+   * fields, preferences) intentionally do NOT live here. They
+   * belong in memory or a future authz capsule.
+   */
+  export interface ContextIdentity {
+    platform: string;
+    platform_instance?: string;
+    platform_user_id: string;
+    /** Opaque per-platform context key. */
+    context_id: string;
+    /** What this user is called *in this context*. */
+    display_name: string;
+    /** Last update timestamp (RFC 3339). */
+    updated_at: string;
+  }
+
+  /**
+   * Resolve a platform identity to an Astrid user, optionally
+   * scoped to a context for display-name layering.
+   * Topic: `users.v1.resolve.request`.
+   */
+  export interface ResolveRequest {
+    source: Source;
+    platform: string;
+    platform_instance?: string;
+    platform_user_id: string;
+    /**
+     * Optional context. When set, the response's `display-name`
+     * uses the per-context override if one exists. When None,
+     * only the link-global and canonical fallbacks apply.
+     */
+    context_id?: string;
+  }
+
+  /**
+   * Response for resolve.
+   * Topic: `users.v1.resolve.response`.
+   * 
+   * A clean "no link exists" is `user = none` with `error = none`.
+   * Validation or storage failures populate `error` and leave the
+   * other success fields empty.
+   */
+  export interface ResolveResponse {
+    correlation_id: string;
+    user?: AstridUser;
+    /**
+     * The right name to address this user. Resolution order
+     * (first non-empty wins):
+     *   1. `context-identity.display-name` (if `context-id` was
+     *      provided in the request and an override exists)
+     *   2. `frontend-link.display-name` (the platform-side name)
+     *   3. `astrid-user.display-name` (the canonical Astrid name)
+     * `None` if none of the three layers carry a name.
+     */
+    display_name?: string;
+    /**
+     * Which layer produced `display-name`. One of `"context"`,
+     * `"link"`, `"canonical"`. `None` when `display-name` is `None`.
+     */
+    display_name_source?: string;
+    error?: string;
+  }
+
+  /**
+   * Link a platform identity to an existing Astrid user. Upsert
+   * semantics: an existing link for the same
+   * `(platform, platform-instance?, platform-user-id)` is overwritten.
+   * Topic: `users.v1.link.request`.
+   */
+  export interface LinkRequest {
+    source: Source;
+    platform: string;
+    platform_instance?: string;
+    platform_user_id: string;
+    /** Target Astrid user UUID. Must already exist. */
+    astrid_user_id: string;
+    /** Audit string — how this link was established. */
+    method: string;
+    /**
+     * Optional platform-side global display name at link time.
+     * Stored on the resulting `frontend-link` for later
+     * resolution / display.
+     */
+    display_name?: string;
+  }
+
+  /**
+   * Response for link.
+   * Topic: `users.v1.link.response`.
+   */
+  export interface LinkResponse {
+    correlation_id: string;
+    link?: FrontendLink;
+    error?: string;
+  }
+
+  /**
+   * Remove a platform link. Also clears any
+   * `context-identity` overlays attached to it (cascading).
+   * Topic: `users.v1.unlink.request`.
+   */
+  export interface UnlinkRequest {
+    source: Source;
+    platform: string;
+    platform_instance?: string;
+    platform_user_id: string;
+  }
+
+  /**
+   * Response for unlink.
+   * Topic: `users.v1.unlink.response`.
+   */
+  export interface UnlinkResponse {
+    correlation_id: string;
+    /**
+     * `true` if a link existed and was removed; `false` for a
+     * no-op delete (link was already absent).
+     */
+    removed: boolean;
+    error?: string;
+  }
+
+  /**
+   * Create a new Astrid user.
+   * Topic: `users.v1.create.request`.
+   */
+  export interface CreateRequest {
+    source: Source;
+    /**
+     * Optional canonical display name. Rejected if it contains
+     * `/` or `\0`.
+     */
+    display_name?: string;
+  }
+
+  /**
+   * Response for create.
+   * Topic: `users.v1.create.response`.
+   */
+  export interface CreateResponse {
+    correlation_id: string;
+    user?: AstridUser;
+    error?: string;
+  }
+
+  /**
+   * Change an `AstridUser`'s canonical `display-name` without
+   * rotating the UUID or breaking any links.
+   * Topic: `users.v1.set_display_name.request`.
+   * 
+   * `display-name = None` clears the name. To leave it unchanged,
+   * don't issue the request.
+   */
+  export interface SetDisplayNameRequest {
+    source: Source;
+    astrid_user_id: string;
+    display_name?: string;
+  }
+
+  /**
+   * Response for set-display-name.
+   * Topic: `users.v1.set_display_name.response`.
+   */
+  export interface SetDisplayNameResponse {
+    correlation_id: string;
+    user?: AstridUser;
+    error?: string;
+  }
+
+  /**
+   * Set or clear an `AstridUser`'s `public-key` without rotating
+   * the UUID.
+   * Topic: `users.v1.set_public_key.request`.
+   * 
+   * `public-key = None` clears the key.
+   */
+  export interface SetPublicKeyRequest {
+    source: Source;
+    astrid_user_id: string;
+    public_key?: number[];
+  }
+
+  /**
+   * Response for set-public-key.
+   * Topic: `users.v1.set_public_key.response`.
+   */
+  export interface SetPublicKeyResponse {
+    correlation_id: string;
+    user?: AstridUser;
+    error?: string;
+  }
+
+  /**
+   * List every platform link for one Astrid user.
+   * Topic: `users.v1.links.request`.
+   */
+  export interface LinksRequest {
+    source: Source;
+    astrid_user_id: string;
+  }
+
+  /**
+   * Response for links.
+   * Topic: `users.v1.links.response`.
+   */
+  export interface LinksResponse {
+    correlation_id: string;
+    links: FrontendLink[];
+    error?: string;
+  }
+
+  /**
+   * Fetch a user record by UUID.
+   * Topic: `users.v1.get.request`.
+   */
+  export interface GetRequest {
+    source: Source;
+    astrid_user_id: string;
+  }
+
+  /**
+   * Response for get.
+   * Topic: `users.v1.get.response`.
+   */
+  export interface GetResponse {
+    correlation_id: string;
+    user?: AstridUser;
+    error?: string;
+  }
+
+  /**
+   * Delete a user, every link pointing at it, and every
+   * per-context overlay tied to those links.
+   * Idempotent — deleting an absent UUID returns `deleted = false`.
+   * Topic: `users.v1.delete.request`.
+   */
+  export interface DeleteRequest {
+    source: Source;
+    astrid_user_id: string;
+  }
+
+  /**
+   * Response for delete.
+   * Topic: `users.v1.delete.response`.
+   */
+  export interface DeleteResponse {
+    correlation_id: string;
+    /** `true` when a user record existed and was deleted. */
+    deleted: boolean;
+    error?: string;
+  }
+
+  /**
+   * List every user record in the principal's store. Paginated.
+   * Topic: `users.v1.list.request`.
+   */
+  export interface ListRequest {
+    source: Source;
+    /**
+     * Cursor from a prior `list-response.next-cursor`. `None`
+     * on the first call.
+     */
+    cursor?: string;
+    /**
+     * Maximum users to return. `None` lets the capsule pick a
+     * sensible default (current impl: 100).
+     */
+    limit?: number;
+  }
+
+  /**
+   * Response for list.
+   * Topic: `users.v1.list.response`.
+   */
+  export interface ListResponse {
+    correlation_id: string;
+    users: AstridUser[];
+    /**
+     * Pass back as `list-request.cursor` to get the next page.
+     * `None` when no more pages remain.
+     */
+    next_cursor?: string;
+    error?: string;
+  }
+
+  /**
+   * Set (or upsert) a per-context display-name override for a
+   * linked platform identity. The underlying `frontend-link` must
+   * already exist — context overlays cannot dangle.
+   * Topic: `users.v1.context.set.request`.
+   */
+  export interface ContextSetRequest {
+    source: Source;
+    platform: string;
+    platform_instance?: string;
+    platform_user_id: string;
+    context_id: string;
+    display_name: string;
+  }
+
+  /**
+   * Response for context-set.
+   * Topic: `users.v1.context.set.response`.
+   */
+  export interface ContextSetResponse {
+    correlation_id: string;
+    context_identity?: ContextIdentity;
+    error?: string;
+  }
+
+  /**
+   * Clear a per-context display-name override. Leaves the link
+   * itself and the global link-level display-name untouched.
+   * Topic: `users.v1.context.clear.request`.
+   */
+  export interface ContextClearRequest {
+    source: Source;
+    platform: string;
+    platform_instance?: string;
+    platform_user_id: string;
+    context_id: string;
+  }
+
+  /**
+   * Response for context-clear.
+   * Topic: `users.v1.context.clear.response`.
+   */
+  export interface ContextClearResponse {
+    correlation_id: string;
+    /**
+     * `true` if an overlay existed and was removed; `false` for
+     * a no-op clear.
+     */
+    removed: boolean;
+    error?: string;
+  }
+
+  /**
+   * Fetch the per-context override for one
+   * `(link, context-id)` pair. Useful when the caller wants the
+   * raw override without the `resolve`-style fallback chain.
+   * Topic: `users.v1.context.get.request`.
+   */
+  export interface ContextGetRequest {
+    source: Source;
+    platform: string;
+    platform_instance?: string;
+    platform_user_id: string;
+    context_id: string;
+  }
+
+  /**
+   * Response for context-get.
+   * Topic: `users.v1.context.get.response`.
+   */
+  export interface ContextGetResponse {
+    correlation_id: string;
+    context_identity?: ContextIdentity;
+    /**
+     * The same user resolved through the underlying link, when
+     * it exists. Saves the caller a separate `resolve` call.
+     */
+    astrid_user_id?: string;
+    error?: string;
+  }
+
+  /**
+   * List every context overlay attached to one Astrid user, across
+   * platforms and contexts. Paginated.
+   * Topic: `users.v1.context.list_for_user.request`.
+   */
+  export interface ContextListForUserRequest {
+    source: Source;
+    astrid_user_id: string;
+    cursor?: string;
+    limit?: number;
+  }
+
+  /**
+   * Response for context-list-for-user.
+   * Topic: `users.v1.context.list_for_user.response`.
+   */
+  export interface ContextListForUserResponse {
+    correlation_id: string;
+    contexts: ContextIdentity[];
+    next_cursor?: string;
+    error?: string;
+  }
+
+  /**
+   * List every user known in one specific context (e.g. every
+   * member of one Discord guild who has a per-guild nickname
+   * recorded). Returns the context overlay rows plus the resolved
+   * `astrid-user-id` for each, so the caller can build a member
+   * roster in one paginated call. Paginated.
+   * Topic: `users.v1.context.list_in_context.request`.
+   */
+  export interface ContextListInContextRequest {
+    source: Source;
+    platform: string;
+    platform_instance?: string;
+    context_id: string;
+    cursor?: string;
+    limit?: number;
+  }
+
+  /** One row of the context-list-in-context response. */
+  export interface ContextMember {
+    context_identity: ContextIdentity;
+    /**
+     * Resolved Astrid user UUID via the underlying link, when
+     * the link still exists. `None` indicates a stale overlay
+     * (link was unlinked but overlay wasn't cleared — the
+     * capsule cleans these on unlink, so this should be rare).
+     */
+    astrid_user_id?: string;
+  }
+
+  /**
+   * Response for context-list-in-context.
+   * Topic: `users.v1.context.list_in_context.response`.
+   */
+  export interface ContextListInContextResponse {
+    correlation_id: string;
+    members: ContextMember[];
+    next_cursor?: string;
+    error?: string;
+  }
+
+}