# Musehub — Type Contracts Reference

> Auto-generated: 2026-04-12
> Source: `tools/gen_type_contracts.py (repo: musehub)`
> Check for drift: `python tools/gen_type_contracts.py --check`
>
> **Do not edit this file manually.** It is regenerated from source on every
> commit.  To update, change the source types and re-run the generator.

---

## Table of Contents

- [Enums](#enums) (5)
- [TypedDicts](#typeddicts) (47)
- [Pydantic Models](#pydantic-models) (215)
- [SQLAlchemy ORM Models](#sqlalchemy-orm-models) (43)
- [Protocols](#protocols) (4)

---

## Enums

### `Permission` — [`musehub/api/routes/musehub/collaborators.py`](musehub/api/routes/musehub/collaborators.py)

Collaborator permission levels in ascending order of authority.

**Bases:** `StrEnum`

| Member | Value |
|--------|-------|
| `read` | `'read'` |
| `write` | `'write'` |
| `admin` | `'admin'` |
| `owner` | `'owner'` |


### `KeyAlgorithm` — [`musehub/crypto/keys.py`](musehub/crypto/keys.py)

Supported key algorithm identifiers (wire strings).

**Bases:** `str`, `Enum`

| Member | Value |
|--------|-------|
| `ED25519` | `'ed25519'` |
| `ML_DSA_65` | `'ml-dsa-65'` |


### `ContextDepth` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

Depth level controlling how much data the context endpoint returns.

**Bases:** `StrEnum`

| Member | Value |
|--------|-------|
| `brief` | `'brief'` |
| `standard` | `'standard'` |
| `verbose` | `'verbose'` |


### `ContextFormat` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

Wire format for the context response.

**Bases:** `StrEnum`

| Member | Value |
|--------|-------|
| `json` | `'json'` |
| `yaml` | `'yaml'` |


### `MuseHubDivergenceLevel` — [`musehub/services/musehub_divergence.py`](musehub/services/musehub_divergence.py)

Qualitative label for a per-dimension or overall divergence score.

**Bases:** `StrEnum`

| Member | Value |
|--------|-------|
| `NONE` | `'NONE'` |
| `LOW` | `'LOW'` |
| `MED` | `'MED'` |
| `HIGH` | `'HIGH'` |


## TypedDicts

### `_IdentityDict` — [`musehub/api/routes/api/identities.py`](musehub/api/routes/api/identities.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `str` | ✓ | `—` |
| `handle` | `str` | ✓ | `—` |
| `identity_type` | `str` | ✓ | `—` |
| `display_name` | `str | None` | ✓ | `—` |
| `bio` | `str | None` | ✓ | `—` |
| `avatar_url` | `str | None` | ✓ | `—` |
| `website_url` | `str | None` | ✓ | `—` |
| `email` | `str | None` | ✓ | `—` |
| `agent_model` | `str | None` | ✓ | `—` |
| `agent_capabilities` | `list[str]` | ✓ | `—` |
| `spawned_by` | `str | None` | ✓ | `—` |
| `scope` | `str | None` | ✓ | `—` |
| `expires_at` | `str | None` | ✓ | `—` |
| `created_at` | `str | None` | ✓ | `—` |
| `updated_at` | `str | None` | ✓ | `—` |


### `MCPPromptArgument` — [`musehub/mcp/prompts.py`](musehub/mcp/prompts.py)

A single named argument for an MCP prompt.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `Required[str]` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `required` | `bool` | ✓ | `—` |


### `MCPPromptDef` — [`musehub/mcp/prompts.py`](musehub/mcp/prompts.py)

Definition of a single MCP prompt exposed to agents.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `Required[str]` | ✓ | `—` |
| `description` | `Required[str]` | ✓ | `—` |
| `arguments` | `list[MCPPromptArgument]` | ✓ | `—` |


### `MCPPromptMessage` — [`musehub/mcp/prompts.py`](musehub/mcp/prompts.py)

A single message in an MCP prompt response.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `role` | `str` | ✓ | `—` |
| `content` | `MCPPromptMessageContent` | ✓ | `—` |


### `MCPPromptMessageContent` — [`musehub/mcp/prompts.py`](musehub/mcp/prompts.py)

The content of a single prompt message.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `str` | ✓ | `—` |
| `text` | `str` | ✓ | `—` |


### `MCPPromptResult` — [`musehub/mcp/prompts.py`](musehub/mcp/prompts.py)

The result returned by ``prompts/get``.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `description` | `str` | ✓ | `—` |
| `messages` | `list[MCPPromptMessage]` | ✓ | `—` |


### `MCPResource` — [`musehub/mcp/resources.py`](musehub/mcp/resources.py)

A concrete MCP resource (static URI).

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `uri` | `Required[str]` | ✓ | `—` |
| `name` | `Required[str]` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `mimeType` | `str` | ✓ | `—` |


### `MCPResourceContent` — [`musehub/mcp/resources.py`](musehub/mcp/resources.py)

The content object returned inside a ``resources/read`` response.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `uri` | `str` | ✓ | `—` |
| `mimeType` | `str` | ✓ | `—` |
| `text` | `str` | ✓ | `—` |


### `MCPResourceTemplate` — [`musehub/mcp/resources.py`](musehub/mcp/resources.py)

An MCP resource template (RFC 6570 URI template).

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `uriTemplate` | `Required[str]` | ✓ | `—` |
| `name` | `Required[str]` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `mimeType` | `str` | ✓ | `—` |


### `IssueEventPayload` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Payload emitted when an issue is opened or closed.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repoId` | `str` | ✓ | `—` |
| `action` | `str` | ✓ | `—` |
| `issueId` | `str` | ✓ | `—` |
| `number` | `int` | ✓ | `—` |
| `title` | `str` | ✓ | `—` |
| `state` | `str` | ✓ | `—` |


### `ProposalEventPayload` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Payload emitted when a merge proposal is opened or merged.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repoId` | `str` | ✓ | `—` |
| `action` | `str` | ✓ | `—` |
| `proposalId` | `str` | ✓ | `—` |
| `title` | `str` | ✓ | `—` |
| `fromBranch` | `str` | ✓ | `—` |
| `toBranch` | `str` | ✓ | `—` |
| `state` | `str` | ✓ | `—` |
| `mergeCommitId` | `NotRequired[str]` | ✓ | `—` |


### `PushEventPayload` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Payload emitted when commits are pushed to a MuseHub repo.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repoId` | `str` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `headCommitId` | `str` | ✓ | `—` |
| `pushedBy` | `str` | ✓ | `—` |
| `commitCount` | `int` | ✓ | `—` |


### `DAWToolCallMessage` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Message sent from the MCP server to the connected DAW over WebSocket.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `Literal['toolCall']` | ✓ | `—` |
| `requestId` | `str` | ✓ | `—` |
| `tool` | `str` | ✓ | `—` |
| `arguments` | `JSONObject` | ✓ | `—` |


### `DAWToolResponse` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Response sent from the DAW back to the MCP server after tool execution.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `success` | `Required[bool]` | ✓ | `—` |
| `content` | `list[MCPContentBlock]` | ✓ | `—` |
| `isError` | `bool` | ✓ | `—` |


### `ElicitationAction` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

The action taken by the user in response to an elicitation request.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `action` | `Required[str]` | ✓ | `—` |
| `content` | `NotRequired[JSONObject]` | ✓ | `—` |


### `ElicitationRequest` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

An ``elicitation/create`` request sent from the server to the client.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `mode` | `Required[str]` | ✓ | `—` |
| `message` | `Required[str]` | ✓ | `—` |
| `requestedSchema` | `NotRequired[JSONObject]` | ✓ | `—` |
| `url` | `NotRequired[str]` | ✓ | `—` |
| `elicitationId` | `NotRequired[str]` | ✓ | `—` |


### `ElicitationResponse` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

A JSON-RPC 2.0 response from the client to an ``elicitation/create`` request.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `action` | `Required[str]` | ✓ | `—` |
| `content` | `NotRequired[JSONObject]` | ✓ | `—` |


### `MCPCallResponse` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Full JSON-RPC response for the ``tools/call`` method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `jsonrpc` | `str` | ✓ | `—` |
| `id` | `str | int | None` | ✓ | `—` |
| `result` | `MCPCallResult` | ✓ | `—` |


### `MCPCallResult` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Result body for the ``tools/call`` JSON-RPC method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `content` | `Required[list[MCPContentBlock]]` | ✓ | `—` |
| `isError` | `bool` | ✓ | `—` |


### `MCPCapabilities` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

MCP server capabilities advertised during the ``initialize`` handshake.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tools` | `MCPToolsCapability` | ✓ | `—` |
| `resources` | `MCPResourcesCapability` | ✓ | `—` |


### `MCPCapabilitiesResult` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Result body for ``initialize`` — capability block.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tools` | `MCPToolsCapability` | ✓ | `—` |


### `MCPContentBlock` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

A content block in an MCP tool result (currently always text).

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `str` | ✓ | `—` |
| `text` | `str` | ✓ | `—` |


### `MCPErrorDetail` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

The ``error`` object inside a JSON-RPC 2.0 error response.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `code` | `Required[int]` | ✓ | `—` |
| `message` | `Required[str]` | ✓ | `—` |
| `data` | `JSONValue` | ✓ | `—` |


### `MCPErrorResponse` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

A JSON-RPC 2.0 error response.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `jsonrpc` | `str` | ✓ | `—` |
| `id` | `str | int | None` | ✓ | `—` |
| `error` | `MCPErrorDetail` | ✓ | `—` |


### `MCPInitializeParams` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Params for the ``initialize`` JSON-RPC method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `protocolVersion` | `Required[str]` | ✓ | `—` |
| `clientInfo` | `StrDict` | ✓ | `—` |
| `capabilities` | `JSONObject` | ✓ | `—` |


### `MCPInitializeResponse` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Full JSON-RPC response for the ``initialize`` method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `jsonrpc` | `str` | ✓ | `—` |
| `id` | `str | int | None` | ✓ | `—` |
| `result` | `MCPInitializeResult` | ✓ | `—` |


### `MCPInitializeResult` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Result body for the ``initialize`` JSON-RPC method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `protocolVersion` | `str` | ✓ | `—` |
| `serverInfo` | `MCPServerInfo` | ✓ | `—` |
| `capabilities` | `MCPCapabilitiesResult` | ✓ | `—` |


### `MCPInputSchema` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

JSON Schema describing an MCP tool's accepted arguments.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `Required[str]` | ✓ | `—` |
| `properties` | `Required[_PropInputMap]` | ✓ | `—` |
| `required` | `list[str]` | ✓ | `—` |


### `MCPPropertyDef` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

JSON Schema definition for a single MCP tool property.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `Required[str]` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `enum` | `list[str | int | float]` | ✓ | `—` |
| `minimum` | `float` | ✓ | `—` |
| `maximum` | `float` | ✓ | `—` |
| `default` | `JSONValue` | ✓ | `—` |
| `items` | `JSONObject` | ✓ | `—` |
| `properties` | `_PropDefMap` | ✓ | `—` |


### `MCPRequest` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

An incoming JSON-RPC 2.0 message from an MCP client.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `jsonrpc` | `Required[str]` | ✓ | `—` |
| `method` | `Required[str]` | ✓ | `—` |
| `id` | `str | int | None` | ✓ | `—` |
| `params` | `JSONObject` | ✓ | `—` |


### `MCPResourcesCapability` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

The ``resources`` entry in ``MCPCapabilities``.

**Bases:** `TypedDict`

_No annotated fields._


### `MCPServerInfo` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

MCP server info returned in ``initialize`` responses and ``get_server_info()``.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `version` | `str` | ✓ | `—` |
| `protocolVersion` | `str` | ✓ | `—` |
| `capabilities` | `MCPCapabilities` | ✓ | `—` |


### `MCPSuccessResponse` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

A JSON-RPC 2.0 success response.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `jsonrpc` | `str` | ✓ | `—` |
| `id` | `str | int | None` | ✓ | `—` |
| `result` | `JSONObject` | ✓ | `—` |


### `MCPToolAnnotations` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

MCP 2025-11-25 tool annotations — behavioural hints for LLM clients.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `readOnlyHint` | `bool` | ✓ | `—` |
| `destructiveHint` | `bool` | ✓ | `—` |
| `idempotentHint` | `bool` | ✓ | `—` |
| `openWorldHint` | `bool` | ✓ | `—` |


### `MCPToolCallParams` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Params for the ``tools/call`` JSON-RPC method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `arguments` | `JSONObject` | ✓ | `—` |


### `MCPToolDef` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Definition of a single MCP tool exposed to LLM clients.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `Required[str]` | ✓ | `—` |
| `description` | `Required[str]` | ✓ | `—` |
| `inputSchema` | `Required[MCPInputSchema]` | ✓ | `—` |
| `annotations` | `MCPToolAnnotations` | ✓ | `—` |
| `server_side` | `bool` | ✓ | `—` |


### `MCPToolsCapability` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

The ``tools`` entry in ``MCPCapabilities``.

**Bases:** `TypedDict`

_No annotated fields._


### `MCPToolsListResponse` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Full JSON-RPC response for the ``tools/list`` method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `jsonrpc` | `str` | ✓ | `—` |
| `id` | `str | int | None` | ✓ | `—` |
| `result` | `MCPToolsListResult` | ✓ | `—` |


### `MCPToolsListResult` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Result body for the ``tools/list`` JSON-RPC method.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tools` | `list[MCPToolDef]` | ✓ | `—` |


### `SessionInfo` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Summary of an active MCP session — returned in server metadata endpoints.

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `session_id` | `Required[str]` | ✓ | `—` |
| `user_id` | `Required[str | None]` | ✓ | `—` |
| `client_capabilities` | `NotRequired[JSONObject]` | ✓ | `—` |
| `pending_count` | `NotRequired[int]` | ✓ | `—` |
| `sse_queue_count` | `NotRequired[int]` | ✓ | `—` |
| `created_at` | `NotRequired[float]` | ✓ | `—` |
| `last_active` | `NotRequired[float]` | ✓ | `—` |
| `supports_form_elicitation` | `NotRequired[bool]` | ✓ | `—` |
| `supports_url_elicitation` | `NotRequired[bool]` | ✓ | `—` |


### `_ChildOp` — [`tests/test_musehub_proposals_touched_symbols.py`](tests/test_musehub_proposals_touched_symbols.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `op` | `str` | ✓ | `—` |
| `address` | `str` | ✓ | `—` |
| `content_summary` | `str` | ✓ | `—` |


### `_Delta` — [`tests/test_musehub_proposals_touched_symbols.py`](tests/test_musehub_proposals_touched_symbols.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `ops` | `list[_DeltaOp]` | ✓ | `—` |


### `_DeltaOp` — [`tests/test_musehub_proposals_touched_symbols.py`](tests/test_musehub_proposals_touched_symbols.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `address` | `str` | ✓ | `—` |
| `child_ops` | `list[_ChildOp]` | ✓ | `—` |


### `_S3GetResponse` — [`tests/test_storage_backends_section33.py`](tests/test_storage_backends_section33.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `Body` | `MagicMock` | ✓ | `—` |


### `_DeltaObjectPayload` — [`tests/test_wire_compression.py`](tests/test_wire_compression.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `content` | `bytes` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `encoding` | `str` | ✓ | `—` |
| `base_id` | `str` | ✓ | `—` |


### `_RawObjectPayload` — [`tests/test_wire_compression.py`](tests/test_wire_compression.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `content` | `bytes` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `encoding` | `str` | ✓ | `—` |


### `_ZlibObjectPayload` — [`tests/test_wire_compression.py`](tests/test_wire_compression.py)

**Bases:** `TypedDict`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `content` | `bytes` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `encoding` | `str` | ✓ | `—` |


## Pydantic Models

### `CreateIdentityRequest` — [`musehub/api/routes/api/identities.py`](musehub/api/routes/api/identities.py)

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `handle` | `str` | ✓ | `—` |
| `identity_type` | `str` |  | `'human'` |
| `display_name` | `str | None` |  | `None` |
| `bio` | `str | None` |  | `None` |
| `avatar_url` | `str | None` |  | `None` |
| `website_url` | `str | None` |  | `None` |
| `email` | `str | None` |  | `None` |
| `agent_model` | `str | None` |  | `None` |
| `agent_capabilities` | `list[str]` |  | `[]` |


### `UpdateIdentityRequest` — [`musehub/api/routes/api/identities.py`](musehub/api/routes/api/identities.py)

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `display_name` | `str | None` |  | `None` |
| `bio` | `str | None` |  | `None` |
| `avatar_url` | `str | None` |  | `None` |
| `website_url` | `str | None` |  | `None` |
| `email` | `str | None` |  | `None` |
| `agent_model` | `str | None` |  | `None` |
| `agent_capabilities` | `list[str] | None` |  | `None` |


### `CollaboratorInviteRequest` — [`musehub/api/routes/musehub/collaborators.py`](musehub/api/routes/musehub/collaborators.py)

Body for POST /collaborators — invite a new collaborator.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `handle` | `str` | ✓ | `—` |
| `permission` | `Permission` | ✓ | `Field(Permission.write, description='Initial permission level (read | write | admin)')` |


### `CollaboratorListResponse` — [`musehub/api/routes/musehub/collaborators.py`](musehub/api/routes/musehub/collaborators.py)

Paginated list of repository collaborators.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `collaborators` | `list[CollaboratorResponse]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `CollaboratorPermissionUpdate` — [`musehub/api/routes/musehub/collaborators.py`](musehub/api/routes/musehub/collaborators.py)

Body for PUT /collaborators/{handle}/permission — update permission.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `permission` | `Permission` | ✓ | `—` |


### `CollaboratorResponse` — [`musehub/api/routes/musehub/collaborators.py`](musehub/api/routes/musehub/collaborators.py)

A single collaborator entry.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `collaborator_id` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `handle` | `str` | ✓ | `—` |
| `permission` | `str` | ✓ | `—` |
| `invited_by` | `str | None` |  | `Field(None, description='Handle of the inviter (null if added programmatically)')` |


### `RegisterDomainRequest` — [`musehub/api/routes/musehub/domains.py`](musehub/api/routes/musehub/domains.py)

Body for registering a new domain plugin.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `author_slug` | `str` | ✓ | `—` |
| `slug` | `str` | ✓ | `—` |
| `display_name` | `str` | ✓ | `—` |
| `description` | `str` |  | `''` |
| `capabilities` | `dict[str, PydanticJson]` | ✓ | `—` |
| `viewer_type` | `str` |  | `'generic'` |
| `version` | `str` |  | `'1.0.0'` |


### `AssignLabelsRequest` — [`musehub/api/routes/musehub/labels.py`](musehub/api/routes/musehub/labels.py)

Body for bulk-assigning labels to an issue or proposal.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `label_ids` | `list[str]` | ✓ | `—` |


### `LabelCreate` — [`musehub/api/routes/musehub/labels.py`](musehub/api/routes/musehub/labels.py)

Payload for creating a new label.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `color` | `str` | ✓ | `—` |
| `description` | `str | None` |  | `Field(None, max_length=200, description='Optional human-readable description')` |


### `LabelListResponse` — [`musehub/api/routes/musehub/labels.py`](musehub/api/routes/musehub/labels.py)

Paginated list of labels.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `items` | `list[LabelResponse]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `LabelResponse` — [`musehub/api/routes/musehub/labels.py`](musehub/api/routes/musehub/labels.py)

Public representation of a label.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `label_id` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `color` | `str` | ✓ | `—` |
| `description` | `str | None` |  | `None` |


### `LabelUpdate` — [`musehub/api/routes/musehub/labels.py`](musehub/api/routes/musehub/labels.py)

Payload for updating an existing label (all fields optional).

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str | None` |  | `Field(None, min_length=1, max_length=50)` |
| `color` | `str | None` |  | `Field(None, pattern='^#[0-9a-fA-F]{6}$')` |
| `description` | `str | None` |  | `Field(None, max_length=200)` |


### `SetTopicsRequest` — [`musehub/api/routes/musehub/topics.py`](musehub/api/routes/musehub/topics.py)

Body for POST /repos/{repo_id}/topics.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `topics` | `list[str]` | ✓ | `—` |


### `SetTopicsResponse` — [`musehub/api/routes/musehub/topics.py`](musehub/api/routes/musehub/topics.py)

Result of POST /repos/{repo_id}/topics.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `topics` | `list[str]` | ✓ | `—` |


### `TopicItem` — [`musehub/api/routes/musehub/topics.py`](musehub/api/routes/musehub/topics.py)

A single topic entry returned by GET /topics.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `repo_count` | `int` | ✓ | `—` |


### `TopicListResponse` — [`musehub/api/routes/musehub/topics.py`](musehub/api/routes/musehub/topics.py)

Response for GET /musehub/topics.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `topics` | `list[TopicItem]` | ✓ | `—` |


### `TopicReposResponse` — [`musehub/api/routes/musehub/topics.py`](musehub/api/routes/musehub/topics.py)

Cursor-paginated repo list for GET /musehub/topics/{tag}/repos.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tag` | `str` | ✓ | `—` |
| `repos` | `list[ExploreRepoResult]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `Field(None, alias='nextCursor')` |


### `CuratedGroup` — [`musehub/api/routes/musehub/ui_topics.py`](musehub/api/routes/musehub/ui_topics.py)

A labelled set of topic items surfaced on the topics index page.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `label` | `str` | ✓ | `—` |
| `topics` | `list[TopicItem]` | ✓ | `—` |


### `TopicsIndexResponse` — [`musehub/api/routes/musehub/ui_topics.py`](musehub/api/routes/musehub/ui_topics.py)

JSON response for GET /topics.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `all_topics` | `list[TopicItem]` | ✓ | `—` |
| `curated_groups` | `list[CuratedGroup]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `CreateProfileBody` — [`musehub/api/routes/musehub/users.py`](musehub/api/routes/musehub/users.py)

Body for POST /api/musehub/users — create a public profile for the authenticated user.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `username` | `str` | ✓ | `—` |
| `bio` | `str | None` |  | `Field(None, max_length=500, description='Short bio (Markdown supported)')` |
| `avatar_url` | `str | None` |  | `Field(None, max_length=2048, description='Avatar image URL')` |


### `UserCardResponse` — [`musehub/api/routes/musehub/users.py`](musehub/api/routes/musehub/users.py)

Compact user card returned by followers-list and following-list endpoints.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `username` | `str` | ✓ | `—` |
| `bio` | `str | None` |  | `None` |
| `avatar_url` | `str | None` |  | `None` |


### `_WorkerObjectEntry` — [`musehub/api/routes/wire.py`](musehub/api/routes/wire.py)

One object stored by the Cloudflare Worker.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `path` | `str` |  | `''` |
| `size` | `int` |  | `0` |


### `_WorkerRegisterRequest` — [`musehub/api/routes/wire.py`](musehub/api/routes/wire.py)

Body sent by the Cloudflare mpack-receiver Worker.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `owner` | `str` | ✓ | `—` |
| `slug` | `str` | ✓ | `—` |
| `objects` | `list[_WorkerObjectEntry]` | ✓ | `—` |


### `Settings` — [`musehub/config.py`](musehub/config.py)

Application settings loaded from environment variables.

**Bases:** `BaseSettings`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `app_name` | `str` |  | `'Muse'` |
| `app_version` | `str` |  | `_app_version_from_package()` |
| `debug` | `bool` |  | `False` |
| `muse_env` | `str` |  | `'production'` |
| `public_url` | `str` |  | `'https://musehub.ai'` |
| `allowed_hosts` | `list[str]` |  | `['musehub.ai', 'staging.musehub.ai', 'localhost:1337']` |
| `host` | `str` |  | `'0.0.0.0'` |
| `port` | `int` |  | `10001` |
| `database_url` | `str | None` |  | `None` |
| `db_password` | `str | None` |  | `None` |
| `cors_origins` | `list[str]` |  | `[]` |
| `aws_region` | `str` |  | `'eu-west-1'` |
| `aws_s3_asset_bucket` | `str | None` |  | `None` |
| `aws_cloudfront_domain` | `str | None` |  | `None` |
| `presign_expiry_seconds` | `int` |  | `1800` |
| `r2_bucket` | `str | None` |  | `None` |
| `r2_endpoint` | `str | None` |  | `None` |
| `r2_access_key_id` | `str | None` |  | `None` |
| `r2_secret_access_key` | `str | None` |  | `None` |
| `r2_region` | `str` |  | `'auto'` |
| `asset_rate_limit_per_device` | `str` |  | `'30/minute'` |
| `asset_rate_limit_per_ip` | `str` |  | `'120/minute'` |
| `mcp_rate_limit_human` | `str` |  | `'60/minute'` |
| `mcp_rate_limit_agent` | `str` |  | `'600/minute'` |
| `mcp_rate_limit_anonymous` | `str` |  | `'20/minute'` |
| `db_pool_timeout` | `int` |  | `30` |
| `slow_query_threshold_ms` | `int` |  | `100` |
| `mcp_push_per_user_quota_bytes` | `int` |  | `10 * 1024 * 1024 * 1024` |
| `per_repo_quota_bytes` | `int` |  | `5 * 1024 * 1024 * 1024` |
| `object_retention_days` | `int` |  | `30` |
| `muse_mcp_url` | `str | None` |  | `None` |
| `mcp_token` | `str | None` |  | `None` |
| `musehub_objects_dir` | `str` |  | `'/data/musehub/objects'` |
| `musehub_releases_dir` | `str` |  | `'/data/releases'` |
| `webhook_secret_key` | `str | None` |  | `None` |
| `require_signed_commits` | `bool` |  | `False` |
| `trusted_agent_ids` | `list[str]` |  | `[]` |
| `worker_internal_key` | `str | None` |  | `None` |
| `pack_worker_url` | `str | None` |  | `None` |


### `CamelModel` — [`musehub/models/base.py`](musehub/models/base.py)

Base model that serializes to camelCase on the wire.

**Bases:** `BaseModel`

_No annotated fields._


### `CoordPollRequest` — [`musehub/models/coord.py`](musehub/models/coord.py)

Request body for ``POST /{owner}/{slug}/coord/pull``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `since_id` | `int` |  | `0` |
| `kinds` | `list[str]` |  | `(factory)` |
| `limit` | `int` |  | `500` |


### `CoordPullResponse` — [`musehub/models/coord.py`](musehub/models/coord.py)

Response for ``POST /{owner}/{slug}/coord/pull``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `records` | `list[CoordRecordOut]` | ✓ | `—` |
| `cursor` | `int` | ✓ | `—` |


### `CoordPushRequest` — [`musehub/models/coord.py`](musehub/models/coord.py)

Request body for ``POST /{owner}/{slug}/coord/push``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `records` | `list[CoordRecordIn]` | ✓ | `—` |


### `CoordPushResponse` — [`musehub/models/coord.py`](musehub/models/coord.py)

Response for ``POST /{owner}/{slug}/coord/push``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `inserted` | `int` | ✓ | `—` |
| `skipped` | `int` | ✓ | `—` |


### `CoordRecordIn` — [`musehub/models/coord.py`](musehub/models/coord.py)

A single coordination record to be pushed to MuseHub.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `kind` | `str` | ✓ | `—` |
| `record_uuid` | `str` | ✓ | `—` |
| `run_id` | `str` |  | `''` |
| `payload` | `PydanticJson` | ✓ | `—` |
| `expires_at` | `datetime | None` |  | `None` |


### `CoordRecordOut` — [`musehub/models/coord.py`](musehub/models/coord.py)

A coordination record returned from MuseHub (pull or watch).

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `int` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `kind` | `str` | ✓ | `—` |
| `record_uuid` | `str` | ✓ | `—` |
| `run_id` | `str` | ✓ | `—` |
| `payload` | `PydanticJson` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |
| `expires_at` | `datetime | None` |  | `None` |


### `ActivityEventResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single repo-level activity event.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `event_id` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `event_type` | `str` | ✓ | `—` |
| `actor` | `str` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `metadata` | `dict[str, PydanticJson]` |  | `(factory)` |
| `created_at` | `datetime` | ✓ | `—` |


### `AgentCardEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single agent that has committed to repos owned by a human identity.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `agent_id` | `str` | ✓ | `—` |
| `model_id` | `str | None` |  | `None` |
| `model_label` | `str` | ✓ | `—` |
| `commit_count` | `int` | ✓ | `—` |
| `repo_count` | `int` | ✓ | `—` |
| `last_seen` | `datetime` | ✓ | `—` |


### `AgentFleetResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

All agents deployed by a given handle, sorted by commit volume.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `handle` | `str` | ✓ | `—` |
| `agents` | `list[AgentCardEntry]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `ApiChangeSummaryResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A public-API symbol that was added, removed, or modified.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `address` | `str` | ✓ | `—` |
| `language` | `str` |  | `''` |
| `kind` | `str` |  | `''` |
| `change` | `str` |  | `''` |


### `BlobMetaResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single file (blob) in the Muse tree browser.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `filename` | `str` | ✓ | `—` |
| `size_bytes` | `int` | ✓ | `—` |
| `sha` | `str` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |
| `raw_url` | `str` | ✓ | `—` |
| `file_type` | `str` | ✓ | `—` |
| `content_text` | `str | None` |  | `Field(None, description='UTF-8 content for JSON/XML files up to 256 KB; None for binary or oversized files')` |


### `BranchDetailListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

List of branches with detail — used by the branch list page and its JSON variant.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `branches` | `list[BranchDetailResponse]` | ✓ | `—` |
| `default_branch` | `str` |  | `Field('main', description="Name of the repo's default branch")` |


### `BranchDetailResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Branch pointer enriched with ahead/behind counts and musical divergence.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `branch_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `head_commit_id` | `str | None` |  | `Field(None, description='HEAD commit ID; null for an empty branch')` |
| `is_default` | `bool` |  | `Field(False, description="True when this is the repo's default branch")` |
| `ahead_count` | `int` |  | `Field(0, ge=0, description='Commits on this branch not yet on the default branch')` |
| `behind_count` | `int` |  | `Field(0, ge=0, description='Commits on the default branch not yet on this branch')` |
| `divergence` | `BranchDivergenceScores` |  | `(factory)` |


### `BranchDivergenceScores` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Placeholder musical divergence scores between a branch and the default branch.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `melodic` | `float | None` |  | `Field(None, description='Melodic divergence (0–1)')` |
| `harmonic` | `float | None` |  | `Field(None, description='Harmonic divergence (0–1)')` |
| `rhythmic` | `float | None` |  | `Field(None, description='Rhythmic divergence (0–1)')` |
| `structural` | `float | None` |  | `Field(None, description='Structural divergence (0–1)')` |
| `dynamic` | `float | None` |  | `Field(None, description='Dynamic divergence (0–1)')` |


### `BranchListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Paginated list of branches.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `branches` | `list[BranchResponse]` | ✓ | `—` |


### `BranchResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a branch pointer.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `branch_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `head_commit_id` | `str | None` |  | `Field(None, description='HEAD commit ID; null for an empty branch', examples=['a3f8c1d2e4b5'])` |


### `ChangelogEntryResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single changelog entry auto-generated from commit metadata.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `sem_ver_bump` | `str` |  | `''` |
| `breaking_changes` | `list[str]` |  | `(factory)` |
| `author` | `str` |  | `''` |
| `timestamp` | `str` |  | `''` |


### `CollaboratorAccessResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Response for the collaborator access-check endpoint.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `username` | `str` | ✓ | `—` |
| `permission` | `str` | ✓ | `—` |
| `accepted_at` | `datetime | None` |  | `Field(None, description='UTC timestamp when the collaborator accepted the invitation; null for owners')` |


### `CommitDiffDimensionScore` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Per-dimension change score between a commit and its parent.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `dimension` | `str` | ✓ | `—` |
| `score` | `float` | ✓ | `—` |
| `label` | `str` | ✓ | `—` |
| `color` | `str` | ✓ | `—` |


### `CommitDiffSummaryResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Multi-dimensional diff summary between a commit and its parent.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `parent_id` | `str | None` |  | `Field(None, description='Parent commit ID; None for root commits')` |
| `dimensions` | `list[CommitDiffDimensionScore]` | ✓ | `—` |
| `overall_score` | `float` | ✓ | `—` |


### `CommitInput` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single commit record transferred in a push payload.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `parent_ids` | `list[str]` |  | `(factory)` |
| `message` | `str` | ✓ | `—` |
| `snapshot_id` | `str | None` |  | `None` |
| `timestamp` | `datetime` | ✓ | `—` |
| `author` | `str | None` |  | `None` |


### `CommitListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of commits (newest first).

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commits` | `list[CommitResponse]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `CommitResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a pushed commit.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `parent_ids` | `list[str]` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `snapshot_id` | `str | None` |  | `None` |


### `CompareResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Multi-dimensional musical comparison between two refs in a MuseHub repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `base_ref` | `str` | ✓ | `—` |
| `head_ref` | `str` | ✓ | `—` |
| `common_ancestor` | `str | None` |  | `None` |
| `dimensions` | `list[DivergenceDimensionResponse]` | ✓ | `—` |
| `overall_score` | `float` | ✓ | `—` |
| `commits` | `list[CommitResponse]` | ✓ | `—` |
| `emotion_diff` | `EmotionDiffResponse` | ✓ | `—` |
| `create_proposal_url` | `str` | ✓ | `—` |


### `ContributionDay` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single day in the contribution heatmap.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `date` | `str` | ✓ | `—` |
| `count` | `int` | ✓ | `—` |


### `ContributorCredits` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single contributor's credit record.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `author` | `str` | ✓ | `—` |
| `session_count` | `int` | ✓ | `—` |
| `contribution_types` | `list[str]` | ✓ | `—` |
| `first_active` | `datetime` | ✓ | `—` |
| `last_active` | `datetime` | ✓ | `—` |


### `CreateRepoRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos — creation wizard.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `owner` | `str` | ✓ | `—` |
| `visibility` | `str` |  | `Field('public')` |
| `description` | `str` |  | `Field('', description='Short description shown on the explore page')` |
| `tags` | `list[str]` |  | `(factory)` |
| `license` | `str | None` |  | `Field(None, max_length=100, description="License identifier (e.g. 'CC BY 4.0', 'MIT')")` |
| `topics` | `list[str]` |  | `(factory)` |
| `initialize` | `bool` |  | `Field(True, description='When true, create an initial empty commit + default branch so the repo is immediately browsable')` |
| `default_branch` | `str` |  | `Field('main', min_length=1, max_length=255, description='Name of the default branch created when initialize=true')` |
| `template_repo_id` | `str | None` |  | `Field(None, description='UUID of a public repo to copy topics/description/labels from; must be public')` |
| `domain_scoped_id` | `str | None` |  | `Field(None, description="Scoped domain ID (e.g. '@gabriel/midi') — always set when created via /domains/@author/slug/new")` |


### `CreditsResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of the full credits roll for a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `contributors` | `list[ContributorCredits]` | ✓ | `—` |
| `sort` | `str` | ✓ | `—` |
| `total_contributors` | `int` | ✓ | `—` |


### `DagEdge` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A directed edge in the commit DAG.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `source` | `str` | ✓ | `—` |
| `target` | `str` | ✓ | `—` |


### `DagGraphResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Topologically sorted commit graph for a MuseHub repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `nodes` | `list[DagNode]` | ✓ | `—` |
| `edges` | `list[DagEdge]` | ✓ | `—` |
| `head_commit_id` | `str | None` |  | `None` |


### `DagNode` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single commit node in the repo's directed acyclic graph.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `parent_ids` | `list[str]` | ✓ | `—` |
| `is_head` | `bool` |  | `False` |
| `branch_labels` | `list[str]` |  | `(factory)` |
| `tag_labels` | `list[str]` |  | `(factory)` |
| `commit_type` | `str` |  | `''` |
| `sem_ver_bump` | `str` |  | `'none'` |
| `is_breaking` | `bool` |  | `False` |
| `is_agent` | `bool` |  | `False` |
| `sym_added` | `int` |  | `0` |
| `sym_removed` | `int` |  | `0` |


### `DivergenceDimensionResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of divergence scores for a single musical dimension.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `dimension` | `str` | ✓ | `—` |
| `level` | `str` | ✓ | `—` |
| `score` | `float` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `branch_a_commits` | `int` | ✓ | `—` |
| `branch_b_commits` | `int` | ✓ | `—` |


### `DivergenceResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Full musical divergence report between two MuseHub branches.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `branch_a` | `str` | ✓ | `—` |
| `branch_b` | `str` | ✓ | `—` |
| `common_ancestor` | `str | None` | ✓ | `—` |
| `dimensions` | `list[DivergenceDimensionResponse]` | ✓ | `—` |
| `overall_score` | `float` | ✓ | `—` |


### `EmotionDiffResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Delta between the emotional character of base and head refs.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `energy_delta` | `float` | ✓ | `—` |
| `valence_delta` | `float` | ✓ | `—` |
| `tension_delta` | `float` | ✓ | `—` |
| `darkness_delta` | `float` | ✓ | `—` |
| `base_energy` | `float` | ✓ | `—` |
| `base_valence` | `float` | ✓ | `—` |
| `base_tension` | `float` | ✓ | `—` |
| `base_darkness` | `float` | ✓ | `—` |
| `head_energy` | `float` | ✓ | `—` |
| `head_valence` | `float` | ✓ | `—` |
| `head_tension` | `float` | ✓ | `—` |
| `head_darkness` | `float` | ✓ | `—` |


### `ExploreRepoResult` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A public repo card shown on the explore/discover page.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `owner` | `str` | ✓ | `—` |
| `slug` | `str` | ✓ | `—` |
| `owner_user_id` | `str` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `tags` | `list[str]` | ✓ | `—` |
| `star_count` | `int` | ✓ | `—` |
| `commit_count` | `int` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |


### `ExploreResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated response from GET /api/discover/repos.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repos` | `list[ExploreRepoResult]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `None` |


### `FileHotspotResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A file and how many times it was touched across the release's commits.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `file_path` | `str` | ✓ | `—` |
| `change_count` | `int` |  | `0` |
| `language` | `str` |  | `''` |


### `ForkNetworkNode` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single node in the fork network tree.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `owner` | `str` | ✓ | `—` |
| `repo_slug` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `divergence_commits` | `int` | ✓ | `—` |
| `forked_by` | `str` | ✓ | `—` |
| `forked_at` | `datetime | None` |  | `Field(None, description='Timestamp when the fork was created (None for root repo)')` |
| `children` | `list['ForkNetworkNode']` |  | `(factory)` |


### `ForkNetworkResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Fork network graph for a repo — root with recursive children.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `root` | `ForkNetworkNode` | ✓ | `—` |
| `total_forks` | `int` | ✓ | `—` |


### `ForkRepoRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Request body for ``POST /api/repos/{repo_id}/fork``.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str | None` |  | `Field(None, description="Name for the new fork repo.  Defaults to the source repo's name.  A unique slug is auto-generated; use this to disambiguate when you already own a repo with the same slug as the source.")` |
| `description` | `str | None` |  | `Field(None, description="Description for the fork.  Defaults to the source repo's description prefixed with 'Fork of {owner}/{slug}: '.")` |
| `visibility` | `Literal['public', 'private'] | None` |  | `Field(None, description="Visibility for the fork repo.  Defaults to 'public'.")` |


### `GlobalSearchCommitMatch` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single commit that matched the search query in a cross-repo search.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `repo_name` | `str` | ✓ | `—` |
| `repo_owner` | `str` | ✓ | `—` |
| `repo_visibility` | `str` | ✓ | `—` |
| `audio_object_id` | `str | None` |  | `None` |


### `GlobalSearchRepoGroup` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

All matching commits for a single repo, with repo-level metadata.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `repo_name` | `str` | ✓ | `—` |
| `repo_owner` | `str` | ✓ | `—` |
| `repo_slug` | `str` | ✓ | `—` |
| `repo_visibility` | `str` | ✓ | `—` |
| `matches` | `list[GlobalSearchCommitMatch]` | ✓ | `—` |
| `total_matches` | `int` | ✓ | `—` |


### `GlobalSearchResult` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Top-level response for GET /search?q={query}.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `query` | `str` | ✓ | `—` |
| `mode` | `str` | ✓ | `—` |
| `groups` | `list[GlobalSearchRepoGroup]` | ✓ | `—` |
| `total_repos_searched` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `None` |


### `GrooveCheckResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Rhythmic consistency dashboard data for a commit range in a MuseHub repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_range` | `str` | ✓ | `—` |
| `threshold` | `float` | ✓ | `—` |
| `total_commits` | `int` | ✓ | `—` |
| `flagged_commits` | `int` | ✓ | `—` |
| `worst_commit` | `str` | ✓ | `—` |
| `entries` | `list[GrooveCommitEntry]` |  | `(factory)` |


### `GrooveCommitEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Per-commit groove metrics within a groove-check analysis window.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit` | `str` | ✓ | `—` |
| `groove_score` | `float` | ✓ | `—` |
| `drift_delta` | `float` | ✓ | `—` |
| `status` | `str` | ✓ | `—` |
| `track` | `str` | ✓ | `—` |
| `section` | `str` | ✓ | `—` |
| `midi_files` | `int` | ✓ | `—` |


### `IssueAssignRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/issues/{number}/assign.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `assignee` | `str | None` |  | `Field(None, description='Display name or user ID to assign; null to unassign', examples=['miles_davis'])` |


### `IssueCommentCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/issues/{number}/comments.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `body` | `str` | ✓ | `—` |
| `parent_id` | `str | None` |  | `Field(None, description='Parent comment UUID for threaded replies; omit for top-level comments')` |


### `IssueCommentListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated discussion on a single issue.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `comments` | `list[IssueCommentResponse]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `IssueCommentResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single issue comment.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `comment_id` | `str` | ✓ | `—` |
| `issue_id` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `body` | `str` | ✓ | `—` |
| `parent_id` | `str | None` |  | `Field(None, description='Parent comment UUID; null for top-level comments')` |
| `is_deleted` | `bool` |  | `Field(False, description='True when the comment has been soft-deleted')` |
| `created_at` | `datetime` | ✓ | `—` |
| `updated_at` | `datetime` | ✓ | `—` |


### `IssueCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/issues.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `title` | `str` | ✓ | `—` |
| `body` | `str` |  | `Field('', max_length=50000, description='Issue description (Markdown)', examples=["The Dm→Am→E7→Am progression in the verse doesn't resolve — suggest Dm→G7→CMaj7."])` |
| `labels` | `list[_Label]` |  | `(factory)` |
| `symbol_anchors` | `list[_SymbolAnchor]` |  | `(factory)` |
| `commit_anchors` | `list[_CommitAnchor]` |  | `(factory)` |
| `agent_id` | `str` |  | `Field('', max_length=255, description="Agent identifier when filed by an AI agent (e.g. 'agentception-worker-42')")` |
| `model_id` | `str` |  | `Field('', max_length=255, description="Model identifier when filed by an AI agent (e.g. 'claude-sonnet-4-6')")` |


### `IssueLabelAssignRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/issues/{number}/labels.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `labels` | `list[_Label]` | ✓ | `—` |


### `IssueListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of issues for a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `issues` | `list[IssueResponse]` | ✓ | `—` |
| `total` | `int` |  | `Field(0, ge=0, description='Total matching issues across all pages')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `IssueResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a MuseHub issue.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `issue_id` | `str` | ✓ | `—` |
| `number` | `int` | ✓ | `—` |
| `title` | `str` | ✓ | `—` |
| `body` | `str` | ✓ | `—` |
| `state` | `str` | ✓ | `—` |
| `labels` | `list[str]` | ✓ | `—` |
| `symbol_anchors` | `list[str]` |  | `(factory)` |
| `commit_anchors` | `list[str]` |  | `(factory)` |
| `author` | `str` |  | `''` |
| `assignee` | `str | None` |  | `Field(None, description='Display name of the assigned collaborator')` |
| `agent_id` | `str` |  | `Field('', description='Agent identifier if filed by an AI agent')` |
| `model_id` | `str` |  | `Field('', description='Model identifier if filed by an AI agent')` |
| `created_at` | `datetime` | ✓ | `—` |
| `updated_at` | `datetime | None` |  | `Field(None, description='Last update timestamp (ISO-8601 UTC)')` |
| `comment_count` | `int` |  | `Field(0, description='Number of non-deleted comments on this issue')` |


### `IssueUpdate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for PATCH /musehub/repos/{repo_id}/issues/{number} — partial update.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `title` | `str | None` |  | `Field(None, min_length=1, max_length=500, description='Updated issue title')` |
| `body` | `str | None` |  | `Field(None, max_length=50000, description='Updated issue body (Markdown)')` |
| `labels` | `list[_Label] | None` |  | `Field(None, max_length=20, description='Replacement label list (max 20, each max 100 chars)')` |
| `symbol_anchors` | `list[_SymbolAnchor] | None` |  | `Field(None, max_length=50, description='Replacement symbol anchor list (max 50, each max 500 chars)')` |
| `commit_anchors` | `list[_CommitAnchor] | None` |  | `Field(None, max_length=50, description='Replacement commit anchor list (max 50, each max 64 chars)')` |
| `agent_id` | `str | None` |  | `Field(None, max_length=255, description='Agent identifier (set when agent-filed)')` |
| `model_id` | `str | None` |  | `Field(None, max_length=255, description='Model identifier (set when agent-filed)')` |


### `LanguageStatResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

File and symbol counts for a single programming language.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `language` | `str` | ✓ | `—` |
| `files` | `int` |  | `0` |
| `symbols` | `int` |  | `0` |


### `MuseHubContextCommitInfo` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Minimal commit metadata included in a MuseHub context document.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |


### `MuseHubContextHistoryEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single ancestor commit in the evolutionary history of the composition.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `active_tracks` | `list[str]` | ✓ | `—` |


### `MuseHubContextMusicalState` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

State at the target commit, derived from stored artifact paths.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `active_tracks` | `list[str]` | ✓ | `—` |


### `MuseHubContextResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Human-readable and agent-consumable musical context document for a commit.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `current_branch` | `str` | ✓ | `—` |
| `head_commit` | `MuseHubContextCommitInfo` | ✓ | `—` |
| `musical_state` | `MuseHubContextMusicalState` | ✓ | `—` |
| `history` | `list[MuseHubContextHistoryEntry]` | ✓ | `—` |
| `missing_elements` | `list[str]` | ✓ | `—` |
| `suggestions` | `StrDict` | ✓ | `—` |


### `ObjectInput` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A binary object transferred in a push payload.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `content_b64` | `str` | ✓ | `—` |


### `ObjectMetaListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

List of artifact metadata for a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `objects` | `list[ObjectMetaResponse]` | ✓ | `—` |


### `ObjectMetaResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a stored artifact -- metadata only, no content bytes.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `size_bytes` | `int` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |


### `ObjectResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A binary object returned in a pull response.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `content_b64` | `str` | ✓ | `—` |


### `ProfileRepoSummary` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Compact repo summary shown on a user's profile page.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `owner` | `str` | ✓ | `—` |
| `slug` | `str` | ✓ | `—` |
| `visibility` | `str` | ✓ | `—` |
| `star_count` | `int` | ✓ | `—` |
| `last_activity_at` | `datetime | None` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |


### `ProfileResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Full wire representation of a MuseHub user profile.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `user_id` | `str` | ✓ | `—` |
| `username` | `str` | ✓ | `—` |
| `display_name` | `str | None` |  | `None` |
| `bio` | `str | None` |  | `None` |
| `avatar_url` | `str | None` |  | `None` |
| `location` | `str | None` |  | `None` |
| `website_url` | `str | None` |  | `None` |
| `social_url` | `str | None` |  | `None` |
| `is_verified` | `bool` |  | `False` |
| `cc_license` | `str | None` |  | `None` |
| `pinned_repo_ids` | `list[str]` | ✓ | `—` |
| `repos` | `list[ProfileRepoSummary]` | ✓ | `—` |
| `contribution_graph` | `list[ContributionDay]` | ✓ | `—` |
| `session_credits` | `int` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |
| `updated_at` | `datetime` | ✓ | `—` |


### `ProfileUpdateRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for PUT /api/users/{username}.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `display_name` | `str | None` |  | `Field(None, max_length=255, description='Human-readable display name')` |
| `bio` | `str | None` |  | `Field(None, max_length=500, description='Short bio (Markdown supported)')` |
| `avatar_url` | `str | None` |  | `Field(None, max_length=2048, description='Avatar image URL')` |
| `location` | `str | None` |  | `Field(None, max_length=255, description='City or region')` |
| `website_url` | `str | None` |  | `Field(None, max_length=2048, description='Personal website or project URL')` |
| `social_url` | `str | None` |  | `Field(None, max_length=2048, description='Full URL to a social profile')` |
| `pinned_repo_ids` | `list[str] | None` |  | `Field(None, max_length=6, description='Up to 6 repo_ids to pin on the profile page')` |


### `ProposalCommentCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/proposals/{proposal_id}/comments.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `body` | `str` | ✓ | `—` |
| `target_type` | `str` |  | `Field('general', pattern='^(general|track|region|note)$', description='Comment target granularity', examples=['region'])` |
| `target_track` | `str | None` |  | `Field(None, max_length=255, description='Instrument track name for track/region/note targets', examples=['bass'])` |
| `target_beat_start` | `float | None` |  | `Field(None, ge=0, description='First beat of the targeted region (inclusive)', examples=[16.0])` |
| `target_beat_end` | `float | None` |  | `Field(None, ge=0, description='Last beat of the targeted region (exclusive)', examples=[24.0])` |
| `target_note_pitch` | `int | None` |  | `Field(None, ge=0, le=127, description='MIDI pitch (0-127) for note-level targets', examples=[46])` |
| `parent_comment_id` | `str | None` |  | `Field(None, description='ID of the parent comment when creating a threaded reply', examples=['a1b2c3d4-e5f6-7890-abcd-ef1234567890'])` |
| `symbol_address` | `str | None` |  | `Field(None, max_length=512, description="Symbol address to anchor this comment to (e.g. 'auth.py::AuthService.login'). Binds the comment to a specific named symbol in the Symbol Delta. Takes precedence over target_type for code-domain proposals.", examples=['core/engine.py::Engine.process'])` |


### `ProposalCommentListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of review comments for a merge proposal.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `comments` | `list[ProposalCommentResponse]` |  | `(factory)` |
| `total` | `int` |  | `Field(0, ge=0, description='Total number of comments (all levels)')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `ProposalCommentResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single proposal review comment.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `comment_id` | `str` | ✓ | `—` |
| `proposal_id` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `body` | `str` | ✓ | `—` |
| `target_type` | `str` | ✓ | `—` |
| `target_track` | `str | None` |  | `Field(None, description='Instrument track name when targeted')` |
| `target_beat_start` | `float | None` |  | `Field(None, description='Region start beat (inclusive)')` |
| `target_beat_end` | `float | None` |  | `Field(None, description='Region end beat (exclusive)')` |
| `target_note_pitch` | `int | None` |  | `Field(None, description='MIDI pitch for note-level targets')` |
| `parent_comment_id` | `str | None` |  | `Field(None, description='Parent comment ID for threaded replies')` |
| `symbol_address` | `str | None` |  | `Field(None, description='Symbol address anchor, if set')` |
| `created_at` | `datetime` | ✓ | `—` |
| `replies` | `list[ProposalCommentResponse]` |  | `(factory)` |


### `ProposalCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/proposals.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `title` | `str` | ✓ | `—` |
| `from_branch` | `str` | ✓ | `—` |
| `to_branch` | `str` | ✓ | `—` |
| `body` | `str` |  | `Field('', max_length=10000, description='Merge proposal description (Markdown)', examples=['This branch adds an 8-bar bossa nova bridge in 5/4 with guitar and upright bass.'])` |


### `ProposalDiffDimensionScore` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Per-dimension musical change score between the from_branch and to_branch of a merge proposal.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `dimension` | `str` | ✓ | `—` |
| `score` | `float` | ✓ | `—` |
| `level` | `str` | ✓ | `—` |
| `delta_label` | `str` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `from_branch_commits` | `int` | ✓ | `—` |
| `to_branch_commits` | `int` | ✓ | `—` |


### `ProposalDiffResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Musical diff between the from_branch and to_branch of a merge proposal.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `proposal_id` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `from_branch` | `str` | ✓ | `—` |
| `to_branch` | `str` | ✓ | `—` |
| `dimensions` | `list[ProposalDiffDimensionScore]` | ✓ | `—` |
| `overall_score` | `float | None` |  | `Field(None, ge=0.0, le=1.0, description='Mean of all five dimension scores; None for code-domain proposals')` |
| `common_ancestor` | `str | None` |  | `Field(None, description='Merge-base commit ID; None if no common ancestor')` |
| `affected_sections` | `list[str]` |  | `(factory)` |


### `ProposalListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of merge proposals for a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `proposals` | `list[ProposalResponse]` | ✓ | `—` |
| `total` | `int` |  | `Field(0, ge=0, description='Total matching merge proposals across all pages')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `ProposalMergeRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/proposals/{proposal_id}/merge.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `merge_strategy` | `str` |  | `Field('merge_commit', pattern='^(merge_commit|squash|rebase)$', description="Merge strategy: 'merge_commit' (default), 'squash', or 'rebase'")` |


### `ProposalMergeResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Confirmation that a merge proposal was merged.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `merged` | `bool` | ✓ | `—` |
| `merge_commit_id` | `str` | ✓ | `—` |


### `ProposalResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a MuseHub merge proposal.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `proposal_id` | `str` | ✓ | `—` |
| `proposal_number` | `int` |  | `Field(0, description='Per-repo sequential proposal number (1-based)')` |
| `title` | `str` | ✓ | `—` |
| `body` | `str` | ✓ | `—` |
| `state` | `str` | ✓ | `—` |
| `from_branch` | `str` | ✓ | `—` |
| `to_branch` | `str` | ✓ | `—` |
| `merge_commit_id` | `str | None` |  | `None` |
| `merged_at` | `datetime | None` |  | `None` |
| `author` | `str` |  | `''` |
| `created_at` | `datetime` | ✓ | `—` |


### `ProposalReviewCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/proposals/{proposal_id}/reviews.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `event` | `str` | ✓ | `—` |
| `body` | `str` |  | `Field('', max_length=10000, description="Review body (Markdown). Required when event='request_changes'.", examples=['Sounds great — the harmonic transitions in the bridge are exactly right.'])` |


### `ProposalReviewListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of reviews for a merge proposal.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `reviews` | `list[ProposalReviewResponse]` |  | `(factory)` |
| `total` | `int` |  | `Field(0, ge=0, description='Total number of review rows')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `ProposalReviewResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single proposal review.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `str` | ✓ | `—` |
| `proposal_id` | `str` | ✓ | `—` |
| `reviewer_username` | `str` | ✓ | `—` |
| `state` | `str` | ✓ | `—` |
| `body` | `str | None` |  | `Field(None, description='Review comment body (Markdown); null for bare assignments')` |
| `submitted_at` | `datetime | None` |  | `Field(None, description='UTC timestamp when the review was submitted')` |
| `created_at` | `datetime` | ✓ | `—` |


### `ProposalReviewerRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/proposals/{proposal_id}/reviewers.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `reviewers` | `list[str]` | ✓ | `—` |


### `PullResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Response for POST /musehub/repos/{repo_id}/pull.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commits` | `list[CommitResponse]` | ✓ | `—` |
| `objects` | `list[ObjectResponse]` | ✓ | `—` |
| `remote_head` | `str | None` | ✓ | `—` |
| `has_more` | `bool` |  | `False` |
| `next_cursor` | `str | None` |  | `None` |


### `PushResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Response for POST /musehub/repos/{repo_id}/push.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `ok` | `bool` | ✓ | `—` |
| `remote_head` | `str` | ✓ | `—` |


### `RefactorEventResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single structural refactoring event detected in the release.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `kind` | `str` |  | `''` |
| `address` | `str` |  | `''` |
| `detail` | `str` |  | `''` |
| `commit_id` | `str` |  | `''` |


### `ReleaseAssetCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/releases/{tag}/assets.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `label` | `str` |  | `Field('', max_length=255, description="Optional human-readable label, e.g. 'MIDI Bundle'")` |
| `content_type` | `str` |  | `Field('', max_length=128, description="MIME type, e.g. 'audio/midi', 'application/zip'")` |
| `size` | `int` |  | `Field(0, ge=0, description='File size in bytes; 0 when unknown')` |
| `download_url` | `str` | ✓ | `—` |


### `ReleaseAssetDownloadCount` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Per-asset download count entry in a release download stats response.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `asset_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `label` | `str` |  | `Field('', description='Optional human-readable label')` |
| `download_count` | `int` |  | `Field(0, ge=0, description='Number of times this asset has been downloaded')` |


### `ReleaseAssetListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of assets attached to a release.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `release_id` | `str` | ✓ | `—` |
| `tag` | `str` | ✓ | `—` |
| `assets` | `list[ReleaseAssetResponse]` | ✓ | `—` |
| `total` | `int` |  | `Field(0, ge=0, description='Total assets attached to this release')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `ReleaseAssetResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single release asset.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `asset_id` | `str` | ✓ | `—` |
| `release_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `label` | `str` |  | `Field('', description='Optional human-readable label')` |
| `content_type` | `str` |  | `Field('', description='MIME type of the artifact')` |
| `size` | `int` |  | `Field(0, ge=0, description='File size in bytes; 0 when unknown')` |
| `download_url` | `str` | ✓ | `—` |
| `download_count` | `int` |  | `Field(0, ge=0, description='Number of times the asset has been downloaded')` |
| `created_at` | `datetime` | ✓ | `—` |


### `ReleaseCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/releases.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tag` | `str` | ✓ | `—` |
| `title` | `str` |  | `Field('', max_length=500, description='Release title', examples=['Summer Sessions 2024 — Final Mix'])` |
| `body` | `str` |  | `Field('', max_length=10000, description='Release notes (Markdown)', examples=['## Summer Sessions 2024\n\nFinal arrangement with full brass section and 132 BPM tempo.'])` |
| `commit_id` | `str | None` |  | `Field(None, description='Commit to pin this release to', examples=['a3f8c1d2e4b5'])` |
| `snapshot_id` | `str | None` |  | `Field(None, description='Snapshot ID for reproducible builds')` |
| `channel` | `str` |  | `Field('stable', description='Distribution channel: stable | beta | alpha | nightly', examples=['stable'])` |
| `semver_major` | `int` |  | `Field(0, ge=0)` |
| `semver_minor` | `int` |  | `Field(0, ge=0)` |
| `semver_patch` | `int` |  | `Field(0, ge=0)` |
| `semver_pre` | `str` |  | `Field('', max_length=255, description="Pre-release label, e.g. 'beta.1'")` |
| `semver_build` | `str` |  | `Field('', max_length=255, description="Build metadata, e.g. '20250101'")` |
| `agent_id` | `str` |  | `Field('', max_length=255)` |
| `model_id` | `str` |  | `Field('', max_length=255)` |
| `changelog` | `list[ChangelogEntryResponse]` |  | `(factory)` |
| `is_draft` | `bool` |  | `Field(False, description='Save as draft — not yet publicly visible')` |
| `gpg_signature` | `str | None` |  | `Field(None, description='ASCII-armoured GPG signature for the tag object; omit when unsigned')` |
| `semantic_report` | `SemanticReleaseReportResponse | None` |  | `Field(None, description='Semantic analysis blob computed by the Muse CLI at push time.')` |


### `ReleaseDownloadStatsResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Download counts per asset for a single release.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `release_id` | `str` | ✓ | `—` |
| `tag` | `str` | ✓ | `—` |
| `assets` | `list[ReleaseAssetDownloadCount]` |  | `(factory)` |
| `total_downloads` | `int` |  | `Field(0, ge=0, description='Sum of download_count across all assets')` |


### `ReleaseDownloadUrls` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Structured download package URLs for a release.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `metadata` | `str | None` |  | `None` |


### `ReleaseListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of releases for a repo (newest first).

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `releases` | `list[ReleaseResponse]` | ✓ | `—` |
| `total` | `int` |  | `Field(0, ge=0, description='Total matching releases across all pages')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `ReleaseResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a MuseHub release.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `release_id` | `str` | ✓ | `—` |
| `tag` | `str` | ✓ | `—` |
| `title` | `str` |  | `''` |
| `body` | `str` |  | `''` |
| `commit_id` | `str | None` |  | `None` |
| `snapshot_id` | `str | None` |  | `None` |
| `channel` | `str` |  | `'stable'` |
| `semver_major` | `int` |  | `0` |
| `semver_minor` | `int` |  | `0` |
| `semver_patch` | `int` |  | `0` |
| `semver_pre` | `str` |  | `''` |
| `semver_build` | `str` |  | `''` |
| `download_urls` | `ReleaseDownloadUrls` | ✓ | `—` |
| `author` | `str` |  | `''` |
| `agent_id` | `str` |  | `''` |
| `model_id` | `str` |  | `''` |
| `changelog` | `list[ChangelogEntryResponse]` |  | `(factory)` |
| `is_prerelease` | `bool` |  | `False` |
| `is_draft` | `bool` |  | `False` |
| `gpg_signature` | `str | None` |  | `None` |
| `semantic_report` | `SemanticReleaseReportResponse | None` |  | `None` |
| `created_at` | `datetime` | ✓ | `—` |


### `RepoListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Paginated list of repos for the authenticated user.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repos` | `list[RepoResponse]` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `Field(None, description='Pagination cursor — pass as ?cursor= to get the next page')` |
| `total` | `int` | ✓ | `—` |


### `RepoResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a MuseHub repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `owner` | `str` | ✓ | `—` |
| `slug` | `str` | ✓ | `—` |
| `visibility` | `str` | ✓ | `—` |
| `owner_user_id` | `str` | ✓ | `—` |
| `clone_url` | `str` | ✓ | `—` |
| `description` | `str` |  | `Field('', description='Short description shown on the explore page', examples=['Classic jazz standards arranged for quartet'])` |
| `tags` | `list[str]` |  | `(factory)` |
| `domain_id` | `str | None` |  | `Field(None, description='ID of the registered Muse domain plugin for this repo')` |
| `key_signature` | `str | None` |  | `Field(None, description="Musical key signature, e.g. 'Bb major'")` |
| `tempo_bpm` | `int | None` |  | `Field(None, description='Tempo in beats per minute')` |
| `created_at` | `datetime` | ✓ | `—` |


### `RepoSettingsPatch` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Partial update body for ``PATCH /api/repos/{repo_id}/settings``.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str | None` |  | `Field(None, description='New repo name')` |
| `description` | `str | None` |  | `Field(None, description='New description')` |
| `visibility` | `str | None` |  | `Field(None, pattern='^(public|private)$', description="'public' or 'private'")` |
| `default_branch` | `str | None` |  | `Field(None, description='New default branch name')` |
| `has_issues` | `bool | None` |  | `Field(None, description='Enable/disable issues tracker')` |
| `has_projects` | `bool | None` |  | `Field(None, description='Enable/disable projects board')` |
| `has_wiki` | `bool | None` |  | `Field(None, description='Enable/disable wiki')` |
| `topics` | `list[str] | None` |  | `Field(None, description='Replace topic tags (full list)')` |
| `license` | `str | None` |  | `Field(None, description='SPDX license identifier or display name')` |
| `homepage_url` | `str | None` |  | `Field(None, description='Project homepage URL')` |
| `allow_merge_commit` | `bool | None` |  | `Field(None, description='Allow merge commits on proposals')` |
| `allow_squash_merge` | `bool | None` |  | `Field(None, description='Allow squash merges on proposals')` |
| `allow_rebase_merge` | `bool | None` |  | `Field(None, description='Allow rebase merges on proposals')` |
| `delete_branch_on_merge` | `bool | None` |  | `Field(None, description='Auto-delete head branch after proposal merge')` |
| `domain_id` | `str | None` |  | `Field(None, description='UUID of the Muse domain plugin for this repo')` |


### `RepoSettingsResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Mutable settings for a MuseHub repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `description` | `str` |  | `Field('', description='Short description shown on the explore page')` |
| `visibility` | `str` | ✓ | `—` |
| `default_branch` | `str` |  | `Field('main', description='Default branch name (used for clone and proposals)')` |
| `has_issues` | `bool` |  | `Field(True, description='Whether the issues tracker is enabled')` |
| `has_projects` | `bool` |  | `Field(False, description='Whether the projects board is enabled')` |
| `has_wiki` | `bool` |  | `Field(False, description='Whether the wiki is enabled')` |
| `topics` | `list[str]` |  | `(factory)` |
| `license` | `str | None` |  | `Field(None, description="SPDX license identifier or display name, e.g. 'CC BY 4.0'")` |
| `homepage_url` | `str | None` |  | `Field(None, description='Project homepage URL')` |
| `allow_merge_commit` | `bool` |  | `Field(True, description='Allow merge commits on proposals')` |
| `allow_squash_merge` | `bool` |  | `Field(True, description='Allow squash merges on proposals')` |
| `allow_rebase_merge` | `bool` |  | `Field(False, description='Allow rebase merges on proposals')` |
| `delete_branch_on_merge` | `bool` |  | `Field(True, description='Auto-delete head branch after proposal merge')` |
| `domain_id` | `str | None` |  | `Field(None, description='UUID of the Muse domain plugin for this repo')` |


### `RepoStatsResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Aggregated counts for the repo home page stats bar.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_count` | `int` |  | `Field(0, ge=0, description='Total number of commits across all branches')` |
| `branch_count` | `int` |  | `Field(0, ge=0, description='Number of branches (including default)')` |
| `release_count` | `int` |  | `Field(0, ge=0, description='Number of published releases / tags')` |


### `SearchCommitMatch` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single commit returned by a search query.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `score` | `float` |  | `Field(1.0, ge=0.0, le=1.0, description='Match score (0–1); always 1.0 for exact-match modes')` |
| `match_source` | `str` |  | `Field('message', description="Where the match was found: 'message', 'branch', or 'property'")` |


### `SearchResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Response envelope for all four in-repo search modes.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `mode` | `str` | ✓ | `—` |
| `query` | `str` | ✓ | `—` |
| `matches` | `list[SearchCommitMatch]` | ✓ | `—` |
| `total_scanned` | `int` | ✓ | `—` |
| `limit` | `int` | ✓ | `—` |


### `SemanticReleaseReportResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Semantic analysis of a release, computed by the Muse CLI at push time.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `languages` | `list[LanguageStatResponse]` |  | `(factory)` |
| `total_files` | `int` |  | `0` |
| `semantic_files` | `int` |  | `0` |
| `total_symbols` | `int` |  | `0` |
| `symbols_by_kind` | `list[SymbolKindCountResponse]` |  | `(factory)` |
| `files_changed` | `int` |  | `0` |
| `api_added` | `list[ApiChangeSummaryResponse]` |  | `(factory)` |
| `api_removed` | `list[ApiChangeSummaryResponse]` |  | `(factory)` |
| `api_modified` | `list[ApiChangeSummaryResponse]` |  | `(factory)` |
| `file_hotspots` | `list[FileHotspotResponse]` |  | `(factory)` |
| `refactor_events` | `list[RefactorEventResponse]` |  | `(factory)` |
| `breaking_changes` | `list[str]` |  | `(factory)` |
| `human_commits` | `int` |  | `0` |
| `agent_commits` | `int` |  | `0` |
| `unique_agents` | `list[str]` |  | `(factory)` |
| `unique_models` | `list[str]` |  | `(factory)` |
| `reviewers` | `list[str]` |  | `(factory)` |


### `SessionCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/sessions.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `started_at` | `datetime | None` |  | `None` |
| `participants` | `list[str]` |  | `(factory)` |
| `intent` | `str` |  | `Field('', description='Free-text creative goal for this session', examples=['Finish the bossa nova bridge — add percussion and finalize the chord changes'])` |
| `location` | `str` |  | `Field('', max_length=255, description='Studio or location label', examples=['Blue Note Studio, NYC'])` |
| `is_active` | `bool` |  | `Field(True, description='True if the session is currently live')` |


### `SessionListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of sessions for a repo (newest first).

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `sessions` | `list[SessionResponse]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `None` |


### `SessionResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single recording session.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `session_id` | `str` | ✓ | `—` |
| `started_at` | `datetime` | ✓ | `—` |
| `ended_at` | `datetime | None` |  | `None` |
| `duration_seconds` | `float | None` |  | `None` |
| `participants` | `list[str]` | ✓ | `—` |
| `commits` | `list[str]` |  | `(factory)` |
| `notes` | `str` |  | `Field('', description='Closing notes for the session (markdown)')` |
| `intent` | `str` | ✓ | `—` |
| `location` | `str` | ✓ | `—` |
| `is_active` | `bool` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |


### `SessionStop` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/sessions/{session_id}/stop.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `ended_at` | `datetime | None` |  | `None` |


### `SnapshotBatchRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Request body for the batch snapshot lookup endpoint.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_ids` | `list[str]` | ✓ | `—` |
| `include_entries` | `bool` |  | `Field(False, description='When true, each result includes its file-tree entries (heavier)')` |


### `SnapshotDiffEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single file-level change between two snapshots.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `path` | `str` | ✓ | `—` |
| `status` | `str` | ✓ | `—` |
| `base_object_id` | `str | None` |  | `Field(None, description='Object ID in the base snapshot (null for added files)', examples=['b2a7d9e1c3f4'])` |
| `new_object_id` | `str | None` |  | `Field(None, description='Object ID in the new snapshot (null for removed files)', examples=['c3b8e0f2d5a6'])` |
| `base_size_bytes` | `int` |  | `Field(0, ge=0, description='File size in base snapshot')` |
| `new_size_bytes` | `int` |  | `Field(0, ge=0, description='File size in new snapshot')` |


### `SnapshotDiffResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

File-level diff between two snapshots.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `str` | ✓ | `—` |
| `base_snapshot_id` | `str` | ✓ | `—` |
| `added_count` | `int` |  | `Field(0, ge=0, description='Files added in new snapshot')` |
| `removed_count` | `int` |  | `Field(0, ge=0, description='Files removed from base snapshot')` |
| `modified_count` | `int` |  | `Field(0, ge=0, description='Files present in both but with changed content')` |
| `unchanged_count` | `int` |  | `Field(0, ge=0, description='Files identical in both snapshots')` |
| `bytes_added` | `int` |  | `Field(0, ge=0, description='Total bytes added (new file sizes)')` |
| `bytes_removed` | `int` |  | `Field(0, ge=0, description='Total bytes removed (base file sizes)')` |
| `changes` | `list[SnapshotDiffEntry]` |  | `(factory)` |


### `SnapshotEntryListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated file-tree entries for a single snapshot.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `str` | ✓ | `—` |
| `entries` | `list[SnapshotEntryResponse]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `SnapshotEntryResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

One file-tree entry within a snapshot.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `path` | `str` | ✓ | `—` |
| `object_id` | `str` | ✓ | `—` |
| `size_bytes` | `int` |  | `Field(0, ge=0, description='Stored file size in bytes; 0 when unknown', examples=[4096])` |


### `SnapshotInput` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A snapshot manifest transferred in a push payload.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `str` | ✓ | `—` |
| `manifest` | `StrDict` |  | `(factory)` |
| `created_at` | `str` |  | `''` |


### `SnapshotListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of snapshot summaries (newest first).

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshots` | `list[SnapshotSummaryResponse]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `SnapshotResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Full snapshot record including all file-tree entries.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `directories` | `list[str]` |  | `(factory)` |
| `entries` | `list[SnapshotEntryResponse]` |  | `(factory)` |
| `entry_count` | `int` |  | `Field(0, ge=0, description='Total number of entries (equal to len(entries) unless paginated)', examples=[142])` |
| `total_size_bytes` | `int` |  | `Field(0, ge=0, description='Sum of all entry size_bytes', examples=[1048576])` |
| `created_at` | `datetime` | ✓ | `—` |


### `SnapshotSummaryResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Lightweight snapshot summary — no file-tree entries.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `entry_count` | `int` |  | `Field(0, ge=0, description='Number of file-tree entries (files) tracked at this snapshot', examples=[142])` |
| `total_size_bytes` | `int` |  | `Field(0, ge=0, description='Sum of all entry size_bytes; 0 when sizes were not recorded', examples=[1048576])` |
| `directories` | `list[str]` |  | `(factory)` |
| `created_at` | `datetime` | ✓ | `—` |


### `StarResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Confirmation that a star was added or removed.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `starred` | `bool` | ✓ | `—` |
| `star_count` | `int` | ✓ | `—` |


### `StargazerEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single user who has starred a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `user_id` | `str` | ✓ | `—` |
| `starred_at` | `datetime` | ✓ | `—` |


### `StargazerListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Paginated list of users who have starred a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `stargazers` | `list[StargazerEntry]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `SymbolBlameEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

One blame annotation attributing a symbol to the commit that last modified it.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `symbol_address` | `str` | ✓ | `—` |
| `symbol_name` | `str` | ✓ | `—` |
| `commit_id` | `str` | ✓ | `—` |
| `commit_message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `op` | `str` | ✓ | `—` |
| `change_count` | `int` |  | `1` |
| `is_hotspot` | `bool` |  | `False` |
| `is_dead` | `bool` |  | `False` |
| `is_blast_risk` | `bool` |  | `False` |
| `blast_co_symbols` | `list[str]` |  | `(factory)` |


### `SymbolBlameResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Response envelope for symbol-level blame.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `entries` | `list[SymbolBlameEntry]` |  | `(factory)` |
| `total_entries` | `int` |  | `0` |
| `path` | `str` |  | `''` |


### `SymbolKindCountResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Count of symbols of a specific kind in the release snapshot.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `kind` | `str` | ✓ | `—` |
| `count` | `int` |  | `0` |


### `TagListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

All tags for a repo, grouped by namespace.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tags` | `list[TagResponse]` | ✓ | `—` |
| `namespaces` | `list[str]` |  | `(factory)` |


### `TagResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single tag entry for the tag browser page.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tag` | `str` | ✓ | `—` |
| `namespace` | `str` | ✓ | `—` |
| `commit_id` | `str | None` |  | `Field(None, description='Commit this tag is pinned to')` |
| `message` | `str` |  | `Field('', description='Release title / description')` |
| `created_at` | `datetime` | ✓ | `—` |


### `TimelineCommitEvent` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A commit plotted as a point on the timeline.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `event_type` | `str` |  | `'commit'` |
| `commit_id` | `str` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `parent_ids` | `list[str]` | ✓ | `—` |


### `TimelineEmotionEvent` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

An emotion-vector data point overlaid on the timeline as a line chart.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `event_type` | `str` |  | `'emotion'` |
| `commit_id` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `valence` | `float` | ✓ | `—` |
| `energy` | `float` | ✓ | `—` |
| `tension` | `float` | ✓ | `—` |


### `TimelineResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Chronological timeline of musical evolution for a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commits` | `list[TimelineCommitEvent]` | ✓ | `—` |
| `emotion` | `list[TimelineEmotionEvent]` | ✓ | `—` |
| `sections` | `list[TimelineSectionEvent]` | ✓ | `—` |
| `tracks` | `list[TimelineTrackEvent]` | ✓ | `—` |
| `total_commits` | `int` | ✓ | `—` |


### `TimelineSectionEvent` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A detected section change plotted as a marker on the timeline.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `event_type` | `str` |  | `'section'` |
| `commit_id` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `section_name` | `str` | ✓ | `—` |
| `action` | `str` | ✓ | `—` |


### `TimelineTrackEvent` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A detected track addition or removal plotted as a marker on the timeline.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `event_type` | `str` |  | `'track'` |
| `commit_id` | `str` | ✓ | `—` |
| `timestamp` | `datetime` | ✓ | `—` |
| `track_name` | `str` | ✓ | `—` |
| `action` | `str` | ✓ | `—` |


### `TransferOwnershipRequest` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Request body for transferring repo ownership to another user.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `new_owner_user_id` | `str` | ✓ | `—` |


### `TreeEntryResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single entry (file or directory) in the Muse tree browser.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `str` | ✓ | `—` |
| `name` | `str` | ✓ | `—` |
| `path` | `str` | ✓ | `—` |
| `size_bytes` | `int | None` |  | `Field(None, description='File size in bytes; None for directories')` |
| `object_id` | `str | None` |  | `Field(None, description='Content-addressed object ID; None for directories and legacy entries')` |


### `TreeListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Directory listing for the Muse tree browser.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `owner` | `str` | ✓ | `—` |
| `repo_slug` | `str` | ✓ | `—` |
| `ref` | `str` | ✓ | `—` |
| `dir_path` | `str` | ✓ | `—` |
| `entries` | `list[TreeEntryResponse]` |  | `(factory)` |


### `UserActivityEventItem` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single event in a user's public activity feed.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `str` | ✓ | `—` |
| `type` | `str` | ✓ | `—` |
| `actor` | `str` | ✓ | `—` |
| `repo` | `str` | ✓ | `—` |
| `payload` | `dict[str, PydanticJson]` |  | `(factory)` |
| `created_at` | `datetime` | ✓ | `—` |


### `UserActivityFeedResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated public activity feed for a MuseHub user (newest-first).

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `events` | `list[UserActivityEventItem]` | ✓ | `—` |
| `next_cursor` | `str | None` |  | `Field(None, description='Pass as before_id to fetch the next page; None on the last page')` |
| `type_filter` | `str | None` |  | `Field(None, description='Active type filter value, or None when all types are shown')` |


### `UserForkedRepoEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single forked repo entry shown on a user's profile Forked tab.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `fork_id` | `str` | ✓ | `—` |
| `fork_repo` | `RepoResponse` | ✓ | `—` |
| `source_owner` | `str` | ✓ | `—` |
| `source_slug` | `str` | ✓ | `—` |
| `forked_at` | `datetime` | ✓ | `—` |


### `UserForksResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Paginated list of repos forked by a user.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `forks` | `list[UserForkedRepoEntry]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `UserStarredRepoEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single starred-repo entry shown on a user's profile Starred tab.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `star_id` | `str` | ✓ | `—` |
| `repo` | `RepoResponse` | ✓ | `—` |
| `starred_at` | `datetime` | ✓ | `—` |


### `UserStarredResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Paginated list of repos starred by a user.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `starred` | `list[UserStarredRepoEntry]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `UserWatchedRepoEntry` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single watched-repo entry shown on a user's profile Watching tab.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `watch_id` | `str` | ✓ | `—` |
| `repo` | `RepoResponse` | ✓ | `—` |
| `watched_at` | `datetime` | ✓ | `—` |


### `UserWatchedResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Paginated list of repos watched by a user.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `watched` | `list[UserWatchedRepoEntry]` | ✓ | `—` |
| `total` | `int` | ✓ | `—` |


### `WebhookCreate` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Body for POST /musehub/repos/{repo_id}/webhooks.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `url` | `str` | ✓ | `—` |
| `events` | `list[str]` | ✓ | `—` |
| `secret` | `str` |  | `Field('', description='Optional HMAC-SHA256 signing secret')` |


### `WebhookDeliveryListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of delivery attempts for a webhook (newest first).

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `deliveries` | `list[WebhookDeliveryResponse]` | ✓ | `—` |
| `total` | `int` |  | `Field(0, ge=0, description='Total delivery attempts for this webhook')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page (older deliveries). Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `WebhookDeliveryResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a single webhook delivery attempt.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `delivery_id` | `str` | ✓ | `—` |
| `webhook_id` | `str` | ✓ | `—` |
| `event_type` | `str` | ✓ | `—` |
| `payload` | `str` |  | `Field('', description='JSON body sent to the subscriber URL')` |
| `attempt` | `int` | ✓ | `—` |
| `success` | `bool` | ✓ | `—` |
| `response_status` | `int` | ✓ | `—` |
| `response_body` | `str` | ✓ | `—` |
| `delivered_at` | `datetime` | ✓ | `—` |


### `WebhookListResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Cursor-paginated list of webhook subscriptions for a repo.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `webhooks` | `list[WebhookResponse]` | ✓ | `—` |
| `total` | `int` |  | `Field(0, ge=0, description='Total webhooks registered for this repo')` |
| `next_cursor` | `str | None` |  | `Field(None, description='Opaque cursor for the next page. Pass verbatim as ?cursor= to advance. Null when this is the last page.')` |


### `WebhookRedeliverResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Confirmation that a delivery reattempt was executed.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `original_delivery_id` | `str` | ✓ | `—` |
| `webhook_id` | `str` | ✓ | `—` |
| `event_type` | `str` | ✓ | `—` |
| `success` | `bool` | ✓ | `—` |
| `response_status` | `int` | ✓ | `—` |
| `response_body` | `str` |  | `Field('', description='Response body snippet from the final attempt (≤512 chars)')` |


### `WebhookResponse` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

Wire representation of a registered webhook subscription.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `webhook_id` | `str` | ✓ | `—` |
| `repo_id` | `str` | ✓ | `—` |
| `url` | `str` | ✓ | `—` |
| `events` | `list[str]` | ✓ | `—` |
| `active` | `bool` | ✓ | `—` |
| `created_at` | `datetime` | ✓ | `—` |


### `WireTagInput` — [`musehub/models/musehub.py`](musehub/models/musehub.py)

A single lightweight tag pushed from a Muse CLI client.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tag_id` | `str` | ✓ | `—` |
| `commit_id` | `str` | ✓ | `—` |
| `tag` | `str` | ✓ | `—` |
| `created_at` | `str` |  | `Field('', description='ISO-8601 creation timestamp from the client')` |


### `AgentRegistrationRequest` — [`musehub/models/musehub_auth.py`](musehub/models/musehub_auth.py)

Operator-signed agent provisioning request — ``POST /api/identities/agent``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `handle` | `str` | ✓ | `—` |
| `public_key_b64` | `str` | ✓ | `—` |
| `fingerprint` | `str` | ✓ | `—` |
| `algorithm` | `str` |  | `'ed25519'` |
| `agent_model` | `str` |  | `''` |
| `scope` | `list[str]` |  | `(factory)` |
| `expires_at` | `str | None` |  | `Field(None, description='ISO-8601 UTC expiry time for this agent key. null = no expiry.')` |
| `label` | `str` |  | `''` |


### `AgentRegistrationResponse` — [`musehub/models/musehub_auth.py`](musehub/models/musehub_auth.py)

Response for ``POST /api/identities/agent``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `handle` | `str` | ✓ | `—` |
| `identity_id` | `str` | ✓ | `—` |
| `is_new_identity` | `bool` | ✓ | `—` |
| `spawned_by` | `str` | ✓ | `—` |
| `key` | `AuthKeyResponse` | ✓ | `—` |


### `AuthKeyResponse` — [`musehub/models/musehub_auth.py`](musehub/models/musehub_auth.py)

Public summary of a registered auth key (never exposes key material).

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `key_id` | `str` | ✓ | `—` |
| `algorithm` | `str` | ✓ | `—` |
| `fingerprint` | `str` | ✓ | `—` |
| `label` | `str` | ✓ | `—` |
| `created_at` | `str` | ✓ | `—` |
| `last_used_at` | `str | None` | ✓ | `—` |


### `ChallengeRequest` — [`musehub/models/musehub_auth.py`](musehub/models/musehub_auth.py)

Request a challenge nonce for the given public key fingerprint.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `fingerprint` | `str` | ✓ | `—` |
| `algorithm` | `str` |  | `Field(default=KeyAlgorithm.ED25519.value, description=f'Signing algorithm for this key. Implemented: {_IMPLEMENTED_ALGO_VALUES}.')` |


### `ChallengeResponse` — [`musehub/models/musehub_auth.py`](musehub/models/musehub_auth.py)

Challenge nonce to sign and submit to /api/auth/verify.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `challenge_token` | `str` | ✓ | `—` |
| `is_new_key` | `bool` | ✓ | `—` |
| `expires_in` | `int` |  | `Field(300, description='Challenge validity in seconds.')` |
| `algorithm` | `str` | ✓ | `—` |


### `VerifyRequest` — [`musehub/models/musehub_auth.py`](musehub/models/musehub_auth.py)

Submit a signed challenge to complete authentication.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `challenge_token` | `str` | ✓ | `—` |
| `public_key_b64` | `str` | ✓ | `—` |
| `signature_b64` | `str` | ✓ | `—` |
| `handle` | `str | None` |  | `Field(None, min_length=1, max_length=64, description='Desired handle (username). Required when registering a new key.')` |
| `display_name` | `str | None` |  | `Field(None, max_length=128, description='Optional display name shown on the profile.')` |
| `label` | `str | None` |  | `Field(None, max_length=255, description='Optional friendly key label, e.g. "MacBook Pro" or "CI agent".')` |
| `identity_type` | `str` |  | `'human'` |


### `VerifyResponse` — [`musehub/models/musehub_auth.py`](musehub/models/musehub_auth.py)

Successful key registration / re-registration response.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `handle` | `str` | ✓ | `—` |
| `identity_id` | `str` | ✓ | `—` |
| `is_new_identity` | `bool` | ✓ | `—` |
| `auth_method` | `str` | ✓ | `—` |
| `key` | `AuthKeyResponse` | ✓ | `—` |


### `ActiveProposalContext` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

An open proposal that may inform composition decisions.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `proposal_id` | `str` | ✓ | `—` |
| `title` | `str` | ✓ | `—` |
| `from_branch` | `str` | ✓ | `—` |
| `to_branch` | `str` | ✓ | `—` |
| `state` | `str` | ✓ | `—` |
| `body` | `str` |  | `''` |


### `AgentContextResponse` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

Complete agent context document for one project ref.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `ref` | `str` | ✓ | `Field(description='The resolved branch name or commit ID')` |
| `depth` | `str` | ✓ | `Field(description='Depth level used to build this response')` |
| `musical_state` | `MusicalStateContext` | ✓ | `—` |
| `history` | `list[HistoryEntryContext]` |  | `(factory)` |
| `analysis` | `AnalysisSummaryContext` | ✓ | `—` |
| `active_proposals` | `list[ActiveProposalContext]` |  | `(factory)` |
| `open_issues` | `list[OpenIssueContext]` |  | `(factory)` |
| `suggestions` | `list[str]` |  | `(factory)` |


### `AnalysisSummaryContext` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

Per-dimension analysis highlights for the current state.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `key_finding` | `Annotated[str | None, Field(description='Key and mode detection summary')]` |  | `None` |
| `chord_progression` | `Annotated[list[str] | None, Field(description="Detected chord progression (e.g. ['Cm', 'Ab', 'Eb', 'Bb'])")]` |  | `None` |
| `groove_score` | `Annotated[float | None, Field(description='Groove quality score [0.0, 1.0]')]` |  | `None` |
| `emotion` | `Annotated[str | None, Field(description='Emotional character')]` |  | `None` |
| `harmonic_tension` | `Annotated[str | None, Field(description="Harmonic tension assessment ('low', 'medium', 'high')")]` |  | `None` |
| `melodic_contour` | `Annotated[str | None, Field(description='Melodic contour description')]` |  | `None` |


### `HistoryEntryContext` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

A single commit entry in the composition history.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `author` | `str` | ✓ | `—` |
| `timestamp` | `str` | ✓ | `Field(description='ISO-8601 UTC timestamp')` |
| `active_tracks` | `list[str]` |  | `(factory)` |


### `MusicalStateContext` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

Current musical state of the project at the resolved ref.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `active_tracks` | `list[str]` |  | `(factory)` |


### `OpenIssueContext` — [`musehub/models/musehub_context.py`](musehub/models/musehub_context.py)

An open issue that may describe desired compositional changes.

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `issue_id` | `str` | ✓ | `—` |
| `number` | `int` | ✓ | `—` |
| `title` | `str` | ✓ | `—` |
| `labels` | `list[str]` |  | `(factory)` |
| `body` | `str` |  | `''` |


### `WireMPack` — [`musehub/models/wire.py`](musehub/models/wire.py)

An mpack sent in a push request.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commits` | `list[WireCommit]` |  | `(factory)` |
| `snapshots` | `list[WireSnapshot]` |  | `(factory)` |
| `objects` | `list[WireObject]` |  | `(factory)` |
| `branch_heads` | `StrDict` |  | `(factory)` |


### `WireCommit` — [`musehub/models/wire.py`](musehub/models/wire.py)

Muse native commit record — mirrors CommitDict from muse.core.store.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `str` | ✓ | `—` |
| `repo_id` | `str` |  | `''` |
| `branch` | `str` |  | `''` |
| `snapshot_id` | `str | None` |  | `None` |
| `message` | `str` |  | `''` |
| `committed_at` | `str` |  | `''` |
| `parent_commit_id` | `str | None` |  | `None` |
| `parent2_commit_id` | `str | None` |  | `None` |
| `author` | `str` |  | `''` |
| `metadata` | `StrDict` |  | `(factory)` |
| `structured_delta` | `PydanticJson | None` |  | `None` |
| `sem_ver_bump` | `str` |  | `'none'` |
| `breaking_changes` | `list[str]` |  | `(factory)` |
| `agent_id` | `str` |  | `''` |
| `model_id` | `str` |  | `''` |
| `toolchain_id` | `str` |  | `''` |
| `prompt_hash` | `str` |  | `''` |
| `signature` | `str` |  | `''` |
| `signer_public_key` | `str` |  | `''` |
| `signer_key_id` | `str` |  | `''` |
| `format_version` | `int` |  | `7` |
| `reviewed_by` | `list[str]` |  | `(factory)` |
| `test_runs` | `int` |  | `0` |


### `WireConfirmObjectsRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /{owner}/{slug}/push/objects/confirm``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_ids` | `list[str]` |  | `(factory)` |
| `sizes` | `dict[str, int]` |  | `(factory)` |


### `WireConfirmObjectsResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``POST /{owner}/{slug}/push/objects/confirm``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `registered` | `int` | ✓ | `—` |
| `skipped` | `int` | ✓ | `—` |


### `WireFetchObjectsRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /{owner}/{slug}/fetch/objects``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_ids` | `list[str]` |  | `(factory)` |


### `WireFetchRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /wire/repos/{repo_id}/fetch``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `want` | `list[str]` |  | `(factory)` |
| `have` | `list[str]` |  | `(factory)` |


### `WireFetchResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``POST /wire/repos/{repo_id}/fetch``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commits` | `list[WireCommit]` |  | `(factory)` |
| `snapshots` | `list[WireSnapshot]` |  | `(factory)` |
| `branch_heads` | `StrDict` |  | `(factory)` |


### `WireFilterRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /{owner}/{slug}/filter-objects``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_ids` | `list[str]` |  | `(factory)` |
| `object_hints` | `dict[str, str]` |  | `(factory)` |


### `WireFilterResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``POST /{owner}/{slug}/filter-objects``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `missing` | `list[str]` | ✓ | `—` |
| `bases` | `dict[str, str]` |  | `(factory)` |


### `WireObject` — [`musehub/models/wire.py`](musehub/models/wire.py)

Content-addressed object payload — mirrors ObjectPayload from muse.core.mpack.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `str` | ✓ | `—` |
| `content` | `bytes` | ✓ | `Field(max_length=MAX_OBJECT_BYTES)` |
| `path` | `str` |  | `''` |
| `encoding` | `str` |  | `'raw'` |
| `base_id` | `str | None` |  | `None` |


### `WireObjectPackRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /{owner}/{slug}/push/object-pack``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `objects` | `list[WireObject]` |  | `(factory)` |


### `WireObjectPackResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``POST /{owner}/{slug}/push/object-pack``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `stored` | `int` | ✓ | `—` |
| `skipped` | `int` | ✓ | `—` |


### `WireObjectsRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /{owner}/{slug}/push/objects`` — chunked object pre-upload.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `objects` | `list[WireObject]` |  | `(factory)` |


### `WireObjectsResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``POST /{owner}/{slug}/push/objects``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `stored` | `int` | ✓ | `—` |
| `skipped` | `int` | ✓ | `—` |


### `WirePresignRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /{owner}/{slug}/presign``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_ids` | `list[str]` |  | `(factory)` |
| `direction` | `str` |  | `'put'` |
| `ttl_seconds` | `int` |  | `3600` |


### `WirePresignResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``POST /{owner}/{slug}/presign``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `presigned` | `StrDict` |  | `(factory)` |
| `inline` | `list[str]` |  | `(factory)` |


### `WirePushRequest` — [`musehub/models/wire.py`](musehub/models/wire.py)

Body for ``POST /wire/repos/{repo_id}/push``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `mpack` | `WireMPack` | ✓ | `—` |
| `branch` | `str` | ✓ | `—` |
| `force` | `bool` |  | `False` |
| `local_head` | `str | None` |  | `None` |


### `WirePushResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``POST /wire/repos/{repo_id}/push``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `ok` | `bool` | ✓ | `—` |
| `message` | `str` | ✓ | `—` |
| `branch_heads` | `StrDict` | ✓ | `—` |
| `remote_head` | `str` |  | `''` |


### `WireRefsResponse` — [`musehub/models/wire.py`](musehub/models/wire.py)

Response for ``GET /wire/repos/{repo_id}/refs``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |
| `domain` | `str` | ✓ | `—` |
| `default_branch` | `str` | ✓ | `—` |
| `branch_heads` | `StrDict` | ✓ | `—` |
| `pack_origin` | `str | None` |  | `None` |


### `WireSnapshot` — [`musehub/models/wire.py`](musehub/models/wire.py)

Muse native snapshot — mirrors SnapshotDict from muse.core.store.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `str` | ✓ | `—` |
| `manifest` | `StrDict` |  | `(factory)` |
| `directories` | `list[str]` |  | `(factory)` |
| `created_at` | `str` |  | `''` |


### `MCPInputSchemaWire` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Pydantic-safe wire model for an MCP tool's JSON Schema input descriptor.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `str` |  | `'object'` |
| `properties` | `dict[str, 'MCPPropertyDefWire']` |  | `(factory)` |
| `required` | `list[str] | None` |  | `None` |


### `MCPPropertyDefWire` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Pydantic-safe wire model for a single JSON Schema property definition.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `type` | `str` | ✓ | `—` |
| `description` | `str | None` |  | `None` |
| `enum` | `list[str | int | float] | None` |  | `None` |
| `minimum` | `float | None` |  | `None` |
| `maximum` | `float | None` |  | `None` |
| `default` | `PydanticJson | None` |  | `None` |
| `items` | `_ItemsSchema | None` |  | `None` |
| `properties` | `_PropWireMap | None` |  | `None` |


### `MCPToolDefWire` — [`musehub/muse_contracts/mcp_types.py`](musehub/muse_contracts/mcp_types.py)

Pydantic-safe wire model for a single MCP tool definition.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `name` | `str` | ✓ | `—` |
| `description` | `str` | ✓ | `—` |
| `inputSchema` | `MCPInputSchemaWire` |  | `(factory)` |
| `annotations` | `_AnnotationsMap | None` |  | `None` |
| `server_side` | `bool | None` |  | `None` |


### `ProtocolInfoResponse` — [`musehub/protocol/responses.py`](musehub/protocol/responses.py)

Response shape for ``GET /protocol``.

**Bases:** `BaseModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `version` | `str` | ✓ | `—` |
| `protocol_hash` | `str` | ✓ | `—` |
| `event_count` | `int` | ✓ | `—` |
| `tool_count` | `int` | ✓ | `—` |


### `M` — [`tests/test_api_contracts_section37.py`](tests/test_api_contracts_section37.py)

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `owner_id` | `str` | ✓ | `—` |


### `MyModel` — [`tests/test_api_contracts_section37.py`](tests/test_api_contracts_section37.py)

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `my_field` | `str` | ✓ | `—` |


### `MyModel` — [`tests/test_api_contracts_section37.py`](tests/test_api_contracts_section37.py)

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |


### `MyModel` — [`tests/test_api_contracts_section37.py`](tests/test_api_contracts_section37.py)

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |


### `MyModel` — [`tests/test_api_contracts_section37.py`](tests/test_api_contracts_section37.py)

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |


### `MyModel` — [`tests/test_api_contracts_section37.py`](tests/test_api_contracts_section37.py)

**Bases:** `CamelModel`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `str` | ✓ | `—` |


## SQLAlchemy ORM Models

### `MusehubCoordRecord` — [`musehub/db/coord_models.py`](musehub/db/coord_models.py)

A single coordination record pushed from a Muse CLI agent.

**Bases:** `Base`

**Table:** `musehub_coord_records`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[int]` |  | `mapped_column(Integer, primary_key=True, autoincrement=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `kind` | `Mapped[str]` |  | `mapped_column(String(32), nullable=False)` |
| `record_uuid` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False)` |
| `run_id` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `payload` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `expires_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True, default=None)` |


### `MusehubCoordReservation` — [`musehub/db/coord_models.py`](musehub/db/coord_models.py)

Persistent store for muse coord reserve events synced from agents.

**Bases:** `Base`

**Table:** `musehub_coord_reservations`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `reservation_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `symbol_address` | `Mapped[str]` |  | `mapped_column(String(512), nullable=False)` |
| `agent_id` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `agent_model_id` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `ttl_s` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=300)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `expires_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False)` |
| `released_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |


### `MusehubCoordTask` — [`musehub/db/coord_models.py`](musehub/db/coord_models.py)

Persistent task queue mirroring muse coord enqueue/claim/complete.

**Bases:** `Base`

**Table:** `musehub_coord_tasks`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `task_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `queue` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='default')` |
| `priority` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=50)` |
| `payload` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False)` |
| `status` | `Mapped[str]` |  | `mapped_column(String(20), nullable=False, default='pending', index=True)` |
| `claimed_by` | `Mapped[str | None]` |  | `mapped_column(String(255), nullable=True)` |
| `claimed_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |
| `completed_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |
| `depends_on` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `run_id` | `Mapped[str | None]` |  | `mapped_column(String(255), nullable=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MuseCliCommit` — [`musehub/db/muse_cli_models.py`](musehub/db/muse_cli_models.py)

A versioned commit record pointing to a snapshot and its parent.

**Bases:** `Base`

**Table:** `muse_commits`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `Mapped[str]` |  | `mapped_column(String(64), primary_key=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False, index=True)` |
| `branch` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `parent_commit_id` | `Mapped[str | None]` |  | `mapped_column(String(64), nullable=True, index=True)` |
| `parent2_commit_id` | `Mapped[str | None]` |  | `mapped_column(String(64), nullable=True, index=True)` |
| `snapshot_id` | `Mapped[str]` |  | `mapped_column(String(64), ForeignKey('muse_snapshots.snapshot_id', ondelete='RESTRICT'), nullable=False)` |
| `message` | `Mapped[str]` |  | `mapped_column(Text, nullable=False)` |
| `author` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `committed_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `commit_metadata` | `Mapped[dict[str, object] | None]` |  | `mapped_column(JSON, nullable=True, default=None)` |


### `MuseCliObject` — [`musehub/db/muse_cli_models.py`](musehub/db/muse_cli_models.py)

A content-addressed blob: sha256(file_bytes) → bytes on disk.

**Bases:** `Base`

**Table:** `muse_objects`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `Mapped[str]` |  | `mapped_column(String(64), primary_key=True)` |
| `size_bytes` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MuseCliSnapshot` — [`musehub/db/muse_cli_models.py`](musehub/db/muse_cli_models.py)

An immutable snapshot manifest: sha256(sorted(path:object_id pairs)).

**Bases:** `Base`

**Table:** `muse_snapshots`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `Mapped[str]` |  | `mapped_column(String(64), primary_key=True)` |
| `manifest` | `Mapped[dict[str, str]]` |  | `mapped_column(JSON, nullable=False)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MuseCliTag` — [`musehub/db/muse_cli_models.py`](musehub/db/muse_cli_models.py)

A music-semantic tag attached to a Muse CLI commit.

**Bases:** `Base`

**Table:** `muse_tags`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tag_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False, index=True)` |
| `commit_id` | `Mapped[str]` |  | `mapped_column(String(64), ForeignKey('muse_commits.commit_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `tag` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, index=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MusehubAuthChallenge` — [`musehub/db/musehub_auth_models.py`](musehub/db/musehub_auth_models.py)

In-flight challenge nonce row.

**Bases:** `Base`

**Table:** `musehub_auth_challenges`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `challenge_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `nonce_hex` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `fingerprint` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `algorithm` | `Mapped[str]` |  | `mapped_column(String(32), nullable=False, default='ed25519')` |
| `expires_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False)` |


### `MusehubAuthKey` — [`musehub/db/musehub_auth_models.py`](musehub/db/musehub_auth_models.py)

One registered public key for a MuseHub identity.

**Bases:** `Base`

**Table:** `musehub_auth_keys`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `key_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `identity_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_identities.id', ondelete='CASCADE'), nullable=False)` |
| `algorithm` | `Mapped[str]` |  | `mapped_column(String(32), nullable=False, default='ed25519')` |
| `public_key_b64` | `Mapped[str]` |  | `mapped_column(Text, nullable=False)` |
| `fingerprint` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `label` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `last_used_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |


### `MusehubCollaborator` — [`musehub/db/musehub_collaborator_models.py`](musehub/db/musehub_collaborator_models.py)

A collaborator record granting a user explicit access to a repo.

**Bases:** `Base`

**Table:** `musehub_collaborators`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False)` |
| `identity_handle` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `permission` | `Mapped[str]` |  | `mapped_column(String(20), nullable=False, default='write')` |
| `invited_by_handle` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `invited_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `accepted_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |


### `MusehubDomain` — [`musehub/db/musehub_domain_models.py`](musehub/db/musehub_domain_models.py)

A registered Muse domain plugin in the MuseHub registry.

**Bases:** `Base`

**Table:** `musehub_domains`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `domain_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `author_user_id` | `Mapped[str | None]` |  | `mapped_column(String(36), nullable=True, index=True)` |
| `author_slug` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, index=True)` |
| `slug` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, index=True)` |
| `display_name` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `description` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `version` | `Mapped[str]` |  | `mapped_column(String(32), nullable=False, default='1.0.0')` |
| `manifest_hash` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, default='')` |
| `capabilities` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False, default=dict)` |
| `viewer_type` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, default='generic')` |
| `install_count` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `is_verified` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False)` |
| `is_deprecated` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |


### `MusehubDomainInstall` — [`musehub/db/musehub_domain_models.py`](musehub/db/musehub_domain_models.py)

Records a user's installation/adoption of a domain plugin.

**Bases:** `Base`

**Table:** `musehub_domain_installs`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `install_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `user_id` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False, index=True)` |
| `domain_id` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False, index=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MusehubIssueLabel` — [`musehub/db/musehub_label_models.py`](musehub/db/musehub_label_models.py)

