fix(storage): canonicalize shorthand namespace URIs on write (#1929)

Author: ehz0ah

docs/en/concepts/04-viking-uri.md

@@ -99,6 +99,11 @@ viking://agent/memories/patterns/             # Learned patterns
 viking://agent/instructions/                  # Agent instructions
 ```
 
+The short `viking://user/...` and `viking://agent/...` forms above are
+relative to the current request identity. OpenViking expands them internally to
+explicit namespace paths such as `viking://user/{user_id}/...` and
+`viking://agent/{agent_id}/...` before storage and retrieval.
+
 ### Session Data
 
 ```

docs/en/concepts/05-storage.md

@@ -41,9 +41,9 @@ VikingFS is the unified URI abstraction layer that hides underlying storage deta
 ### URI Mapping
 
 ```
-viking://resources/docs/auth  →  /local/resources/docs/auth
-viking://user/memories        →  /local/user/memories
-viking://agent/skills         →  /local/agent/skills
+viking://resources/docs/auth  →  /local/{account_id}/resources/docs/auth
+viking://user/memories        →  /local/{account_id}/user/{user_id}/memories
+viking://agent/skills         →  /local/{account_id}/agent/{agent_id}/skills
 ```
 
 ### Core API

docs/zh/concepts/04-viking-uri.md

@@ -98,6 +98,10 @@ viking://agent/memories/patterns/             # 学习的模式
 viking://agent/instructions/                  # Agent 指令
 ```
 
+上面的 `viking://user/...` 和 `viking://agent/...` 短路径会按当前请求身份解析。
+OpenViking 会在存储和检索前将它们展开为显式命名空间路径，例如
+`viking://user/{user_id}/...` 和 `viking://agent/{agent_id}/...`。
+
 ### 会话数据
 
 ```

docs/zh/concepts/05-storage.md

@@ -39,9 +39,9 @@ VikingFS 是统一的 URI 抽象层，屏蔽底层存储细节。
 ### URI 映射
 
 ```
-viking://resources/docs/auth  →  /local/resources/docs/auth
-viking://user/memories        →  /local/user/memories
-viking://agent/skills         →  /local/agent/skills
+viking://resources/docs/auth  →  /local/{account_id}/resources/docs/auth
+viking://user/memories        →  /local/{account_id}/user/{user_id}/memories
+viking://agent/skills         →  /local/{account_id}/agent/{agent_id}/skills
 ```
 
 ### 核心 API

openviking/core/namespace.py

@@ -101,7 +101,11 @@ def uri_parts(uri: str) -> list[str]:
 
 def _content_segment_index(parts: tuple[str, ...]) -> Optional[int]:
     """Return the first content segment after a user/agent namespace root."""
-    if len(parts) < 3 or parts[0] not in _CONTENT_TYPES_BY_SCOPE:
+    if len(parts) < 2 or parts[0] not in _CONTENT_TYPES_BY_SCOPE:
+        return None
+    if parts[1] in _CONTENT_TYPES_BY_SCOPE[parts[0]]:
+        return 1
+    if len(parts) < 3:
         return None
     cross_scope_segment = _CROSS_SCOPE_OWNER_SEGMENT[parts[0]]
     if len(parts) >= 5 and parts[2] == cross_scope_segment:

openviking/storage/content_write.py

@@ -7,7 +7,7 @@
 import os
 from typing import Any, Dict, Optional
 
-from openviking.core.namespace import context_type_for_uri
+from openviking.core.namespace import NamespaceShapeError, canonicalize_uri, context_type_for_uri
 from openviking.resource.watch_storage import is_watch_task_control_uri
 from openviking.server.identity import RequestContext
 from openviking.session.memory.utils.content import deserialize_full, serialize_with_metadata
@@ -52,7 +52,10 @@ async def write(
         wait: bool = False,
         timeout: Optional[float] = None,
     ) -> Dict[str, Any]:
-        normalized_uri = VikingURI.normalize(uri)
+        try:
+            normalized_uri = canonicalize_uri(uri, ctx)
+        except NamespaceShapeError as exc:
+            raise InvalidArgumentError(str(exc)) from exc
         self._validate_mode(mode)
         self._validate_target_uri(normalized_uri)
 

openviking/storage/queuefs/embedding_msg_converter.py

@@ -34,14 +34,19 @@ def from_context(context: Context) -> EmbeddingMsg:
         if not context_data.get("account_id"):
             user = context_data.get("user") or {}
             context_data["account_id"] = user.get("account_id", "default")
-        if context_data.get("owner_user_id") is None and context_data.get("owner_agent_id") is None:
+        uri = context_data.get("uri", "")
+        owner_fields = None
+        if uri:
             owner_fields = owner_fields_for_uri(
-                context_data.get("uri", ""),
+                uri,
                 user=context.user,
                 account_id=context_data.get("account_id"),
             )
-            context_data["owner_user_id"] = owner_fields["owner_user_id"]
-            context_data["owner_agent_id"] = owner_fields["owner_agent_id"]
+            context_data["uri"] = owner_fields["uri"]
+        if context_data.get("owner_user_id") is None and context_data.get("owner_agent_id") is None:
+            if owner_fields is not None:
+                context_data["owner_user_id"] = owner_fields["owner_user_id"]
+                context_data["owner_agent_id"] = owner_fields["owner_agent_id"]
 
         # Derive level field for hierarchical retrieval.
         uri = context_data.get("uri", "")

tests/server/test_content_write_service.py

@@ -510,6 +510,62 @@ async def _fake_wait_for_queues(*, timeout):
     assert write_calls == [(file_uri, "new content")]
 
 
+@pytest.mark.asyncio
+async def test_create_mode_canonicalizes_user_shorthand_memory_uri(monkeypatch):
+    input_uri = "viking://user/memories/new_file.md"
+    canonical_uri = "viking://user/default/memories/new_file.md"
+    root_uri = "viking://user/default/memories"
+    ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
+    viking_fs = _FakeVikingFSForCreate(
+        file_uri=canonical_uri,
+        root_uri=root_uri,
+        file_exists=False,
+    )
+    coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
+    lock_manager = _FakeLockManager()
+
+    monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
+
+    write_calls = []
+    vectorize_calls = []
+    refresh_calls = []
+
+    async def _fake_write_in_place(uri, content, *, mode, ctx):
+        del mode, ctx
+        write_calls.append((uri, content))
+        return content
+
+    async def _fake_vectorize_single_file(uri, *, context_type, ctx):
+        del ctx
+        vectorize_calls.append((uri, context_type))
+        return None
+
+    async def _fake_enqueue_memory_refresh(**kwargs):
+        refresh_calls.append(kwargs)
+        return None
+
+    async def _fake_wait_for_queues(*, timeout):
+        del timeout
+        return None
+
+    monkeypatch.setattr(coordinator, "_write_in_place", _fake_write_in_place)
+    monkeypatch.setattr(coordinator, "_vectorize_single_file", _fake_vectorize_single_file)
+    monkeypatch.setattr(coordinator, "_enqueue_memory_refresh", _fake_enqueue_memory_refresh)
+    monkeypatch.setattr(coordinator, "_wait_for_queues", _fake_wait_for_queues)
+
+    result = await coordinator.write(
+        uri=input_uri, content="new content", mode="create", ctx=ctx, wait=True
+    )
+
+    assert result["uri"] == canonical_uri
+    assert result["root_uri"] == root_uri
+    assert result["context_type"] == "memory"
+    assert write_calls == [(canonical_uri, "new content")]
+    assert vectorize_calls == [(canonical_uri, "memory")]
+    assert refresh_calls[0]["root_uri"] == root_uri
+    assert refresh_calls[0]["modified_uri"] == canonical_uri
+
+
 @pytest.mark.asyncio
 async def test_create_mode_existing_file_raises_409(monkeypatch):
     file_uri = "viking://user/default/memories/existing.md"

tests/storage/test_embedding_msg_converter_tenant.py

@@ -11,27 +11,30 @@
 
 
 @pytest.mark.parametrize(
-    ("uri", "expected_owner_user_id", "expected_owner_agent_id"),
+    ("uri", "expected_uri", "expected_owner_user_id", "expected_owner_agent_id"),
     [
         (
             "viking://user/memories/preferences/me.md",
+            lambda user: f"viking://user/{user.user_id}/memories/preferences/me.md",
             lambda user: user.user_id,
             None,
         ),
         (
             "viking://agent/memories/cases/me.md",
+            lambda user: f"viking://agent/{user.agent_id}/memories/cases/me.md",
             None,
             lambda user: user.agent_id,
         ),
         (
+            "viking://resources/doc.md",
             "viking://resources/doc.md",
             None,
             None,
         ),
     ],
 )
 def test_embedding_msg_converter_backfills_account_and_owner_fields(
-    uri, expected_owner_user_id, expected_owner_agent_id
+    uri, expected_uri, expected_owner_user_id, expected_owner_agent_id
 ):
     user = UserIdentifier("acme", "alice", "helper")
     context = Context(uri=uri, abstract="hello", user=user)
@@ -45,6 +48,8 @@ def test_embedding_msg_converter_backfills_account_and_owner_fields(
 
     assert msg is not None
     assert msg.context_data["account_id"] == "acme"
+    resolved_uri = expected_uri(user) if callable(expected_uri) else expected_uri
+    assert msg.context_data["uri"] == resolved_uri
     expected_user = (
         expected_owner_user_id(user) if callable(expected_owner_user_id) else expected_owner_user_id
     )

tests/unit/test_namespace_uri_classification.py

@@ -13,6 +13,9 @@
 
 def test_context_type_for_uri_uses_path_segments():
     assert context_type_for_uri("viking://user/alice/memories/entities/m1.md") == "memory"
+    assert context_type_for_uri("viking://user/memories/entities/m1.md") == "memory"
+    assert context_type_for_uri("viking://agent/memories/cases/m1.md") == "memory"
+    assert context_type_for_uri("viking://agent/skills/demo") == "skill"
     assert context_type_for_uri("viking://agent/default/memories/cases/m1.md") == "memory"
     assert (
         context_type_for_uri("viking://user/alice/agent/default/memories/entities/m1.md")
@@ -27,10 +30,12 @@ def test_context_type_for_uri_uses_path_segments():
 def test_exact_memory_and_skill_root_detection():
     assert classify_uri("viking://user/alice/memories/preferences/prefs.md").is_memory
     assert classify_uri("viking://user/alice/memories").is_memory_root
+    assert classify_uri("viking://user/memories").is_memory_root
     assert not classify_uri("viking://user/alice/memories/preferences").is_memory_root
 
     assert classify_uri("viking://agent/default/skills/demo/SKILL.md").is_skill
     assert classify_uri("viking://agent/default/skills/demo").is_skill_root
+    assert classify_uri("viking://agent/skills/demo").is_skill_root
     assert not classify_uri("viking://agent/default/skills").is_skill_root
     assert not classify_uri("viking://agent/default/skills/demo/assets").is_skill_root