Add clarifying comments for Asset/AssetReference naming and preview_id

Amp-Thread-ID: https://ampcode.com/threads/T-019cef49-f94e-7348-bf23-9a19ebf65e0d
Co-authored-by: Amp <amp@ampcode.com>

app/assets/api/schemas_in.py

@@ -101,7 +101,7 @@ class UpdateAssetBody(BaseModel):
     name: str | None = None
     user_metadata: dict[str, Any] | None = None
     mime_type: str | None = None
-    preview_id: str | None = None
+    preview_id: str | None = None  # references an asset_reference id, not an asset id
 
     @model_validator(mode="after")
     def _validate_at_least_one_field(self):
@@ -123,7 +123,7 @@ class CreateFromHashBody(BaseModel):
     tags: list[str] = Field(default_factory=list)
     user_metadata: dict[str, Any] = Field(default_factory=dict)
     mime_type: str | None = None
-    preview_id: str | None = None
+    preview_id: str | None = None  # references an asset_reference id, not an asset id
 
     @field_validator("hash")
     @classmethod
@@ -241,7 +241,7 @@ class UploadAssetSpec(BaseModel):
     - user_metadata: arbitrary JSON object (optional)
     - hash: optional canonical 'blake3:<hex>' for validation / fast-path
     - mime_type: optional MIME type override
-    - preview_id: optional asset ID for preview
+    - preview_id: optional asset_reference ID for preview
 
     Files are stored using the content hash as filename stem.
     """
@@ -253,7 +253,7 @@ class UploadAssetSpec(BaseModel):
     user_metadata: dict[str, Any] = Field(default_factory=dict)
     hash: str | None = Field(default=None)
     mime_type: str | None = Field(default=None)
-    preview_id: str | None = Field(default=None)
+    preview_id: str | None = Field(default=None)  # references an asset_reference id
 
     @field_validator("hash", mode="before")
     @classmethod

app/assets/api/schemas_out.py

@@ -5,6 +5,9 @@ from pydantic import BaseModel, ConfigDict, Field, field_serializer
 
 
 class Asset(BaseModel):
+    """API view of an asset. Maps to DB ``AssetReference`` joined with its ``Asset`` blob;
+    ``id`` here is the AssetReference id, not the content-addressed Asset id."""
+
     id: str
     name: str
     asset_hash: str | None = None
@@ -12,7 +15,7 @@ class Asset(BaseModel):
     mime_type: str | None = None
     tags: list[str] = Field(default_factory=list)
     preview_url: str | None = None
-    preview_id: str | None = None
+    preview_id: str | None = None  # references an asset_reference id, not an asset id
     user_metadata: dict[str, Any] = Field(default_factory=dict)
     is_immutable: bool = False
     metadata: dict[str, Any] | None = None