Join table linking issues to labels.

**Bases:** `Base`

**Table:** `musehub_issue_labels`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `issue_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_issues.issue_id', ondelete='CASCADE'), primary_key=True)` |
| `label_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_labels.id', ondelete='CASCADE'), primary_key=True)` |
| `label` | `Mapped[MusehubLabel]` |  | `relationship('MusehubLabel', back_populates='issue_labels')` |


### `MusehubLabel` — [`musehub/db/musehub_label_models.py`](musehub/db/musehub_label_models.py)

A coloured label tag that can be applied to issues and proposals.

**Bases:** `Base`

**Table:** `musehub_labels`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False)` |
| `name` | `Mapped[str]` |  | `mapped_column(String(50), nullable=False)` |
| `color` | `Mapped[str]` |  | `mapped_column(String(7), nullable=False)` |
| `description` | `Mapped[str | None]` |  | `mapped_column(String(200), nullable=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `issue_labels` | `Mapped[list[MusehubIssueLabel]]` |  | `relationship('MusehubIssueLabel', back_populates='label', cascade='all, delete-orphan')` |
| `proposal_labels` | `Mapped[list[MusehubProposalLabel]]` |  | `relationship('MusehubProposalLabel', back_populates='label', cascade='all, delete-orphan')` |


### `MusehubProposalLabel` — [`musehub/db/musehub_label_models.py`](musehub/db/musehub_label_models.py)

Join table linking proposals to labels.

**Bases:** `Base`

**Table:** `musehub_proposal_labels`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `proposal_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_proposals.proposal_id', ondelete='CASCADE'), primary_key=True)` |
| `label_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_labels.id', ondelete='CASCADE'), primary_key=True)` |
| `label` | `Mapped[MusehubLabel]` |  | `relationship('MusehubLabel', back_populates='proposal_labels')` |


### `MusehubBackgroundJob` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A durable background job enqueued by the web process and processed by the worker.

**Bases:** `Base`

**Table:** `musehub_background_jobs`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `job_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `job_type` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `payload` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False, default=dict)` |
| `status` | `Mapped[str]` |  | `mapped_column(String(16), nullable=False, default='pending', index=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `claimed_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |
| `done_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |
| `attempt` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `error` | `Mapped[str | None]` |  | `mapped_column(Text, nullable=True)` |


### `MusehubBranch` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A named branch pointer inside a MuseHub repo.

**Bases:** `Base`

**Table:** `musehub_branches`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `branch_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `name` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `head_commit_id` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='branches')` |


### `MusehubCommit` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A commit record pushed to the MuseHub.

**Bases:** `Base`

**Table:** `musehub_commits`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `commit_id` | `Mapped[str]` |  | `mapped_column(String(64), primary_key=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `branch` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, index=True)` |
| `parent_ids` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `message` | `Mapped[str]` |  | `mapped_column(Text, nullable=False)` |
| `author` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `timestamp` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, index=True)` |
| `snapshot_id` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `commit_meta` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False, default=dict)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='commits')` |


### `MusehubFileIntelCache` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

Per-file IntelSnapshot cache, keyed by (repo_id, file_path).

**Bases:** `Base`

**Table:** `musehub_file_intel_cache`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `cache_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False)` |
| `file_path` | `Mapped[str]` |  | `mapped_column(String(1024), nullable=False)` |
| `ref` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `intel_json` | `Mapped[str]` |  | `mapped_column(sa.Text, nullable=False)` |
| `symbol_history_json` | `Mapped[str]` |  | `mapped_column(sa.Text, nullable=False)` |
| `computed_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MusehubFork` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

Fork relationship record — links a source repo to its forked copy.

**Bases:** `Base`

**Table:** `musehub_forks`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `fork_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `source_repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `fork_repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `forked_by` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, index=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MusehubIdentity` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

Unified identity — human, agent, or org.

**Bases:** `Base`

**Table:** `musehub_identities`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `handle` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, index=True)` |
| `identity_type` | `Mapped[str]` |  | `mapped_column(String(16), nullable=False, default='human')` |
| `display_name` | `Mapped[str | None]` |  | `mapped_column(String(255), nullable=True)` |
| `bio` | `Mapped[str | None]` |  | `mapped_column(Text, nullable=True)` |
| `avatar_url` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `website_url` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `email` | `Mapped[str | None]` |  | `mapped_column(String(255), nullable=True, index=True)` |
| `agent_model` | `Mapped[str | None]` |  | `mapped_column(String(255), nullable=True)` |
| `agent_capabilities` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `location` | `Mapped[str | None]` |  | `mapped_column(String(255), nullable=True)` |
| `social_url` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `is_verified` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False, index=True)` |
| `cc_license` | `Mapped[str | None]` |  | `mapped_column(String(50), nullable=True)` |
| `pinned_repo_ids` | `Mapped[list]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |
| `deleted_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True, default=None)` |
| `spawned_by` | `Mapped[str | None]` |  | `mapped_column(String(64), nullable=True, index=True)` |
| `scope` | `Mapped[list[str] | None]` |  | `mapped_column(JSON, nullable=True)` |
| `expires_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True, index=True)` |
| `tos_accepted_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True, default=None)` |
| `tos_version` | `Mapped[str | None]` |  | `mapped_column(String(16), nullable=True, default=None)` |


