@unicity-astrid/sdk 0.1.0

package/wit-contracts/astrid-contracts.wit

@@ -0,0 +1,1266 @@
+// AUTO-GENERATED — DO NOT EDIT.
+//
+// Concatenated from contracts/interfaces/*.wit by
+// scripts/sync-contracts-wit.sh.
+//
+// Source of truth: unicity-astrid/wit (git submodule at contracts/).
+// Run `scripts/sync-contracts-wit.sh` after pulling the submodule to
+// regenerate this file.
+
+package astrid:contracts@1.0.0;
+
+// ── types ──────────────────────────────────────────────────────────
+package astrid-bus:types@1.0.0;
+
+/// Shared types used across Astrid interfaces.
+///
+/// Foundation types for messages, tool calls, and token usage.
+/// Imported by llm, session, prompt, context, and tool interfaces.
+interface types {
+    /// A conversation message.
+    record message {
+        role: message-role,
+        content: message-content,
+    }
+
+    enum message-role {
+        system,
+        user,
+        assistant,
+        tool,
+    }
+
+    /// Message content — text, tool calls, tool results, or mixed.
+    variant message-content {
+        text(string),
+        tool-calls(list<tool-call>),
+        tool-result(tool-call-result),
+        multi-part(list<content-part>),
+    }
+
+    variant content-part {
+        text(string),
+        image(image-data),
+    }
+
+    record image-data {
+        data: string,
+        media-type: string,
+    }
+
+    /// A tool call requested by the model.
+    record tool-call {
+        /// 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.
+    record tool-call-result {
+        call-id: string,
+        content: string,
+        is-error: bool,
+    }
+
+    /// A tool definition provided to the model.
+    record tool-definition {
+        name: string,
+        description: option<string>,
+        input-schema: string,
+    }
+
+    /// Token usage statistics.
+    record usage {
+        input-tokens: u64,
+        output-tokens: u64,
+    }
+}
+
+// ── agent ──────────────────────────────────────────────────────────
+package astrid-bus:agent@1.0.0;
+
+/// Agent interface — runtime envelopes the agent loop publishes for uplinks.
+///
+/// The agent capsule publishes `agent.v1.response` with streaming and final
+/// turn output, and `agent.v1.session_changed` whenever the active session
+/// rolls over. Uplink capsules subscribe to surface these to the user.
+interface agent {
+    /// A response generated by the agent for the user.
+    record 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: bool,
+        /// 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.
+    record session-changed {
+        /// The session ID that is now active.
+        session-id: string,
+        /// Optional ID of the session that was previously active.
+        previous-session-id: option<string>,
+        /// Reason for the change (e.g. "clear", "restore", "branch").
+        reason: string,
+    }
+}
+
+// ── approval ──────────────────────────────────────────────────────────
+package astrid-bus:approval@1.0.0;
+
+/// Approval interface — human-in-the-loop authorization envelopes.
+///
+/// A capsule publishes `astrid.v1.approval` when it needs user authorization
+/// for a sensitive action that did not match a pre-approved allowance. The
+/// TUI prompts, then publishes the decision on
+/// `astrid.v1.approval.response.<request-id>`. Distinct from the host
+/// `request-approval` syscall (in-capsule API) — these envelopes carry the
+/// same flow over the IPC bus for uplink consumption.
+interface approval {
+    /// An interceptor or capsule request for human authorization.
+    record 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.
+    record 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: option<string>,
+    }
+}
+
+// ── client ──────────────────────────────────────────────────────────
+package astrid-bus:client@1.0.0;
+
+/// Client interface — connection lifecycle envelopes for uplinks.
+///
+/// Uplinks publish `client.v1.connect` on attach and `client.v1.disconnect`
+/// on detach so the kernel can update the active-connection count and
+/// trigger idle-shutdown when the last client disconnects.
+interface client {
+    /// A client has connected to an uplink.
+    record connect {
+        /// Optional client identifier (e.g. process name + PID).
+        client-id: option<string>,
+    }
+
+    /// A client is disconnecting gracefully.
+    record disconnect {
+        /// Optional reason for disconnection (e.g. "quit", "timeout").
+        reason: option<string>,
+    }
+}
+
+// ── context ──────────────────────────────────────────────────────────
+package astrid-bus:context@1.0.0;
+
+/// Context interface — conversation compaction and token management.
+///
+/// A capsule exporting this interface handles `context_engine.v1.*`
+/// requests and publishes compaction responses and hooks for plugin
+/// capsules to influence compaction behaviour.
+interface context {
+    use astrid-bus:types/types.{message};
+
+    /// Request to compact messages within a token budget.
+    record compact-request {
+        session-id: string,
+        messages: list<message>,
+        max-tokens: u64,
+        target-tokens: u64,
+    }
+
+    /// Result of compaction.
+    record compact-response {
+        messages: list<message>,
+        compacted: bool,
+        messages-removed: u32,
+        strategy: string,
+    }
+
+    /// Request to estimate token count for messages.
+    record estimate-request {
+        messages: list<message>,
+    }
+
+    /// Token count estimate.
+    record estimate-response {
+        estimated-tokens: u64,
+    }
+
+    /// Hook payload sent before compaction (plugins can influence).
+    record before-compaction-hook {
+        session-id: string,
+        messages: list<message>,
+        message-count: u32,
+        estimated-tokens: u64,
+        max-tokens: u64,
+        response-topic: string,
+    }
+
+    /// Plugin response to before-compaction hook.
+    record before-compaction-hook-response {
+        skip: option<bool>,
+        pinned-message-ids: list<string>,
+        custom-strategy: option<string>,
+    }
+
+    /// Notification after compaction completes.
+    record after-compaction-event {
+        session-id: string,
+        messages-before: u32,
+        messages-after: u32,
+        tokens-before: u64,
+        tokens-after: u64,
+        strategy-used: string,
+    }
+}
+
+// ── elicit ──────────────────────────────────────────────────────────
+package astrid-bus:elicit@1.0.0;
+
+/// Elicit interface — interactive user input during a capsule lifecycle hook.
+///
+/// A capsule publishes `astrid.v1.elicit.<key>` when its install / upgrade
+/// hook needs a value from the user. The TUI prompts, then publishes the
+/// answer on `astrid.v1.elicit.response.<key>`. Distinct from the host
+/// `elicit` syscall (which is the in-capsule API) — these envelopes carry
+/// the same flow over the IPC bus for uplink consumption.
+interface elicit {
+    use astrid-bus:onboarding/onboarding.{field};
+
+    /// A lifecycle hook is requesting user input.
+    record request {
+        /// Correlation ID matching the response.
+        request-id: string,
+        /// The capsule requesting input.
+        capsule-id: string,
+        /// Field descriptor reusing the onboarding schema.
+        field: field,
+    }
+
+    /// Response to an elicit request.
+    record response {
+        /// Must match the `request-id` from the originating request.
+        request-id: string,
+        /// The user's input. Absent if the user cancelled.
+        value: option<string>,
+        /// For `array`-type fields, the collected items.
+        values: option<list<string>>,
+    }
+}
+
+// ── hook ──────────────────────────────────────────────────────────
+package astrid-bus:hook@1.0.0;
+
+/// Hook interface — maps kernel lifecycle events to semantic hooks.
+///
+/// A capsule exporting this interface intercepts `astrid.v1.lifecycle.*`
+/// events and publishes `hook.v1.result.*` with merge strategy results.
+/// Plugin capsules subscribe to specific hooks to extend behaviour.
+interface hook {
+    /// Lifecycle events emitted by the kernel.
+    enum lifecycle-event {
+        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.
+    record hook-result {
+        /// Whether the operation should be skipped.
+        skip: option<bool>,
+        /// Merged data from interceptor responses (opaque JSON).
+        data: option<string>,
+    }
+}
+
+// ── llm ──────────────────────────────────────────────────────────
+package astrid-bus:llm@1.0.0;
+
+/// LLM interface — streaming text generation with tool use support.
+///
+/// A capsule exporting this interface handles `llm.v1.request.generate.*`
+/// events and publishes `llm.v1.stream.*` streaming responses.
+interface llm {
+    use astrid-bus:types/types.{message, tool-definition, usage};
+    use astrid-bus:registry/registry.{provider-entry};
+
+    /// 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.
+    record describe-request {
+        /// 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>`.
+    record describe-response {
+        /// 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: list<provider-entry>,
+    }
+
+    /// Request to generate a response.
+    record generate-request {
+        request-id: string,
+        model: string,
+        messages: list<message>,
+        tools: list<tool-definition>,
+        /// System prompt.
+        system: string,
+    }
+
+    /// A streaming event from the provider.
+    variant stream-event {
+        text-delta(string),
+        tool-call-start(tool-call-start-event),
+        tool-call-delta(tool-call-delta-event),
+        tool-call-end(tool-call-end-event),
+        reasoning-delta(string),
+        usage(usage),
+        done,
+        error(string),
+    }
+
+    record tool-call-start-event {
+        id: string,
+        name: string,
+    }
+
+    record tool-call-delta-event {
+        id: string,
+        args-delta: string,
+    }
+
+    record tool-call-end-event {
+        id: string,
+    }
+
+    /// Final (non-streaming) response.
+    record generate-response {
+        message: message,
+        has-tool-calls: bool,
+        stop-reason: stop-reason,
+        usage: usage,
+    }
+
+    enum stop-reason {
+        end-turn,
+        max-tokens,
+        tool-use,
+        stop-sequence,
+    }
+}
+
+// ── onboarding ──────────────────────────────────────────────────────────
+package astrid-bus:onboarding@1.0.0;
+
+/// Onboarding interface — env-var collection at install / first-run.
+///
+/// A capsule publishes `astrid.v1.onboarding.required` when it cannot start
+/// without configuration values that the operator has not yet supplied.
+/// The TUI / installer subscribes, prompts the user per field, and writes
+/// the collected values back to the capsule's `[env]` configuration.
+interface onboarding {
+    /// A capsule needs environment variables to be provided by the user.
+    record required {
+        /// The ID of the capsule requiring onboarding.
+        capsule-id: string,
+        /// Rich field descriptors for each missing env var.
+        fields: list<field>,
+    }
+
+    /// A field descriptor for capsule onboarding.
+    record field {
+        /// The environment variable key.
+        key: string,
+        /// The prompt shown to the user.
+        prompt: string,
+        /// Optional description for additional context.
+        description: option<string>,
+        /// The input type for this field.
+        field-type: field-type,
+        /// Optional default value.
+        default: option<string>,
+        /// Placeholder hint text shown when the input is empty (e.g. `"sk-..."`).
+        placeholder: option<string>,
+    }
+
+    /// The type of input expected for an onboarding field.
+    variant field-type {
+        /// Free-form text input.
+        text,
+        /// Masked secret input (stored in the SecretStore).
+        secret,
+        /// Selection from a fixed set of choices.
+        choice(list<string>),
+        /// Multi-value array input (user adds items one at a time).
+        array,
+    }
+}
+
+// ── prompt ──────────────────────────────────────────────────────────
+package astrid-bus:prompt@1.0.0;
+
+/// Prompt interface — assembles LLM prompts with plugin hooks.
+///
+/// A capsule exporting this interface handles `prompt_builder.v1.assemble`
+/// and publishes assembled prompts, with before/after hooks for context
+/// injection by plugin capsules.
+interface prompt {
+    use astrid-bus:types/types.{message, tool-definition};
+
+    /// Request to assemble a prompt for LLM generation.
+    record assemble-request {
+        messages: list<message>,
+        system-prompt: string,
+        request-id: string,
+        model: string,
+        provider: string,
+        session-id: option<string>,
+    }
+
+    /// Assembled prompt ready for LLM.
+    record assemble-response {
+        system-prompt: string,
+        user-context-prefix: string,
+        request-id: string,
+        session-id: option<string>,
+        /// Collected tool schemas from tool-providing capsules.
+        tools: list<tool-definition>,
+        /// Session conversation history messages.
+        messages: list<message>,
+    }
+
+    /// Hook payload sent before prompt build (plugins inject context).
+    record before-build-hook {
+        messages: list<message>,
+        system-prompt: string,
+        request-id: string,
+        model: string,
+        provider: string,
+        response-topic: string,
+    }
+
+    /// Plugin response to before-build hook.
+    record before-build-hook-response {
+        prepend-system-context: option<string>,
+        append-system-context: option<string>,
+        system-prompt: option<string>,
+        prepend-context: option<string>,
+    }
+
+    /// Notification after prompt is built.
+    record after-build-event {
+        system-prompt: string,
+        user-context-prefix: string,
+        request-id: string,
+    }
+}
+
+// ── registry ──────────────────────────────────────────────────────────
+package astrid-bus:registry@1.0.0;
+
+/// Registry interface — LLM provider discovery and model management.
+///
+/// A capsule exporting this interface handles `registry.v1.*` requests,
+/// discovers available LLM providers from loaded capsule metadata, and
+/// manages the active model selection.
+interface registry {
+    /// An available LLM provider entry.
+    record provider-entry {
+        /// 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: list<string>,
+        /// Provider's context window size in tokens.
+        context-window: option<u64>,
+        /// Provider's max output tokens per request.
+        max-output-tokens: option<u64>,
+    }
+
+    /// A single option in a selection picker.
+    record selection-option {
+        /// 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: option<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`.
+    record selection-required {
+        /// Correlation ID for the callback.
+        request-id: string,
+        /// Title or prompt shown above the list.
+        title: string,
+        /// The selectable options.
+        options: list<selection-option>,
+        /// 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`).
+    record selection-callback {
+        /// Must match the `request-id` from the originating
+        /// `selection-required`.
+        request-id: string,
+        /// `id` of the chosen `selection-option`.
+        selected-id: string,
+    }
+}
+
+// ── session ──────────────────────────────────────────────────────────
+package astrid-bus:session@1.0.0;
+
+/// Session protocol — persistent conversation history management.
+///
+/// A capsule exporting this interface handles `session.v1.request.*`
+/// events and publishes `session.v1.response.*` replies scoped by
+/// correlation ID.
+interface session {
+    use astrid-bus:types/types.{message};
+
+    /// Request to fetch conversation history.
+    record get-messages-request {
+        session-id: string,
+        correlation-id: string,
+        append-before-read: option<list<message>>,
+    }
+
+    /// Response containing conversation history.
+    record get-messages-response {
+        correlation-id: string,
+        messages: list<message>,
+    }
+
+    /// Request to clear a session and start fresh.
+    record clear-request {
+        session-id: string,
+        correlation-id: string,
+    }
+
+    /// Response confirming session cleared.
+    record clear-response {
+        correlation-id: string,
+        new-session-id: string,
+        old-session-id: string,
+    }
+
+    /// Fire-and-forget append to conversation history.
+    record append-request {
+        session-id: string,
+        messages: list<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`.
+    record session-cleared {
+        /// Session ID that was cleared.
+        session-id: string,
+    }
+}
+
+// ── spark ──────────────────────────────────────────────────────────
+package astrid-bus:spark@1.0.0;
+
+/// Spark interface — agent persona and system prompt construction.
+///
+/// A capsule exporting this interface handles `identity.v1.request.build`
+/// and publishes `identity.v1.response.ready` with the assembled system
+/// prompt for the current workspace and session.
+///
+/// Named "spark" to distinguish from user identity management (the host
+/// ABI `identity-*` functions for principal/account resolution).
+interface spark {
+    /// Request to build the agent's system prompt.
+    record build-request {
+        workspace-root: string,
+        session-id: option<string>,
+    }
+
+    /// Response with the assembled system prompt.
+    record build-response {
+        prompt: string,
+        session-id: option<string>,
+    }
+}
+
+// ── system ──────────────────────────────────────────────────────────
+package astrid-bus:system@1.0.0;
+
+/// System interface — kernel-emitted lifecycle, health, and CLI envelopes.
+///
+/// The kernel publishes these on the IPC bus so capsules can react to
+/// boot-completion, shutdown, watchdog ticks, bus health warnings, and
+/// inbound CLI slash-commands.
+interface system {
+    /// Published once after every capsule has reported ready, signalling
+    /// that the agent stack is fully online. Topic: `astrid.v1.capsules_loaded`.
+    record capsules-loaded {
+        /// IDs of every capsule that successfully loaded.
+        capsule-ids: list<string>,
+    }
+
+    /// Periodic kernel watchdog tick, used by long-lived capsules to age
+    /// out stale state (timeouts, abandoned correlations, etc.).
+    /// Topic: `astrid.v1.watchdog.tick`.
+    record watchdog-tick {
+        /// Wall-clock time of the tick (UNIX epoch milliseconds).
+        timestamp-ms: u64,
+    }
+
+    /// 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`.
+    record event-bus-lagged {
+        /// Topic that lagged.
+        topic: string,
+        /// Number of messages dropped.
+        dropped: u64,
+    }
+
+    /// Cooperative restart signal — the kernel asks long-lived capsules
+    /// to flush ephemeral state and re-arm. Topic: `system.v1.lifecycle.restart`.
+    record lifecycle-restart {
+        /// 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`.
+    record command-execute {
+        /// 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,
+    }
+}
+
+// ── tool ──────────────────────────────────────────────────────────
+package astrid-bus:tool@1.0.0;
+
+/// Tool interface — dispatches tool calls to capsule handlers.
+///
+/// A capsule exporting this interface handles `tool.v1.request.execute`,
+/// routes to the appropriate tool capsule via `tool.v1.execute.<name>`,
+/// and collects results on `tool.v1.execute.*.result`.
+interface tool {
+    use astrid-bus:types/types.{tool-call, tool-call-result, tool-definition};
+
+    /// Request to cancel in-flight tool executions.
+    record cancel-request {
+        call-ids: list<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.
+    record describe-request {
+        /// 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>`.
+    record describe-response {
+        /// Must match the `correlation-id` from the originating request.
+        correlation-id: string,
+        /// The capsule's exposed tools.
+        tools: list<tool-definition>,
+    }
+}
+
+// ── user ──────────────────────────────────────────────────────────
+package astrid-bus:user@1.0.0;
+
+/// User interface — input envelopes from a human via an uplink.
+///
+/// Uplink capsules (CLI, Telegram, Discord, etc.) publish `user.v1.prompt`
+/// when the human types a message. The agent loop subscribes to drive a
+/// new turn.
+interface user {
+    /// A prompt typed by a human via an uplink.
+    record 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: option<string>,
+    }
+}
+
+// ── users ──────────────────────────────────────────────────────────
+package astrid-bus:users@1.0.0;
+
+/// Users interface — within-principal user identity store.
+///
+/// Owns the cross-platform user identity mapping for a single Astrid
+/// principal. A capsule exporting this interface (the `users` capsule)
+/// handles `users.v1.<op>.request` events and publishes
+/// `users.v1.<op>.response` replies correlated by `correlation-id`.
+///
+/// This is distinct from the `user` interface (`user.v1.prompt`), which
+/// carries inbound human prompts from uplinks. Naming separation:
+///
+///   - `user`  (singular) — a single human typing into an uplink.
+///   - `users` (plural)   — the identity directory that maps platform
+///                           IDs to canonical AstridUserIds.
+///
+/// Kernel-side principal tenancy is unaffected: this interface covers
+/// user identity *within* one principal's KV scope only. Different
+/// principals have independent stores.
+///
+/// ## Two-layer identity model
+///
+/// 1. **Identity layer** — `frontend-link` records map a platform's
+///    stable opaque ID (Discord snowflake, Telegram user-id, Nostr
+///    pubkey) to a canonical `astrid-user-id`. Global per
+///    `(platform, platform-instance, platform-user-id)` triple.
+/// 2. **Presentation layer** — `context-identity` records overlay a
+///    per-context display name on a given identity link. `context-id`
+///    is opaque to the capsule — uplinks define their own scheme
+///    (`"guild:123"`, `"room:!abc:matrix.org"`, `"channel:C01234"`).
+///    Used for "how should the agent address this user *right now*"
+///    when the platform supports per-context names (Discord guild
+///    nicknames, Matrix room display names, Slack channel profiles).
+///
+/// `resolve` is context-aware: it returns a layered `display-name`
+/// in one round-trip — context override > link's platform name >
+/// AstridUser's canonical Astrid name.
+interface users {
+    // ── Envelope ──────────────────────────────────────────────────
+
+    /// 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.
+    record 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: option<string>,
+        /// Correlation token. The requester subscribes to the response
+        /// topic and filters incoming responses by this string.
+        correlation-id: string,
+    }
+
+    // ── Domain records ────────────────────────────────────────────
+
+    /// 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.
+    record astrid-user {
+        /// 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: option<list<u8>>,
+        /// Operator/canonical Astrid-side display name. Mutable via
+        /// `set-display-name`. Distinct from any platform-side name.
+        display-name: option<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.
+    record frontend-link {
+        /// 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: option<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: option<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.
+    record context-identity {
+        platform: string,
+        platform-instance: option<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,
+    }
+
+    // ── Pagination ─────────────────────────────────────────────────
+    //
+    // Paginated topics use opaque `cursor: option<string>` tokens.
+    // Callers treat the value as a black box — pass `None` on the
+    // first request, then loop while the response's `next-cursor`
+    // is `Some(token)`, passing that token back unchanged. The
+    // capsule defines the format. (Modelled as bare `option<string>`
+    // rather than a `type cursor = string` alias for codegen
+    // portability — wit-bindgen handles aliases but our JS codegen
+    // does not.)
+
+    // ── Resolve (context-aware) ───────────────────────────────────
+
+    /// Resolve a platform identity to an Astrid user, optionally
+    /// scoped to a context for display-name layering.
+    /// Topic: `users.v1.resolve.request`.
+    record resolve-request {
+        source: source,
+        platform: string,
+        platform-instance: option<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: option<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.
+    record resolve-response {
+        correlation-id: string,
+        user: option<astrid-user>,
+        /// 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: option<string>,
+        /// Which layer produced `display-name`. One of `"context"`,
+        /// `"link"`, `"canonical"`. `None` when `display-name` is `None`.
+        display-name-source: option<string>,
+        error: option<string>,
+    }
+
+    // ── Link ───────────────────────────────────────────────────────
+
+    /// 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`.
+    record link-request {
+        source: source,
+        platform: string,
+        platform-instance: option<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: option<string>,
+    }
+
+    /// Response for link.
+    /// Topic: `users.v1.link.response`.
+    record link-response {
+        correlation-id: string,
+        link: option<frontend-link>,
+        error: option<string>,
+    }
+
+    // ── Unlink ─────────────────────────────────────────────────────
+
+    /// Remove a platform link. Also clears any
+    /// `context-identity` overlays attached to it (cascading).
+    /// Topic: `users.v1.unlink.request`.
+    record unlink-request {
+        source: source,
+        platform: string,
+        platform-instance: option<string>,
+        platform-user-id: string,
+    }
+
+    /// Response for unlink.
+    /// Topic: `users.v1.unlink.response`.
+    record unlink-response {
+        correlation-id: string,
+        /// `true` if a link existed and was removed; `false` for a
+        /// no-op delete (link was already absent).
+        removed: bool,
+        error: option<string>,
+    }
+
+    // ── Create ─────────────────────────────────────────────────────
+
+    /// Create a new Astrid user.
+    /// Topic: `users.v1.create.request`.
+    record create-request {
+        source: source,
+        /// Optional canonical display name. Rejected if it contains
+        /// `/` or `\0`.
+        display-name: option<string>,
+    }
+
+    /// Response for create.
+    /// Topic: `users.v1.create.response`.
+    record create-response {
+        correlation-id: string,
+        user: option<astrid-user>,
+        error: option<string>,
+    }
+
+    // ── Mutate canonical fields on an AstridUser ──────────────────
+
+    /// 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.
+    record set-display-name-request {
+        source: source,
+        astrid-user-id: string,
+        display-name: option<string>,
+    }
+
+    /// Response for set-display-name.
+    /// Topic: `users.v1.set_display_name.response`.
+    record set-display-name-response {
+        correlation-id: string,
+        user: option<astrid-user>,
+        error: option<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.
+    record set-public-key-request {
+        source: source,
+        astrid-user-id: string,
+        public-key: option<list<u8>>,
+    }
+
+    /// Response for set-public-key.
+    /// Topic: `users.v1.set_public_key.response`.
+    record set-public-key-response {
+        correlation-id: string,
+        user: option<astrid-user>,
+        error: option<string>,
+    }
+
+    // ── Links (list every link for one user) ──────────────────────
+
+    /// List every platform link for one Astrid user.
+    /// Topic: `users.v1.links.request`.
+    record links-request {
+        source: source,
+        astrid-user-id: string,
+    }
+
+    /// Response for links.
+    /// Topic: `users.v1.links.response`.
+    record links-response {
+        correlation-id: string,
+        links: list<frontend-link>,
+        error: option<string>,
+    }
+
+    // ── Get (lookup user by UUID) ─────────────────────────────────
+
+    /// Fetch a user record by UUID.
+    /// Topic: `users.v1.get.request`.
+    record get-request {
+        source: source,
+        astrid-user-id: string,
+    }
+
+    /// Response for get.
+    /// Topic: `users.v1.get.response`.
+    record get-response {
+        correlation-id: string,
+        user: option<astrid-user>,
+        error: option<string>,
+    }
+
+    // ── Delete (admin) ────────────────────────────────────────────
+
+    /// 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`.
+    record delete-request {
+        source: source,
+        astrid-user-id: string,
+    }
+
+    /// Response for delete.
+    /// Topic: `users.v1.delete.response`.
+    record delete-response {
+        correlation-id: string,
+        /// `true` when a user record existed and was deleted.
+        deleted: bool,
+        error: option<string>,
+    }
+
+    // ── List users (paginated) ────────────────────────────────────
+
+    /// List every user record in the principal's store. Paginated.
+    /// Topic: `users.v1.list.request`.
+    record list-request {
+        source: source,
+        /// Cursor from a prior `list-response.next-cursor`. `None`
+        /// on the first call.
+        cursor: option<string>,
+        /// Maximum users to return. `None` lets the capsule pick a
+        /// sensible default (current impl: 100).
+        limit: option<u32>,
+    }
+
+    /// Response for list.
+    /// Topic: `users.v1.list.response`.
+    record list-response {
+        correlation-id: string,
+        users: list<astrid-user>,
+        /// Pass back as `list-request.cursor` to get the next page.
+        /// `None` when no more pages remain.
+        next-cursor: option<string>,
+        error: option<string>,
+    }
+
+    // ── Context: per-context display-name overlay ─────────────────
+
+    /// 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`.
+    record context-set-request {
+        source: source,
+        platform: string,
+        platform-instance: option<string>,
+        platform-user-id: string,
+        context-id: string,
+        display-name: string,
+    }
+
+    /// Response for context-set.
+    /// Topic: `users.v1.context.set.response`.
+    record context-set-response {
+        correlation-id: string,
+        context-identity: option<context-identity>,
+        error: option<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`.
+    record context-clear-request {
+        source: source,
+        platform: string,
+        platform-instance: option<string>,
+        platform-user-id: string,
+        context-id: string,
+    }
+
+    /// Response for context-clear.
+    /// Topic: `users.v1.context.clear.response`.
+    record context-clear-response {
+        correlation-id: string,
+        /// `true` if an overlay existed and was removed; `false` for
+        /// a no-op clear.
+        removed: bool,
+        error: option<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`.
+    record context-get-request {
+        source: source,
+        platform: string,
+        platform-instance: option<string>,
+        platform-user-id: string,
+        context-id: string,
+    }
+
+    /// Response for context-get.
+    /// Topic: `users.v1.context.get.response`.
+    record context-get-response {
+        correlation-id: string,
+        context-identity: option<context-identity>,
+        /// The same user resolved through the underlying link, when
+        /// it exists. Saves the caller a separate `resolve` call.
+        astrid-user-id: option<string>,
+        error: option<string>,
+    }
+
+    /// List every context overlay attached to one Astrid user, across
+    /// platforms and contexts. Paginated.
+    /// Topic: `users.v1.context.list_for_user.request`.
+    record context-list-for-user-request {
+        source: source,
+        astrid-user-id: string,
+        cursor: option<string>,
+        limit: option<u32>,
+    }
+
+    /// Response for context-list-for-user.
+    /// Topic: `users.v1.context.list_for_user.response`.
+    record context-list-for-user-response {
+        correlation-id: string,
+        contexts: list<context-identity>,
+        next-cursor: option<string>,
+        error: option<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`.
+    record context-list-in-context-request {
+        source: source,
+        platform: string,
+        platform-instance: option<string>,
+        context-id: string,
+        cursor: option<string>,
+        limit: option<u32>,
+    }
+
+    /// One row of the context-list-in-context response.
+    record context-member {
+        context-identity: context-identity,
+        /// 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: option<string>,
+    }
+
+    /// Response for context-list-in-context.
+    /// Topic: `users.v1.context.list_in_context.response`.
+    record context-list-in-context-response {
+        correlation-id: string,
+        members: list<context-member>,
+        next-cursor: option<string>,
+        error: option<string>,
+    }
+}
+