Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(system): 建立 Account 级 system 目录与资产同步 (#6374)

hezhang-12164c29ed7ff085
diff --git a/bot/vikingbot/compile/service.py b/bot/vikingbot/compile/service.py
index 12a76b137..d4e408650 100644
--- a/bot/vikingbot/compile/service.py
+++ b/bot/vikingbot/compile/service.py
@@ -678,18 +678,21 @@ class BotCompileService:
@staticmethod
def _skill_name_and_target(skill_uri: str) -> tuple[str, str]:
- parts = uri_parts(skill_uri)
- try:
- index = parts.index("skills")
- except ValueError as exc:
+ classification = classify_uri(skill_uri)
+ if not classification.is_skill:
raise CompileFailure(
"SKILL_INVALID", "Skill URI is outside a skills namespace", stage="queued"
- ) from exc
- if len(parts) != index + 2:
+ )
+ if not classification.is_skill_root:
raise CompileFailure(
"SKILL_INVALID", "Skill URI must identify one Skill root", stage="queued"
)
- return parts[-1], "viking://" + "/".join(parts[: index + 1])
+ assert classification.content_index is not None
+ parts = classification.parts
+ return (
+ parts[-1],
+ "viking://" + "/".join(parts[: classification.content_index + 1]),
+ )
async def _retain_target_lock(self, target: tuple[str, str]) -> asyncio.Lock:
"""Retain a task lock keyed by effective account and canonical target URI."""
diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.md
index 611ad2c78..55da4f491 100644
--- a/docs/en/api/04-skills.md
+++ b/docs/en/api/04-skills.md
@@ -396,8 +396,8 @@ require confirmation unless `--yes` is set.
ov add-skill https://github.com/volcengine/OpenViking/tree/skills/llm-wiki
# Inspect a local collection, then select skills to import
-ov add-skill ./examples/compile/ov-compile-skills --list
-ov add-skill ./examples/compile/ov-compile-skills --skill llm-wiki daily-report --yes
+ov add-skill ./openviking/system_assets/compile/example-skills --list
+ov add-skill ./openviking/system_assets/compile/example-skills --skill llm-wiki daily-report --yes
# Add a skill from a local file or directory
ov add-skill ./skills/search-web/SKILL.md
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.md
index e254c2fa6..4ceb5d013 100644
--- a/docs/en/api/08-admin.md
+++ b/docs/en/api/08-admin.md
@@ -309,7 +309,7 @@ objects using YAML field names such as `fields[].type`. List returns
Storage is per Account and per type:
```text
-/local/{account_id}/_system/memory_templates/
+viking://system/memory/memory_templates/custom/
profile.yaml
preferences.yaml
events.yaml
@@ -318,12 +318,19 @@ Storage is per Account and per type:
Only published overrides create files. Each file contains the complete schema
and an internal `_updated_at` timestamp; no `memory_templates.json` is used.
-The previous content is backed up to `{type}.yaml.backup`. Access goes through
+Updates and resets do not create visible backups and remove legacy
+`{type}.yaml.backup` files. Access goes through
AGFS, preserving the deployment's encryption/storage configuration. Do not edit
encrypted backing files directly. `setting.json` and User `user_config.json`
are unchanged. Personal deployments use the default Account; enterprise
deployments use the target Account, with no separate kernel storage layout.
+Reads prefer the new path above and only fall back to
+`/local/{account_id}/_system/memory_templates/{type}.yaml` when the new file is
+absent. Reads never migrate or rewrite files. If the higher-priority file is
+damaged, the server reports an error instead of silently falling back to the
+lower-priority file or deployment defaults.
+
Template reads do not acquire locks. Publication writes a unique staging file in
the same directory, then switches the active path through AGFS: LocalFS uses a
file rename; S3 copies the complete object over the destination before deleting
@@ -331,11 +338,15 @@ the staging object, without deleting the destination first. Readers may see the
complete old or new version, or deployment defaults before the first publication
and after DELETE. This is per-file publication, not a transaction across an
entire template listing or registry snapshot.
-Writers/DELETE still use cross-process locks; publication locks cover both the
-active and staging paths. Contention uses zero-wait attempts with asynchronous
+Writers/DELETE still use cross-process locks; publication locks cover the new,
+legacy, obsolete backup, and staging paths. PUT publishes only to the new path
+and removes the legacy file after publication succeeds. DELETE removes the
+legacy file before the new file so that an old override cannot become active
+again. Explicit PUT/DELETE requests may replace or remove damaged content. Contention uses
+zero-wait attempts with asynchronous
backoff for up to 10 seconds, leaving executor threads available for I/O/release.
-A failed staging write leaves the active file unchanged. Post-publication cleanup
-errors only produce warnings, never an in-place rollback. If the move reports an
+A failed staging write leaves the active file unchanged. Post-publication staging
+cleanup errors only produce warnings, never an in-place rollback. If the move reports an
error, the destination is checked: a verified publication is retained; an
unverifiable outcome returns an error without blindly restoring the old version.
Use GET to confirm its state. Cancellation stops lock retries, but already
diff --git a/docs/en/context-compilation/02-llm-wiki.md b/docs/en/context-compilation/02-llm-wiki.md
index 7c0a54081..6d49e093e 100644
--- a/docs/en/context-compilation/02-llm-wiki.md
+++ b/docs/en/context-compilation/02-llm-wiki.md
@@ -15,7 +15,7 @@ The Skill picks the smallest page type that matches each page's retrieval purpos
The default page types are `entity` and `concept`; other types follow the conditions in the Skill. Related material from multiple sources is grouped under the same topic.
-Skill source: [examples/compile/ov-compile-skills/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/llm-wiki) · Visualization script: [examples/compile/graph-show/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/llm-wiki)
+Skill source: [openviking/system_assets/compile/example-skills/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/llm-wiki) · Visualization script: [examples/compile/graph-show/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/llm-wiki)
Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
@@ -44,7 +44,7 @@ ov ls -r viking://resources/research
This example installs the Skill under `viking://agent/skills`, matching the compile command below. Omit `-p` for a private installation, then use the returned URI in `--skill`:
```bash
-ov add-skill examples/compile/ov-compile-skills/llm-wiki -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/llm-wiki -p viking://agent/skills --wait
```
Find the installed Skill URI:
diff --git a/docs/en/context-compilation/03-knowledge-graph.md b/docs/en/context-compilation/03-knowledge-graph.md
index 6c81a82ae..7aaa8a9ef 100644
--- a/docs/en/context-compilation/03-knowledge-graph.md
+++ b/docs/en/context-compilation/03-knowledge-graph.md
@@ -16,7 +16,7 @@ Each edge is a compact JSON line, readable as the statement `<from> <relation> <
`relation` is a stable, language-independent machine predicate (`member_of`, `leads`, `located_in`…), `label` is its localized display name, and `entity_type` drives node color, shape, and filtering in the visualization. The graph refreshes incrementally: existing nodes and edges are preserved, evidence is merged, and new knowledge is appended.
-Skill source: [examples/compile/ov-compile-skills/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-graph) · Visualization script: [examples/compile/graph-show/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/knowledge-graph)
+Skill source: [openviking/system_assets/compile/example-skills/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/knowledge-graph) · Visualization script: [examples/compile/graph-show/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/knowledge-graph)
Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
@@ -30,7 +30,7 @@ ov ls -r viking://resources/journal
## Step 2: Add the Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-graph -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/knowledge-graph -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/knowledge-graph
```
diff --git a/docs/en/context-compilation/04-daily-report.md b/docs/en/context-compilation/04-daily-report.md
index 42de5563a..4f5bfa3f3 100644
--- a/docs/en/context-compilation/04-daily-report.md
+++ b/docs/en/context-compilation/04-daily-report.md
@@ -2,7 +2,7 @@
Compile timestamped conversation logs, agent sessions, IM messages, collaborative documents, meeting notes, and task records into concise, evidence-grounded **daily reports**: one page per day.
-Skill source: [examples/compile/ov-compile-skills/daily-report](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/daily-report)
+Skill source: [openviking/system_assets/compile/example-skills/daily-report](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/daily-report)
Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
@@ -18,7 +18,7 @@ ov ls -r viking://resources/work-logs
## Step 2: Add the Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/daily-report -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/daily-report -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/daily-report
```
diff --git a/docs/en/context-compilation/05-knowledge-distillation.md b/docs/en/context-compilation/05-knowledge-distillation.md
index 0432569a9..ac51c3733 100644
--- a/docs/en/context-compilation/05-knowledge-distillation.md
+++ b/docs/en/context-compilation/05-knowledge-distillation.md
@@ -18,7 +18,7 @@ risk/
> This is a shape example only — the real topics and findings come from the domain you supply. Note that page names state the **conclusion itself** (`growth-shifted-from-volume-to-pricing`), not a source title (`q2-report-summary`).
-Skill source: [examples/compile/ov-compile-skills/knowledge-distillation](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-distillation)
+Skill source: [openviking/system_assets/compile/example-skills/knowledge-distillation](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/knowledge-distillation)
Check the [prerequisites](01-overview.md#prerequisites) and run these commands from the OpenViking repository root. Replace the source directory with your own material.
@@ -32,7 +32,7 @@ ov ls -r viking://resources/finance-reports
## Step 2: Add the Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-distillation -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/knowledge-distillation -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/knowledge-distillation
```
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
index 3d64691ef..81fefc928 100644
--- a/docs/en/guides/06-mcp-integration.md
+++ b/docs/en/guides/06-mcp-integration.md
@@ -146,7 +146,7 @@ The built-in MCP tools are listed below. Use the connected server's `tools/list`
| `forget` | Delete any `viking://` URI (use `search` to find it first; pass `recursive=true` to delete a directory). Deleting a skill directory this way leaves the skill's privacy configuration behind; remove a skill with `ov skills remove` or `DELETE /api/v1/skills/{name}` | `uri`, `recursive` (optional) |
| `health` | Check OpenViking service health | none |
| `privacy_tree` | Check which credentials are saved; return active field metadata and references without values | `category` (optional) |
-| `privacy_resolve` | Turn a complete `{{ov_privacy:...}}` placeholder into one current field's actual value for immediate use | `reference` |
+| `privacy_resolve` | Turn a complete <code v-pre>{{ov_privacy:...}}</code> placeholder into one current field's actual value for immediate use | `reference` |
| `privacy_upsert` | Save user-supplied credential fields with an atomic merge; return metadata and references without values | `category`, `target_key`, `values` |
| `list_users` | Find user IDs in the caller's account; credentials are excluded by default, including for administrators | `query` (ID substring), `limit` (100), `page` (1), `include_credentials` (false; true requires ADMIN/ROOT) |
| `list_groups` | List group IDs in the caller's account without membership | None |
diff --git a/docs/en/guides/10-prompt-guide.md b/docs/en/guides/10-prompt-guide.md
index 41bbe1039..19a6b5410 100644
--- a/docs/en/guides/10-prompt-guide.md
+++ b/docs/en/guides/10-prompt-guide.md
@@ -18,7 +18,7 @@ OpenViking's current prompts fall into two main groups:
- Stored under `openviking/prompts/templates/<category>/*.yaml`
- Used to instruct the model to perform tasks such as image understanding, document summarization, memory extraction, and retrieval intent analysis
2. Memory schema templates
- - Stored under `openviking/prompts/templates/memory/*.yaml`
+ - Stored under `openviking/system_assets/memory/memory_templates/builtin/*.yaml`
- Used to define the fields, filename templates, content templates, and directory rules for a memory type
From a usage perspective, these templates mainly serve the following processing stages:
diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.md
index 69b0c73a4..ded61a3e7 100644
--- a/docs/zh/api/04-skills.md
+++ b/docs/zh/api/04-skills.md
@@ -396,8 +396,8 @@ fmt.Println(result["task_id"])
ov add-skill https://github.com/volcengine/OpenViking/tree/skills/llm-wiki
# 查看本地技能集合,再选择导入
-ov add-skill ./examples/compile/ov-compile-skills --list
-ov add-skill ./examples/compile/ov-compile-skills --skill llm-wiki daily-report --yes
+ov add-skill ./openviking/system_assets/compile/example-skills --list
+ov add-skill ./openviking/system_assets/compile/example-skills --skill llm-wiki daily-report --yes
# 添加技能(从文件或目录)
ov add-skill ./skills/search-web/SKILL.md
diff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.md
index 5fbd0a81f..a3d98d18a 100644
--- a/docs/zh/api/08-admin.md
+++ b/docs/zh/api/08-admin.md
@@ -284,7 +284,7 @@ DELETE 始终移除该类型的覆盖;重复 PUT 默认配置或 DELETE 都是
按 Account、按模板独立存储:
```text
-/local/{account_id}/_system/memory_templates/
+viking://system/memory/memory_templates/custom/
profile.yaml
preferences.yaml
events.yaml
@@ -292,18 +292,26 @@ DELETE 始终移除该类型的覆盖;重复 PUT 默认配置或 DELETE 都是
```
仅发布自定义时创建对应文件。文件包含完整 Schema 和内部 `_updated_at` 时间戳,
-不再使用集中式 `memory_templates.json`。更新前备份至 `{type}.yaml.backup`。
+不再使用集中式 `memory_templates.json`。更新和重置不生成可见备份,并会清理旧版本遗留的
+`{type}.yaml.backup`。
读写经过 AGFS,沿用当前部署的加密和存储配置,不能直接编辑加密后的底层文件。
不修改 Account 的 `setting.json` 或 User 的 `user_config.json`。
个人版使用默认 Account;企业版使用指定 Account,内核不区分两套文件结构。
+读取优先使用上述新路径;仅当新文件不存在时,才兼容读取旧路径
+`/local/{account_id}/_system/memory_templates/{type}.yaml`。读取不会迁移或改写文件。
+如果优先级更高的文件损坏,不会静默回退到低优先级文件或部署默认。
+
模板读取不加锁。发布先在同目录写完唯一临时文件,再通过 AGFS 切换到正式路径:
LocalFS 使用文件重命名,S3 使用完整对象复制替换目标后再删除临时对象,不先删除目标。
读者允许看到完整旧版或新版;首次发布之前、恢复默认之后读取部署默认值,不读取临时文件。
这是单文件发布语义,不保证一次列表/Registry 读取中的所有模板来自同一发布时刻。
-发布与 DELETE 仍使用跨进程写锁;发布锁同时覆盖正式路径和临时路径。锁冲突采用零等待尝试和
+发布与 DELETE 仍使用跨进程写锁;发布锁同时覆盖新路径、旧路径、遗留 backup 路径和临时路径。
+PUT 只发布到新路径,确认发布成功后再删除旧文件;DELETE 先删除旧文件,再删除新文件,
+防止旧配置重新生效。
+显式 PUT/DELETE 可替换或清理损坏文件。锁冲突采用零等待尝试和
协程退避,最多等待 10 秒,避免锁等待占满执行后续 I/O 的默认线程池。
-临时写入失败不修改当前文件;切换后清理失败只记警告,不覆盖回滚已发布版本。
+临时写入失败不修改当前文件;切换后临时文件清理失败只记警告,不覆盖回滚已发布版本。
若切换返回错误,会核验目标内容:确认已发布则保留新版本;无法确认则返回错误且不盲目回滚,调用方可 GET 确认状态。
取消等待锁的请求会停止重试;已下发的 native 操作不能强行中断,会完成收尾并释放锁后再传播取消。
因此取消已开始发布的请求不保证撤销发布。进程异常退出或清理失败可能留下 `.tmp` 文件,但读取不会使用它们。
diff --git a/docs/zh/context-compilation/02-llm-wiki.md b/docs/zh/context-compilation/02-llm-wiki.md
index 5523a9fbc..ec30579fa 100644
--- a/docs/zh/context-compilation/02-llm-wiki.md
+++ b/docs/zh/context-compilation/02-llm-wiki.md
@@ -15,7 +15,7 @@
默认生成 `entity` 和 `concept` 页面,其他类型按 Skill 中的条件生成。多个来源中的相关内容会合并到同一主题下。
-Skill 源码:[examples/compile/ov-compile-skills/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/llm-wiki) · 可视化脚本:[examples/compile/graph-show/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/llm-wiki)
+Skill 源码:[openviking/system_assets/compile/example-skills/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/llm-wiki) · 可视化脚本:[examples/compile/graph-show/llm-wiki](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/llm-wiki)
先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
@@ -44,7 +44,7 @@ ov ls -r viking://resources/research
本例将 Skill 安装到共享目录 `viking://agent/skills`,与后面的编译命令保持一致。省略 `-p` 会安装到用户私有目录,此时应把 `--skill` 改为安装返回的 URI:
```bash
-ov add-skill examples/compile/ov-compile-skills/llm-wiki -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/llm-wiki -p viking://agent/skills --wait
```
查看装好的 Skill URI:
diff --git a/docs/zh/context-compilation/03-knowledge-graph.md b/docs/zh/context-compilation/03-knowledge-graph.md
index 2d5b13df7..84c87b79a 100644
--- a/docs/zh/context-compilation/03-knowledge-graph.md
+++ b/docs/zh/context-compilation/03-knowledge-graph.md
@@ -16,7 +16,7 @@ relations.jsonl # 每行一条有向边
`relation` 是稳定、语言无关的机器谓词(`member_of`、`leads`、`located_in`……),`label` 是对应的本地化显示名(`属于`、`率领`、`位于`……),`entity_type` 用于可视化时的节点颜色、形状和过滤。图谱可以增量刷新:已有节点和边会被保留、合并证据,新知识追加进来。
-Skill 源码:[examples/compile/ov-compile-skills/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-graph) · 可视化脚本:[examples/compile/graph-show/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/knowledge-graph)
+Skill 源码:[openviking/system_assets/compile/example-skills/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/knowledge-graph) · 可视化脚本:[examples/compile/graph-show/knowledge-graph](https://github.com/volcengine/OpenViking/tree/main/examples/compile/graph-show/knowledge-graph)
先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
@@ -30,7 +30,7 @@ ov ls -r viking://resources/journal
## 第二步:添加 Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-graph -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/knowledge-graph -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/knowledge-graph
```
diff --git a/docs/zh/context-compilation/04-daily-report.md b/docs/zh/context-compilation/04-daily-report.md
index cd59573ae..f99af87b1 100644
--- a/docs/zh/context-compilation/04-daily-report.md
+++ b/docs/zh/context-compilation/04-daily-report.md
@@ -2,7 +2,7 @@
把带时间戳的对话记录、Agent 会话、IM 消息、协作文档、会议纪要、任务记录等材料,编译成简洁、有出处的**日报**:每天一页。
-Skill 源码:[examples/compile/ov-compile-skills/daily-report](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/daily-report)
+Skill 源码:[openviking/system_assets/compile/example-skills/daily-report](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/daily-report)
先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
@@ -18,7 +18,7 @@ ov ls -r viking://resources/work-logs
## 第二步:添加 Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/daily-report -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/daily-report -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/daily-report
```
diff --git a/docs/zh/context-compilation/05-knowledge-distillation.md b/docs/zh/context-compilation/05-knowledge-distillation.md
index bf1852ed1..4dbf9c87e 100644
--- a/docs/zh/context-compilation/05-knowledge-distillation.md
+++ b/docs/zh/context-compilation/05-knowledge-distillation.md
@@ -18,7 +18,7 @@ risk/
> 以上仅展示目录结构。实际主题和结论由来源与指令决定,文件名概括结论。
-Skill 源码:[examples/compile/ov-compile-skills/knowledge-distillation](https://github.com/volcengine/OpenViking/tree/main/examples/compile/ov-compile-skills/knowledge-distillation)
+Skill 源码:[openviking/system_assets/compile/example-skills/knowledge-distillation](https://github.com/volcengine/OpenViking/tree/main/openviking/system_assets/compile/example-skills/knowledge-distillation)
先确认[前置条件](01-overview.md#前置条件),并在 OpenViking 仓库根目录运行以下命令。来源目录需替换为自己的资料目录。
@@ -32,7 +32,7 @@ ov ls -r viking://resources/finance-reports
## 第二步:添加 Skill
```bash
-ov add-skill examples/compile/ov-compile-skills/knowledge-distillation -p viking://agent/skills --wait
+ov add-skill openviking/system_assets/compile/example-skills/knowledge-distillation -p viking://agent/skills --wait
ov skills list
# → viking://agent/skills/knowledge-distillation
```
diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
index fde424c3d..da7a43749 100644
--- a/docs/zh/guides/06-mcp-integration.md
+++ b/docs/zh/guides/06-mcp-integration.md
@@ -142,7 +142,7 @@ claude mcp add --transport http openviking \
| `forget` | 删除任意 `viking://` URI(先用 `search` 查找;删除目录需 `recursive=true`)。用它删 skill 目录会残留该 skill 的 privacy 配置,请改用 `ov skills remove` 或 `DELETE /api/v1/skills/{name}` | `uri`, `recursive`(可选) |
| `health` | 检查 OpenViking 服务健康状态 | 无 |
| `privacy_tree` | 盘点已保存的凭据;返回当前字段元数据及引用,不含值 | `category`(可选) |
-| `privacy_resolve` | 将完整的 `{{ov_privacy:...}}` 占位符解析为一个当前字段的实际值,供立即使用 | `reference` |
+| `privacy_resolve` | 将完整的 <code v-pre>{{ov_privacy:...}}</code> 占位符解析为一个当前字段的实际值,供立即使用 | `reference` |
| `privacy_upsert` | 原子合并用户提供的凭据字段;返回元数据和引用,不回显值 | `category`, `target_key`, `values` |
| `list_users` | 查询当前 account 的用户 ID;默认不返回凭证,管理员也一样 | `query`(可选,ID 子串), `limit`(默认 100), `page`(默认 1), `include_credentials`(默认 false,仅 ADMIN/ROOT 可设为 true) |
| `list_groups` | 查询当前 account 的组 ID,不返回成员名单 | 无 |
diff --git a/docs/zh/guides/10-prompt-guide.md b/docs/zh/guides/10-prompt-guide.md
index 32a7dc2a2..3619e429e 100644
--- a/docs/zh/guides/10-prompt-guide.md
+++ b/docs/zh/guides/10-prompt-guide.md
@@ -18,7 +18,7 @@ OpenViking 当前的 prompt 主要分为两类:
- 存放在 `openviking/prompts/templates/<category>/*.yaml`
- 用于给模型下发任务,例如做图片理解、文档总结、记忆提取、检索意图分析等
2. memory schema 模板
- - 存放在 `openviking/prompts/templates/memory/*.yaml`
+ - 存放在 `openviking/system_assets/memory/memory_templates/builtin/*.yaml`
- 用于定义某类记忆的字段、文件名模板、内容模板和目录规则
从使用角度看,这些模板主要服务于以下处理环节:
diff --git a/openviking/core/directories.py b/openviking/core/directories.py
index 6c2a1cd7f..9b522bac6 100644
--- a/openviking/core/directories.py
+++ b/openviking/core/directories.py
@@ -26,6 +26,7 @@ from openviking.storage.vector_ids import vector_record_id
if TYPE_CHECKING:
from openviking.storage import VikingDBManager
from openviking.storage.viking_fs import VikingFS
+ from openviking.system_assets.sync import SystemAssetSynchronizer
from openviking_cli.exceptions import NotFoundError
@@ -195,9 +196,11 @@ class DirectoryInitializer:
self,
vikingdb: "VikingDBManager",
viking_fs: Optional["VikingFS"] = None,
+ system_asset_synchronizer: Optional["SystemAssetSynchronizer"] = None,
):
self.vikingdb = vikingdb
self._viking_fs = viking_fs
+ self._system_asset_synchronizer = system_asset_synchronizer
def _get_viking_fs(self) -> "VikingFS":
if self._viking_fs is not None:
@@ -206,8 +209,15 @@ class DirectoryInitializer:
return get_viking_fs()
- async def initialize_account_workspace(self, ctx: RequestContext) -> tuple[int, int]:
+ async def initialize_account_workspace(
+ self,
+ ctx: RequestContext,
+ *,
+ sync_system_assets: bool = True,
+ ) -> tuple[int, int]:
"""Initialize account and first-user preset directories as one batch."""
+ if sync_system_assets and self._system_asset_synchronizer is not None:
+ await self._system_asset_synchronizer.sync(ctx)
account_roots, account_children = self._account_directory_targets(ctx)
user_root, user_children = self._user_directory_targets(ctx)
created = await self._initialize_directory_trees(
@@ -223,6 +233,8 @@ class DirectoryInitializer:
Its concrete metadata belongs to ``viking://user/{user_id}`` and is
created by ``initialize_user_directories``.
"""
+ if self._system_asset_synchronizer is not None:
+ await self._system_asset_synchronizer.sync(ctx)
roots, children = self._account_directory_targets(ctx)
return len(await self._initialize_directory_trees(roots, children))
diff --git a/openviking/core/namespace.py b/openviking/core/namespace.py
index e8694e7dd..7cdef5329 100644
--- a/openviking/core/namespace.py
+++ b/openviking/core/namespace.py
@@ -14,6 +14,7 @@ from openviking_cli.utils.uri import VikingURI
_CONTENT_TYPES_BY_SCOPE = {
"user": {"memories": "memory", "resources": "resource", "skills": "skill"},
"agent": {"skills": "skill"},
+ "system": {"example-skills": "skill"},
}
_PEER_CONTENT_SEGMENTS = frozenset({"memories", "resources"})
_USER_RELATIVE_ROOT_SEGMENTS = frozenset({"peers", "privacy", "sessions"})
@@ -51,6 +52,10 @@ class UriClassification:
def is_skill(self) -> bool:
return self.context_type == "skill"
+ @property
+ def is_system(self) -> bool:
+ return self.scope == "system"
+
@property
def is_user_namespace_root(self) -> bool:
return _is_namespace_root_parts(self.parts, "user")
@@ -115,6 +120,8 @@ def _content_segment_index(parts: tuple[str, ...]) -> Optional[int]:
"""Return the content segment for a supported namespace shape."""
if len(parts) >= 2 and parts[:2] == ("agent", "skills"):
return 1
+ if len(parts) >= 3 and parts[:3] == ("system", "compile", "example-skills"):
+ return 2
if len(parts) < 2 or parts[0] != "user":
return None
if len(parts) >= 5 and parts[2] == "peers" and parts[4] in _PEER_CONTENT_SEGMENTS:
diff --git a/openviking/core/namespace_policy.py b/openviking/core/namespace_policy.py
new file mode 100644
index 000000000..b259b4f67
--- /dev/null
+++ b/openviking/core/namespace_policy.py
@@ -0,0 +1,92 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Processing and capability policy for Viking URI namespaces."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+from openviking.core.namespace import uri_parts
+
+SYSTEM_ROOT_URI = "viking://system"
+SYSTEM_COMPILE_ROOT = f"{SYSTEM_ROOT_URI}/compile"
+SYSTEM_EXAMPLE_SKILLS_ROOT = f"{SYSTEM_COMPILE_ROOT}/example-skills"
+SYSTEM_MEMORY_ROOT = f"{SYSTEM_ROOT_URI}/memory"
+SYSTEM_MEMORY_TEMPLATES_ROOT = f"{SYSTEM_MEMORY_ROOT}/memory_templates"
+SYSTEM_MEMORY_BUILTIN_ROOT = f"{SYSTEM_MEMORY_TEMPLATES_ROOT}/builtin"
+SYSTEM_MEMORY_CUSTOM_ROOT = f"{SYSTEM_MEMORY_TEMPLATES_ROOT}/custom"
+
+SYSTEM_FIXED_DIRECTORIES = frozenset(
+ {
+ SYSTEM_ROOT_URI,
+ SYSTEM_COMPILE_ROOT,
+ SYSTEM_EXAMPLE_SKILLS_ROOT,
+ SYSTEM_MEMORY_ROOT,
+ SYSTEM_MEMORY_TEMPLATES_ROOT,
+ SYSTEM_MEMORY_BUILTIN_ROOT,
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+ }
+)
+SYSTEM_OFFICIAL_ASSET_ROOTS = frozenset(
+ {
+ SYSTEM_EXAMPLE_SKILLS_ROOT,
+ SYSTEM_MEMORY_BUILTIN_ROOT,
+ }
+)
+
+
+class NamespaceProcessingMode(str, Enum):
+ INDEXED = "indexed"
+ FILE_ONLY = "file_only"
+
+
+@dataclass(frozen=True)
+class NamespacePolicy:
+ processing_mode: NamespaceProcessingMode
+ supports_acl: bool
+ supports_tags: bool
+ supports_reindex: bool
+
+
+_INDEXED_NAMESPACE_POLICY = NamespacePolicy(
+ processing_mode=NamespaceProcessingMode.INDEXED,
+ supports_acl=True,
+ supports_tags=True,
+ supports_reindex=True,
+)
+_SYSTEM_NAMESPACE_POLICY = NamespacePolicy(
+ processing_mode=NamespaceProcessingMode.FILE_ONLY,
+ supports_acl=False,
+ supports_tags=False,
+ supports_reindex=False,
+)
+
+
+def _is_same_or_descendant(uri: str, root_uri: str) -> bool:
+ parts = uri_parts(uri)
+ root_parts = uri_parts(root_uri)
+ return parts[: len(root_parts)] == root_parts
+
+
+def is_system_uri(uri: str) -> bool:
+ """Return whether uri is the system namespace root or one of its descendants."""
+ return _is_same_or_descendant(uri, SYSTEM_ROOT_URI)
+
+
+def is_system_fixed_directory_uri(uri: str) -> bool:
+ """Return whether uri is one of the fixed system directory paths."""
+ normalized_parts = tuple(uri_parts(uri))
+ return any(normalized_parts == tuple(uri_parts(root)) for root in SYSTEM_FIXED_DIRECTORIES)
+
+
+def is_system_custom_asset_uri(uri: str) -> bool:
+ """Return whether uri is an asset below the mutable custom template root."""
+ parts = uri_parts(uri)
+ root_parts = uri_parts(SYSTEM_MEMORY_CUSTOM_ROOT)
+ return len(parts) > len(root_parts) and parts[: len(root_parts)] == root_parts
+
+
+def namespace_policy_for_uri(uri: str) -> NamespacePolicy:
+ """Return processing and capability policy for uri's namespace."""
+ if is_system_uri(uri):
+ return _SYSTEM_NAMESPACE_POLICY
+ return _INDEXED_NAMESPACE_POLICY
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 86423c7c1..2837b3337 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -171,6 +171,9 @@ async def _initialize_runtime_state(
await service.apply_agent_evolution_config()
await _initialize_auth_plugin(app, service, config)
manager = getattr(app.state, "api_key_manager", None)
+ if manager is not None:
+ account_count = await service.reconcile_system_assets(manager)
+ logger.info("Reconciled system assets for %d active accounts", account_count)
compile_scheduler = getattr(service, "compile_scheduler", None)
if manager is not None and compile_scheduler is not None:
# Scheduled Compile re-verifies its saved key before every submission.
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 064140023..5f4edf058 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -8,6 +8,7 @@ from fastapi import APIRouter, Body, Depends, Query
from pydantic import BaseModel
from openviking.core.namespace import context_type_for_uri
+from openviking.core.namespace_policy import namespace_policy_for_uri
from openviking.core.path_variables import resolve_path_variables
from openviking.core.uri_validation import validate_request_viking_uri
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
@@ -228,14 +229,16 @@ async def attrs(
uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
try:
stat_result = await service.fs.stat(uri, ctx=_ctx, skip_count=True)
+ namespace_policy = namespace_policy_for_uri(uri)
+ tags = (
+ await _tags_attr(service, uri, _ctx, is_dir=stat_result.get("isDir", False))
+ if namespace_policy.supports_tags
+ else []
+ )
result = {
"uri": uri,
"context_type": context_type_for_uri(uri),
- "attrs": {
- "tags": await _tags_attr(
- service, uri, _ctx, is_dir=stat_result.get("isDir", False)
- ),
- },
+ "attrs": {"tags": tags},
}
if result["context_type"] == "memory" and not stat_result.get("isDir", False):
result["attrs"]["memory"] = _clean_memory_attrs(await service.fs.read(uri, ctx=_ctx))
diff --git a/openviking/service/compile_service.py b/openviking/service/compile_service.py
index d798618db..a1c767af6 100644
--- a/openviking/service/compile_service.py
+++ b/openviking/service/compile_service.py
@@ -858,8 +858,10 @@ class CompileService:
classification = classify_uri(target)
parts = uri_parts(target)
if classification.context_type == "skill":
- if not classification.is_skill_namespace or (
- classification.scope == "agent" and parts != ["agent", "skills"]
+ if (
+ not classification.is_skill_namespace
+ or classification.scope not in {"user", "agent"}
+ or (classification.scope == "agent" and parts != ["agent", "skills"])
):
raise InvalidArgumentError(
"Compile Skill target must be a supported skills namespace"
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 44a5a1add..708225c99 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -44,6 +44,8 @@ from openviking.storage.queuefs.reindex_processor import ReindexProcessor
from openviking.storage.queuefs.session_commit_processor import SessionCommitProcessor
from openviking.storage.viking_fs import VikingFS, init_viking_fs
from openviking.storage.vikingdb_manager import VikingDBManager
+from openviking.system_assets.reconcile import AccountLister, SystemAssetReconciler
+from openviking.system_assets.sync import SystemAssetSynchronizer
from openviking.utils.agfs_utils import (
build_runtime_ragfs_binding_config,
resolve_queuefs_mount_point,
@@ -105,6 +107,7 @@ class OpenVikingService:
self._skill_processor: Optional[SkillProcessor] = None
self._session_compressor: Optional["SessionCompressorV3"] = None
self._directory_initializer: Optional[DirectoryInitializer] = None
+ self._system_asset_synchronizer: Optional[SystemAssetSynchronizer] = None
self._uri_mutation_coordinator = UriMutationCoordinator()
self._watch_scheduler: Optional[WatchScheduler] = None
self._session_auto_commit_scheduler: Optional[SessionAutoCommitScheduler] = None
@@ -521,14 +524,20 @@ class OpenVikingService:
)
# Initialize directories
+ system_asset_synchronizer = SystemAssetSynchronizer(
+ viking_fs=self._viking_fs,
+ )
+ self._system_asset_synchronizer = system_asset_synchronizer
directory_initializer = DirectoryInitializer(
vikingdb=self._vikingdb_manager,
viking_fs=self._viking_fs,
+ system_asset_synchronizer=system_asset_synchronizer,
)
self._directory_initializer = directory_initializer
default_ctx = RequestContext(user=self._user, role=Role.ROOT)
account_count, user_count = await directory_initializer.initialize_account_workspace(
- default_ctx
+ default_ctx,
+ sync_system_assets=False,
)
logger.info(
"Initialized preset directories account=%d user=%d",
@@ -710,6 +719,7 @@ class OpenVikingService:
if self._queue_manager:
self._queue_manager.start()
logger.info("QueueManager workers started")
+ await system_asset_synchronizer.sync(default_ctx)
compile_expiry_enabled = self._compile_scheduler is not None
if session_expiry_enabled or compile_expiry_enabled:
@@ -970,6 +980,18 @@ class OpenVikingService:
return 0, 0
return await self._directory_initializer.initialize_account_workspace(ctx)
+ async def reconcile_system_assets(self, account_lister: AccountLister) -> int:
+ """Synchronize packaged system assets for every active account."""
+ self._ensure_initialized()
+ if not self._system_asset_synchronizer:
+ return 0
+ return await SystemAssetReconciler(
+ self._system_asset_synchronizer,
+ account_lister,
+ user_id=self._config.default_user or self._user.user_id,
+ skip_account_ids={self._user.account_id},
+ ).sync_all()
+
async def initialize_user_directories(self, ctx: RequestContext) -> int:
"""Initialize current user's directory tree."""
self._ensure_initialized()
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index c5be0140f..7166ae0a4 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -21,6 +21,10 @@ from openviking.core.namespace import (
uri_leaf_name,
uri_parts,
)
+from openviking.core.namespace_policy import (
+ NamespaceProcessingMode,
+ namespace_policy_for_uri,
+)
from openviking.privacy.sanitizer import PrivacySanitizer
from openviking.privacy.service import UserPrivacyConfigService
from openviking.privacy.skill_restore import get_skill_name_from_uri, restore_skill_content
@@ -30,9 +34,13 @@ from openviking.server.identity import RequestContext
from openviking.service.task_tracker import get_task_tracker, run_tracked_operation
from openviking.service.task_tracker_concurrency import run_to_completion
from openviking.service.task_work_index import get_enqueued_work_ids, get_task_context
+from openviking.session.memory.account_templates import (
+ validate_account_memory_template_transfer,
+)
from openviking.session.memory.memory_updater import MemoryUpdater
from openviking.session.memory.utils.content_visibility import visible_content
from openviking.storage.abstract_overview import (
+ is_abstract_overview_uri,
mark_abstract_overview_pending,
plan_abstract_overview_refresh,
render_abstract_overview,
@@ -301,6 +309,24 @@ class FSService:
"""
viking_fs = self._ensure_initialized()
extra_fields = extra_fields or []
+ if namespace_policy_for_uri(uri).processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ await viking_fs._ensure_access(uri, ctx)
+ unsupported_fields = {"id", "count", "abstract", "overview", "tags"}.intersection(
+ extra_fields
+ )
+ if tags or include_tags:
+ raise InvalidArgumentError(f"tags are not supported for namespace: {uri}")
+ if include_abstract is True or include_overview is True:
+ raise InvalidArgumentError(
+ f"semantic listing output is not supported for namespace: {uri}"
+ )
+ if unsupported_fields:
+ raise InvalidArgumentError(
+ f"fields are not supported for namespace {uri}: "
+ + ", ".join(sorted(unsupported_fields))
+ )
+ include_abstract = False
+ include_overview = False
use_simple_paths = simple and not extra_fields
async def fetch_page(page_offset: int, page_limit: Optional[int]) -> List[Dict[str, Any]]:
@@ -390,6 +416,13 @@ class FSService:
if any(is_storage_internal_name(part) for part in uri_parts(uri)):
raise InvalidArgumentError(f"cannot create storage internal name: {uri}")
+ @staticmethod
+ def _reject_file_only_semantic_sidecar_target(uri: str) -> None:
+ if namespace_policy_for_uri(
+ uri
+ ).processing_mode is NamespaceProcessingMode.FILE_ONLY and is_abstract_overview_uri(uri):
+ raise InvalidArgumentError(f"semantic sidecars are not supported for namespace: {uri}")
+
async def mkdir(
self,
uri: str,
@@ -401,6 +434,19 @@ class FSService:
viking_fs = self._ensure_initialized()
self._reject_storage_internal_target(uri)
directory_uri, abstract_uri = self._resolve_directory_uris(uri)
+ namespace_policy = namespace_policy_for_uri(directory_uri)
+ if namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ await viking_fs._ensure_access(directory_uri, ctx, action=AclAction.WRITE)
+ if acl is not None and not namespace_policy.supports_acl:
+ raise InvalidArgumentError(f"ACL is not supported for namespace: {directory_uri}")
+ if description is not None:
+ raise InvalidArgumentError(
+ f"directory descriptions are not supported for namespace: {directory_uri}"
+ )
+ async with self._uri_mutation_coordinator.mutation(ctx.account_id, [directory_uri]):
+ await viking_fs.mkdir(uri, ctx=ctx)
+ return
+
versions = self.compile_versions
managed = versions is not None and await versions.owning_target(
ctx.account_id, directory_uri
@@ -528,6 +574,14 @@ class FSService:
) -> Optional[Dict[str, Any]]:
"""Remove resource."""
viking_fs = self._ensure_initialized()
+ namespace_policy = namespace_policy_for_uri(uri)
+ if namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ result = await viking_fs.rm(uri, recursive=recursive, ctx=ctx, no_vector=True)
+ if isinstance(result, dict):
+ result["semantic_status"] = "skipped"
+ result["vector_status"] = "skipped"
+ return result
+
cleanup_result: Optional[Dict[str, Any]] = None
context_type = context_type_for_uri(uri)
refresh_parent_uri = self._semantic_refresh_parent_uri(uri, context_type)
@@ -639,6 +693,8 @@ class FSService:
@staticmethod
def _semantic_refresh_parent_uri(uri: str, context_type: str) -> Optional[str]:
+ if namespace_policy_for_uri(uri).processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ return None
if context_type not in {"resource", "skill"}:
return None
parent = VikingURI(uri).parent
@@ -793,6 +849,58 @@ class FSService:
await semantic_queue.enqueue(msg)
return "queued"
+ async def _enqueue_transfer_rebuild(
+ self,
+ *,
+ root_uri: str,
+ target_uri: str,
+ recursive: bool,
+ context_type: str,
+ ctx: RequestContext,
+ ) -> str:
+ """Queue fresh semantic processing when the source has no index artifacts."""
+ if not recursive:
+ await mark_abstract_overview_pending(
+ viking_fs=self._viking_fs,
+ dir_uri=root_uri,
+ changed_entries=1,
+ ctx=ctx,
+ )
+ try:
+ queue_manager = get_queue_manager()
+ except RuntimeError as exc:
+ logger.warning("QueueManager not available, skipping transfer rebuild: %s", exc)
+ return "skipped"
+ semantic_queue = queue_manager.get_queue(queue_manager.SEMANTIC, allow_create=True)
+ telemetry_id = get_current_telemetry().telemetry_id
+ msg = SemanticMsg(
+ uri=root_uri,
+ context_type=context_type,
+ recursive=recursive,
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ group_ids=ctx.group_ids,
+ peer_id=ctx.user.user_id,
+ role=str(ctx.role),
+ skip_vectorization=False,
+ telemetry_id=telemetry_id,
+ coalesce_key=(
+ ""
+ if recursive
+ else build_semantic_coalesce_key(
+ context_type=context_type,
+ uri=root_uri,
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ peer_id=ctx.user.user_id,
+ )
+ ),
+ changes=None if recursive else {"added": [target_uri]},
+ generation_trigger="content_transfer_rebuild",
+ )
+ await semantic_queue.enqueue(msg)
+ return "queued"
+
async def _wait_for_refresh(self) -> Dict[str, Any]:
context = get_task_context()
if context is None:
@@ -825,6 +933,8 @@ class FSService:
from_uri = VikingFS._normalize_transfer_uri(from_uri)
to_uri = VikingFS._normalize_transfer_uri(to_uri)
self._reject_storage_internal_target(to_uri)
+ self._reject_file_only_semantic_sidecar_target(to_uri)
+ validate_account_memory_template_transfer(to_uri)
return await self._finish_transfer_after_caller_cancel(
self._cp_and_refresh(from_uri, to_uri, recursive=recursive, ctx=ctx),
operation="copy",
@@ -840,18 +950,28 @@ class FSService:
) -> Dict[str, Any]:
"""Commit copy and enqueue its parent refresh as one cancellation-safe unit."""
viking_fs = self._ensure_initialized()
+ source_policy = namespace_policy_for_uri(from_uri)
+ target_policy = namespace_policy_for_uri(to_uri)
+ source_indexed = source_policy.processing_mode is NamespaceProcessingMode.INDEXED
+ target_indexed = target_policy.processing_mode is NamespaceProcessingMode.INDEXED
async def copy() -> Dict[str, Any]:
async with self._uri_mutation_coordinator.mutation(ctx.account_id, [from_uri, to_uri]):
async with self._record_transfer(
from_uri, to_uri, ctx, recursive=recursive
) as lease:
+ options = {"lease_ref": lease} if lease is not None else {}
+ if not (source_indexed and target_indexed):
+ options.update(
+ maintain_vectors=False,
+ copy_semantic_sidecars=False,
+ )
return await viking_fs.cp(
from_uri,
to_uri,
recursive=recursive,
ctx=ctx,
- **({"lease_ref": lease} if lease is not None else {}),
+ **options,
)
if self.compile_versions is None:
@@ -871,8 +991,42 @@ class FSService:
result.setdefault("to", to_uri)
result.setdefault("recursive", recursive)
context_type = context_type_for_uri(to_uri)
+ if not source_indexed and target_indexed:
+ target_stat = await viking_fs.stat(to_uri, ctx=ctx, skip_count=True)
+ target_is_dir = bool(target_stat.get("isDir"))
+ rebuild_root_uri = (
+ to_uri
+ if target_is_dir
+ else self._semantic_refresh_parent_uri(to_uri, context_type)
+ )
+ if not rebuild_root_uri:
+ result["semantic_status"] = "skipped"
+ result["vector_status"] = "skipped"
+ return result
+ result["semantic_root_uri"] = rebuild_root_uri
+ try:
+ result["semantic_status"] = await self._enqueue_transfer_rebuild(
+ root_uri=rebuild_root_uri,
+ target_uri=to_uri,
+ recursive=target_is_dir,
+ context_type=context_type,
+ ctx=ctx,
+ )
+ except Exception as exc:
+ logger.warning(
+ "Copy committed but semantic rebuild failed for %s: %s",
+ to_uri,
+ exc,
+ )
+ result["semantic_status"] = "failed"
+ result["semantic_error"] = str(exc)
+ return result
+
refresh_parent_uri = self._semantic_refresh_parent_uri(to_uri, context_type)
if not refresh_parent_uri:
+ if target_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ result["semantic_status"] = "skipped"
+ result["vector_status"] = "skipped"
return result
result["semantic_root_uri"] = refresh_parent_uri
@@ -899,6 +1053,8 @@ class FSService:
from_uri = VikingFS._normalize_transfer_uri(from_uri)
to_uri = VikingFS._normalize_transfer_uri(to_uri)
self._reject_storage_internal_target(to_uri)
+ self._reject_file_only_semantic_sidecar_target(to_uri)
+ validate_account_memory_template_transfer(to_uri)
await self._finish_transfer_after_caller_cancel(
self._mv_and_refresh(from_uri, to_uri, ctx=ctx),
operation="move",
@@ -918,9 +1074,23 @@ class FSService:
watch_manager is not None
and context_type_for_uri(from_uri) == "resource"
and context_type_for_uri(to_uri) == "resource"
+ and namespace_policy_for_uri(from_uri).processing_mode
+ is NamespaceProcessingMode.INDEXED
+ and namespace_policy_for_uri(to_uri).processing_mode is NamespaceProcessingMode.INDEXED
and not is_watch_task_control_uri(from_uri)
and not is_watch_task_control_uri(to_uri)
)
+ source_policy = namespace_policy_for_uri(from_uri)
+ target_policy = namespace_policy_for_uri(to_uri)
+ source_indexed = source_policy.processing_mode is NamespaceProcessingMode.INDEXED
+ target_indexed = target_policy.processing_mode is NamespaceProcessingMode.INDEXED
+ vector_mode: Literal["transfer", "delete_source", "none"]
+ if source_indexed and target_indexed:
+ vector_mode = "transfer"
+ elif source_indexed:
+ vector_mode = "delete_source"
+ else:
+ vector_mode = "none"
async def move() -> None:
async with self._uri_mutation_coordinator.mutation(ctx.account_id, [from_uri, to_uri]):
@@ -930,6 +1100,11 @@ class FSService:
)
async with self._record_transfer(from_uri, to_uri, ctx, move=True) as lease:
options = {"lease_ref": lease} if lease is not None else {}
+ if vector_mode != "transfer":
+ options.update(
+ vector_mode=vector_mode,
+ copy_semantic_sidecars=False,
+ )
await viking_fs.mv(
from_uri,
to_uri,
@@ -960,7 +1135,39 @@ class FSService:
move,
recursive=True,
)
- await self._refresh_move_parents(from_uri=from_uri, to_uri=to_uri, ctx=ctx)
+ rebuild_target = not source_indexed and target_indexed
+ if rebuild_target:
+ await self._refresh_move_parents(
+ from_uri=from_uri,
+ to_uri=to_uri,
+ ctx=ctx,
+ refresh_target=False,
+ )
+ target_stat = await viking_fs.stat(to_uri, ctx=ctx, skip_count=True)
+ target_is_dir = bool(target_stat.get("isDir"))
+ context_type = context_type_for_uri(to_uri)
+ rebuild_root_uri = (
+ to_uri
+ if target_is_dir
+ else self._semantic_refresh_parent_uri(to_uri, context_type)
+ )
+ if rebuild_root_uri:
+ try:
+ await self._enqueue_transfer_rebuild(
+ root_uri=rebuild_root_uri,
+ target_uri=to_uri,
+ recursive=target_is_dir,
+ context_type=context_type,
+ ctx=ctx,
+ )
+ except Exception as exc:
+ logger.warning(
+ "Move committed but semantic rebuild failed for %s: %s",
+ to_uri,
+ exc,
+ )
+ else:
+ await self._refresh_move_parents(from_uri=from_uri, to_uri=to_uri, ctx=ctx)
@asynccontextmanager
async def _record_transfer(
@@ -1078,6 +1285,7 @@ class FSService:
from_uri: str,
to_uri: str,
ctx: RequestContext,
+ refresh_target: bool = True,
) -> None:
"""Queue transfer refreshes for both affected parents after mv commits."""
if is_watch_task_control_uri(from_uri) or is_watch_task_control_uri(to_uri):
@@ -1091,7 +1299,7 @@ class FSService:
refreshes: List[tuple[str, str, Literal["added", "deleted"], str]] = []
if source_parent_uri and source_parent_uri != target_parent_uri:
refreshes.append((source_parent_uri, from_uri, "deleted", source_context_type))
- if target_parent_uri:
+ if target_parent_uri and refresh_target:
refreshes.append((target_parent_uri, to_uri, "added", target_context_type))
for parent_uri, changed_uri, change_kind, context_type in refreshes:
@@ -1148,6 +1356,24 @@ class FSService:
) -> ListingPage:
"""Get directory tree."""
viking_fs = self._ensure_initialized()
+ if namespace_policy_for_uri(uri).processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ await viking_fs._ensure_access(uri, ctx)
+ unsupported_fields = {"id", "count", "abstract", "overview", "tags"}.intersection(
+ extra_fields or []
+ )
+ if tags or include_tags:
+ raise InvalidArgumentError(f"tags are not supported for namespace: {uri}")
+ if include_abstract is True or include_overview is True:
+ raise InvalidArgumentError(
+ f"semantic listing output is not supported for namespace: {uri}"
+ )
+ if unsupported_fields:
+ raise InvalidArgumentError(
+ f"fields are not supported for namespace {uri}: "
+ + ", ".join(sorted(unsupported_fields))
+ )
+ include_abstract = False
+ include_overview = False
async def fetch_page(page_offset: int, page_limit: Optional[int]) -> List[Dict[str, Any]]:
"""Fetch and return one pre-tag tree page."""
@@ -1217,12 +1443,16 @@ class FSService:
) -> Dict[str, Any]:
"""Get resource status."""
viking_fs = self._ensure_initialized()
- return await viking_fs.stat(
- uri,
- ctx=ctx,
- skip_count=skip_count,
- include_lock_status=include_lock_status,
- )
+ namespace_policy = namespace_policy_for_uri(uri)
+ kwargs = {
+ "ctx": ctx,
+ "skip_count": skip_count,
+ "include_lock_status": include_lock_status,
+ }
+ if namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ kwargs["skip_count"] = True
+ kwargs["include_vector_fields"] = False
+ return await viking_fs.stat(uri, **kwargs)
async def ensure_write_access(self, uri: str, ctx: RequestContext) -> None:
"""Validate write access without mutating the target."""
@@ -1306,11 +1536,17 @@ class FSService:
async def abstract(self, uri: str, ctx: RequestContext) -> str:
"""Read L0 abstract (.abstract.md)."""
viking_fs = self._ensure_initialized()
+ if namespace_policy_for_uri(uri).processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ await viking_fs._ensure_access(uri, ctx)
+ raise InvalidArgumentError(f"abstract is not supported for namespace: {uri}")
return await viking_fs.abstract(uri, ctx=ctx)
async def overview(self, uri: str, ctx: RequestContext) -> str:
"""Read L1 overview (.overview.md)."""
viking_fs = self._ensure_initialized()
+ if namespace_policy_for_uri(uri).processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ await viking_fs._ensure_access(uri, ctx)
+ raise InvalidArgumentError(f"overview is not supported for namespace: {uri}")
return await viking_fs.overview(uri, ctx=ctx)
async def grep(
@@ -1329,6 +1565,11 @@ class FSService:
) -> Dict:
"""Content search."""
viking_fs = self._ensure_initialized()
+ namespace_policy = namespace_policy_for_uri(uri)
+ if namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ await viking_fs._ensure_access(uri, ctx)
+ if tags or include_tags:
+ raise InvalidArgumentError(f"tags are not supported for namespace: {uri}")
normalized_tags = normalize_search_tags(tags, discard_invalid=True)
tag_filter = None
if normalized_tags:
@@ -1345,6 +1586,7 @@ class FSService:
"include_tags": include_tags or bool(normalized_tags),
"before_context": before_context,
"after_context": after_context,
+ "force_fs": namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY,
}
if _may_include_memory_content(uri):
kwargs["content_transform"] = _visible_grep_content
@@ -1368,6 +1610,21 @@ class FSService:
) -> Dict:
"""File pattern matching."""
viking_fs = self._ensure_initialized()
+ namespace_policy = namespace_policy_for_uri(uri)
+ if namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ await viking_fs._ensure_access(uri, ctx)
+ if tags or include_tags:
+ raise InvalidArgumentError(f"tags are not supported for namespace: {uri}")
+ unsupported_fields = {"id", "count", "abstract", "overview", "tags"}.intersection(
+ extra_fields or []
+ )
+ if unsupported_fields and (
+ namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY
+ ):
+ raise InvalidArgumentError(
+ f"fields are not supported for namespace {uri}: "
+ + ", ".join(sorted(unsupported_fields))
+ )
normalized_tags = normalize_search_tags(tags, discard_invalid=True)
project_tags = bool(normalized_tags) or include_tags
tag_filter = None
@@ -1385,6 +1642,7 @@ class FSService:
if extra_fields is not None
else ([] if project_tags else None),
tag_filter=tag_filter,
+ force_fs=namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY,
)
)
if not project_tags:
diff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.py
index efe7df664..6883d8c99 100644
--- a/openviking/service/reindex_executor.py
+++ b/openviking/service/reindex_executor.py
@@ -25,6 +25,7 @@ from openviking.core.namespace import (
is_session_uri,
owner_space_for_uri,
)
+from openviking.core.namespace_policy import namespace_policy_for_uri
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.service.task_domain import TaskPatch
@@ -210,6 +211,8 @@ class ReindexExecutor:
A replay reuses accepted work. A pending record without queued work
resumes enqueueing under the same identity.
"""
+ if not namespace_policy_for_uri(uri).supports_reindex:
+ raise InvalidArgumentError(f"reindex is not supported for namespace: {uri}")
if task_id is not None and wait:
raise InvalidArgumentError("task_id requires asynchronous reindex")
object_type = self._infer_target_type(uri)
diff --git a/openviking/service/search_service.py b/openviking/service/search_service.py
index 321c41652..5fa26c387 100644
--- a/openviking/service/search_service.py
+++ b/openviking/service/search_service.py
@@ -8,6 +8,7 @@ Provides search operations: search, find.
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+from openviking.core.namespace_policy import is_system_uri
from openviking.core.retrieval_types import SearchType
from openviking.server.identity import RequestContext
from openviking.storage.viking_fs import VikingFS
@@ -28,6 +29,13 @@ if TYPE_CHECKING:
logger = get_logger(__name__)
+def _reject_system_targets(target_uri: Union[str, List[str]]) -> None:
+ targets = [target_uri] if isinstance(target_uri, str) else target_uri
+ for uri in targets:
+ if uri and is_system_uri(uri):
+ raise InvalidArgumentError(f"search is not supported for namespace: {uri}")
+
+
def _validate_query(
query: str,
image_url: str | list[str] | None = None,
@@ -146,6 +154,7 @@ class SearchService:
raise InvalidArgumentError("image_url is not supported when search_type='keywords'")
resolved_image_url = await self._resolve_image_url(image_url, ctx)
_validate_query(query, resolved_image_url)
+ _reject_system_targets(target_uri)
if search_type == "keywords":
await self.ensure_keywords_search_supported(ctx)
viking_fs = self._ensure_initialized()
@@ -202,6 +211,7 @@ class SearchService:
raise InvalidArgumentError("image_url is not supported when search_type='keywords'")
resolved_image_url = await self._resolve_image_url(image_url, ctx)
_validate_query(query, resolved_image_url, filter)
+ _reject_system_targets(target_uri)
viking_fs = self._ensure_initialized()
result = await viking_fs.find(
query=query,
@@ -235,6 +245,7 @@ class SearchService:
from openviking_cli.retrieve import ContextType, FindResult, TypedQuery
_validate_query(query)
+ _reject_system_targets(target_uri)
fs = self._ensure_initialized()
targets = resolve_retrieval_targets(target_uri, ctx).target_directories
for target in targets:
diff --git a/openviking/session/memory/account_templates.py b/openviking/session/memory/account_templates.py
index 803c083e1..19be90dbd 100644
--- a/openviking/session/memory/account_templates.py
+++ b/openviking/session/memory/account_templates.py
@@ -14,10 +14,11 @@ from typing import TYPE_CHECKING, Any
import yaml
from jinja2 import Environment, TemplateSyntaxError
+from openviking.core.namespace_policy import SYSTEM_MEMORY_CUSTOM_ROOT
from openviking.pyagfs import AGFSAlreadyExistsError, AGFSNotFoundError, AsyncAGFSClient
from openviking.pyagfs.async_client import fs_ctx_from_agfs_path
from openviking.session.memory.dataclass import MemoryTypeSchema
-from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry, get_default_registry
from openviking.session.memory.utils.content_template import (
CONTENT_TEMPLATE_FIELDS,
ContentTemplateError,
@@ -41,6 +42,19 @@ _MAX_CONFIG_BYTES = 1024 * 1024
_TEMPLATE_LOCK_TIMEOUT_SECONDS = 10.0
_TEMPLATE_LOCK_RETRY_SECONDS = 0.05
+
+class _ReadableTemplateDumper(yaml.SafeDumper):
+ pass
+
+
+def _represent_template_string(dumper: yaml.SafeDumper, value: str) -> yaml.nodes.ScalarNode:
+ style = "|" if "\n" in value else None
+ return dumper.represent_scalar("tag:yaml.org,2002:str", value, style=style)
+
+
+_ReadableTemplateDumper.add_representer(str, _represent_template_string)
+
+
# Field names select existing fields; only their descriptions are editable.
EDITABLE_MEMORY_TEMPLATE_FIELDS = {
"profile": ("content",),
@@ -53,16 +67,125 @@ EDITABLE_MEMORY_TEMPLATE_FIELDS = {
_EDITABLE_CONTENT_TEMPLATES = set(CONTENT_TEMPLATE_FIELDS)
-def account_memory_template_path(account_id: str, memory_type: str) -> str:
- error = validate_account_id(account_id)
- if error:
- raise InvalidArgumentError(error)
+def _validate_memory_type(memory_type: str) -> None:
if (
not memory_type
or any(c in memory_type for c in ("/", "\\", "\0"))
or memory_type in {".", ".."}
):
raise InvalidArgumentError("memory_type must be a single file name")
+
+
+def account_memory_template_uri(memory_type: str) -> str:
+ _validate_memory_type(memory_type)
+ return f"{SYSTEM_MEMORY_CUSTOM_ROOT}/{memory_type}.yaml"
+
+
+def _managed_memory_type_for_uri(uri: str) -> str | None:
+ prefix = f"{SYSTEM_MEMORY_CUSTOM_ROOT}/"
+ if not uri.startswith(prefix):
+ return None
+ filename = uri.removeprefix(prefix)
+ if "/" in filename or not filename.endswith(".yaml"):
+ return None
+ memory_type = filename.removesuffix(".yaml")
+ return memory_type or None
+
+
+def normalize_account_memory_template_write(
+ uri: str,
+ content: str | bytes,
+ mode: str,
+ *,
+ registry: MemoryTypeRegistry | None = None,
+) -> str | bytes:
+ """Enforce managed template rules and replace server-owned metadata."""
+ memory_type = _managed_memory_type_for_uri(uri)
+ if memory_type is None:
+ return content
+ registry = registry or get_default_registry()
+ schema = registry.get(memory_type)
+ if schema is None:
+ return content
+ if memory_type not in EDITABLE_MEMORY_TEMPLATE_FIELDS:
+ raise InvalidArgumentError(f"Memory template is not editable: {memory_type}")
+ if mode == "append":
+ raise InvalidArgumentError("append is not supported for managed memory templates")
+
+ try:
+ raw = content.encode("utf-8") if isinstance(content, str) else content
+ if len(raw) > _MAX_CONFIG_BYTES:
+ raise ValueError("A memory template must not exceed 1 MiB")
+ data = yaml.safe_load(raw)
+ if not isinstance(data, dict):
+ raise ValueError("Expected a YAML mapping")
+ supplied = dict(data)
+ supplied.pop("_updated_at", None)
+ defaults = memory_template_data(schema)
+ complete = _complete_template(defaults, supplied, memory_type)
+ if complete != supplied:
+ raise ValueError("generic writes require the complete deployment template")
+ complete["_updated_at"] = datetime.now(timezone.utc).isoformat()
+ normalized = yaml.dump(
+ complete,
+ Dumper=_ReadableTemplateDumper,
+ allow_unicode=True,
+ sort_keys=False,
+ )
+ normalized_raw = normalized.encode("utf-8")
+ if len(normalized_raw) > _MAX_CONFIG_BYTES:
+ raise ValueError("A memory template must not exceed 1 MiB")
+ return normalized if isinstance(content, str) else normalized_raw
+ except DescriptionTemplateError as exc:
+ raise InvalidArgumentError(
+ str(exc),
+ details={"field": exc.field, "reason": exc.reason, "line": exc.line},
+ ) from exc
+ except ContentTemplateError as exc:
+ raise InvalidArgumentError(
+ str(exc),
+ details={"field": "content_template", "reason": exc.reason, "line": exc.line},
+ ) from exc
+ except (
+ UnicodeDecodeError,
+ ValueError,
+ TypeError,
+ KeyError,
+ AttributeError,
+ yaml.YAMLError,
+ TemplateSyntaxError,
+ ) as exc:
+ raise InvalidArgumentError(f"Invalid memory template: {exc}") from exc
+
+
+def validate_account_memory_template_transfer(
+ uri: str, *, registry: MemoryTypeRegistry | None = None
+) -> None:
+ """Reject cp/mv targets that would bypass a registered template contract."""
+ memory_type = _managed_memory_type_for_uri(uri)
+ if memory_type is None:
+ return
+ registry = registry or get_default_registry()
+ if registry.get(memory_type) is not None:
+ raise InvalidArgumentError(
+ f"Registered memory templates must be updated through write or the admin API: {uri}"
+ )
+
+
+def account_memory_template_path(account_id: str, memory_type: str) -> str:
+ error = validate_account_id(account_id)
+ if error:
+ raise InvalidArgumentError(error)
+ _validate_memory_type(memory_type)
+ relative_root = SYSTEM_MEMORY_CUSTOM_ROOT.removeprefix("viking://")
+ return f"/local/{account_id}/{relative_root}/{memory_type}.yaml"
+
+
+def legacy_account_memory_template_path(account_id: str, memory_type: str) -> str:
+ error = validate_account_id(account_id)
+ if error:
+ raise InvalidArgumentError(error)
+ _validate_memory_type(memory_type)
return f"/local/{account_id}/_system/memory_templates/{memory_type}.yaml"
@@ -176,6 +299,13 @@ def _complete_template(defaults: dict, supplied: dict, memory_type: str) -> dict
async def _read_raw(client: AsyncAGFSClient, path: str) -> bytes | None:
+ raw = await _read_unchecked_raw(client, path)
+ if raw is not None and len(raw) > _MAX_CONFIG_BYTES:
+ raise FailedPreconditionError("Invalid persisted account memory template")
+ return raw
+
+
+async def _read_unchecked_raw(client: AsyncAGFSClient, path: str) -> bytes | None:
try:
result = await client.read(path)
except AGFSNotFoundError:
@@ -183,7 +313,7 @@ async def _read_raw(client: AsyncAGFSClient, path: str) -> bytes | None:
raw = getattr(result, "content", result)
if isinstance(raw, str):
raw = raw.encode("utf-8")
- if not isinstance(raw, bytes) or len(raw) > _MAX_CONFIG_BYTES:
+ if not isinstance(raw, bytes):
raise FailedPreconditionError("Invalid persisted account memory template")
return raw
@@ -239,23 +369,20 @@ async def _finish_storage_call(
raise
-async def _acquire_template_lock(
- client: AsyncAGFSClient, path: str, staging_path: str | None = None
-):
+async def _acquire_template_lock(client: AsyncAGFSClient, paths: list[str], uri: str):
# Keep the cross-process lock, but never wait for contention in a worker:
# the holder needs that same executor to finish its I/O and release the lease.
loop = asyncio.get_running_loop()
deadline = loop.time() + _TEMPLATE_LOCK_TIMEOUT_SECONDS
+ primary_path = paths[0]
async def release_cancelled_acquire(lease):
- await client.pathlock_release(lease, fs_ctx=fs_ctx_from_agfs_path(path))
+ await client.pathlock_release(lease, fs_ctx=fs_ctx_from_agfs_path(primary_path))
while True:
try:
return await _finish_storage_call(
- client.pathlock_acquire_exact_batch([path, staging_path], timeout_secs=0.0)
- if staging_path is not None
- else client.pathlock_acquire_exact(path, timeout_secs=0.0),
+ client.pathlock_acquire_exact_batch(paths, timeout_secs=0.0),
on_cancel=release_cancelled_acquire,
)
except LockAcquisitionError as exc:
@@ -266,7 +393,7 @@ async def _acquire_template_lock(
continue
raise ResourceBusyError(
"Another memory template operation is in progress. Please retry.",
- uri=path,
+ uri=uri,
conflict_type="memory_templates_busy",
) from exc
@@ -275,10 +402,14 @@ async def read_account_memory_template(
viking_fs: VikingFS, account_id: str, memory_type: str
) -> dict | None:
path = account_memory_template_path(account_id, memory_type)
+ legacy_path = legacy_account_memory_template_path(account_id, memory_type)
client = AsyncAGFSClient(viking_fs.agfs)
# Publication switches a fully-written staging file into place. Readers may
# see either complete version (or no override after DELETE), without a lock.
- return _parse_template(await _read_raw(client, path), memory_type)
+ raw = await _read_raw(client, path)
+ if raw is not None:
+ return _parse_template(raw, memory_type)
+ return _parse_template(await _read_raw(client, legacy_path), memory_type)
def memory_template_result(
@@ -329,16 +460,38 @@ async def update_account_memory_template(
complete = None
else:
complete["_updated_at"] = datetime.now(timezone.utc).isoformat()
- encoded = yaml.safe_dump(complete, allow_unicode=True, sort_keys=False).encode("utf-8")
+ encoded = yaml.dump(
+ complete,
+ Dumper=_ReadableTemplateDumper,
+ allow_unicode=True,
+ sort_keys=False,
+ ).encode("utf-8")
if len(encoded) > _MAX_CONFIG_BYTES:
raise InvalidArgumentError("A memory template must not exceed 1 MiB")
path = account_memory_template_path(account_id, memory_type)
+ legacy_path = legacy_account_memory_template_path(account_id, memory_type)
+ backup_path = f"{path}.backup"
staging_path = f"{path}.{uuid.uuid4().hex}.tmp" if complete is not None else None
client = AsyncAGFSClient(viking_fs.agfs)
- lease = await _acquire_template_lock(client, path, staging_path)
+ lock_paths = [path, legacy_path, backup_path]
+ if staging_path is not None:
+ lock_paths.append(staging_path)
+ lease = await _acquire_template_lock(
+ client, lock_paths, account_memory_template_uri(memory_type)
+ )
return await _finish_storage_call(
- _update_locked_template(client, path, staging_path, memory_type, complete, encoded, lease)
+ _update_locked_template(
+ client,
+ path,
+ legacy_path,
+ backup_path,
+ staging_path,
+ memory_type,
+ complete,
+ encoded,
+ lease,
+ )
)
@@ -381,6 +534,8 @@ async def _publish_template(
async def _update_locked_template(
client: AsyncAGFSClient,
path: str,
+ legacy_path: str,
+ backup_path: str,
staging_path: str | None,
memory_type: str,
complete: dict | None,
@@ -394,32 +549,96 @@ async def _update_locked_template(
if lease_ref:
fs_ctx["lease_ref"] = lease_ref
try:
- raw = await _read_raw(client, path)
- current = _parse_template(raw, memory_type)
- if complete is None and current is None:
+ raw = await _read_unchecked_raw(client, path)
+ legacy_raw = await _read_unchecked_raw(client, legacy_path)
+ active_raw = raw if raw is not None else legacy_raw
+ current = None
+ if active_raw is not None and len(active_raw) <= _MAX_CONFIG_BYTES:
+ try:
+ current = _parse_template(active_raw, memory_type)
+ except FailedPreconditionError:
+ # Explicit PUT/DELETE is the recovery path for damaged persisted
+ # content, so allow the operation to replace or remove it.
+ pass
+ if complete is None and active_raw is None:
+ await _remove_obsolete_backup(client, backup_path, fs_ctx)
return None
- if complete is not None and current is not None:
+ if complete is not None and raw is not None and current is not None:
if {k: v for k, v in current.items() if k != "_updated_at"} == {
k: v for k, v in complete.items() if k != "_updated_at"
}:
+ if legacy_raw is not None:
+ try:
+ await client.rm(legacy_path, fs_ctx=fs_ctx)
+ except AGFSNotFoundError:
+ pass
+ except Exception as exc:
+ raise FailedPreconditionError(
+ "Memory template is published, but legacy cleanup failed. "
+ "Retry the request.",
+ details={
+ "published": True,
+ "legacy_cleanup_pending": True,
+ "retryable": True,
+ },
+ ) from exc
+ await _remove_obsolete_backup(client, backup_path, fs_ctx)
return current
try:
await client.ensure_parent_dirs(path)
except AGFSAlreadyExistsError:
pass
- if raw is not None:
- await client.write(path + ".backup", raw)
if complete is None:
- await client.rm(path, fs_ctx=fs_ctx)
+ try:
+ await client.rm(legacy_path, fs_ctx=fs_ctx)
+ except AGFSNotFoundError:
+ pass
+ except Exception as exc:
+ raise FailedPreconditionError(
+ "Failed to remove the legacy memory template. Retry the request.",
+ details={"legacy_cleanup_pending": True, "retryable": True},
+ ) from exc
+ try:
+ await client.rm(path, fs_ctx=fs_ctx)
+ except AGFSNotFoundError:
+ pass
+ except Exception as exc:
+ raise FailedPreconditionError(
+ "Failed to remove the current memory template. Retry the request.",
+ details={"current_cleanup_pending": True, "retryable": True},
+ ) from exc
else:
assert staging_path is not None and encoded is not None
await _publish_template(client, path, staging_path, encoded, fs_ctx)
+ try:
+ await client.rm(legacy_path, fs_ctx=fs_ctx)
+ except AGFSNotFoundError:
+ pass
+ except Exception as exc:
+ raise FailedPreconditionError(
+ "Memory template is published, but legacy cleanup failed. Retry the request.",
+ details={
+ "published": True,
+ "legacy_cleanup_pending": True,
+ "retryable": True,
+ },
+ ) from exc
+ await _remove_obsolete_backup(client, backup_path, fs_ctx)
logger.info("Updated account memory template: %s reset=%s", path, complete is None)
return complete
finally:
await client.pathlock_release(lease, fs_ctx=fs_ctx_from_agfs_path(path))
+async def _remove_obsolete_backup(client: AsyncAGFSClient, backup_path: str, fs_ctx: dict) -> None:
+ try:
+ await client.rm(backup_path, fs_ctx=fs_ctx)
+ except AGFSNotFoundError:
+ pass
+ except Exception:
+ logger.warning("Failed to remove obsolete memory template backup: %s", backup_path)
+
+
async def resolve_account_memory_registry(
viking_fs: VikingFS, account_id: str, registry: MemoryTypeRegistry
) -> MemoryTypeRegistry:
diff --git a/openviking/session/memory/memory_type_registry.py b/openviking/session/memory/memory_type_registry.py
index cb1a3cb51..e48360430 100644
--- a/openviking/session/memory/memory_type_registry.py
+++ b/openviking/session/memory/memory_type_registry.py
@@ -16,6 +16,7 @@ from openviking.session.memory.dataclass import MemoryField, MemoryTypeSchema
from openviking.session.memory.merge_op import MergeOp
from openviking.session.memory.merge_op.base import FieldType
from openviking.session.memory.utils.template_utils import TemplateUtils
+from openviking.system_assets import builtin_memory_templates_dir
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
@@ -23,7 +24,10 @@ logger = get_logger(__name__)
def resolve_memory_templates_dir() -> Path:
"""Resolve the memory templates directory from PromptManager semantics."""
- return PromptManager._resolve_templates_dir(None) / "memory"
+ templates_dir = PromptManager._resolve_templates_dir(None)
+ if templates_dir == PromptManager._get_bundled_templates_dir():
+ return builtin_memory_templates_dir()
+ return templates_dir / "memory"
class MemoryTypeRegistry:
@@ -46,7 +50,7 @@ class MemoryTypeRegistry:
from openviking_cli.utils.config import get_openviking_config
- memory_templates_dir = str(PromptManager._get_bundled_templates_dir() / "memory")
+ memory_templates_dir = str(builtin_memory_templates_dir())
config = get_openviking_config()
custom_dir = config.memory.custom_templates_dir
@@ -81,9 +85,9 @@ class MemoryTypeRegistry:
)
else:
memory_templates_dir = str(resolve_memory_templates_dir())
- if memory_templates_dir != str(
- PromptManager._get_bundled_templates_dir() / "memory"
- ) and os.path.exists(memory_templates_dir):
+ if memory_templates_dir != str(builtin_memory_templates_dir()) and os.path.exists(
+ memory_templates_dir
+ ):
loaded = self.load_from_directory(memory_templates_dir, replace=True)
logger.info(
"Loaded %s memory schemas from configured prompt templates: %s",
diff --git a/openviking/storage/content_write.py b/openviking/storage/content_write.py
index c536aba22..6fd651751 100644
--- a/openviking/storage/content_write.py
+++ b/openviking/storage/content_write.py
@@ -24,6 +24,10 @@ from openviking.core.namespace import (
relative_uri_path,
uri_parts,
)
+from openviking.core.namespace_policy import (
+ NamespaceProcessingMode,
+ namespace_policy_for_uri,
+)
from openviking.privacy.sanitizer import PrivacySanitizer
from openviking.resource.processing_mode import (
DEFAULT_PROCESSING_MODE,
@@ -31,7 +35,7 @@ from openviking.resource.processing_mode import (
normalize_processing_mode,
)
from openviking.resource.watch_storage import is_watch_task_control_uri
-from openviking.server.identity import RequestContext
+from openviking.server.identity import RequestContext, Role
from openviking.service.task_tracker import (
TaskStatus,
get_task_tracker,
@@ -42,6 +46,7 @@ from openviking.service.task_work_index import (
get_enqueued_work_ids,
get_task_context,
)
+from openviking.session.memory.account_templates import normalize_account_memory_template_write
from openviking.session.memory.memory_updater import MemoryUpdater
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.session.memory.utils.resource_refs import (
@@ -507,8 +512,21 @@ class ContentWriteCoordinator:
)
self._ensure_content_write_policy(normalized_uri)
await self._viking_fs._ensure_access(normalized_uri, ctx, action=AclAction.WRITE)
+ namespace_policy = namespace_policy_for_uri(normalized_uri)
+ if (
+ namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY
+ and is_abstract_overview_uri(normalized_uri)
+ ):
+ raise InvalidArgumentError(
+ f"semantic sidecars are not supported for namespace: {normalized_uri}"
+ )
+ if tags is not None and not namespace_policy.supports_tags:
+ raise InvalidArgumentError(f"tags are not supported for namespace: {normalized_uri}")
+ if acl is not None and not namespace_policy.supports_acl:
+ raise InvalidArgumentError(f"ACL is not supported for namespace: {normalized_uri}")
if isinstance(content, str):
content = await self._sanitize_text(content, uri=normalized_uri, ctx=ctx)
+ content = normalize_account_memory_template_write(normalized_uri, content, mode)
ingest_options = IngestOptions.from_search_tags(tags, mode=tag_mode)
if acl is not None:
ingest_options = replace(
@@ -525,6 +543,21 @@ class ContentWriteCoordinator:
mode = "replace"
context_type = context_type_for_uri(normalized_uri)
+ if namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY:
+ parent = VikingURI(normalized_uri).parent
+ root_uri = parent.uri if parent is not None else normalized_uri
+ return await self._write_file_only(
+ uri=normalized_uri,
+ root_uri=root_uri,
+ content=content,
+ mode=mode,
+ response_mode=response_mode,
+ context_type=context_type,
+ ctx=ctx,
+ root_operation=root_operation,
+ root_task_factory=root_task_factory,
+ )
+
root_uri = await self._resolve_root_uri(
normalized_uri,
ctx=ctx,
@@ -664,6 +697,20 @@ class ContentWriteCoordinator:
):
raise InvalidArgumentError("defer_processing does not support tags or ACL updates")
await self._sanitize_batch_operations(normalized_operations, ctx=ctx)
+ for operation in normalized_operations:
+ operation["content"] = normalize_account_memory_template_write(
+ operation["uri"], operation["content"], operation["mode"]
+ )
+ root_policy = namespace_policy_for_uri(normalized_root)
+ if any(
+ namespace_policy_for_uri(operation["uri"]).processing_mode
+ is not root_policy.processing_mode
+ for operation in normalized_operations
+ ):
+ raise InvalidArgumentError(
+ "batch-write cannot mix FILE_ONLY and INDEXED namespace targets"
+ )
+ file_only = root_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY
target_paths = [
self._viking_fs._uri_to_path(operation["uri"], ctx=ctx)
@@ -739,7 +786,7 @@ class ContentWriteCoordinator:
continue
pending.append((operation, exists, write_mode))
- if not defer_processing:
+ if not file_only and not defer_processing:
prepared_resources = await self._prepare_batch_resource_plans(
pending=pending,
ctx=ctx,
@@ -784,10 +831,15 @@ class ContentWriteCoordinator:
if prepared is not None:
final_content = prepared.final_bytes
committed_resource_plans.append(prepared)
- if context_type_for_uri(uri) in {
- "resource",
- "skill",
- } and not is_abstract_overview_uri(uri):
+ if (
+ not file_only
+ and context_type_for_uri(uri)
+ in {
+ "resource",
+ "skill",
+ }
+ and not is_abstract_overview_uri(uri)
+ ):
file_md5s[uri] = content_md5(final_content)
options = operation["ingest_options"]
if options.acl_update:
@@ -807,11 +859,11 @@ class ContentWriteCoordinator:
# deterministic operation order matches sequential
# write semantics: the last operation's options win.
sidecar_directories[parent.uri] = options
- elif prepared is None:
+ elif not file_only and prepared is None:
refresh_kinds[uri] = "modified"
else:
created.append(uri)
- if prepared is None:
+ if not file_only and prepared is None:
refresh_kinds[uri] = "added"
finally:
if self._batch_commit is not None:
@@ -838,10 +890,15 @@ class ContentWriteCoordinator:
}
if skip_conflicts:
result["conflicts"] = conflicts
- if defer_processing:
+ if file_only:
+ result["semantic_status"] = "skipped"
+ result["vector_status"] = "skipped"
+ elif defer_processing:
result.update(semantic_status="deferred", vector_status="deferred")
- has_refresh_work = not defer_processing and bool(
- refresh_kinds or sidecar_directories or committed_resource_plans
+ has_refresh_work = (
+ not file_only
+ and not defer_processing
+ and bool(refresh_kinds or sidecar_directories or committed_resource_plans)
)
if write_error is not None and not has_refresh_work:
await lock_guard.close()
@@ -936,7 +993,15 @@ class ContentWriteCoordinator:
async def _validate_batch_root(self, root_uri: str, *, ctx: RequestContext) -> None:
classification = classify_uri(root_uri)
parts = uri_parts(root_uri)
- if classification.context_type not in {"resource", "memory"}:
+ is_root_system_skill_namespace = (
+ ctx.role == Role.ROOT
+ and classification.scope == "system"
+ and classification.is_skill_namespace
+ )
+ if (
+ classification.context_type not in {"resource", "memory"}
+ and not is_root_system_skill_namespace
+ ):
raise InvalidArgumentError("batch-write root must be a resource or memory directory")
if classification.context_type == "memory":
if (
@@ -946,9 +1011,12 @@ class ContentWriteCoordinator:
raise InvalidArgumentError(
"batch-write root must be inside a memory type directory"
)
- elif parts == ["resources"] or (
- classification.content_index is not None
- and len(parts) <= classification.content_index + 1
+ elif classification.context_type == "resource" and (
+ parts == ["resources"]
+ or (
+ classification.content_index is not None
+ and len(parts) <= classification.content_index + 1
+ )
):
raise InvalidArgumentError("batch-write root must be inside a resource directory")
await self._viking_fs._ensure_access(root_uri, ctx, action=AclAction.WRITE)
@@ -986,6 +1054,14 @@ class ContentWriteCoordinator:
)
self._ensure_content_write_policy(uri)
await self._viking_fs._ensure_access(uri, ctx, action=AclAction.WRITE)
+ namespace_policy = namespace_policy_for_uri(uri)
+ if (
+ namespace_policy.processing_mode is NamespaceProcessingMode.FILE_ONLY
+ and is_abstract_overview_uri(uri)
+ ):
+ raise InvalidArgumentError(
+ f"semantic sidecars are not supported for namespace: {uri}"
+ )
has_content = "content" in raw
has_content_base64 = "content_base64" in raw
@@ -1038,10 +1114,14 @@ class ContentWriteCoordinator:
not isinstance(tags, list) or any(not isinstance(tag, str) for tag in tags)
):
raise InvalidArgumentError(f"batch-write tags must be a string list: {uri}")
+ if tags is not None and not namespace_policy.supports_tags:
+ raise InvalidArgumentError(f"tags are not supported for namespace: {uri}")
tag_mode = raw.get("tag_mode", "replace")
self._validate_tag_mode(tag_mode)
ingest_options = IngestOptions.from_search_tags(tags, mode=tag_mode)
if (acl := raw.get("acl")) is not None:
+ if not namespace_policy.supports_acl:
+ raise InvalidArgumentError(f"ACL is not supported for namespace: {uri}")
ingest_options = replace(
ingest_options,
acl_update=await self._viking_fs.prepare_acl_update(uri, acl, ctx),
@@ -1344,6 +1424,8 @@ class ContentWriteCoordinator:
normalized_tags = (
[] if requested_mode == "clear" else normalize_search_tags(tags, discard_invalid=True)
)
+ if not namespace_policy_for_uri(normalized_uri).supports_tags:
+ raise InvalidArgumentError(f"tags are not supported for namespace: {normalized_uri}")
await self._viking_fs._ensure_access(normalized_uri, ctx, action=AclAction.WRITE)
stat = await self._safe_stat(normalized_uri, ctx=ctx)
context_type = context_type_for_uri(normalized_uri)
@@ -2180,6 +2262,85 @@ class ContentWriteCoordinator:
except ImportError:
return False
+ async def _write_file_only(
+ self,
+ *,
+ uri: str,
+ root_uri: str,
+ content: str,
+ mode: str,
+ response_mode: str,
+ context_type: str,
+ ctx: RequestContext,
+ root_operation: str = "content_write",
+ root_task_factory: Callable[[], Awaitable[Any]] | None = None,
+ ) -> Dict[str, Any]:
+ lock_path = self._viking_fs._uri_to_path(uri, ctx=ctx)
+ lock_guard = PathLockGuard(self._viking_fs._async_agfs)
+ try:
+ lease = await lock_guard.acquire(
+ lambda: self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
+ )
+ except LockAcquisitionError as exc:
+ raise ResourceBusyError(
+ f"resource is busy and cannot be written now: {uri}",
+ uri=uri,
+ ) from exc
+ except BaseException:
+ await lock_guard.close()
+ raise
+
+ try:
+ target_state = await self._classify_locked_write_target(uri, ctx=ctx)
+ final_bytes = await self._write_in_place(
+ uri,
+ content,
+ mode=mode,
+ ctx=ctx,
+ lease_ref=lease,
+ is_new_file=target_state.is_new_file,
+ )
+ result = self._build_write_result(
+ uri=uri,
+ root_uri=root_uri,
+ context_type=context_type,
+ mode=response_mode,
+ written_bytes=len(final_bytes),
+ queue_status=None,
+ semantic_status="skipped",
+ vector_status="skipped",
+ )
+ if root_task_factory is not None:
+ await root_task_factory()
+ root_dispatched = False
+
+ async def dispatch() -> str:
+ nonlocal root_dispatched
+ work_id = await self._enqueue_content_write_root(
+ operation=root_operation,
+ resource_id=uri,
+ result=result,
+ refresh={"kind": "none"},
+ ctx=ctx,
+ telemetry_id=get_current_telemetry().telemetry_id,
+ lock_scope="dispatch",
+ root_task_factory=root_task_factory,
+ )
+ root_dispatched = True
+ return work_id
+
+ try:
+ await lock_guard.dispatch_and_close(dispatch)
+ except BaseException as exc:
+ if root_dispatched:
+ _mark_root_owns_failure(exc)
+ raise
+ return result
+ raise RuntimeError("Content write root Task was not created")
+ finally:
+ if lock_guard.lease is not None:
+ await lock_guard.close()
+
async def _safe_stat(
self, uri: str, *, ctx: RequestContext, allow_not_found: bool = False
) -> Dict[str, Any]:
diff --git a/openviking/storage/viking_fs/_access.py b/openviking/storage/viking_fs/_access.py
index d56a6e797..41163a0e3 100644
--- a/openviking/storage/viking_fs/_access.py
+++ b/openviking/storage/viking_fs/_access.py
@@ -17,6 +17,7 @@ from openviking.core.namespace import (
is_hidden_by_actor_peer_view,
may_include_hidden_actor_peers,
)
+from openviking.core.namespace_policy import is_system_custom_asset_uri, is_system_uri
from openviking.resource.watch_storage import is_watch_task_control_uri
from openviking.server.error_mapping import is_not_found_error
from openviking.server.identity import RequestContext, Role
@@ -167,6 +168,23 @@ class _AccessMixin:
digest = hashlib.sha256(relative_path.encode("utf-8")).hexdigest()
return f"{mount_prefix}{temp_root}/{digest}.encrypt"
+ @staticmethod
+ def _system_permission_allows(
+ uri: str,
+ ctx: RequestContext,
+ action: AclAction,
+ ) -> bool:
+ """Apply the fixed role and path policy for the account system namespace."""
+ if ctx.role == Role.ROOT:
+ return True
+ if action is AclAction.READ:
+ return True
+ return (
+ ctx.role == Role.ADMIN
+ and action in {AclAction.WRITE, AclAction.MANAGE}
+ and is_system_custom_asset_uri(uri)
+ )
+
async def _can_access_many(
self,
uris: Sequence[str],
@@ -187,13 +205,22 @@ class _AccessMixin:
else:
valid.append(uri)
+ remaining: List[str] = []
+ for uri in valid:
+ if is_system_uri(uri):
+ result[uri] = self._system_permission_allows(uri, real_ctx, action)
+ else:
+ remaining.append(uri)
+ if not remaining:
+ return result
+
acl_manager = self.acl_manager
if acl_manager is None or not await acl_manager.is_enabled(real_ctx.account_id):
- result.update({uri: self._is_accessible(uri, real_ctx) for uri in valid})
+ result.update({uri: self._is_accessible(uri, real_ctx) for uri in remaining})
return result
pending: List[str] = []
- for uri in valid:
+ for uri in remaining:
if is_watch_task_control_uri(uri):
result[uri] = self._is_accessible(uri, real_ctx)
continue
diff --git a/openviking/storage/viking_fs/_grep.py b/openviking/storage/viking_fs/_grep.py
index ed7f3b38d..b9c88fc21 100644
--- a/openviking/storage/viking_fs/_grep.py
+++ b/openviking/storage/viking_fs/_grep.py
@@ -42,6 +42,7 @@ class _GrepMixin:
include_tags: bool = False,
before_context: int = 0,
after_context: int = 0,
+ force_fs: bool = False,
) -> Dict:
"""Content search by pattern or keywords.
@@ -84,7 +85,7 @@ class _GrepMixin:
# persisted raw content, so it cannot safely recall projected results.
resolved_engine = (
"fs"
- if content_transform is not None or is_session_uri(uri)
+ if force_fs or content_transform is not None or is_session_uri(uri)
else await self._resolve_grep_engine(engine, uri, ctx, switch_to_remote_threshold)
)
tags_by_uri: Dict[str, List[str]] = {}
diff --git a/openviking/storage/viking_fs/_ops.py b/openviking/storage/viking_fs/_ops.py
index c2363a23a..a055c09f5 100644
--- a/openviking/storage/viking_fs/_ops.py
+++ b/openviking/storage/viking_fs/_ops.py
@@ -7,7 +7,7 @@ import math
import uuid
from dataclasses import replace
from datetime import datetime, timezone
-from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+from typing import Any, Awaitable, Callable, Dict, List, Literal, Optional, Union
from openviking.core.context import ContextLevel
from openviking.core.namespace import (
@@ -404,8 +404,11 @@ class _OpsMixin:
recursive: bool = False,
ctx: Optional[RequestContext] = None,
lease_ref: Dict[str, Any] | None = None,
+ *,
+ maintain_vectors: bool = True,
+ copy_semantic_sidecars: bool = True,
) -> Dict[str, Any]:
- """Copy a file or directory together with its vector records."""
+ """Copy a file or directory, optionally including semantic state."""
old_uri = self._normalize_transfer_uri(old_uri)
new_uri = self._normalize_transfer_uri(new_uri)
await self._ensure_copy_source_access(old_uri, recursive=recursive, ctx=ctx)
@@ -467,23 +470,26 @@ class _OpsMixin:
is_dir=is_dir,
ctx=ctx,
lease_ref=lease,
+ copy_semantic_sidecars=copy_semantic_sidecars,
)
- try:
- vector_result = await self._copy_vector_store_uris(
- old_uri,
- new_uri,
- recursive=is_dir,
- ctx=ctx,
- **({"source_uris": source_uris} if is_dir else {}),
- )
- except Exception:
+ vector_result = None
+ if maintain_vectors:
try:
- await self._cleanup_transfer_target(
- new_path, is_dir=is_dir, ctx=ctx, lease_ref=lease
+ vector_result = await self._copy_vector_store_uris(
+ old_uri,
+ new_uri,
+ recursive=is_dir,
+ ctx=ctx,
+ **({"source_uris": source_uris} if is_dir else {}),
)
except Exception:
- logger.warning("Failed to clean copy target %s", new_uri, exc_info=True)
- raise
+ try:
+ await self._cleanup_transfer_target(
+ new_path, is_dir=is_dir, ctx=ctx, lease_ref=lease
+ )
+ except Exception:
+ logger.warning("Failed to clean copy target %s", new_uri, exc_info=True)
+ raise
result: Dict[str, Any] = {
"operation_id": operation_id,
"operation": "copy",
@@ -663,6 +669,7 @@ class _OpsMixin:
is_dir: bool,
ctx: Optional[RequestContext],
lease_ref: Dict[str, Any],
+ copy_semantic_sidecars: bool = True,
) -> int:
if is_dir:
return await self._copy_directory_under_tree_locks(
@@ -672,6 +679,7 @@ class _OpsMixin:
new_uri=new_uri,
ctx=ctx,
lease_ref=lease_ref,
+ copy_semantic_sidecars=copy_semantic_sidecars,
)
await self._async_agfs.cp(
@@ -702,6 +710,9 @@ class _OpsMixin:
new_uri: str,
ctx: Optional[RequestContext] = None,
lease_ref: Dict[str, Any] | None = None,
+ *,
+ vector_mode: Literal["transfer", "delete_source", "none"] = "transfer",
+ copy_semantic_sidecars: bool = True,
) -> Dict[str, Any]:
"""Move file/directory while extending an optional outer pathlock lease.
@@ -801,6 +812,7 @@ class _OpsMixin:
is_temp=is_temp,
ctx=ctx,
lease_ref=lease,
+ copy_semantic_sidecars=copy_semantic_sidecars,
)
or 0
)
@@ -818,18 +830,24 @@ class _OpsMixin:
)
raise
- # Update VectorDB URIs (on failure, clean up the copy)
+ # Update or remove source VectorDB records before deleting the source.
vector_transfer_completed = False
try:
- vector_result = await self._update_vector_store_uris(
- old_uri,
- new_uri,
- recursive=is_dir,
- ctx=ctx,
- **({"source_uris": uris_to_move} if is_dir else {}),
- )
- vector_transfer_completed = True
- if acl_manager is not None and new_acl_scope:
+ vector_result = None
+ if vector_mode == "transfer":
+ vector_result = await self._update_vector_store_uris(
+ old_uri,
+ new_uri,
+ recursive=is_dir,
+ ctx=ctx,
+ **({"source_uris": uris_to_move} if is_dir else {}),
+ )
+ vector_transfer_completed = True
+ elif vector_mode == "delete_source":
+ await self._delete_from_vector_store(uris_to_move, ctx=ctx)
+ elif vector_mode != "none":
+ raise ValueError(f"unsupported move vector mode: {vector_mode}")
+ if vector_mode == "transfer" and acl_manager is not None and new_acl_scope:
await acl_manager.refresh_context_subtree(
new_uri,
self._ctx_or_default(ctx),
@@ -902,6 +920,7 @@ class _OpsMixin:
is_temp: bool,
ctx: Optional[RequestContext] = None,
lease_ref: Dict[str, Any] | None = None,
+ copy_semantic_sidecars: bool = True,
) -> int:
"""Copy source to destination for mv without deleting source."""
del is_temp
@@ -915,6 +934,7 @@ class _OpsMixin:
is_dir=is_dir,
ctx=ctx,
lease_ref=lease_ref,
+ copy_semantic_sidecars=copy_semantic_sidecars,
)
async def _copy_directory_under_tree_locks(
@@ -927,6 +947,7 @@ class _OpsMixin:
lease_ref: Dict[str, Any] | None,
transfer_source_uri: str | None = None,
transfer_target_uri: str | None = None,
+ copy_semantic_sidecars: bool = True,
) -> int:
"""Copy a directory under the operation's source and target Tree leases.
@@ -979,9 +1000,12 @@ class _OpsMixin:
lease_ref=lease_ref,
transfer_source_uri=transfer_source_uri,
transfer_target_uri=transfer_target_uri,
+ copy_semantic_sidecars=copy_semantic_sidecars,
)
else:
if name in ABSTRACT_OVERVIEW_FILENAMES:
+ if not copy_semantic_sidecars:
+ continue
raw = await self._async_agfs.cat(old_child, fs_ctx=fs_ctx)
level = (
ContextLevel.ABSTRACT if name == ".abstract.md" else ContextLevel.OVERVIEW
@@ -1089,6 +1113,7 @@ class _OpsMixin:
ctx: Optional[RequestContext] = None,
skip_count: bool = False,
include_lock_status: bool = False,
+ include_vector_fields: bool = True,
) -> Dict[str, Any]:
"""
File/directory information.
@@ -1160,10 +1185,10 @@ class _OpsMixin:
# Add deterministic vector record id for files (level 2).
# This matches the ID used in VikingDB so callers can cross-reference
# vector records without an extra lookup.
- if not result.get("isDir", False):
+ if include_vector_fields and not result.get("isDir", False):
result["id"] = vector_record_id(real_ctx.account_id, uri, level=2)
# Add count for directories if vector store available
- if not skip_count and result.get("isDir", False):
+ if include_vector_fields and not skip_count and result.get("isDir", False):
try:
vector_store = self._get_vector_store()
if vector_store:
@@ -1206,6 +1231,7 @@ class _OpsMixin:
ctx: Optional[RequestContext] = None,
extra_fields: Optional[List[str]] = None,
tag_filter: Optional[Dict[str, Any]] = None,
+ force_fs: bool = False,
) -> Dict:
"""File pattern matching, supports **/*.md recursive.
@@ -1232,17 +1258,18 @@ class _OpsMixin:
return {"matches": [], "count": 0}
raise NotFoundError(uri, "directory")
- remote_result = await self._try_glob_vikingdb(
- pattern=pattern,
- uri=uri,
- node_limit=node_limit,
- return_entries=return_entries,
- extra_fields=aug_fields,
- tag_filter=tag_filter,
- ctx=real_ctx,
- )
- if remote_result is not None:
- return remote_result
+ if not force_fs:
+ remote_result = await self._try_glob_vikingdb(
+ pattern=pattern,
+ uri=uri,
+ node_limit=node_limit,
+ return_entries=return_entries,
+ extra_fields=aug_fields,
+ tag_filter=tag_filter,
+ ctx=real_ctx,
+ )
+ if remote_result is not None:
+ return remote_result
# Tag filtering happens in FSService on the local fallback path. Fetch
# all matches so an early filesystem limit cannot discard later tagged
diff --git a/openviking/system_assets/__init__.py b/openviking/system_assets/__init__.py
new file mode 100644
index 000000000..4aeac841a
--- /dev/null
+++ b/openviking/system_assets/__init__.py
@@ -0,0 +1,12 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Packaged system assets shipped with OpenViking."""
+
+from pathlib import Path
+
+SYSTEM_ASSETS_DIR = Path(__file__).parent
+
+
+def builtin_memory_templates_dir() -> Path:
+ """Return the packaged builtin memory template directory."""
+ return SYSTEM_ASSETS_DIR / "memory" / "memory_templates" / "builtin"
diff --git a/examples/compile/ov-compile-skills/daily-report/SKILL.md b/openviking/system_assets/compile/example-skills/daily-report/SKILL.md
similarity index 100%
rename from examples/compile/ov-compile-skills/daily-report/SKILL.md
rename to openviking/system_assets/compile/example-skills/daily-report/SKILL.md
diff --git a/examples/compile/ov-compile-skills/knowledge-distillation/SKILL.md b/openviking/system_assets/compile/example-skills/knowledge-distillation/SKILL.md
similarity index 100%
rename from examples/compile/ov-compile-skills/knowledge-distillation/SKILL.md
rename to openviking/system_assets/compile/example-skills/knowledge-distillation/SKILL.md
diff --git a/examples/compile/ov-compile-skills/knowledge-graph/SKILL.md b/openviking/system_assets/compile/example-skills/knowledge-graph/SKILL.md
similarity index 100%
rename from examples/compile/ov-compile-skills/knowledge-graph/SKILL.md
rename to openviking/system_assets/compile/example-skills/knowledge-graph/SKILL.md
diff --git a/examples/compile/ov-compile-skills/llm-wiki/SKILL.md b/openviking/system_assets/compile/example-skills/llm-wiki/SKILL.md
similarity index 96%
rename from examples/compile/ov-compile-skills/llm-wiki/SKILL.md
rename to openviking/system_assets/compile/example-skills/llm-wiki/SKILL.md
index b66058ab7..d44f09c82 100644
--- a/examples/compile/ov-compile-skills/llm-wiki/SKILL.md
+++ b/openviking/system_assets/compile/example-skills/llm-wiki/SKILL.md
@@ -1,6 +1,6 @@
---
name: llm-wiki
-description: Compile heterogeneous knowledge sources—including documents, notes, web content, transcripts, research materials, and code repositories—into a Karpathy-style, evidence-grounded LLM Wiki with a maintained index; default entity and concept pages; and selective method, comparison, analysis, or instruction-requested summary pages. Use with ov compile to create or incrementally refresh knowledge that is easy for people and agents to retrieve, navigate, and reuse.
+description: Compile heterogeneous knowledge sources—including documents, notes, web content, transcripts, research materials, and code repositories—into a Karpathy-style, evidence-grounded LLM Wiki with a maintained index; default entity and concept pages; and selective method, comparison, analysis, or instruction-requested summary pages. Use with ov compile to create or incrementally refresh knowledge that is easy for people and agents to retrieve, navigate, and reuse.
---
# LLM Wiki
diff --git a/examples/compile/ov-compile-skills/ov-session-report/SKILL.md b/openviking/system_assets/compile/example-skills/ov-session-report/SKILL.md
similarity index 100%
rename from examples/compile/ov-compile-skills/ov-session-report/SKILL.md
rename to openviking/system_assets/compile/example-skills/ov-session-report/SKILL.md
diff --git a/openviking/prompts/templates/memory/cases.yaml b/openviking/system_assets/memory/memory_templates/builtin/cases.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/cases.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/cases.yaml
diff --git a/openviking/prompts/templates/memory/entities.yaml b/openviking/system_assets/memory/memory_templates/builtin/entities.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/entities.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/entities.yaml
diff --git a/openviking/prompts/templates/memory/events.yaml b/openviking/system_assets/memory/memory_templates/builtin/events.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/events.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/events.yaml
diff --git a/openviking/prompts/templates/memory/experiences.yaml b/openviking/system_assets/memory/memory_templates/builtin/experiences.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/experiences.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/experiences.yaml
diff --git a/openviking/prompts/templates/memory/experimental_memory/entities.yaml b/openviking/system_assets/memory/memory_templates/builtin/experimental_memory/entities.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/experimental_memory/entities.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/experimental_memory/entities.yaml
diff --git a/openviking/prompts/templates/memory/experimental_memory/profile.yaml b/openviking/system_assets/memory/memory_templates/builtin/experimental_memory/profile.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/experimental_memory/profile.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/experimental_memory/profile.yaml
diff --git a/openviking/prompts/templates/memory/identity.yaml b/openviking/system_assets/memory/memory_templates/builtin/identity.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/identity.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/identity.yaml
diff --git a/openviking/prompts/templates/memory/preferences.yaml b/openviking/system_assets/memory/memory_templates/builtin/preferences.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/preferences.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/preferences.yaml
diff --git a/openviking/prompts/templates/memory/profile.yaml b/openviking/system_assets/memory/memory_templates/builtin/profile.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/profile.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/profile.yaml
diff --git a/openviking/prompts/templates/memory/skills.yaml b/openviking/system_assets/memory/memory_templates/builtin/skills.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/skills.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/skills.yaml
diff --git a/openviking/prompts/templates/memory/soul.yaml b/openviking/system_assets/memory/memory_templates/builtin/soul.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/soul.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/soul.yaml
diff --git a/openviking/prompts/templates/memory/tools.yaml b/openviking/system_assets/memory/memory_templates/builtin/tools.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/tools.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/tools.yaml
diff --git a/openviking/prompts/templates/memory/trajectories.yaml b/openviking/system_assets/memory/memory_templates/builtin/trajectories.yaml
similarity index 100%
rename from openviking/prompts/templates/memory/trajectories.yaml
rename to openviking/system_assets/memory/memory_templates/builtin/trajectories.yaml
diff --git a/openviking/system_assets/reconcile.py b/openviking/system_assets/reconcile.py
new file mode 100644
index 000000000..18ab19174
--- /dev/null
+++ b/openviking/system_assets/reconcile.py
@@ -0,0 +1,94 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Reconcile packaged system assets across all active accounts."""
+
+import asyncio
+from collections.abc import Collection
+from typing import Protocol
+
+from openviking.server.account_stores.models import AccountSummary
+from openviking.server.identity import RequestContext, Role
+from openviking.system_assets.sync import SystemAssetSynchronizer
+from openviking_cli.session.user_id import UserIdentifier
+
+
+class AccountLister(Protocol):
+ async def list_accounts(self, **filters) -> list[AccountSummary]: ...
+
+
+class SystemAssetReconciler:
+ """Coordinate bounded, paginated system-asset sync for active accounts."""
+
+ def __init__(
+ self,
+ synchronizer: SystemAssetSynchronizer,
+ account_lister: AccountLister,
+ *,
+ user_id: str,
+ skip_account_ids: Collection[str] | None = None,
+ page_size: int = 100,
+ max_concurrency: int = 4,
+ ) -> None:
+ if page_size <= 0:
+ raise ValueError("page_size must be positive")
+ if max_concurrency <= 0:
+ raise ValueError("max_concurrency must be positive")
+ self._synchronizer = synchronizer
+ self._account_lister = account_lister
+ self._user_id = user_id
+ self._skip_account_ids = frozenset(skip_account_ids or ())
+ self._page_size = page_size
+ self._semaphore = asyncio.Semaphore(max_concurrency)
+
+ async def sync_all(self) -> int:
+ synced_accounts = 0
+ page = 1
+ while True:
+ accounts = await self._account_lister.list_accounts(
+ limit=self._page_size,
+ page=page,
+ )
+ active_accounts = [
+ account
+ for account in accounts
+ if account.get("status", "active") == "active"
+ and account.get("account_id") not in self._skip_account_ids
+ ]
+ results = await asyncio.gather(
+ *(self._sync_account(account) for account in active_accounts),
+ return_exceptions=True,
+ )
+ for result in results:
+ if isinstance(result, asyncio.CancelledError):
+ raise result
+ failures = [
+ (account.get("account_id") or "<missing>", result)
+ for account, result in zip(active_accounts, results, strict=True)
+ if isinstance(result, Exception)
+ ]
+ if failures:
+ details = ", ".join(
+ f"{account_id}: {type(error).__name__}: {error}"
+ for account_id, error in failures
+ )
+ raise RuntimeError(
+ f"system asset reconciliation failed for {len(failures)} account(s): {details}"
+ ) from failures[0][1]
+
+ synced_accounts += len(active_accounts)
+ if len(accounts) < self._page_size:
+ break
+ page += 1
+ return synced_accounts
+
+ async def _sync_account(self, account: AccountSummary) -> int:
+ account_id = account.get("account_id")
+ if not account_id:
+ raise ValueError("account summary is missing account_id")
+ async with self._semaphore:
+ return await self._synchronizer.sync(
+ RequestContext(
+ user=UserIdentifier(account_id, self._user_id),
+ role=Role(Role.ROOT),
+ )
+ )
diff --git a/openviking/system_assets/sync.py b/openviking/system_assets/sync.py
new file mode 100644
index 000000000..39fbc98a4
--- /dev/null
+++ b/openviking/system_assets/sync.py
@@ -0,0 +1,73 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Synchronize packaged system assets into an account's system namespace."""
+
+import base64
+from dataclasses import replace
+from pathlib import Path
+
+from openviking.core.namespace import uri_parts
+from openviking.core.namespace_policy import (
+ SYSTEM_EXAMPLE_SKILLS_ROOT,
+ SYSTEM_FIXED_DIRECTORIES,
+ SYSTEM_MEMORY_BUILTIN_ROOT,
+)
+from openviking.server.identity import RequestContext, Role
+from openviking.storage.content_write import ContentWriteCoordinator
+from openviking.storage.viking_fs import VikingFS
+from openviking.system_assets import SYSTEM_ASSETS_DIR
+from openviking_cli.exceptions import NotFoundError
+
+_MANAGED_ASSET_ROOTS = (
+ (Path("compile/example-skills"), SYSTEM_EXAMPLE_SKILLS_ROOT),
+ (Path("memory/memory_templates/builtin"), SYSTEM_MEMORY_BUILTIN_ROOT),
+)
+
+
+class SystemAssetSynchronizer:
+ """Converge one account's builtin assets to the packaged contents."""
+
+ def __init__(
+ self,
+ viking_fs: VikingFS,
+ assets_dir: Path = SYSTEM_ASSETS_DIR,
+ ):
+ self._viking_fs = viking_fs
+ self._coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
+ self._assets_dir = assets_dir
+
+ async def sync(self, ctx: RequestContext) -> int:
+ root_ctx = replace(ctx, role=Role.ROOT, actor_peer_id=None)
+ for uri in sorted(SYSTEM_FIXED_DIRECTORIES, key=lambda value: len(uri_parts(value))):
+ await self._viking_fs.mkdir(uri, exist_ok=True, ctx=root_ctx)
+
+ pending_by_root: dict[str, list[dict[str, str]]] = {}
+ for relative_root, target_root in _MANAGED_ASSET_ROOTS:
+ source_root = self._assets_dir / relative_root
+ if not source_root.is_dir():
+ raise FileNotFoundError(f"packaged system asset directory not found: {source_root}")
+ for source_path in sorted(path for path in source_root.rglob("*") if path.is_file()):
+ relative_path = source_path.relative_to(source_root).as_posix()
+ target_uri = f"{target_root}/{relative_path}"
+ expected = source_path.read_bytes()
+ try:
+ current = await self._viking_fs.read_file_bytes(target_uri, ctx=root_ctx)
+ except (FileNotFoundError, NotFoundError):
+ current = None
+ if current == expected:
+ continue
+ pending_by_root.setdefault(target_root, []).append(
+ {
+ "uri": target_uri,
+ "content_base64": base64.b64encode(expected).decode("ascii"),
+ "mode": "replace",
+ }
+ )
+
+ for root_uri, operations in pending_by_root.items():
+ await self._coordinator.batch_write(
+ root_uri=root_uri,
+ operations=operations,
+ ctx=root_ctx,
+ )
+ return sum(len(operations) for operations in pending_by_root.values())
diff --git a/openviking_cli/utils/uri.py b/openviking_cli/utils/uri.py
index 993f419c4..6a7123b52 100644
--- a/openviking_cli/utils/uri.py
+++ b/openviking_cli/utils/uri.py
@@ -43,6 +43,7 @@ class VikingURI:
viking://user/{user_id}/sessions/{session_id}.
- session: Legacy alias for user sessions (viking://session/{session_id}/...)
- agent: Agent capabilities scope (viking://agent/skills/..., viking://agent/endpoints/...)
+ - system: Account-level system assets (viking://system/...)
- queue: Queue scope (viking://queue/...)
- ~: Server-side alias for the caller's user root, expanded to viking://user/{user_id}
@@ -59,6 +60,7 @@ class VikingURI:
"resources",
"user",
"agent",
+ "system",
}
PUBLIC_SCOPES = frozenset(LISTABLE_SCOPES)
LEGACY_SCOPES = frozenset({"session"})
diff --git a/pyproject.toml b/pyproject.toml
index f9558f9cf..5f1a6dca2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -248,6 +248,7 @@ openviking_gateway = ["client-rules.json"]
"vikingbot.studio.providers.feishu" = ["icon.png"]
openviking = [
"prompts/templates/**/*.yaml",
+ "system_assets/**/*",
"server/static/**/*",
"web_studio/dist/**/*",
"lib/ragfs_python*.so",
diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.py
index 38fb90412..eae7162e4 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -47,6 +47,7 @@ from openviking.service.task_work_index import (
from openviking.session.memory.account_templates import (
EDITABLE_MEMORY_TEMPLATE_FIELDS,
account_memory_template_path,
+ legacy_account_memory_template_path,
resolve_account_memory_registry,
)
from openviking.session.memory.extract_loop import ExtractLoop
@@ -607,7 +608,7 @@ async def test_account_memory_templates_publish_and_reset(
)
assert replacement.status_code == 200, replacement.text
assert replacement.json()["result"]["effective"]["fields"] == result["defaults"]["fields"]
- assert yaml.safe_load(fs.agfs._files[path + ".backup"])["description"] == body["description"]
+ assert path + ".backup" not in fs.agfs._files
# An earlier extraction retains its complete snapshot across publication.
assert resolved.get(memory_type).description == body["description"]
reset = await client.delete(f"{root}/{memory_type}", headers=headers)
@@ -628,6 +629,31 @@ async def test_account_memory_templates_publish_and_reset(
assert path not in fs.agfs._files
+async def test_account_memory_template_yaml_uses_literal_multiline_strings(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+):
+ account_id, headers = template_account
+ path = account_memory_template_path(account_id, "profile")
+ backup_path = path + ".backup"
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ fs.agfs._files[backup_path] = b"obsolete"
+ description = "# Role and objective\nReadable custom instructions."
+
+ response = await lightweight_admin_client.put(
+ f"/api/v1/admin/accounts/{account_id}/memory-templates/profile",
+ json={"description": description},
+ headers=headers,
+ )
+
+ assert response.status_code == 200, response.text
+ raw = fs.agfs._files[path].decode("utf-8")
+ assert "description: |" in raw
+ assert yaml.safe_load(raw)["description"] == description
+ assert backup_path not in fs.agfs._files
+
+
@pytest.mark.parametrize(
"memory_type,edit",
[
@@ -765,7 +791,6 @@ async def test_account_memory_templates_module_reset_clears_override(
assert result["status"] == "custom"
fs = lightweight_admin_app.state.fake_service.viking_fs
path = account_memory_template_path(account_id, memory_type)
- previous = fs.agfs._files[path]
snapshot = await resolve_account_memory_registry(fs, account_id, get_default_registry())
previous_schema = snapshot.get(memory_type).model_dump()
untouched = {key: value for key, value in fs.agfs._files.items() if key != path}
@@ -786,7 +811,7 @@ async def test_account_memory_templates_module_reset_clears_override(
assert restored.status_code == 200, restored.text
assert restored.json()["result"] == initial
assert path not in fs.agfs._files
- assert fs.agfs._files[path + ".backup"] == previous
+ assert path + ".backup" not in fs.agfs._files
assert all(fs.agfs._files[key] == value for key, value in untouched.items())
assert (await client.get(url, headers=headers)).json()["result"] == initial
listed = (await client.get(root, headers=headers)).json()["result"]["templates"]
@@ -1337,7 +1362,7 @@ async def test_account_memory_templates_old_content_can_be_read_replaced_and_res
),
)
assert response.status_code == 200, response.text
- assert fs.agfs._files[path + ".backup"] == raw
+ assert path + ".backup" not in fs.agfs._files
@pytest.mark.parametrize(
@@ -1805,7 +1830,7 @@ async def test_account_memory_templates_reject_oversized_serialized_config(
assert fs.agfs._files == original
-async def test_account_memory_templates_corrupt_storage_is_not_overwritten(
+async def test_account_memory_templates_read_rejects_corrupt_storage_but_writes_can_recover(
lightweight_admin_client,
lightweight_admin_app,
template_account,
@@ -1813,19 +1838,175 @@ async def test_account_memory_templates_corrupt_storage_is_not_overwritten(
account_id, headers = template_account
fs = lightweight_admin_app.state.fake_service.viking_fs
path = account_memory_template_path(account_id, "profile")
- fs.agfs._files[path] = b'{"invalid-json"'
- original = dict(fs.agfs._files)
url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
- for method in ("GET", "PUT", "DELETE"):
- response = await lightweight_admin_client.request(
- method,
- url,
- headers=headers,
- **({"json": {"description": "New"}} if method == "PUT" else {}),
- )
- assert response.status_code == 412, response.text
- assert response.json()["error"]["code"] == "FAILED_PRECONDITION"
- assert fs.agfs._files == original
+ corrupt = b'{"invalid-json"'
+
+ fs.agfs._files[path] = corrupt
+ response = await lightweight_admin_client.get(url, headers=headers)
+ assert response.status_code == 412, response.text
+ assert response.json()["error"]["code"] == "FAILED_PRECONDITION"
+ assert fs.agfs._files[path] == corrupt
+
+ response = await lightweight_admin_client.put(
+ url, headers=headers, json={"description": "Recovered"}
+ )
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["effective"]["description"] == "Recovered"
+ assert path + ".backup" not in fs.agfs._files
+
+ fs.agfs._files[path] = corrupt
+ response = await lightweight_admin_client.delete(url, headers=headers)
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["status"] == "system_default"
+ assert path not in fs.agfs._files
+ assert path + ".backup" not in fs.agfs._files
+
+
+async def test_account_memory_templates_read_legacy_without_side_effect_then_migrate_on_put(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+):
+ account_id, headers = template_account
+ client = lightweight_admin_client
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ legacy_path = legacy_account_memory_template_path(account_id, "profile")
+
+ published = await client.put(url, headers=headers, json={"description": "Legacy"})
+ assert published.status_code == 200, published.text
+ original = fs.agfs._files.pop(path)
+ fs.agfs._files[legacy_path] = original
+
+ read = await client.get(url, headers=headers)
+ assert read.status_code == 200, read.text
+ assert read.json()["result"]["effective"]["description"] == "Legacy"
+ assert path not in fs.agfs._files
+ assert fs.agfs._files[legacy_path] == original
+
+ migrated = await client.put(url, headers=headers, json=read.json()["result"]["effective"])
+ assert migrated.status_code == 200, migrated.text
+ assert migrated.json()["result"]["effective"]["description"] == "Legacy"
+ assert path in fs.agfs._files
+ assert legacy_path not in fs.agfs._files
+ assert path + ".backup" not in fs.agfs._files
+
+
+async def test_account_memory_templates_invalid_new_path_does_not_fallback_to_legacy(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+):
+ account_id, headers = template_account
+ client = lightweight_admin_client
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ legacy_path = legacy_account_memory_template_path(account_id, "profile")
+
+ published = await client.put(url, headers=headers, json={"description": "Legacy"})
+ assert published.status_code == 200, published.text
+ fs.agfs._files[legacy_path] = fs.agfs._files[path]
+ fs.agfs._files[path] = b"invalid: ["
+
+ response = await client.get(url, headers=headers)
+ assert response.status_code == 412, response.text
+ assert response.json()["error"]["code"] == "FAILED_PRECONDITION"
+
+
+async def test_account_memory_templates_retry_cleans_legacy_after_published_migration(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ account_id, headers = template_account
+ client = lightweight_admin_client
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ legacy_path = legacy_account_memory_template_path(account_id, "profile")
+
+ published = await client.put(url, headers=headers, json={"description": "Legacy"})
+ assert published.status_code == 200, published.text
+ fs.agfs._files[legacy_path] = fs.agfs._files.pop(path)
+ remove = fs.agfs.rm
+ failed = False
+
+ def fail_legacy_cleanup_once(target, **kwargs):
+ nonlocal failed
+ if target == legacy_path and not failed:
+ failed = True
+ raise OSError("legacy cleanup failed")
+ return remove(target, **kwargs)
+
+ monkeypatch.setattr(fs.agfs, "rm", fail_legacy_cleanup_once)
+ response = await client.put(url, headers=headers, json={"description": "Current"})
+ assert response.status_code == 412, response.text
+ assert response.json()["error"]["details"] == {
+ "published": True,
+ "legacy_cleanup_pending": True,
+ "retryable": True,
+ }
+ assert path in fs.agfs._files
+ assert legacy_path in fs.agfs._files
+ current = (await client.get(url, headers=headers)).json()["result"]
+ assert current["effective"]["description"] == "Current"
+
+ retry = await client.put(url, headers=headers, json={"description": "Current"})
+ assert retry.status_code == 200, retry.text
+ assert retry.json()["result"]["updated_at"] == current["updated_at"]
+ assert legacy_path not in fs.agfs._files
+
+
+async def test_account_memory_templates_reset_removes_legacy_before_current(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ account_id, headers = template_account
+ client = lightweight_admin_client
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ legacy_path = legacy_account_memory_template_path(account_id, "profile")
+
+ published = await client.put(url, headers=headers, json={"description": "Current"})
+ assert published.status_code == 200, published.text
+ current = fs.agfs._files[path]
+ fs.agfs._files[legacy_path] = current
+ remove = fs.agfs.rm
+ removed = []
+ failed = False
+
+ def fail_legacy_cleanup_once(target, **kwargs):
+ nonlocal failed
+ removed.append(target)
+ if target == legacy_path and not failed:
+ failed = True
+ raise OSError("legacy cleanup failed")
+ return remove(target, **kwargs)
+
+ monkeypatch.setattr(fs.agfs, "rm", fail_legacy_cleanup_once)
+ response = await client.delete(url, headers=headers)
+ assert response.status_code == 412, response.text
+ assert response.json()["error"]["details"] == {
+ "legacy_cleanup_pending": True,
+ "retryable": True,
+ }
+ assert removed == [legacy_path]
+ assert fs.agfs._files[path] == current
+ assert fs.agfs._files[legacy_path] == current
+
+ response = await client.delete(url, headers=headers)
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["status"] == "system_default"
+ assert removed[-3:] == [legacy_path, path, path + ".backup"]
+ assert path not in fs.agfs._files
+ assert legacy_path not in fs.agfs._files
+ assert path + ".backup" not in fs.agfs._files
async def test_create_account(
diff --git a/tests/server/test_compile_studio.py b/tests/server/test_compile_studio.py
index 32b496949..cd8eaf7be 100644
--- a/tests/server/test_compile_studio.py
+++ b/tests/server/test_compile_studio.py
@@ -20,6 +20,61 @@ from openviking_cli.session.user_id import UserIdentifier
from tests.test_task_tracker import _FakeAgfs
+def test_compile_accepts_builtin_example_skill():
+ from openviking.service.compile_service import CompileRequest, CompileService
+ from openviking_cli.utils.config.open_viking_config import CompileApiConfig
+
+ service = CompileService(CompileApiConfig(), ExternalTaskService(), SimpleNamespace())
+ ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)
+ request = CompileRequest.model_validate(
+ {
+ "from": ["viking://resources/source"],
+ "to": "viking://resources/wiki",
+ "skill": "viking://system/compile/example-skills/llm-wiki/SKILL.md",
+ }
+ )
+
+ normalized = service._normalize_request_uris(request, ctx)
+
+ assert normalized.skill == "viking://system/compile/example-skills/llm-wiki"
+
+
+ "skill",
+ [
+ "viking://system/compile/example-skills",
+ "viking://system/compile/example-skills/llm-wiki/references",
+ "viking://system/memory/memory_templates/builtin",
+ ],
+)
+def test_compile_rejects_other_system_directories(skill):
+ from openviking.service.compile_service import CompileRequest, CompileService
+ from openviking_cli.utils.config.open_viking_config import CompileApiConfig
+
+ service = CompileService(CompileApiConfig(), ExternalTaskService(), SimpleNamespace())
+ ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)
+ request = CompileRequest.model_validate(
+ {
+ "from": ["viking://resources/source"],
+ "to": "viking://resources/wiki",
+ "skill": skill,
+ }
+ )
+
+ with pytest.raises(InvalidArgumentError, match="skill must resolve"):
+ service._normalize_request_uris(request, ctx)
+
+
+def test_compile_builtin_skill_namespace_is_source_only():
+ from openviking.service.compile_service import CompileService
+
+ CompileService._validate_target("viking://user/alice/skills")
+ CompileService._validate_target("viking://agent/skills")
+
+ with pytest.raises(InvalidArgumentError, match="supported skills namespace"):
+ CompileService._validate_target("viking://system/compile/example-skills")
+
+
@pytest.mark.asyncio
async def test_page_reads_past_200_and_isolates_owner():
agfs = _FakeAgfs()
diff --git a/tests/server/test_content_batch_write.py b/tests/server/test_content_batch_write.py
index 923f77f60..e6306d2b4 100644
--- a/tests/server/test_content_batch_write.py
+++ b/tests/server/test_content_batch_write.py
@@ -44,6 +44,11 @@ class _PathLockClient:
self.held = True
return {"lease_ref": "lock-1"}
+ async def pathlock_acquire_exact(self, path):
+ self.paths = [path]
+ self.held = True
+ return {"lease_ref": "lock-1"}
+
async def pathlock_to_handoff(self, lease):
assert lease == {"lease_ref": "lock-1"}
assert self.held is True
@@ -123,6 +128,157 @@ class _VFS:
self.writes.append(uri)
+async def test_system_write_is_file_only_without_queue_work(
+ _coordinator_queue_for_unit_tests,
+):
+ root = "viking://system/memory/memory_templates/custom/demo"
+ uri = f"{root}/template.md"
+ vfs = _VFS(root)
+ coordinator = ContentWriteCoordinator(vfs)
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ADMIN)
+
+ result = await coordinator.write(
+ uri=uri,
+ content="template",
+ ctx=ctx,
+ wait=False,
+ )
+
+ assert vfs.files[uri] == "template"
+ assert vfs._async_agfs.releases == 1
+ assert vfs._async_agfs.handoffs == 0
+ assert result["root_uri"] == root
+ assert result["semantic_status"] == "skipped"
+ assert result["vector_status"] == "skipped"
+ assert result["queue_status"] is None
+ assert _last_content_write_refresh(_coordinator_queue_for_unit_tests) == {"kind": "none"}
+ _coordinator_queue_for_unit_tests.content_write.enqueue.assert_awaited_once()
+ _coordinator_queue_for_unit_tests.semantic.enqueue.assert_not_awaited()
+
+
+async def test_system_batch_write_is_file_only_without_queue_work(
+ _coordinator_queue_for_unit_tests,
+):
+ root = "viking://system/memory/memory_templates/custom/demo"
+ first = f"{root}/first.md"
+ second = f"{root}/second.md"
+ vfs = _VFS(root, {first: "old"})
+ coordinator = ContentWriteCoordinator(vfs)
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ADMIN)
+
+ result = await coordinator.batch_write(
+ root_uri=root,
+ operations=[
+ {"uri": first, "content": "new"},
+ {"uri": second, "content": "created"},
+ ],
+ ctx=ctx,
+ wait=False,
+ )
+
+ assert result["updated"] == [first]
+ assert result["created"] == [second]
+ assert result["semantic_status"] == "skipped"
+ assert result["vector_status"] == "skipped"
+ assert result["queue_status"] is None
+ assert vfs._async_agfs.releases == 1
+ assert vfs._async_agfs.handoffs == 0
+ assert _last_content_write_refresh(_coordinator_queue_for_unit_tests) == {"kind": "none"}
+ _coordinator_queue_for_unit_tests.content_write.enqueue.assert_awaited_once()
+ _coordinator_queue_for_unit_tests.semantic.enqueue.assert_not_awaited()
+
+
+async def test_system_builtin_batch_write_accepts_binary_assets(
+ _coordinator_queue_for_unit_tests,
+):
+ root = "viking://system/compile/example-skills"
+ uri = f"{root}/demo/assets/icon.bin"
+ content = b"\x89PNG\r\n\x1a\nasset"
+ vfs = _VFS(root)
+ coordinator = ContentWriteCoordinator(vfs)
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
+
+ result = await coordinator.batch_write(
+ root_uri=root,
+ operations=[
+ {
+ "uri": uri,
+ "content_base64": base64.b64encode(content).decode("ascii"),
+ "mode": "replace",
+ }
+ ],
+ ctx=ctx,
+ wait=False,
+ )
+
+ assert result["created"] == [uri]
+ assert vfs.files[uri] == content
+ assert result["semantic_status"] == "skipped"
+ assert result["vector_status"] == "skipped"
+ assert _last_content_write_refresh(_coordinator_queue_for_unit_tests) == {"kind": "none"}
+ _coordinator_queue_for_unit_tests.content_write.enqueue.assert_awaited_once()
+ _coordinator_queue_for_unit_tests.semantic.enqueue.assert_not_awaited()
+
+
+async def test_user_skill_namespace_batch_write_remains_rejected():
+ root = "viking://user/default/skills"
+ coordinator = ContentWriteCoordinator(_VFS(root))
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
+
+ with pytest.raises(
+ InvalidArgumentError,
+ match="batch-write root must be a resource or memory directory",
+ ):
+ await coordinator.batch_write(
+ root_uri=root,
+ operations=[
+ {
+ "uri": f"{root}/demo/SKILL.md",
+ "content": "skill",
+ "mode": "replace",
+ }
+ ],
+ ctx=ctx,
+ )
+
+
+async def test_system_write_rejects_indexed_metadata():
+ root = "viking://system/memory/memory_templates/custom/demo"
+ uri = f"{root}/template.md"
+ coordinator = ContentWriteCoordinator(_VFS(root))
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ADMIN)
+
+ with pytest.raises(InvalidArgumentError, match="tags are not supported"):
+ await coordinator.write(
+ uri=uri,
+ content="template",
+ tags=["kind=template"],
+ ctx=ctx,
+ )
+
+
+async def test_system_set_tags_rejects_capability_before_write_access():
+ uri = "viking://system/memory/memory_templates/custom/demo/template.md"
+ ensure_access = AsyncMock(side_effect=AssertionError("write access must not be checked"))
+ coordinator = ContentWriteCoordinator(SimpleNamespace(_ensure_access=ensure_access))
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
+
+ with pytest.raises(InvalidArgumentError, match="tags are not supported"):
+ await coordinator.set_tags(
+ uri=uri,
+ tags=["kind=template"],
+ ctx=ctx,
+ )
+
+ ensure_access.assert_not_awaited()
+
+
@pytest.fixture(autouse=True)
def _coordinator_queue_for_unit_tests(monkeypatch, request):
if "service" in request.fixturenames:
diff --git a/tests/server/test_filesystem_router.py b/tests/server/test_filesystem_router.py
index 1e7ae0940..a1aef50f0 100644
--- a/tests/server/test_filesystem_router.py
+++ b/tests/server/test_filesystem_router.py
@@ -2,6 +2,7 @@
# SPDX-License-Identifier: AGPL-3.0
"""Filesystem router tests."""
+import asyncio
from types import SimpleNamespace
from unittest.mock import AsyncMock
@@ -9,10 +10,16 @@ import httpx
import pytest
from fastapi import FastAPI
+from openviking.core.namespace_policy import (
+ SYSTEM_MEMORY_BUILTIN_ROOT,
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+)
from openviking.server.auth import get_request_context
from openviking.server.identity import RequestContext, Role
from openviking.server.routers import filesystem
from openviking.service.fs_service import ListingPage
+from openviking.storage.queuefs.queue_manager import get_queue_manager
+from openviking.system_assets import builtin_memory_templates_dir
from openviking_cli.exceptions import InvalidURIError
from openviking_cli.session.user_id import UserIdentifier
@@ -107,9 +114,73 @@ def test_cp_request_defaults_to_non_recursive():
assert request.recursive is False
+ ("operation", "source", "target", "recursive", "indexed_file"),
+ [
+ (
+ "cp",
+ "viking://system/compile/example-skills/llm-wiki/SKILL.md",
+ "viking://resources/transferred-file-copy.md",
+ False,
+ "viking://resources/transferred-file-copy.md",
+ ),
+ (
+ "mv",
+ "viking://system/compile/example-skills/llm-wiki/SKILL.md",
+ "viking://resources/transferred-file-move.md",
+ False,
+ "viking://resources/transferred-file-move.md",
+ ),
+ (
+ "cp",
+ "viking://system/compile/example-skills/llm-wiki",
+ "viking://resources/transferred-dir-copy",
+ True,
+ "viking://resources/transferred-dir-copy/SKILL.md",
+ ),
+ (
+ "mv",
+ "viking://system/compile/example-skills/llm-wiki",
+ "viking://resources/transferred-dir-move",
+ True,
+ "viking://resources/transferred-dir-move/SKILL.md",
+ ),
+ ],
+)
+async def test_file_only_transfer_builds_searchable_target_index(
+ service,
+ operation,
+ source,
+ target,
+ recursive,
+ indexed_file,
+):
+ ctx = RequestContext(user=service.user, role=Role.ROOT)
+
+ if operation == "cp":
+ await service.fs.cp(source, target, recursive=recursive, ctx=ctx)
+ else:
+ await service.fs.mv(source, target, ctx=ctx)
+ await asyncio.wait_for(get_queue_manager().wait_complete(), 30)
+
+ record = await service.viking_fs.vector_store.fetch_by_uri(indexed_file, ctx=ctx)
+ assert record is not None
+ assert record["level"] == 2
+ result = await service.search.search(
+ query="Fake summary for testing",
+ target_uri=target if recursive else target.rsplit("/", 1)[0],
+ level=[2],
+ score_threshold=0,
+ ctx=ctx,
+ )
+ assert any(item.uri == indexed_file for item in result.resources)
+
+
@pytest.mark.asyncio
async def test_cp_canonicalizes_home_aliases(monkeypatch):
calls = []
+ calls = []
async def fake_cp(from_uri, to_uri, recursive=False, ctx=None):
calls.append((from_uri, to_uri, recursive, ctx))
@@ -214,6 +285,32 @@ async def test_attrs_returns_memory_fields_and_tags(monkeypatch):
assert attrs["tags"] == ["team=search"]
+async def test_system_attrs_returns_empty_tags_without_querying_vector_store(monkeypatch):
+ uri = "viking://system/memory/memory_templates/custom/demo.md"
+ stat = AsyncMock(return_value={"isDir": False})
+ vector_filter = AsyncMock(side_effect=AssertionError("system attrs must not query vectors"))
+ monkeypatch.setattr(
+ filesystem,
+ "get_service",
+ lambda: SimpleNamespace(
+ fs=SimpleNamespace(stat=stat),
+ vikingdb_manager=SimpleNamespace(filter=vector_filter),
+ ),
+ )
+ ctx = RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER)
+
+ response = await filesystem.attrs(uri=uri, _ctx=ctx)
+
+ assert response.result == {
+ "uri": uri,
+ "context_type": "resource",
+ "attrs": {"tags": []},
+ }
+ stat.assert_awaited_once_with(uri, ctx=ctx, skip_count=True)
+ vector_filter.assert_not_awaited()
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("role", [Role.USER, Role.ADMIN, Role.ROOT])
async def test_mkdir_echoes_canonical_home_alias(monkeypatch, role):
@@ -375,6 +472,51 @@ async def test_ls_user_container_lists_only_caller_space(app, client, service):
assert response.json()["has_more"] is False
[email protected]("endpoint", ["ls", "tree"])
+async def test_system_listing_default_http_output_uses_only_physical_metadata(
+ app, client, service, endpoint
+):
+ root = "viking://system/memory/memory_templates/custom/http-default"
+ child = f"{root}/demo"
+ root_ctx = RequestContext(user=UserIdentifier("default", "default"), role=Role.ROOT)
+ await service.viking_fs.mkdir(child, exist_ok=True, ctx=root_ctx)
+
+ app.dependency_overrides[get_request_context] = lambda: RequestContext(
+ user=UserIdentifier("default", "alice"), role=Role.USER
+ )
+ try:
+ response = await client.get(
+ f"/api/v1/fs/{endpoint}",
+ params={"uri": root},
+ )
+ finally:
+ app.dependency_overrides.pop(get_request_context, None)
+
+ assert response.status_code == 200, response.text
+ entries = response.json()["result"]
+ assert entries
+ assert all("abstract" not in entry and "overview" not in entry for entry in entries)
+
+
+async def test_service_startup_syncs_builtin_assets_and_custom_directory(service):
+ ctx = RequestContext(user=UserIdentifier("default", "default"), role=Role.ROOT)
+ profile_uri = f"{SYSTEM_MEMORY_BUILTIN_ROOT}/profile.yaml"
+
+ assert await service.viking_fs.read_file_bytes(
+ profile_uri,
+ ctx=ctx,
+ ) == (builtin_memory_templates_dir() / "profile.yaml").read_bytes()
+ assert (
+ await service.viking_fs.stat(
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+ ctx=ctx,
+ skip_count=True,
+ )
+ )["isDir"]
+
+
@pytest.mark.asyncio
async def test_ls_and_tree_forward_pagination_to_filesystem_service(monkeypatch):
seen = {"ls": {}, "tree": {}}
diff --git a/tests/server/test_server_health.py b/tests/server/test_server_health.py
index d02d4a7c2..90390c2f8 100644
--- a/tests/server/test_server_health.py
+++ b/tests/server/test_server_health.py
@@ -324,7 +324,9 @@ async def test_slow_init_does_not_block_health(monkeypatch):
async def test_initialize_runtime_state_loads_api_key_manager(monkeypatch):
- """The auth plugin must publish its manager before deletion setup."""
+ """System assets reconcile after auth loading and before deletion setup."""
+
+ events = []
class MockService:
def __init__(self):
@@ -334,16 +336,27 @@ async def test_initialize_runtime_state_loads_api_key_manager(monkeypatch):
async def initialize(self):
self._initialized = True
+ events.append("service")
async def apply_agent_evolution_config(self):
- pass
+ events.append("agent-evolution")
+
+ async def reconcile_system_assets(self, account_lister):
+ assert account_lister is manager
+ events.append("system-assets")
+ return 1
manager = object()
- setup = AsyncMock(return_value=None)
+
+ async def setup(**kwargs):
+ assert kwargs["manager"] is manager
+ events.append("deletion")
+
monkeypatch.setattr("openviking.service.deletion.setup_deletion", setup)
async def initialize_plugin(app, service, config):
app.state.api_key_manager = manager
+ events.append("auth")
monkeypatch.setattr("openviking.server.app._initialize_auth_plugin", initialize_plugin)
@@ -355,4 +368,31 @@ async def test_initialize_runtime_state_loads_api_key_manager(monkeypatch):
assert service._initialized is True
assert app.state.api_key_manager is manager
- assert setup.await_args.kwargs["manager"] is manager
+ assert events == [
+ "service",
+ "agent-evolution",
+ "auth",
+ "system-assets",
+ "deletion",
+ ]
+
+
+async def test_initialize_runtime_state_skips_reconcile_without_account_manager(monkeypatch):
+ service = SimpleNamespace(
+ initialize=AsyncMock(),
+ apply_agent_evolution_config=AsyncMock(),
+ reconcile_system_assets=AsyncMock(),
+ )
+ setup = AsyncMock(return_value=None)
+ monkeypatch.setattr("openviking.service.deletion.setup_deletion", setup)
+
+ async def initialize_plugin(app, service, config):
+ app.state.api_key_manager = None
+
+ monkeypatch.setattr("openviking.server.app._initialize_auth_plugin", initialize_plugin)
+
+ app = SimpleNamespace(state=SimpleNamespace(api_key_manager=None))
+ await _initialize_runtime_state(app, service, ServerConfig())
+
+ service.reconcile_system_assets.assert_not_awaited()
+ assert setup.await_args.kwargs["manager"] is None
diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.py
index 733682ff1..3cf759d1b 100644
--- a/tests/service/test_fs_service.py
+++ b/tests/service/test_fs_service.py
@@ -1443,6 +1443,51 @@ async def test_transfer_refresh_message_records_deleted_source_entry(
assert queue_manager.messages[0].changes == {"deleted": ["viking://resources/source/moved.md"]}
[email protected]("recursive", [False, True])
+async def test_file_only_transfer_rebuild_uses_fresh_semantic_processing(
+ request_context,
+ monkeypatch,
+ recursive,
+):
+ service = FSService(viking_fs=_FakeVikingFS())
+ queue_manager = _FakeQueueManager()
+ mark_pending = AsyncMock()
+ monkeypatch.setattr(
+ "openviking.service.fs_service.get_queue_manager",
+ lambda: queue_manager,
+ )
+ monkeypatch.setattr(
+ "openviking.service.fs_service.mark_abstract_overview_pending",
+ mark_pending,
+ )
+ target = (
+ "viking://resources/archive/copied"
+ if recursive
+ else "viking://resources/archive/copied.md"
+ )
+ root = target if recursive else "viking://resources/archive"
+
+ status = await service._enqueue_transfer_rebuild(
+ root_uri=root,
+ target_uri=target,
+ recursive=recursive,
+ context_type="resource",
+ ctx=request_context,
+ )
+
+ assert status == "queued"
+ msg = queue_manager.messages[0]
+ assert msg.uri == root
+ assert msg.recursive is recursive
+ assert msg.changes is None if recursive else msg.changes == {"added": [target]}
+ assert msg.generation_trigger == "content_transfer_rebuild"
+ if recursive:
+ mark_pending.assert_not_awaited()
+ else:
+ mark_pending.assert_awaited_once()
+
+
@pytest.mark.asyncio
async def test_resource_rm_does_not_cleanup_memory_if_resource_delete_fails(request_context):
delete_error = RuntimeError("delete failed")
@@ -1509,3 +1554,415 @@ async def test_resource_rm_refreshes_memory_overview_for_cleaned_memories(
}
]
assert result["memory_cleanup"] == cleanup
+
+
+async def test_system_mkdir_skips_semantic_sidecar_and_vectorization(request_context):
+ uri = "viking://system/memory/memory_templates/custom/demo"
+ viking_fs = SimpleNamespace(_ensure_access=AsyncMock(), mkdir=AsyncMock())
+ service = FSService(viking_fs=viking_fs)
+
+ await service.mkdir(uri, ctx=request_context)
+
+ viking_fs._ensure_access.assert_awaited_once()
+ viking_fs.mkdir.assert_awaited_once_with(uri, ctx=request_context)
+
+
+async def test_system_rm_skips_vector_and_semantic_work(request_context):
+ uri = "viking://system/memory/memory_templates/custom/demo.md"
+ viking_fs = SimpleNamespace(
+ rm=AsyncMock(return_value={"estimated_deleted_count": 0}),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ result = await service._rm(uri, ctx=request_context)
+
+ viking_fs.rm.assert_awaited_once_with(
+ uri,
+ recursive=False,
+ ctx=request_context,
+ no_vector=True,
+ )
+ assert result["semantic_status"] == "skipped"
+ assert result["vector_status"] == "skipped"
+
+
+async def test_system_stat_suppresses_vector_fields(request_context):
+ uri = "viking://system/memory/memory_templates/custom/demo.md"
+ viking_fs = SimpleNamespace(stat=AsyncMock(return_value={"uri": uri}))
+ service = FSService(viking_fs=viking_fs)
+
+ await service.stat(uri, ctx=request_context)
+
+ viking_fs.stat.assert_awaited_once_with(
+ uri,
+ ctx=request_context,
+ skip_count=True,
+ include_lock_status=False,
+ include_vector_fields=False,
+ )
+
+
+async def test_system_ls_allows_agent_output_without_semantic_enrichment(request_context):
+ uri = "viking://system/memory/memory_templates/custom"
+ entries = [{"uri": f"{uri}/demo.md", "isDir": False}]
+ formatted = [{**entries[0], "size": 4}]
+ viking_fs = SimpleNamespace(
+ _ensure_access=AsyncMock(),
+ ls=AsyncMock(return_value=entries),
+ _finalize_listing_entries=AsyncMock(return_value=formatted),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ result = await service.ls(uri, ctx=request_context, output="agent")
+
+ assert result == ListingPage(entries=formatted, has_more=False)
+ finalize_call = viking_fs._finalize_listing_entries.await_args
+ assert finalize_call.args[1] == "agent"
+ assert finalize_call.kwargs["include_abstract"] is False
+ assert finalize_call.kwargs["include_overview"] is False
+
+
+async def test_system_tree_allows_agent_output_without_semantic_enrichment(request_context):
+ uri = "viking://system/memory/memory_templates/custom"
+ entries = [{"uri": f"{uri}/demo.md", "isDir": False, "rel_path": "demo.md"}]
+ viking_fs = SimpleNamespace(
+ _ensure_access=AsyncMock(),
+ tree=AsyncMock(return_value=entries),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ result = await service.tree(uri, ctx=request_context, output="agent")
+
+ assert result == ListingPage(entries=entries, has_more=False)
+ tree_options = viking_fs.tree.await_args.kwargs
+ assert tree_options["output"] == "agent"
+ assert tree_options["include_abstract"] is False
+ assert tree_options["include_overview"] is False
+
+
+async def test_copy_to_system_uses_physical_file_strategy(request_context):
+ source = "viking://resources/project/demo.md"
+ target = "viking://system/memory/memory_templates/custom/demo.md"
+ viking_fs = SimpleNamespace(
+ cp=AsyncMock(return_value={"from": source, "to": target, "recursive": False}),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ result = await service.cp(source, target, recursive=False, ctx=request_context)
+
+ viking_fs.cp.assert_awaited_once_with(
+ source,
+ target,
+ recursive=False,
+ ctx=request_context,
+ maintain_vectors=False,
+ copy_semantic_sidecars=False,
+ )
+ assert result["semantic_status"] == "skipped"
+ assert result["vector_status"] == "skipped"
+
+
+async def test_indexed_copy_preserves_native_vectors_and_content_copy_refresh(request_context):
+ source = "viking://resources/source/demo.md"
+ target = "viking://resources/target/demo.md"
+ viking_fs = SimpleNamespace(
+ cp=AsyncMock(return_value={"from": source, "to": target, "recursive": False}),
+ )
+ service = FSService(viking_fs=viking_fs)
+ service._enqueue_copy_refresh = AsyncMock(return_value="queued")
+
+ await service.cp(source, target, recursive=False, ctx=request_context)
+
+ viking_fs.cp.assert_awaited_once_with(
+ source,
+ target,
+ recursive=False,
+ ctx=request_context,
+ )
+ service._enqueue_copy_refresh.assert_awaited_once()
+
+
+async def test_indexed_move_preserves_native_vector_transfer(request_context):
+ source = "viking://resources/source/demo.md"
+ target = "viking://resources/target/demo.md"
+ viking_fs = SimpleNamespace(mv=AsyncMock())
+ service = FSService(viking_fs=viking_fs)
+ service._refresh_move_parents = AsyncMock()
+
+ await service.mv(source, target, ctx=request_context)
+
+ viking_fs.mv.assert_awaited_once_with(source, target, ctx=request_context)
+ service._refresh_move_parents.assert_awaited_once_with(
+ from_uri=source,
+ to_uri=target,
+ ctx=request_context,
+ )
+
+
[email protected]("operation", ["cp", "mv"])
+async def test_transfer_to_registered_memory_template_is_rejected(request_context, operation):
+ source = "viking://resources/project/demo.yaml"
+ target = "viking://system/memory/memory_templates/custom/profile.yaml"
+ viking_fs = SimpleNamespace(cp=AsyncMock(), mv=AsyncMock())
+ service = FSService(viking_fs=viking_fs)
+
+ with pytest.raises(InvalidArgumentError, match="must be updated through write"):
+ if operation == "cp":
+ await service.cp(source, target, recursive=False, ctx=request_context)
+ else:
+ await service.mv(source, target, ctx=request_context)
+
+ getattr(viking_fs, operation).assert_not_awaited()
+
+
+async def test_move_to_system_deletes_source_vectors_without_target_index(
+ monkeypatch,
+ request_context,
+):
+ source = "viking://resources/project/demo.md"
+ target = "viking://system/memory/memory_templates/custom/demo.md"
+ viking_fs = SimpleNamespace(mv=AsyncMock())
+ service = FSService(viking_fs=viking_fs)
+ refresh = AsyncMock()
+ monkeypatch.setattr(service, "_refresh_move_parents", refresh)
+
+ await service.mv(source, target, ctx=request_context)
+
+ viking_fs.mv.assert_awaited_once_with(
+ source,
+ target,
+ ctx=request_context,
+ vector_mode="delete_source",
+ copy_semantic_sidecars=False,
+ )
+ refresh.assert_awaited_once()
+
+
[email protected]("sidecar_name", [".abstract.md", ".overview.md"])
+async def test_copy_to_system_rejects_semantic_sidecar_target(
+ request_context,
+ sidecar_name,
+):
+ source = "viking://resources/project/demo.md"
+ target = f"viking://system/memory/memory_templates/custom/{sidecar_name}"
+ viking_fs = SimpleNamespace(cp=AsyncMock())
+ service = FSService(viking_fs=viking_fs)
+
+ with pytest.raises(InvalidArgumentError, match="semantic sidecars are not supported"):
+ await service.cp(source, target, recursive=False, ctx=request_context)
+
+ viking_fs.cp.assert_not_awaited()
+
+
[email protected]("sidecar_name", [".abstract.md", ".overview.md"])
+async def test_move_to_system_rejects_semantic_sidecar_target(
+ request_context,
+ sidecar_name,
+):
+ source = "viking://resources/project/demo.md"
+ target = f"viking://system/memory/memory_templates/custom/{sidecar_name}"
+ viking_fs = SimpleNamespace(mv=AsyncMock())
+ service = FSService(viking_fs=viking_fs)
+
+ with pytest.raises(InvalidArgumentError, match="semantic sidecars are not supported"):
+ await service.mv(source, target, ctx=request_context)
+
+ viking_fs.mv.assert_not_awaited()
+
+
+async def test_copy_from_system_rebuilds_target_index(request_context):
+ source = "viking://system/memory/memory_templates/custom/demo.md"
+ target = "viking://resources/project/demo.md"
+ viking_fs = SimpleNamespace(
+ cp=AsyncMock(return_value={"from": source, "to": target, "recursive": False}),
+ stat=AsyncMock(return_value={"isDir": False}),
+ )
+ service = FSService(viking_fs=viking_fs)
+ service._enqueue_transfer_rebuild = AsyncMock(return_value="queued")
+
+ result = await service.cp(source, target, recursive=False, ctx=request_context)
+
+ viking_fs.cp.assert_awaited_once_with(
+ source,
+ target,
+ recursive=False,
+ ctx=request_context,
+ maintain_vectors=False,
+ copy_semantic_sidecars=False,
+ )
+ service._enqueue_transfer_rebuild.assert_awaited_once_with(
+ root_uri="viking://resources/project",
+ target_uri=target,
+ recursive=False,
+ context_type="resource",
+ ctx=request_context,
+ )
+ assert result["semantic_status"] == "queued"
+
+
+async def test_recursive_copy_from_system_rebuilds_target_subtree(request_context):
+ source = "viking://system/compile/example-skills/demo"
+ target = "viking://resources/project/demo"
+ viking_fs = SimpleNamespace(
+ cp=AsyncMock(return_value={"from": source, "to": target, "recursive": True}),
+ stat=AsyncMock(return_value={"isDir": True}),
+ )
+ service = FSService(viking_fs=viking_fs)
+ service._enqueue_transfer_rebuild = AsyncMock(return_value="queued")
+
+ await service.cp(source, target, recursive=True, ctx=request_context)
+
+ service._enqueue_transfer_rebuild.assert_awaited_once_with(
+ root_uri=target,
+ target_uri=target,
+ recursive=True,
+ context_type="resource",
+ ctx=request_context,
+ )
+
+
+async def test_move_from_system_rebuilds_target_index(request_context):
+ source = "viking://system/memory/memory_templates/custom/demo.md"
+ target = "viking://resources/project/demo.md"
+ viking_fs = SimpleNamespace(
+ mv=AsyncMock(),
+ stat=AsyncMock(return_value={"isDir": False}),
+ )
+ service = FSService(viking_fs=viking_fs)
+ service._enqueue_transfer_rebuild = AsyncMock(return_value="queued")
+ service._refresh_move_parents = AsyncMock()
+
+ await service.mv(source, target, ctx=request_context)
+
+ viking_fs.mv.assert_awaited_once_with(
+ source,
+ target,
+ ctx=request_context,
+ vector_mode="none",
+ copy_semantic_sidecars=False,
+ )
+ service._refresh_move_parents.assert_awaited_once_with(
+ from_uri=source,
+ to_uri=target,
+ ctx=request_context,
+ refresh_target=False,
+ )
+ service._enqueue_transfer_rebuild.assert_awaited_once_with(
+ root_uri="viking://resources/project",
+ target_uri=target,
+ recursive=False,
+ context_type="resource",
+ ctx=request_context,
+ )
+
+
+async def test_move_target_refresh_failure_does_not_roll_back_physical_move(request_context):
+ source = "viking://system/memory/memory_templates/custom/demo.md"
+ target = "viking://resources/project/demo.md"
+ viking_fs = SimpleNamespace(
+ mv=AsyncMock(),
+ stat=AsyncMock(return_value={"isDir": False}),
+ )
+ service = FSService(viking_fs=viking_fs)
+ service._enqueue_transfer_rebuild = AsyncMock(side_effect=RuntimeError("queue unavailable"))
+
+ await service.mv(source, target, ctx=request_context)
+
+ viking_fs.mv.assert_awaited_once()
+ service._enqueue_transfer_rebuild.assert_awaited_once()
+
+
+async def test_recursive_move_from_system_rebuilds_target_subtree(request_context):
+ source = "viking://system/compile/example-skills/demo"
+ target = "viking://resources/project/demo"
+ viking_fs = SimpleNamespace(
+ mv=AsyncMock(),
+ stat=AsyncMock(return_value={"isDir": True}),
+ )
+ service = FSService(viking_fs=viking_fs)
+ service._enqueue_transfer_rebuild = AsyncMock(return_value="queued")
+ service._refresh_move_parents = AsyncMock()
+
+ await service.mv(source, target, ctx=request_context)
+
+ service._enqueue_transfer_rebuild.assert_awaited_once_with(
+ root_uri=target,
+ target_uri=target,
+ recursive=True,
+ context_type="resource",
+ ctx=request_context,
+ )
+
+
+async def test_system_grep_and_glob_force_filesystem_implementation(request_context):
+ uri = "viking://system/memory/memory_templates/custom"
+ viking_fs = SimpleNamespace(
+ _ensure_access=AsyncMock(),
+ grep=AsyncMock(return_value={"matches": []}),
+ glob=AsyncMock(return_value={"matches": []}),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ await service.grep(uri, "demo", ctx=request_context)
+ await service.glob("*.md", uri=uri, ctx=request_context)
+
+ assert viking_fs.grep.await_args.kwargs["force_fs"] is True
+ assert viking_fs.glob.await_args.kwargs["force_fs"] is True
+
+
[email protected]("operation", ["grep_tags", "glob_tags", "glob_vector_fields"])
+async def test_system_file_search_rejects_index_features(request_context, operation):
+ uri = "viking://system/memory/memory_templates/custom"
+ viking_fs = SimpleNamespace(
+ _ensure_access=AsyncMock(),
+ grep=AsyncMock(return_value={"matches": []}),
+ glob=AsyncMock(return_value={"matches": []}),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ with pytest.raises(InvalidArgumentError, match="not supported"):
+ if operation == "grep_tags":
+ await service.grep(uri, "demo", ctx=request_context, include_tags=True)
+ elif operation == "glob_tags":
+ await service.glob("*.md", uri=uri, ctx=request_context, tags=["team=search"])
+ else:
+ await service.glob("*.md", uri=uri, ctx=request_context, extra_fields=["id"])
+
+ viking_fs.grep.assert_not_awaited()
+ viking_fs.glob.assert_not_awaited()
+
+
[email protected]("operation", ["abstract", "overview"])
+async def test_system_rejects_semantic_sidecar_reads(request_context, operation):
+ uri = "viking://system/memory/memory_templates/custom/demo.md"
+ viking_fs = SimpleNamespace(
+ _ensure_access=AsyncMock(),
+ abstract=AsyncMock(),
+ overview=AsyncMock(),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ with pytest.raises(InvalidArgumentError, match=f"{operation} is not supported"):
+ await getattr(service, operation)(uri, ctx=request_context)
+
+ getattr(viking_fs, operation).assert_not_awaited()
diff --git a/tests/service/test_reindex_namespace_policy.py b/tests/service/test_reindex_namespace_policy.py
new file mode 100644
index 000000000..22c8307ff
--- /dev/null
+++ b/tests/service/test_reindex_namespace_policy.py
@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.service.reindex_executor import ReindexExecutor
+from openviking_cli.exceptions import InvalidArgumentError
+
+
+async def test_reindex_rejects_file_only_namespace_before_task_creation():
+ executor = ReindexExecutor()
+
+ with pytest.raises(InvalidArgumentError, match="reindex is not supported"):
+ await executor.execute(
+ uri="viking://system/memory/memory_templates/custom/demo",
+ mode="full",
+ wait=False,
+ ctx=None,
+ )
diff --git a/tests/service/test_search_service_image.py b/tests/service/test_search_service_image.py
index be3ff50c7..85212652d 100644
--- a/tests/service/test_search_service_image.py
+++ b/tests/service/test_search_service_image.py
@@ -1,10 +1,12 @@
import asyncio
+from unittest.mock import AsyncMock
import pytest
from openviking.server.identity import RequestContext, Role
from openviking.service.search_service import SearchService
from openviking.utils.model_retry import effective_max_retries
+from openviking_cli.exceptions import InvalidArgumentError
from openviking_cli.session.user_id import UserIdentifier
@@ -47,3 +49,20 @@ async def test_image_search_resolves_uri_and_isolates_retry_scope():
assert fs.retry_values == {"find": 0, "search": 0}
assert effective_max_retries(3) == 3
+
+
[email protected]("operation", ["search", "find", "find_skills"])
+async def test_search_operations_reject_system_target_before_vector_access(operation):
+ fs = FakeVikingFS()
+ fs.search = AsyncMock(side_effect=AssertionError("system target must not reach vector search"))
+ fs.find = AsyncMock(side_effect=AssertionError("system target must not reach vector find"))
+ service = SearchService(fs)
+ ctx = RequestContext(user=UserIdentifier("acc", "user"), role=Role.USER)
+ target_uri = "viking://system/memory/memory_templates/custom"
+
+ with pytest.raises(InvalidArgumentError, match="search is not supported"):
+ await getattr(service, operation)(query="demo", target_uri=target_uri, ctx=ctx)
+
+ fs.search.assert_not_awaited()
+ fs.find.assert_not_awaited()
diff --git a/tests/session/memory/test_account_template_generic_write.py b/tests/session/memory/test_account_template_generic_write.py
new file mode 100644
index 000000000..fcae37b36
--- /dev/null
+++ b/tests/session/memory/test_account_template_generic_write.py
@@ -0,0 +1,127 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+import yaml
+
+from openviking.session.memory.account_templates import (
+ EDITABLE_MEMORY_TEMPLATE_FIELDS,
+ memory_template_data,
+ normalize_account_memory_template_write,
+ validate_account_memory_template_transfer,
+)
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking_cli.exceptions import InvalidArgumentError
+
+
[email protected](scope="module")
+def registry() -> MemoryTypeRegistry:
+ return MemoryTypeRegistry()
+
+
[email protected]("memory_type", EDITABLE_MEMORY_TEMPLATE_FIELDS)
+def test_generic_write_accepts_complete_template_with_editable_changes(registry, memory_type):
+ data = memory_template_data(registry.get(memory_type))
+ data["description"] += "\nAccount instructions."
+
+ normalize_account_memory_template_write(
+ f"viking://system/memory/memory_templates/custom/{memory_type}.yaml",
+ yaml.safe_dump(data),
+ "replace",
+ registry=registry,
+ )
+
+
[email protected]("memory_type", EDITABLE_MEMORY_TEMPLATE_FIELDS)
+def test_generic_write_rejects_locked_field_change(registry, memory_type):
+ data = memory_template_data(registry.get(memory_type))
+ data["filename_template"] = "unmanaged-{{ memory_type }}.md"
+
+ with pytest.raises(InvalidArgumentError, match="filename_template is locked"):
+ normalize_account_memory_template_write(
+ f"viking://system/memory/memory_templates/custom/{memory_type}.yaml",
+ yaml.safe_dump(data),
+ "replace",
+ registry=registry,
+ )
+
+
+def test_generic_write_requires_complete_template(registry):
+ with pytest.raises(InvalidArgumentError, match="complete deployment template"):
+ normalize_account_memory_template_write(
+ "viking://system/memory/memory_templates/custom/profile.yaml",
+ yaml.safe_dump({"memory_type": "profile", "description": "Account profile"}),
+ "replace",
+ registry=registry,
+ )
+
+
+def test_generic_write_rejects_append_for_managed_template(registry):
+ data = memory_template_data(registry.get("profile"))
+
+ with pytest.raises(InvalidArgumentError, match="append is not supported"):
+ normalize_account_memory_template_write(
+ "viking://system/memory/memory_templates/custom/profile.yaml",
+ yaml.safe_dump(data),
+ "append",
+ registry=registry,
+ )
+
+
+def test_generic_write_rejects_registered_noneditable_template(registry):
+ private_registry = MemoryTypeRegistry(load_schemas=False)
+ private_registry.register(
+ registry.get("profile").model_copy(update={"memory_type": "private"}, deep=True)
+ )
+
+ with pytest.raises(InvalidArgumentError, match="not editable"):
+ normalize_account_memory_template_write(
+ "viking://system/memory/memory_templates/custom/private.yaml",
+ "arbitrary",
+ "replace",
+ registry=private_registry,
+ )
+
+
+ "uri",
+ [
+ "viking://system/memory/memory_templates/custom/customer-defined.yaml",
+ "viking://system/memory/memory_templates/custom/team/profile.yaml",
+ ],
+)
+def test_generic_write_keeps_unmanaged_custom_files_unrestricted(registry, uri):
+ assert (
+ normalize_account_memory_template_write(uri, "arbitrary", "append", registry=registry)
+ == "arbitrary"
+ )
+
+
+def test_generic_write_roundtrip_replaces_server_timestamp(registry):
+ data = memory_template_data(registry.get("profile"))
+ data["description"] += "\nAccount instructions."
+ data["_updated_at"] = "forged"
+
+ normalized = normalize_account_memory_template_write(
+ "viking://system/memory/memory_templates/custom/profile.yaml",
+ yaml.safe_dump(data),
+ "replace",
+ registry=registry,
+ )
+
+ stored = yaml.safe_load(normalized)
+ assert stored.pop("_updated_at") != "forged"
+ assert stored == {key: value for key, value in data.items() if key != "_updated_at"}
+
+
+def test_transfer_rejects_registered_template_target_only(registry):
+ with pytest.raises(InvalidArgumentError, match="must be updated through write"):
+ validate_account_memory_template_transfer(
+ "viking://system/memory/memory_templates/custom/profile.yaml",
+ registry=registry,
+ )
+
+ validate_account_memory_template_transfer(
+ "viking://system/memory/memory_templates/custom/customer-defined.yaml",
+ registry=registry,
+ )
diff --git a/tests/session/memory/test_account_template_locking.py b/tests/session/memory/test_account_template_locking.py
index 16762b329..38508879d 100644
--- a/tests/session/memory/test_account_template_locking.py
+++ b/tests/session/memory/test_account_template_locking.py
@@ -12,13 +12,16 @@ import pytest
from openviking.pyagfs import AGFSNotFoundError
from openviking.session.memory.account_templates import (
account_memory_template_path,
+ account_memory_template_uri,
default_memory_template,
+ legacy_account_memory_template_path,
read_account_memory_template,
resolve_account_memory_registry,
update_account_memory_template,
)
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
+from openviking_cli.exceptions import FailedPreconditionError
class LockingAGFS:
@@ -304,7 +307,7 @@ def test_waiting_writer_does_not_block_readers_or_leak_locks(monkeypatch, cancel
else:
with pytest.raises(ResourceBusyError) as exc:
await writer
- assert exc.value.uri == path
+ assert exc.value.uri == account_memory_template_uri("profile")
assert exc.value.conflict_type == "memory_templates_busy"
assert agfs.timeouts and set(agfs.timeouts) == {0.0}
assert not agfs.leases
@@ -367,53 +370,52 @@ def test_publication_failures_never_overwrite_the_active_file(monkeypatch, exist
] == "After"
assert not agfs.leases
assert all(not held.locked() for held in agfs.locks.values())
- if existing:
- assert agfs.files[path + ".backup"] == old
+ assert path + ".backup" not in agfs.files
asyncio.run(run())
[email protected]("failure", [None, "backup", "remove"])
[email protected]("failure", [None, "remove"])
def test_saving_defaults_uses_locked_reset_and_preserves_failed_writes(monkeypatch, failure):
agfs = LockingAGFS()
fs = SimpleNamespace(agfs=agfs)
registry = MemoryTypeRegistry()
path = account_memory_template_path("locking-test", "profile")
+ legacy_path = legacy_account_memory_template_path("locking-test", "profile")
async def run():
await update_account_memory_template(
fs, "locking-test", "profile", {"description": "Custom"}, registry
)
previous = agfs.files[path]
- write, remove = agfs.write, agfs.rm
-
- def checked_write(target, data, **kwargs):
- assert target == path + ".backup", "saving defaults must not publish another file"
- assert path in agfs.leases
- if failure == "backup":
- raise OSError("backup failed")
- return write(target, data, **kwargs)
+ backup_path = path + ".backup"
+ agfs.files[backup_path] = b"obsolete"
+ remove = agfs.rm
def checked_remove(target, **kwargs):
+ if target == legacy_path:
+ return remove(target, **kwargs)
+ if target == backup_path:
+ assert path not in agfs.files
+ return remove(target, **kwargs)
assert target == path
- assert agfs.files[path + ".backup"] == previous
if failure == "remove":
raise OSError("remove failed")
return remove(target, **kwargs)
- monkeypatch.setattr(agfs, "write", checked_write)
monkeypatch.setattr(agfs, "rm", checked_remove)
update = update_account_memory_template(
fs, "locking-test", "profile", default_memory_template(registry, "profile"), registry
)
- if failure:
- with pytest.raises(OSError, match=f"{failure} failed"):
+ if failure == "remove":
+ with pytest.raises(FailedPreconditionError, match="current memory template"):
await update
assert agfs.files[path] == previous
+ assert agfs.files[backup_path] == b"obsolete"
else:
assert await update is None
assert path not in agfs.files
- assert agfs.files[path + ".backup"] == previous
+ assert backup_path not in agfs.files
assert not agfs.leases
assert all(not lock.locked() for lock in agfs.locks.values())
assert not any(name.endswith(".tmp") for name in agfs.files)
diff --git a/tests/session/memory/test_entities_template.py b/tests/session/memory/test_entities_template.py
index ced732647..01c76fcbf 100644
--- a/tests/session/memory/test_entities_template.py
+++ b/tests/session/memory/test_entities_template.py
@@ -11,8 +11,8 @@ from jinja2 import Template
@pytest.mark.parametrize(
"schema_path",
[
- "openviking/prompts/templates/memory/entities.yaml",
- "openviking/prompts/templates/memory/experimental_memory/entities.yaml",
+ "openviking/system_assets/memory/memory_templates/builtin/entities.yaml",
+ "openviking/system_assets/memory/memory_templates/builtin/experimental_memory/entities.yaml",
],
)
def test_entity_filename_is_case_insensitive(schema_path):
diff --git a/tests/session/memory/test_memory_updater.py b/tests/session/memory/test_memory_updater.py
index fe59f227f..64bf1c074 100644
--- a/tests/session/memory/test_memory_updater.py
+++ b/tests/session/memory/test_memory_updater.py
@@ -12,7 +12,6 @@ import pytest
from openviking.message import Message
from openviking.message.part import TextPart, ToolPart
-from openviking.prompts.manager import PromptManager
from openviking.pyagfs.exceptions import AGFSIoError
from openviking.server.identity import RequestContext, Role
from openviking.session.memory.dataclass import (
@@ -44,6 +43,7 @@ from openviking.session.memory.utils import (
parse_memory_file_with_fields,
)
from openviking.storage.abstract_overview import parse_abstract_overview
+from openviking.system_assets import builtin_memory_templates_dir
from openviking_cli.exceptions import ConflictError, NotFoundError
from openviking_cli.session.user_id import UserIdentifier
@@ -127,9 +127,7 @@ class TestMemoryUpdater:
assert "User reason" not in content
registry = MemoryTypeRegistry(load_schemas=False)
- registry.load_from_yaml(
- str(PromptManager._get_bundled_templates_dir() / "memory" / "events.yaml")
- )
+ registry.load_from_yaml(str(builtin_memory_templates_dir() / "events.yaml"))
rendered = MemoryFileUtils.write(
MemoryFile(
extra_fields={
@@ -205,9 +203,7 @@ class TestMemoryUpdater:
assert messages == original
registry = MemoryTypeRegistry(load_schemas=False)
- registry.load_from_yaml(
- str(PromptManager._get_bundled_templates_dir() / "memory" / "events.yaml")
- )
+ registry.load_from_yaml(str(builtin_memory_templates_dir() / "events.yaml"))
rendered = MemoryFileUtils.write(
MemoryFile(extra_fields={"summary": "Summary", "ranges": "0-3"}),
content_template=registry.get("events").content_template,
@@ -450,9 +446,10 @@ class TestMemoryUpdater:
@pytest.mark.asyncio
async def test_generate_overview_template_fallbacks_for_builtin_memories(self):
registry = MemoryTypeRegistry(load_schemas=False)
- registry.load_from_yaml("openviking/prompts/templates/memory/cases.yaml")
- registry.load_from_yaml("openviking/prompts/templates/memory/entities.yaml")
- registry.load_from_yaml("openviking/prompts/templates/memory/preferences.yaml")
+ memory_dir = builtin_memory_templates_dir()
+ registry.load_from_yaml(str(memory_dir / "cases.yaml"))
+ registry.load_from_yaml(str(memory_dir / "entities.yaml"))
+ registry.load_from_yaml(str(memory_dir / "preferences.yaml"))
case_dir = "viking://user/alice/memories/cases"
case_uri = f"{case_dir}/merged_case.md"
diff --git a/tests/storage/test_content_write_processing_mode.py b/tests/storage/test_content_write_processing_mode.py
index 00dd02310..a3cfbcdbe 100644
--- a/tests/storage/test_content_write_processing_mode.py
+++ b/tests/storage/test_content_write_processing_mode.py
@@ -5,9 +5,12 @@ from types import SimpleNamespace
from unittest.mock import AsyncMock
import pytest
+import yaml
from openviking.core.context import ContextLevel
from openviking.server.identity import RequestContext, Role
+from openviking.session.memory.account_templates import memory_template_data
+from openviking.session.memory.memory_type_registry import get_default_registry
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.storage import content_write as content_write_module
from openviking.storage.abstract_overview import (
@@ -27,6 +30,7 @@ class _FakePathLock:
def __init__(self):
self._lease = SimpleNamespace(id="lock-1")
self.exact_acquire_calls = []
+ self.exact_batch_acquire_calls = []
self.tree_acquire_calls = []
self.release_calls = []
self.to_handoff_calls = []
@@ -40,6 +44,10 @@ class _FakePathLock:
self.tree_acquire_calls.append(lock_path)
raise AssertionError("Skill content writes must not acquire a package tree lock")
+ async def pathlock_acquire_exact_batch(self, lock_paths):
+ self.exact_batch_acquire_calls.append(lock_paths)
+ return self._lease
+
async def pathlock_release(self, lease):
self.release_calls.append(lease.id)
@@ -242,6 +250,76 @@ async def test_missing_generated_sidecar_is_rejected_after_exact_lock(monkeypatc
coordinator._classify_locked_write_target.assert_awaited_once()
+async def test_managed_template_is_validated_before_single_write(ctx):
+ fake_fs = _FakeVikingFS()
+ coordinator = ContentWriteCoordinator(viking_fs=fake_fs)
+ coordinator._write_file_only = AsyncMock()
+
+ with pytest.raises(InvalidArgumentError, match="complete deployment template"):
+ await coordinator._write(
+ uri="viking://system/memory/memory_templates/custom/profile.yaml",
+ content="memory_type: profile\ndescription: Partial\n",
+ mode="replace",
+ ctx=ctx,
+ )
+
+ coordinator._write_file_only.assert_not_awaited()
+ assert fake_fs._async_agfs.exact_acquire_calls == []
+
+
+async def test_managed_template_single_write_replaces_server_timestamp(ctx):
+ fake_fs = _FakeVikingFS()
+ coordinator = ContentWriteCoordinator(viking_fs=fake_fs)
+ coordinator._write_file_only = AsyncMock(return_value={"semantic_status": "skipped"})
+ data = memory_template_data(get_default_registry().get("profile"))
+ data["description"] += "\nAccount instructions."
+ data["_updated_at"] = "forged"
+
+ await coordinator._write(
+ uri="viking://system/memory/memory_templates/custom/profile.yaml",
+ content=yaml.safe_dump(data),
+ mode="replace",
+ ctx=ctx,
+ )
+
+ normalized = yaml.safe_load(coordinator._write_file_only.await_args.kwargs["content"])
+ assert normalized.pop("_updated_at") != "forged"
+ assert normalized == {key: value for key, value in data.items() if key != "_updated_at"}
+
+
+async def test_managed_template_batch_is_preflighted_before_any_lock(ctx):
+ fake_fs = _FakeVikingFS()
+ coordinator = ContentWriteCoordinator(viking_fs=fake_fs)
+ root = "viking://system/memory/memory_templates/custom"
+ coordinator._validate_batch_root = AsyncMock()
+ coordinator._normalize_batch_operations = AsyncMock(
+ return_value=[
+ {
+ "uri": f"{root}/profile.yaml",
+ "content": "memory_type: profile\ndescription: Partial\n",
+ "mode": "replace",
+ "expected_sha256": None,
+ "ingest_options": IngestOptions(),
+ },
+ {
+ "uri": f"{root}/customer-defined.yaml",
+ "content": "arbitrary",
+ "mode": "replace",
+ "expected_sha256": None,
+ "ingest_options": IngestOptions(),
+ },
+ ]
+ )
+
+ with pytest.raises(InvalidArgumentError, match="complete deployment template"):
+ await coordinator._batch_write(root_uri=root, operations=[{}], ctx=ctx)
+
+ assert fake_fs._async_agfs.exact_batch_acquire_calls == []
+
+
def test_new_memory_file_renders_from_replace_mode_and_explicit_new_file_state():
uri = "viking://user/account-1/memories/new.md"
coordinator = ContentWriteCoordinator(viking_fs=_FakeVikingFS())
diff --git a/tests/storage/test_semantic_executor_incremental.py b/tests/storage/test_semantic_executor_incremental.py
index 14e9d2334..ccf83d8c0 100644
--- a/tests/storage/test_semantic_executor_incremental.py
+++ b/tests/storage/test_semantic_executor_incremental.py
@@ -1170,6 +1170,85 @@ async def test_content_copy_rebuilds_target_overview_from_target_l2_summaries(mo
assert abstract.strip() == "abstract"
+async def test_transfer_rebuild_generates_file_summary_and_vector(monkeypatch):
+ root_uri = "viking://resources/archive"
+ copied_uri = f"{root_uri}/copied.md"
+ fake_fs = _FakeVikingFS(
+ tree={root_uri: [{"name": "copied.md", "isDir": False}]},
+ file_contents={copied_uri: "copied body"},
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.semantic_executor.get_viking_fs", lambda: fake_fs
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.semantic_executor.get_openviking_config",
+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=32)),
+ )
+ processor = _FakeProcessor(fake_fs)
+ executor = SemanticTreeExecutor(
+ processor=processor,
+ context_type="resource",
+ max_concurrent_llm=2,
+ ctx=RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER),
+ incremental_update=True,
+ target_uri=root_uri,
+ recursive=False,
+ changes={"added": [copied_uri]},
+ generation_trigger="content_transfer_rebuild",
+ )
+
+ await executor.run(root_uri)
+
+ assert processor.summarized_files == [copied_uri]
+ assert processor.vectorized_files == [copied_uri]
+ assert processor.transfer_summary_calls == []
+
+
+async def test_recursive_transfer_rebuild_generates_subtree_vectors(monkeypatch):
+ root_uri = "viking://resources/archive/copied"
+ child_uri = f"{root_uri}/nested"
+ root_file = f"{root_uri}/root.md"
+ child_file = f"{child_uri}/child.md"
+ fake_fs = _FakeVikingFS(
+ tree={
+ root_uri: [
+ {"name": "nested", "isDir": True},
+ {"name": "root.md", "isDir": False},
+ ],
+ child_uri: [{"name": "child.md", "isDir": False}],
+ },
+ file_contents={
+ root_file: "root body",
+ child_file: "child body",
+ },
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.semantic_executor.get_viking_fs", lambda: fake_fs
+ )
+ monkeypatch.setattr(
+ "openviking.storage.queuefs.semantic_executor.get_openviking_config",
+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=32)),
+ )
+ processor = _FakeProcessor(fake_fs)
+ executor = SemanticTreeExecutor(
+ processor=processor,
+ context_type="resource",
+ max_concurrent_llm=2,
+ ctx=RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER),
+ recursive=True,
+ generation_trigger="content_transfer_rebuild",
+ )
+
+ await executor.run(root_uri)
+
+ assert set(processor.summarized_files) == {root_file, child_file}
+ assert set(processor.vectorized_files) == {root_file, child_file}
+ assert set(processor.vectorized_dirs) == {root_uri, child_uri}
+ assert processor.transfer_summary_calls == []
+
+
@pytest.mark.asyncio
async def test_content_copy_samples_before_loading_summaries(monkeypatch):
root_uri = "viking://resources/archive"
diff --git a/tests/storage/test_viking_fs_system_permissions.py b/tests/storage/test_viking_fs_system_permissions.py
new file mode 100644
index 000000000..b509df0d4
--- /dev/null
+++ b/tests/storage/test_viking_fs_system_permissions.py
@@ -0,0 +1,138 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.core.namespace_policy import (
+ SYSTEM_EXAMPLE_SKILLS_ROOT,
+ SYSTEM_MEMORY_BUILTIN_ROOT,
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+ SYSTEM_ROOT_URI,
+)
+from openviking.server.identity import RequestContext, Role
+from openviking.storage.acl import AclAction
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.exceptions import InvalidArgumentError, PermissionDeniedError
+from openviking_cli.session.user_id import UserIdentifier
+
+CUSTOM_ASSET_URI = f"{SYSTEM_MEMORY_CUSTOM_ROOT}/customer_service.yaml"
+
+
+def _ctx(role: Role, *, bypass_acl: bool = False) -> RequestContext:
+ return RequestContext(
+ user=UserIdentifier("acct", "alice"),
+ role=role,
+ bypass_acl=bypass_acl,
+ )
+
+
+def _fs(*, acl_manager=None) -> VikingFS:
+ return VikingFS(agfs=SimpleNamespace(), acl_manager=acl_manager)
+
+
[email protected]("role", [Role.USER, Role.ADMIN, Role.ROOT])
+ "uri",
+ [
+ SYSTEM_ROOT_URI,
+ f"{SYSTEM_EXAMPLE_SKILLS_ROOT}/example.md",
+ f"{SYSTEM_MEMORY_BUILTIN_ROOT}/default.yaml",
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+ CUSTOM_ASSET_URI,
+ ],
+)
+def test_system_namespace_is_readable_by_every_account_role(role, uri):
+ assert _fs()._system_permission_allows(uri, _ctx(role), AclAction.READ)
+
+
[email protected]("action", [AclAction.WRITE, AclAction.MANAGE])
+def test_root_can_manage_every_system_path(action):
+ fs = _fs()
+
+ assert fs._system_permission_allows(SYSTEM_ROOT_URI, _ctx(Role.ROOT), action)
+ assert fs._system_permission_allows(SYSTEM_MEMORY_BUILTIN_ROOT, _ctx(Role.ROOT), action)
+ assert fs._system_permission_allows(CUSTOM_ASSET_URI, _ctx(Role.ROOT), action)
+
+
[email protected]("action", [AclAction.WRITE, AclAction.MANAGE])
+def test_admin_can_manage_only_concrete_custom_assets(action):
+ fs = _fs()
+ admin = _ctx(Role.ADMIN)
+
+ assert fs._system_permission_allows(CUSTOM_ASSET_URI, admin, action)
+ assert not fs._system_permission_allows(SYSTEM_MEMORY_CUSTOM_ROOT, admin, action)
+ assert not fs._system_permission_allows(SYSTEM_MEMORY_BUILTIN_ROOT, admin, action)
+ assert not fs._system_permission_allows(SYSTEM_EXAMPLE_SKILLS_ROOT, admin, action)
+
+
[email protected]("action", [AclAction.WRITE, AclAction.MANAGE])
+def test_user_cannot_modify_system_assets(action):
+ fs = _fs()
+
+ assert not fs._system_permission_allows(CUSTOM_ASSET_URI, _ctx(Role.USER), action)
+
+
+async def test_system_permissions_do_not_consult_acl_or_honor_bypass():
+ acl_manager = SimpleNamespace(
+ is_enabled=AsyncMock(side_effect=AssertionError("system must bypass ACL")),
+ resolve_many=AsyncMock(side_effect=AssertionError("system must bypass ACL")),
+ )
+ fs = _fs(acl_manager=acl_manager)
+
+ access = await fs._can_access_many(
+ [SYSTEM_MEMORY_BUILTIN_ROOT, CUSTOM_ASSET_URI],
+ _ctx(Role.USER, bypass_acl=True),
+ action=AclAction.WRITE,
+ )
+
+ assert access == {
+ SYSTEM_MEMORY_BUILTIN_ROOT: False,
+ CUSTOM_ASSET_URI: False,
+ }
+ acl_manager.is_enabled.assert_not_awaited()
+ acl_manager.resolve_many.assert_not_awaited()
+
+
+async def test_system_permissions_are_partitioned_before_acl_disabled_fallback(monkeypatch):
+ acl_manager = SimpleNamespace(is_enabled=AsyncMock(return_value=False))
+ fs = _fs(acl_manager=acl_manager)
+ monkeypatch.setattr(fs, "_is_accessible", lambda uri, _ctx: uri == "viking://agent")
+
+ access = await fs._can_access_many(
+ [CUSTOM_ASSET_URI, "viking://agent"],
+ _ctx(Role.USER),
+ action=AclAction.WRITE,
+ )
+
+ assert access == {
+ CUSTOM_ASSET_URI: False,
+ "viking://agent": True,
+ }
+
+
+async def test_ensure_access_enforces_system_path_boundaries():
+ fs = _fs()
+
+ await fs._ensure_access(CUSTOM_ASSET_URI, _ctx(Role.ADMIN), action=AclAction.WRITE)
+ await fs._ensure_access(SYSTEM_MEMORY_BUILTIN_ROOT, _ctx(Role.USER), action=AclAction.READ)
+
+ with pytest.raises(PermissionDeniedError, match="write permission required"):
+ await fs._ensure_access(
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+ _ctx(Role.ADMIN),
+ action=AclAction.WRITE,
+ )
+
+
+async def test_system_namespace_does_not_support_acl_management():
+ fs = _fs(acl_manager=SimpleNamespace())
+
+ with pytest.raises(InvalidArgumentError, match="ACL is only supported"):
+ await fs.get_acl(SYSTEM_ROOT_URI, ctx=_ctx(Role.ROOT))
diff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.py
index 8553ff2ea..8130cb862 100644
--- a/tests/storage/test_viking_fs_tree.py
+++ b/tests/storage/test_viking_fs_tree.py
@@ -192,6 +192,7 @@ def patch_tree_env(
("resources", "/local/test_account", True),
("user", "/local/test_account", True),
("agent", "/local/test_account", True),
+ ("system", "/local/test_account", True),
("session", "/local/test_account", False),
("tasks", "/local/test_account", False),
("_system", "/local/test_account", False),
diff --git a/tests/test_prompt_manager.py b/tests/test_prompt_manager.py
index 0559f71b1..fa4308381 100644
--- a/tests/test_prompt_manager.py
+++ b/tests/test_prompt_manager.py
@@ -12,6 +12,7 @@ import yaml
from openviking.prompts.manager import PromptManager
from openviking.session.memory import memory_type_registry as registry_module
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.system_assets import builtin_memory_templates_dir
from openviking_cli.utils.config import (
OPENVIKING_CONFIG_ENV,
OPENVIKING_PROMPT_TEMPLATES_DIR_ENV,
@@ -70,7 +71,7 @@ def teardown_function() -> None:
def test_profile_memory_template_includes_stable_identity_work_style_and_preferences():
- template_path = PromptManager._get_bundled_templates_dir() / "memory" / "profile.yaml"
+ template_path = builtin_memory_templates_dir() / "profile.yaml"
schema = yaml.safe_load(template_path.read_text(encoding="utf-8"))
text = "\n".join(
[
@@ -89,7 +90,7 @@ def test_profile_memory_template_includes_stable_identity_work_style_and_prefere
def test_preferences_memory_template_keeps_topic_specific_preferences():
- template_path = PromptManager._get_bundled_templates_dir() / "memory" / "preferences.yaml"
+ template_path = builtin_memory_templates_dir() / "preferences.yaml"
schema = yaml.safe_load(template_path.read_text(encoding="utf-8"))
text = "\n".join(
[
diff --git a/tests/unit/session/memory/test_embedding_template.py b/tests/unit/session/memory/test_embedding_template.py
index 5009cf863..d44a27293 100644
--- a/tests/unit/session/memory/test_embedding_template.py
+++ b/tests/unit/session/memory/test_embedding_template.py
@@ -6,7 +6,6 @@ from unittest.mock import AsyncMock, Mock, patch
import pytest
-from openviking.prompts.manager import PromptManager
from openviking.session.memory.dataclass import MemoryField, MemoryFile
from openviking.session.memory.experience_lineage import experience_source_tag
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
@@ -15,6 +14,7 @@ from openviking.session.memory.merge_op import MergeOp
from openviking.session.memory.merge_op.base import FieldType
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
+from openviking.system_assets import builtin_memory_templates_dir
from openviking.utils.ingest_options import IngestOptions
@@ -27,7 +27,7 @@ class TestMemoryFieldSchema:
class TestEmbeddingTemplateYamlParsing:
@pytest.fixture(autouse=True)
def setup(self):
- memory_dir = PromptManager._get_bundled_templates_dir() / "memory"
+ memory_dir = builtin_memory_templates_dir()
self.registry = MemoryTypeRegistry(load_schemas=False)
self.registry.load_from_yaml(str(memory_dir / "events.yaml"))
self.registry.load_from_yaml(str(memory_dir / "preferences.yaml"))
@@ -113,7 +113,7 @@ class TestEmbeddingTextConstruction:
)
async def test_vectorization_preserves_write_tag_mode(self, tags, mode, expected_mode):
registry = MemoryTypeRegistry(load_schemas=False)
- memory_dir = PromptManager._get_bundled_templates_dir() / "memory"
+ memory_dir = builtin_memory_templates_dir()
registry.load_from_yaml(str(memory_dir / "trajectories.yaml"))
uri = "viking://user/alice/memories/trajectories/exchange.md"
updater = MemoryUpdater(registry=registry, vikingdb=Mock())
@@ -156,7 +156,7 @@ class TestEmbeddingTextConstruction:
@pytest.mark.asyncio
async def test_trajectory_vectorization_adds_source_experience_search_tags(self):
registry = MemoryTypeRegistry(load_schemas=False)
- memory_dir = PromptManager._get_bundled_templates_dir() / "memory"
+ memory_dir = builtin_memory_templates_dir()
registry.load_from_yaml(str(memory_dir / "trajectories.yaml"))
experience_uri = "viking://user/alice/memories/experiences/exchange.md"
trajectory_uri = "viking://user/alice/memories/trajectories/exchange.md"
diff --git a/tests/unit/test_directory_initializer.py b/tests/unit/test_directory_initializer.py
index f4e937838..60cae9bce 100644
--- a/tests/unit/test_directory_initializer.py
+++ b/tests/unit/test_directory_initializer.py
@@ -1,4 +1,5 @@
-from unittest.mock import AsyncMock
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, call
import pytest
@@ -134,6 +135,26 @@ async def test_initialize_user_directories_ignores_actor_peer_view_for_preset_st
assert set(viking_fs.contexts) == expected_uris
+async def test_system_assets_sync_only_for_account_initialization():
+ synchronizer = SimpleNamespace(sync=AsyncMock())
+ initializer = DirectoryInitializer(
+ _FakeVikingDB(),
+ viking_fs=_FakeVikingFS(),
+ system_asset_synchronizer=synchronizer,
+ )
+ ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.ADMIN)
+
+ await initializer.initialize_account_workspace(ctx, sync_system_assets=False)
+ synchronizer.sync.assert_not_awaited()
+
+ await initializer.initialize_account_workspace(ctx)
+ await initializer.initialize_account_directories(ctx)
+ await initializer.initialize_user_directories(ctx)
+
+ assert synchronizer.sync.await_args_list == [call(ctx), call(ctx)]
+
+
def test_preset_directory_uris_cover_seeded_directories_only():
from openviking.core.directories import preset_directory_uris
diff --git a/tests/unit/test_namespace_policy.py b/tests/unit/test_namespace_policy.py
new file mode 100644
index 000000000..0f81ab171
--- /dev/null
+++ b/tests/unit/test_namespace_policy.py
@@ -0,0 +1,93 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for system namespace constants and processing policy."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from openviking.core.namespace_policy import (
+ SYSTEM_FIXED_DIRECTORIES,
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+ SYSTEM_OFFICIAL_ASSET_ROOTS,
+ NamespaceProcessingMode,
+ is_system_custom_asset_uri,
+ is_system_fixed_directory_uri,
+ is_system_uri,
+ namespace_policy_for_uri,
+)
+from openviking.server.identity import RequestContext, Role
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def test_system_namespace_uses_file_only_policy():
+ policy = namespace_policy_for_uri("viking://system/compile/example-skills/demo")
+
+ assert policy.processing_mode is NamespaceProcessingMode.FILE_ONLY
+ assert policy.supports_acl is False
+ assert policy.supports_tags is False
+ assert policy.supports_reindex is False
+
+
+ "uri",
+ [
+ "viking://resources/project",
+ "viking://user/alice/memories/preferences",
+ "viking://agent/skills/demo",
+ ],
+)
+def test_existing_namespaces_keep_indexed_policy(uri: str):
+ policy = namespace_policy_for_uri(uri)
+
+ assert policy.processing_mode is NamespaceProcessingMode.INDEXED
+ assert policy.supports_acl is True
+ assert policy.supports_tags is True
+ assert policy.supports_reindex is True
+
+
+def test_system_uri_detection_matches_complete_path_segments():
+ assert is_system_uri("viking://system")
+ assert is_system_uri("viking://system/")
+ assert is_system_uri("viking://system/memory?level=1")
+ assert not is_system_uri("viking://resources/system")
+ assert not is_system_uri("viking://systematic")
+ assert not is_system_uri("viking://resources/system-foo")
+
+
+def test_fixed_and_official_system_roots_are_explicit():
+ assert "viking://system" in SYSTEM_FIXED_DIRECTORIES
+ assert SYSTEM_MEMORY_CUSTOM_ROOT in SYSTEM_FIXED_DIRECTORIES
+ assert SYSTEM_OFFICIAL_ASSET_ROOTS == {
+ "viking://system/compile/example-skills",
+ "viking://system/memory/memory_templates/builtin",
+ }
+ assert is_system_fixed_directory_uri("viking://system/memory/memory_templates/custom/")
+ assert not is_system_fixed_directory_uri(
+ "viking://system/memory/memory_templates/custom/team.yaml"
+ )
+ assert not is_system_fixed_directory_uri("viking://system/memory-templates")
+
+
+def test_custom_asset_detection_excludes_fixed_custom_root():
+ assert not is_system_custom_asset_uri(SYSTEM_MEMORY_CUSTOM_ROOT)
+ assert is_system_custom_asset_uri(f"{SYSTEM_MEMORY_CUSTOM_ROOT}/team.yaml")
+ assert is_system_custom_asset_uri(f"{SYSTEM_MEMORY_CUSTOM_ROOT}/nested/team.yaml")
+ assert not is_system_custom_asset_uri(
+ "viking://system/memory/memory_templates/customized/team.yaml"
+ )
+
+
+def test_system_uri_storage_mapping_is_isolated_by_account():
+ fs = VikingFS(agfs=SimpleNamespace())
+ uri = "viking://system/memory/memory_templates/custom/team.yaml"
+
+ for account_id in ("account-a", "account-b"):
+ ctx = RequestContext(
+ user=UserIdentifier(account_id=account_id, user_id="admin"),
+ role=Role.ADMIN,
+ )
+ path = f"/local/{account_id}/system/memory/memory_templates/custom/team.yaml"
+ assert fs._uri_to_path(uri, ctx=ctx) == path
+ assert fs._path_to_uri(path, ctx=ctx) == uri
diff --git a/tests/unit/test_namespace_uri_classification.py b/tests/unit/test_namespace_uri_classification.py
index 765a420aa..5a9fbe831 100644
--- a/tests/unit/test_namespace_uri_classification.py
+++ b/tests/unit/test_namespace_uri_classification.py
@@ -28,6 +28,8 @@ from openviking_cli.session.user_id import UserIdentifier
def test_context_type_for_uri_uses_path_segments():
+ assert context_type_for_uri("viking://system") == "resource"
+ assert context_type_for_uri("viking://system/memory/memory_templates") == "resource"
assert context_type_for_uri("viking://user/alice/memories/entities/m1.md") == "memory"
assert context_type_for_uri("viking://user/memories/entities/m1.md") == "resource"
assert context_type_for_uri("viking://user/alice/skills/demo") == "skill"
@@ -48,6 +50,13 @@ def test_context_type_for_uri_uses_path_segments():
assert context_type_for_uri("viking://agent/skills/demo") == "skill"
assert context_type_for_uri("viking://resources/memories-report.md") == "resource"
assert context_type_for_uri("viking://user/alice/resources/skills-report.md") == "resource"
+ assert context_type_for_uri("viking://resources/system/guide.md") == "resource"
+
+
+def test_system_namespace_detection_uses_scope_segment():
+ assert classify_uri("viking://system/memory").is_system
+ assert resolve_uri("viking://system/memory").scope == "system"
+ assert not classify_uri("viking://resources/system").is_system
def test_peer_content_target_uri_rejects_invalid_peer_id():
@@ -89,6 +98,19 @@ def test_exact_memory_and_skill_root_detection():
assert not classify_uri("viking://user/skills/demo").is_skill_root
assert classify_uri("viking://agent/skills").is_skill_namespace
assert classify_uri("viking://agent/skills/demo").is_skill_root
+ assert classify_uri(
+ "viking://system/compile/example-skills"
+ ).is_skill_namespace
+ assert classify_uri(
+ "viking://system/compile/example-skills/llm-wiki"
+ ).is_skill_root
+ assert classify_uri(
+ "viking://system/compile/example-skills/llm-wiki/SKILL.md"
+ ).is_skill
+ assert not classify_uri("viking://system/compile").is_skill
+ assert not classify_uri(
+ "viking://system/compile/example-skills/llm-wiki/references"
+ ).is_skill_root
assert not classify_uri("viking://user/alice/skills").is_skill_root
assert not classify_uri("viking://user/alice/skills/demo/assets").is_skill_root
diff --git a/tests/unit/test_system_asset_reconcile.py b/tests/unit/test_system_asset_reconcile.py
new file mode 100644
index 000000000..9cd0c828f
--- /dev/null
+++ b/tests/unit/test_system_asset_reconcile.py
@@ -0,0 +1,113 @@
+import asyncio
+
+import pytest
+
+from openviking.server.identity import Role
+from openviking.system_assets.reconcile import SystemAssetReconciler
+
+
+class _FakeAccountLister:
+ def __init__(self, accounts):
+ self._accounts = accounts
+ self.calls = []
+
+ async def list_accounts(self, *, limit, page):
+ self.calls.append((limit, page))
+ start = (page - 1) * limit
+ return self._accounts[start : start + limit]
+
+
+class _TrackingSynchronizer:
+ def __init__(self, failures=()):
+ self._failures = set(failures)
+ self.accounts = []
+ self.active = 0
+ self.max_active = 0
+
+ async def sync(self, ctx):
+ account_id = ctx.user.account_id
+ assert ctx.role == Role.ROOT
+ assert ctx.user.user_id == "system-user"
+ self.accounts.append(account_id)
+ self.active += 1
+ self.max_active = max(self.max_active, self.active)
+ try:
+ await asyncio.sleep(0.01)
+ if account_id in self._failures:
+ raise OSError(f"failed {account_id}")
+ return 0
+ finally:
+ self.active -= 1
+
+
+async def test_reconciler_pages_active_accounts_with_bounded_concurrency():
+ lister = _FakeAccountLister(
+ [
+ {"account_id": "a", "status": "active"},
+ {"account_id": "b", "status": "deleting"},
+ {"account_id": "c", "status": "active"},
+ {"account_id": "d", "status": "active"},
+ {"account_id": "e", "status": "active"},
+ ]
+ )
+ synchronizer = _TrackingSynchronizer()
+ reconciler = SystemAssetReconciler(
+ synchronizer,
+ lister,
+ user_id="system-user",
+ page_size=2,
+ max_concurrency=2,
+ )
+
+ assert await reconciler.sync_all() == 4
+ assert lister.calls == [(2, 1), (2, 2), (2, 3)]
+ assert set(synchronizer.accounts) == {"a", "c", "d", "e"}
+ assert synchronizer.max_active == 2
+
+
+async def test_reconciler_skips_already_synced_account_without_ending_pagination():
+ lister = _FakeAccountLister(
+ [
+ {"account_id": "default", "status": "active"},
+ {"account_id": "a", "status": "active"},
+ {"account_id": "b", "status": "active"},
+ ]
+ )
+ synchronizer = _TrackingSynchronizer()
+ reconciler = SystemAssetReconciler(
+ synchronizer,
+ lister,
+ user_id="system-user",
+ skip_account_ids={"default"},
+ page_size=2,
+ )
+
+ assert await reconciler.sync_all() == 2
+ assert lister.calls == [(2, 1), (2, 2)]
+ assert set(synchronizer.accounts) == {"a", "b"}
+
+
+async def test_reconciler_reports_all_failures_in_page():
+ lister = _FakeAccountLister(
+ [
+ {"account_id": "a", "status": "active"},
+ {"account_id": "b", "status": "active"},
+ ]
+ )
+ synchronizer = _TrackingSynchronizer(failures={"a", "b"})
+ reconciler = SystemAssetReconciler(
+ synchronizer,
+ lister,
+ user_id="system-user",
+ page_size=2,
+ max_concurrency=2,
+ )
+
+ with pytest.raises(RuntimeError, match="failed for 2 account") as exc_info:
+ await reconciler.sync_all()
+
+ assert "a: OSError: failed a" in str(exc_info.value)
+ assert "b: OSError: failed b" in str(exc_info.value)
diff --git a/tests/unit/test_system_asset_sync.py b/tests/unit/test_system_asset_sync.py
new file mode 100644
index 000000000..df2a817e8
--- /dev/null
+++ b/tests/unit/test_system_asset_sync.py
@@ -0,0 +1,129 @@
+import base64
+
+import pytest
+
+from openviking.core.namespace_policy import (
+ SYSTEM_EXAMPLE_SKILLS_ROOT,
+ SYSTEM_FIXED_DIRECTORIES,
+ SYSTEM_MEMORY_BUILTIN_ROOT,
+ SYSTEM_MEMORY_CUSTOM_ROOT,
+)
+from openviking.server.identity import RequestContext, Role
+from openviking.system_assets.sync import SystemAssetSynchronizer
+from openviking_cli.session.user_id import UserIdentifier
+
+
+class _FakeVikingFS:
+ def __init__(self, files=None):
+ self.directories = set()
+ self.files = dict(files or {})
+ self.mkdir_contexts = []
+
+ async def mkdir(self, uri, exist_ok, ctx):
+ assert exist_ok is True
+ self.directories.add(uri)
+ self.mkdir_contexts.append(ctx)
+
+ async def read_file_bytes(self, uri, ctx):
+ assert ctx.role == Role.ROOT
+ if uri not in self.files:
+ raise FileNotFoundError(uri)
+ return self.files[uri]
+
+
+class _FakeCoordinator:
+ def __init__(self, viking_fs):
+ self._viking_fs = viking_fs
+ self.calls = []
+
+ async def batch_write(self, *, root_uri, operations, ctx):
+ assert ctx.role == Role.ROOT
+ self.calls.append((root_uri, operations, ctx))
+ for operation in operations:
+ self._viking_fs.files[operation["uri"]] = base64.b64decode(
+ operation["content_base64"]
+ )
+
+
+async def test_system_asset_sync_converges_managed_roots_without_touching_custom(
+ tmp_path, monkeypatch
+):
+ compile_source = tmp_path / "compile/example-skills/demo/SKILL.md"
+ reference_source = tmp_path / "compile/example-skills/demo/references/guide.bin"
+ memory_source = tmp_path / "memory/memory_templates/builtin/profile.yaml"
+ compile_source.parent.mkdir(parents=True)
+ reference_source.parent.mkdir(parents=True)
+ memory_source.parent.mkdir(parents=True)
+ compile_source.write_bytes(b"same skill")
+ reference_source.write_bytes(b"\x00guide")
+ memory_source.write_bytes(b"new profile")
+
+ compile_target = f"{SYSTEM_EXAMPLE_SKILLS_ROOT}/demo/SKILL.md"
+ reference_target = f"{SYSTEM_EXAMPLE_SKILLS_ROOT}/demo/references/guide.bin"
+ memory_target = f"{SYSTEM_MEMORY_BUILTIN_ROOT}/profile.yaml"
+ stale_target = f"{SYSTEM_EXAMPLE_SKILLS_ROOT}/retired/SKILL.md"
+ custom_target = f"{SYSTEM_MEMORY_CUSTOM_ROOT}/profile.yaml"
+ viking_fs = _FakeVikingFS(
+ {
+ compile_target: b"same skill",
+ memory_target: b"old profile",
+ stale_target: b"keep",
+ custom_target: b"custom",
+ }
+ )
+ coordinator = _FakeCoordinator(viking_fs)
+ monkeypatch.setattr(
+ "openviking.system_assets.sync.ContentWriteCoordinator",
+ lambda **kwargs: coordinator,
+ )
+ synchronizer = SystemAssetSynchronizer(
+ viking_fs=viking_fs,
+ assets_dir=tmp_path,
+ )
+ ctx = RequestContext(
+ user=UserIdentifier("acme", "admin"),
+ role=Role.ADMIN,
+ actor_peer_id="peer",
+ )
+
+ assert await synchronizer.sync(ctx) == 2
+ assert viking_fs.directories == set(SYSTEM_FIXED_DIRECTORIES)
+ assert all(
+ item.role == Role.ROOT and item.actor_peer_id is None
+ for item in viking_fs.mkdir_contexts
+ )
+ assert [call[0] for call in coordinator.calls] == [
+ SYSTEM_EXAMPLE_SKILLS_ROOT,
+ SYSTEM_MEMORY_BUILTIN_ROOT,
+ ]
+ assert viking_fs.files[reference_target] == b"\x00guide"
+ assert viking_fs.files[memory_target] == b"new profile"
+ assert viking_fs.files[stale_target] == b"keep"
+ assert viking_fs.files[custom_target] == b"custom"
+
+ coordinator.calls.clear()
+ assert await synchronizer.sync(ctx) == 0
+ assert coordinator.calls == []
+
+
+async def test_system_asset_sync_rejects_missing_packaged_root(tmp_path, monkeypatch):
+ (tmp_path / "compile/example-skills").mkdir(parents=True)
+ viking_fs = _FakeVikingFS()
+ monkeypatch.setattr(
+ "openviking.system_assets.sync.ContentWriteCoordinator",
+ lambda **kwargs: _FakeCoordinator(viking_fs),
+ )
+ synchronizer = SystemAssetSynchronizer(
+ viking_fs=viking_fs,
+ assets_dir=tmp_path,
+ )
+
+ with pytest.raises(FileNotFoundError, match="memory/memory_templates/builtin"):
+ await synchronizer.sync(
+ RequestContext(
+ user=UserIdentifier("acme", "admin"),
+ role=Role.ADMIN,
+ )
+ )
diff --git a/tests/unit/test_uri_short_format.py b/tests/unit/test_uri_short_format.py
index 3318cdd85..6e85e4f97 100644
--- a/tests/unit/test_uri_short_format.py
+++ b/tests/unit/test_uri_short_format.py
@@ -62,6 +62,13 @@ class TestVikingURIExplicitFormat:
assert uri.scope == "~"
assert uri.full_path == "~/notes"
+ def test_system_scope_is_parsable_public_and_listable(self):
+ uri = VikingURI("viking://system/memory")
+ assert uri.scope == "system"
+ assert VikingURI.build("system", "memory") == uri.uri
+ assert "system" in VikingURI.PUBLIC_SCOPES
+ assert "system" in VikingURI.LISTABLE_SCOPES
+
def test_invalid_scope_error_copy_hides_home_alias(self):
"""The parser's own scope enumeration never advertises the alias."""
with pytest.raises(ValueError, match="Invalid scope") as exc_info:
diff --git a/tests/unit/test_uri_validation.py b/tests/unit/test_uri_validation.py
index ca529b812..cabd1b94e 100644
--- a/tests/unit/test_uri_validation.py
+++ b/tests/unit/test_uri_validation.py
@@ -15,6 +15,7 @@ from openviking_cli.exceptions import InvalidURIError
"viking://resources/docs",
"viking://session/s1",
"viking://agent/skills/demo/SKILL.md",
+ "viking://system/memory",
"viking://",
"viking://~",
"viking://~/memories/x",