### `MusehubIssue` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

An issue opened against a MuseHub repo.

**Bases:** `Base`

**Table:** `musehub_issues`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `issue_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `number` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, index=True)` |
| `title` | `Mapped[str]` |  | `mapped_column(String(500), nullable=False)` |
| `body` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `state` | `Mapped[str]` |  | `mapped_column(String(20), nullable=False, default='open', index=True)` |
| `labels` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `symbol_anchors` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `commit_anchors` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `author` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `assignee` | `Mapped[str | None]` |  | `mapped_column(String(255), nullable=True)` |
| `agent_id` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `model_id` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='issues')` |
| `comments` | `Mapped[list[MusehubIssueComment]]` |  | `relationship('MusehubIssueComment', back_populates='issue', cascade='all, delete-orphan', order_by='MusehubIssueComment.created_at')` |
| `events` | `Mapped[list[MusehubIssueEvent]]` |  | `relationship('MusehubIssueEvent', back_populates='issue', cascade='all, delete-orphan', order_by='MusehubIssueEvent.created_at')` |


### `MusehubIssueComment` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A comment in a threaded discussion on a MuseHub issue.

**Bases:** `Base`

**Table:** `musehub_issue_comments`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `comment_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `issue_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_issues.issue_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `author` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `body` | `Mapped[str]` |  | `mapped_column(Text, nullable=False)` |
| `parent_id` | `Mapped[str | None]` |  | `mapped_column(String(36), nullable=True, index=True)` |
| `is_deleted` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, index=True)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |
| `issue` | `Mapped[MusehubIssue]` |  | `relationship('MusehubIssue', back_populates='comments')` |


### `MusehubIssueEvent` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A typed activity event on a MuseHub issue (Phase 4B).

**Bases:** `Base`

**Table:** `musehub_issue_events`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `event_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `issue_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_issues.issue_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `actor` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `event_type` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `payload` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False, default=dict)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, index=True)` |
| `issue` | `Mapped[MusehubIssue]` |  | `relationship('MusehubIssue', back_populates='events')` |


