Add friendly names system for recipes, effects, and media

- Add friendly_names table with unique constraints per actor
- Create NamingService with HMAC-signed timestamp version IDs
- Version IDs use base32-crockford encoding, always increase alphabetically
- Name normalization: spaces/underscores to dashes, lowercase, strip special chars
- Format: "my-effect 01hw3x9k" (space separator ensures uniqueness)
- Integrate naming into recipe, effect, and media uploads
- Resolve friendly names to CIDs during DAG execution
- Update effects UI to display friendly names
- Add 30 tests covering normalization, parsing, and service structure

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/routers/cache.py

@@ -224,9 +224,21 @@ async def upload_content(
     if error:
         raise HTTPException(400, error)
 
+    # Assign friendly name (use IPFS CID if available, otherwise local hash)
+    final_cid = ipfs_cid or cid
+    from ..services.naming_service import get_naming_service
+    naming = get_naming_service()
+    friendly_entry = await naming.assign_name(
+        cid=final_cid,
+        actor_id=ctx.actor_id,
+        item_type="media",
+        filename=file.filename,
+    )
+
     return {
-        "cid": ipfs_cid or cid,
+        "cid": final_cid,
         "content_hash": cid,  # Legacy, for backwards compatibility
+        "friendly_name": friendly_entry["friendly_name"],
         "filename": file.filename,
         "size": len(content),
         "uploaded": True,

app/routers/effects.py

@@ -200,12 +200,24 @@ async def upload_effect(
     # Also store metadata in IPFS for discoverability
     meta_cid = ipfs_client.add_json(full_meta)
 
-    logger.info(f"Uploaded effect '{meta.get('name')}' cid={cid} by {ctx.actor_id}")
+    # Assign friendly name
+    from ..services.naming_service import get_naming_service
+    naming = get_naming_service()
+    friendly_entry = await naming.assign_name(
+        cid=cid,
+        actor_id=ctx.actor_id,
+        item_type="effect",
+        display_name=meta.get("name"),
+        filename=file.filename,
+    )
+
+    logger.info(f"Uploaded effect '{meta.get('name')}' cid={cid} friendly_name='{friendly_entry['friendly_name']}' by {ctx.actor_id}")
 
     return {
         "cid": cid,
         "metadata_cid": meta_cid,
         "name": meta.get("name"),
+        "friendly_name": friendly_entry["friendly_name"],
         "version": meta.get("version"),
         "temporal": meta.get("temporal", False),
         "params": meta.get("params", []),
@@ -244,6 +256,15 @@ async def get_effect(
         meta = {"cid": cid, "meta": parsed_meta}
         (effect_dir / "metadata.json").write_text(json.dumps(meta, indent=2))
 
+    # Add friendly name if available
+    from ..services.naming_service import get_naming_service
+    naming = get_naming_service()
+    friendly = await naming.get_by_cid(ctx.actor_id, cid)
+    if friendly:
+        meta["friendly_name"] = friendly["friendly_name"]
+        meta["base_name"] = friendly["base_name"]
+        meta["version_id"] = friendly["version_id"]
+
     if wants_json(request):
         return meta
 
@@ -295,6 +316,10 @@ async def list_effects(
     effects_dir = get_effects_dir()
     effects = []
 
+    # Get naming service for friendly name lookup
+    from ..services.naming_service import get_naming_service
+    naming = get_naming_service()
+
     if effects_dir.exists():
         for effect_dir in effects_dir.iterdir():
             if effect_dir.is_dir():
@@ -302,6 +327,13 @@ async def list_effects(
                 if metadata_path.exists():
                     try:
                         meta = json.loads(metadata_path.read_text())
+                        # Add friendly name if available
+                        cid = meta.get("cid")
+                        if cid:
+                            friendly = await naming.get_by_cid(ctx.actor_id, cid)
+                            if friendly:
+                                meta["friendly_name"] = friendly["friendly_name"]
+                                meta["base_name"] = friendly["base_name"]
                         effects.append(meta)
                     except json.JSONDecodeError:
                         pass

app/routers/recipes.py

@@ -158,13 +158,59 @@ def bind_inputs(
     return warnings
 
 
-def prepare_dag_for_execution(
+async def resolve_friendly_names_in_registry(
+    registry: dict,
+    actor_id: str,
+) -> dict:
+    """
+    Resolve friendly names to CIDs in the registry.
+
+    Friendly names are identified by containing a space (e.g., "brightness 01hw3x9k")
+    or by not being a valid CID format.
+    """
+    from ..services.naming_service import get_naming_service
+    import re
+
+    naming = get_naming_service()
+    resolved = {"assets": {}, "effects": {}}
+
+    # CID patterns: IPFS CID (Qm..., bafy...) or SHA256 hash (64 hex chars)
+    cid_pattern = re.compile(r'^(Qm[a-zA-Z0-9]{44}|bafy[a-zA-Z0-9]+|[a-f0-9]{64})$')
+
+    for asset_name, asset_info in registry.get("assets", {}).items():
+        cid = asset_info.get("cid", "")
+        if cid and not cid_pattern.match(cid):
+            # Looks like a friendly name, resolve it
+            resolved_cid = await naming.resolve(actor_id, cid, item_type="media")
+            if resolved_cid:
+                asset_info = dict(asset_info)
+                asset_info["cid"] = resolved_cid
+                asset_info["_resolved_from"] = cid
+        resolved["assets"][asset_name] = asset_info
+
+    for effect_name, effect_info in registry.get("effects", {}).items():
+        cid = effect_info.get("cid", "")
+        if cid and not cid_pattern.match(cid):
+            # Looks like a friendly name, resolve it
+            resolved_cid = await naming.resolve(actor_id, cid, item_type="effect")
+            if resolved_cid:
+                effect_info = dict(effect_info)
+                effect_info["cid"] = resolved_cid
+                effect_info["_resolved_from"] = cid
+        resolved["effects"][effect_name] = effect_info
+
+    return resolved
+
+
+async def prepare_dag_for_execution(
     recipe: Recipe,
     user_inputs: Dict[str, str],
+    actor_id: str = None,
 ) -> Tuple[str, List[str]]:
     """
     Prepare a recipe DAG for execution by transforming nodes and binding inputs.
 
+    Resolves friendly names to CIDs if actor_id is provided.
     Returns (dag_json, warnings).
     """
     recipe_dag = recipe.get("dag")
@@ -177,6 +223,11 @@ def prepare_dag_for_execution(
 
     # Get registry for resolving references
     registry = recipe.get("registry", {})
+
+    # Resolve friendly names to CIDs
+    if actor_id and registry:
+        registry = await resolve_friendly_names_in_registry(registry, actor_id)
+
     assets = registry.get("assets", {}) if registry else {}
     effects = registry.get("effects", {}) if registry else {}
 
@@ -506,10 +557,10 @@ async def run_recipe(
         # Create run using run service
         run_service = RunService(database, get_redis_client(), get_cache_manager())
 
-        # Prepare DAG for execution (transform nodes, bind inputs)
+        # Prepare DAG for execution (transform nodes, bind inputs, resolve friendly names)
         dag_json = None
         if recipe.get("dag"):
-            dag_json, warnings = prepare_dag_for_execution(recipe, req.inputs)
+            dag_json, warnings = await prepare_dag_for_execution(recipe, req.inputs, actor_id=ctx.actor_id)
             for warning in warnings:
                 logger.warning(warning)