### `MusehubObject` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A binary artifact (MIDI, MP3, WebP piano roll) stored in MuseHub.

**Bases:** `Base`

**Table:** `musehub_objects`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `object_id` | `Mapped[str]` |  | `mapped_column(String(128), primary_key=True)` |
| `path` | `Mapped[str]` |  | `mapped_column(String(1024), nullable=False)` |
| `size_bytes` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `storage_uri` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `content_cache` | `Mapped[bytes | None]` |  | `mapped_column(sa.LargeBinary, nullable=True, default=None)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `deleted_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True, default=None)` |


### `MusehubProposal` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A merge proposal — the V2 name for a proposal.

**Bases:** `Base`

**Table:** `musehub_proposals`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `proposal_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `proposal_number` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False)` |
| `title` | `Mapped[str]` |  | `mapped_column(String(500), nullable=False)` |
| `body` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `state` | `Mapped[str]` |  | `mapped_column(String(20), nullable=False, default='open', index=True)` |
| `from_branch` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `to_branch` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `merge_commit_id` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `merged_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |
| `author` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |
| `domain_diff` | `Mapped[dict[str, object] | None]` |  | `mapped_column(JSON, nullable=True, default=None)` |
| `risk_score` | `Mapped[float | None]` |  | `mapped_column(sa.Float, nullable=True)` |
| `blast_delta` | `Mapped[float | None]` |  | `mapped_column(sa.Float, nullable=True)` |
| `breakage_count` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `test_gap_count` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `symbols_changed` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `touched_symbols` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='proposals')` |
| `reviews` | `Mapped[list[MusehubProposalReview]]` |  | `relationship('MusehubProposalReview', back_populates='proposal', cascade='all, delete-orphan')` |
| `review_comments` | `Mapped[list[MusehubProposalComment]]` |  | `relationship('MusehubProposalComment', back_populates='proposal', cascade='all, delete-orphan')` |


### `MusehubProposalComment` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

Inline review comment on a dimensional diff within a merge proposal.

**Bases:** `Base`

**Table:** `musehub_proposal_comments`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `comment_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `proposal_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_proposals.proposal_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False, index=True)` |
| `author` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `body` | `Mapped[str]` |  | `mapped_column(Text, nullable=False)` |
| `dimension_ref` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False, default=dict)` |
| `symbol_address` | `Mapped[str | None]` |  | `mapped_column(String(512), nullable=True)` |
| `parent_comment_id` | `Mapped[str | None]` |  | `mapped_column(String(36), nullable=True, index=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, index=True)` |
| `proposal` | `Mapped[MusehubProposal]` |  | `relationship('MusehubProposal', back_populates='review_comments')` |


### `MusehubProposalReview` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A formal review submission on a merge proposal.

**Bases:** `Base`

**Table:** `musehub_proposal_reviews`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `proposal_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_proposals.proposal_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `reviewer_username` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, index=True)` |
| `state` | `Mapped[str]` |  | `mapped_column(String(30), nullable=False, default='pending', index=True)` |
| `body` | `Mapped[str | None]` |  | `mapped_column(Text, nullable=True)` |
| `submitted_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `proposal` | `Mapped[MusehubProposal]` |  | `relationship('MusehubProposal', back_populates='reviews')` |


### `MusehubRelease` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A published version release for a MuseHub repo.

**Bases:** `Base`

**Table:** `musehub_releases`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `release_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `tag` | `Mapped[str]` |  | `mapped_column(String(100), nullable=False, index=True)` |
| `title` | `Mapped[str]` |  | `mapped_column(String(500), nullable=False, default='')` |
| `body` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `commit_id` | `Mapped[str | None]` |  | `mapped_column(String(2048), nullable=True)` |
| `snapshot_id` | `Mapped[str | None]` |  | `mapped_column(String(128), nullable=True)` |
| `semver_major` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `semver_minor` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `semver_patch` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `semver_pre` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `semver_build` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `channel` | `Mapped[str]` |  | `mapped_column(String(20), nullable=False, default='stable', index=True)` |
| `download_urls` | `Mapped[dict[str, str]]` |  | `mapped_column(JSON, nullable=False, default=dict)` |
| `author` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `agent_id` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `model_id` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `changelog_json` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='[]')` |
| `is_draft` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False)` |
| `gpg_signature` | `Mapped[str | None]` |  | `mapped_column(Text, nullable=True)` |
| `semantic_report_json` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='releases')` |
| `assets` | `Mapped[list[MusehubReleaseAsset]]` |  | `relationship('MusehubReleaseAsset', back_populates='release', cascade='all, delete-orphan')` |


### `MusehubReleaseAsset` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

An asset (file attachment) associated with a MuseHub release.

**Bases:** `Base`

**Table:** `musehub_release_assets`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `asset_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `release_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_releases.release_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False, index=True)` |
| `name` | `Mapped[str]` |  | `mapped_column(String(500), nullable=False)` |
| `label` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='')` |
| `content_type` | `Mapped[str]` |  | `mapped_column(String(128), nullable=False, default='')` |
| `size` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `download_url` | `Mapped[str]` |  | `mapped_column(String(2048), nullable=False)` |
| `download_count` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `release` | `Mapped[MusehubRelease]` |  | `relationship('MusehubRelease', back_populates='assets')` |


### `MusehubRepo` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A remote Muse repository — the hub-side equivalent of a Git remote.

**Bases:** `Base`

**Table:** `musehub_repos`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `name` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False)` |
| `owner` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, index=True)` |
| `slug` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, index=True)` |
| `visibility` | `Mapped[str]` |  | `mapped_column(String(20), nullable=False, default='public')` |
| `owner_user_id` | `Mapped[str]` |  | `mapped_column(String(36), nullable=False, index=True)` |
| `description` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `tags` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `domain_id` | `Mapped[str | None]` |  | `mapped_column(String(36), nullable=True, index=True)` |
| `domain_meta` | `Mapped[dict[str, object]]` |  | `mapped_column(JSON, nullable=False, default=dict)` |
| `settings` | `Mapped[dict[str, object] | None]` |  | `mapped_column(JSON, nullable=True)` |
| `default_branch` | `Mapped[str]` |  | `mapped_column(String(255), nullable=False, default='main')` |
| `pushed_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True, default=None)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |
| `deleted_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True, default=None)` |
| `training_opt_out` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False)` |
| `branches` | `Mapped[list[MusehubBranch]]` |  | `relationship('MusehubBranch', back_populates='repo', cascade='all, delete-orphan')` |
| `commits` | `Mapped[list[MusehubCommit]]` |  | `relationship('MusehubCommit', back_populates='repo', cascade='all, delete-orphan')` |
| `objects` | `Mapped[list[MusehubObject]]` |  | `relationship('MusehubObject', back_populates='repo', cascade='all, delete-orphan')` |
| `issues` | `Mapped[list[MusehubIssue]]` |  | `relationship('MusehubIssue', back_populates='repo', cascade='all, delete-orphan')` |
| `proposals` | `Mapped[list[MusehubProposal]]` |  | `relationship('MusehubProposal', back_populates='repo', cascade='all, delete-orphan')` |
| `releases` | `Mapped[list[MusehubRelease]]` |  | `relationship('MusehubRelease', back_populates='repo', cascade='all, delete-orphan')` |
| `sessions` | `Mapped[list[MusehubSession]]` |  | `relationship('MusehubSession', back_populates='repo', cascade='all, delete-orphan')` |
| `webhooks` | `Mapped[list[MusehubWebhook]]` |  | `relationship('MusehubWebhook', back_populates='repo', cascade='all, delete-orphan')` |
| `wire_tags` | `Mapped[list[MusehubWireTag]]` |  | `relationship('MusehubWireTag', back_populates='repo', cascade='all, delete-orphan')` |


### `MusehubSession` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A recording session record pushed to MuseHub from the CLI.

**Bases:** `Base`

**Table:** `musehub_sessions`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `session_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `schema_version` | `Mapped[str]` |  | `mapped_column(String(10), nullable=False, default='1')` |
| `started_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, index=True)` |
| `ended_at` | `Mapped[datetime | None]` |  | `mapped_column(DateTime(timezone=True), nullable=True)` |
| `participants` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `location` | `Mapped[str]` |  | `mapped_column(String(500), nullable=False, default='')` |
| `intent` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `commits` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `notes` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `is_active` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False, index=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='sessions')` |


### `MusehubSnapshot` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

Immutable file-tree record stored alongside commits.

**Bases:** `Base`

**Table:** `musehub_snapshots`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `snapshot_id` | `Mapped[str]` |  | `mapped_column(String(128), primary_key=True)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `directories` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `manifest_blob` | `Mapped[bytes]` |  | `mapped_column(sa.LargeBinary, nullable=False)` |
| `entry_count` | `Mapped[int]` |  | `mapped_column(Integer(), nullable=False, default=0)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |



### `MusehubSymbolIndex` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

Materialized symbol intelligence cache for a repo at a given commit.

**Bases:** `Base`

**Table:** `musehub_symbol_index`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `index_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `ref` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `symbol_history` | `Mapped[bytes | None]` |  | `mapped_column(sa.LargeBinary, nullable=True)` |
| `hash_occurrence` | `Mapped[bytes | None]` |  | `mapped_column(sa.LargeBinary, nullable=True)` |
| `intel_summary` | `Mapped[str | None]` |  | `mapped_column(sa.Text, nullable=True)` |
| `intel_full_json` | `Mapped[str | None]` |  | `mapped_column(sa.Text, nullable=True)` |
| `per_symbol_intel_json` | `Mapped[str | None]` |  | `mapped_column(sa.Text, nullable=True)` |
| `built_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |


### `MusehubWebhook` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A registered webhook subscription for a MuseHub repo.

**Bases:** `Base`

**Table:** `musehub_webhooks`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `webhook_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `url` | `Mapped[str]` |  | `mapped_column(String(2048), nullable=False)` |
| `events` | `Mapped[list[str]]` |  | `mapped_column(JSON, nullable=False, default=list)` |
| `secret` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `active` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `updated_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now, onupdate=_utc_now)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='webhooks')` |
| `deliveries` | `Mapped[list[MusehubWebhookDelivery]]` |  | `relationship('MusehubWebhookDelivery', back_populates='webhook', cascade='all, delete-orphan')` |


### `MusehubWebhookDelivery` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

One delivery attempt for a webhook event.

**Bases:** `Base`

**Table:** `musehub_webhook_deliveries`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `delivery_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `webhook_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_webhooks.webhook_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `event_type` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False, index=True)` |
| `payload` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `attempt` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=1)` |
| `success` | `Mapped[bool]` |  | `mapped_column(Boolean, nullable=False, default=False)` |
| `response_status` | `Mapped[int]` |  | `mapped_column(Integer, nullable=False, default=0)` |
| `response_body` | `Mapped[str]` |  | `mapped_column(Text, nullable=False, default='')` |
| `delivered_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `webhook` | `Mapped[MusehubWebhook]` |  | `relationship('MusehubWebhook', back_populates='deliveries')` |


### `MusehubWireTag` — [`musehub/db/musehub_models.py`](musehub/db/musehub_models.py)

A lightweight tag pushed from a Muse CLI client via the wire protocol.

**Bases:** `Base`

**Table:** `musehub_wire_tags`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `tag_id` | `Mapped[str]` |  | `mapped_column(String(36), primary_key=True, default=_new_uuid)` |
| `repo_id` | `Mapped[str]` |  | `mapped_column(String(36), ForeignKey('musehub_repos.repo_id', ondelete='CASCADE'), nullable=False, index=True)` |
| `commit_id` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `tag` | `Mapped[str]` |  | `mapped_column(String(500), nullable=False, index=True)` |
| `created_at` | `Mapped[datetime]` |  | `mapped_column(DateTime(timezone=True), nullable=False, default=_utc_now)` |
| `repo` | `Mapped[MusehubRepo]` |  | `relationship('MusehubRepo', back_populates='wire_tags')` |


### `_A` — [`tests/test_schema_check.py`](tests/test_schema_check.py)

**Bases:** `_ABase`

**Table:** `a_table`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[int]` |  | `mapped_column(Integer, primary_key=True)` |
| `python_name` | `Mapped[str | None]` |  | `mapped_column('db_name', String(64), nullable=True)` |


### `_A` — [`tests/test_schema_check.py`](tests/test_schema_check.py)

**Bases:** `_ABase`

**Table:** `atbl`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[int]` |  | `mapped_column(Integer, primary_key=True)` |
| `py_name` | `Mapped[str | None]` |  | `mapped_column('db_name', String(64), nullable=True)` |


### `_B` — [`tests/test_schema_check.py`](tests/test_schema_check.py)

**Bases:** `_BBase`

**Table:** `btbl`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[int]` |  | `mapped_column(Integer, primary_key=True)` |
| `new_name` | `Mapped[str | None]` |  | `mapped_column('old_name', String(64), nullable=True)` |


### `_Clean` — [`tests/test_schema_check.py`](tests/test_schema_check.py)

**Bases:** `_CleanBase`

**Table:** `clean`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[int]` |  | `mapped_column(Integer, primary_key=True)` |
| `value` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |


### `_Gadget` — [`tests/test_schema_check.py`](tests/test_schema_check.py)

**Bases:** `_TestBase`

**Table:** `gadgets`

| Field | Type | Required | Default |
|-------|------|:--------:|---------|
| `id` | `Mapped[int]` |  | `mapped_column(Integer, primary_key=True)` |
| `serial` | `Mapped[str]` |  | `mapped_column(String(64), nullable=False)` |
| `notes` | `Mapped[str | None]` |  | `mapped_column(String(256), nullable=True)` |


## Protocols

### `StorageBackend` — [`musehub/storage/backends.py`](musehub/storage/backends.py)

Content-addressed binary store protocol.

**Bases:** `Protocol`

_No annotated fields._


### `_S3Client` — [`musehub/storage/backends.py`](musehub/storage/backends.py)

**Bases:** `Protocol`

_No annotated fields._


### `_S3Response` — [`musehub/storage/backends.py`](musehub/storage/backends.py)

**Bases:** `Protocol`

_No annotated fields._


### `_StreamingBody` — [`musehub/storage/backends.py`](musehub/storage/backends.py)

**Bases:** `Protocol`

_No annotated fields._