Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat: add freshness-aware parent aggregation (#4180)
MaojiaShenga7c77e6cf7f2
diff --git a/README_CN.md b/README_CN.mdindex bc2d565bc..7214e5212 100644--- a/README_CN.md+++ b/README_CN.md@@ -139,7 +139,7 @@ ov find "what is openviking"ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh```-重建已有索引:`ov reindex <uri> --mode vectors_only` 只刷新向量;`--mode semantic_and_vectors` 先重新生成语义产物(`.abstract.md`、`.overview.md`)再刷新向量;`--mode prune_orphans` 清理源文件已不存在的向量记录(加 `--dry-run` 可预览)。没有 `semantic` 或 `full` 这样的模式别名。+重建已有索引:`ov reindex <uri> --mode vectors_only` 只刷新向量;`--mode semantic_and_vectors` 先重新生成语义产物(`.abstract.md`、`.overview.md`)再刷新向量;添加 `--recursive=false` 可只刷新目标目录自身的语义产物及 L0/L1 向量;`--mode prune_orphans` 清理源文件已不存在的向量记录(加 `--dry-run` 可预览)。没有 `semantic` 或 `full` 这样的模式别名。客户端配置可以用 `ov config` 交互式初始化;有多台服务器时,用 `ov config switch` 切换。diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex e191771cc..9a21d0027 100644--- a/crates/ov_cli/src/client.rs+++ b/crates/ov_cli/src/client.rs@@ -461,6 +461,7 @@ impl HttpClient {dry_run: bool,tags: Vec<String>,tag_mode: &str,+ recursive: bool,) -> Result<serde_json::Value> {let mut body = serde_json::json!({"uri": uri,@@ -468,6 +469,9 @@ impl HttpClient {"wait": wait,"dry_run": dry_run,});+ if !recursive {+ body["recursive"] = serde_json::json!(false);+ }if !tags.is_empty() {let obj = body.as_object_mut()diff --git a/crates/ov_cli/src/commands/content.rs b/crates/ov_cli/src/commands/content.rsindex e0f78f0e7..f78b0d534 100644--- a/crates/ov_cli/src/commands/content.rs+++ b/crates/ov_cli/src/commands/content.rs@@ -77,11 +77,12 @@ pub async fn reindex(dry_run: bool,tags: Vec<String>,tag_mode: &str,+ recursive: bool,output_format: OutputFormat,compact: bool,) -> Result<()> {let result = client- .reindex(uri, mode, wait, dry_run, tags, tag_mode)+ .reindex(uri, mode, wait, dry_run, tags, tag_mode, recursive).await?;crate::output::output_success(result, output_format, compact);Ok(())diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rsindex 784808d94..a2341f098 100644--- a/crates/ov_cli/src/handlers.rs+++ b/crates/ov_cli/src/handlers.rs@@ -1358,6 +1358,7 @@ pub async fn handle_reindex(dry_run: bool,tags: Vec<String>,tag_mode: String,+ recursive: bool,ctx: CliContext,) -> Result<()> {let client = ctx.get_client();@@ -1369,6 +1370,7 @@ pub async fn handle_reindex(dry_run,tags,&tag_mode,+ recursive,ctx.output_format,ctx.compact,)diff --git a/crates/ov_cli/src/help_ui.rs b/crates/ov_cli/src/help_ui.rsindex 0ec15021c..ad6a77e63 100644--- a/crates/ov_cli/src/help_ui.rs+++ b/crates/ov_cli/src/help_ui.rs@@ -1333,6 +1333,10 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[label: "ov reindex viking://projects/acme --mode semantic_and_vectors --wait true",description: "Regenerate semantic artifacts, then vectors.",},+ HelpItem {+ label: "ov reindex viking://projects/acme --mode semantic_and_vectors --recursive=false",+ description: "Refresh only the target directory semantics and vectors, without sub-directory.",+ },HelpItem {label: "ov reindex viking://projects/acme --mode prune_orphans --dry-run",description: "Preview orphan vector cleanup.",@@ -2887,6 +2891,7 @@ mod tests {assert!(rendered.contains("--mode <vectors_only|semantic_and_vectors|prune_orphans>"));assert!(rendered.contains("--dry-run"));+ assert!(rendered.contains("--recursive <true|false>"));assert!(rendered.contains("Regenerate semantic artifacts, then vectors."));}diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 05fcd72d9..152935a68 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -1155,6 +1155,15 @@ enum Commands {help_heading = "Common options")]tag_mode: String,+ /// Recursively reindex subdirectories (only affects semantic_and_vectors)+ #[arg(+ long,+ default_value_t = true,+ action = ArgAction::Set,+ value_name = "bool",+ help_heading = "Common options"+ )]+ recursive: bool,},}@@ -3501,7 +3510,10 @@ async fn main() {dry_run,tags,tag_mode,- } => handlers::handle_reindex(uri, mode, wait, dry_run, tags, tag_mode, ctx).await,+ recursive,+ } => {+ handlers::handle_reindex(uri, mode, wait, dry_run, tags, tag_mode, recursive, ctx).await+ }Commands::Get { uri, local_path } => handlers::handle_get(uri, local_path, ctx).await,Commands::Find {query,@@ -5355,13 +5367,20 @@ mod tests {"team=search","--tag-mode","append",+ "--recursive=false",]);let cli = result.expect("reindex command should parse");match cli.command {- Commands::Reindex { tags, tag_mode, .. } => {+ Commands::Reindex {+ tags,+ tag_mode,+ recursive,+ ..+ } => {assert_eq!(tags, vec!["team=search"]);assert_eq!(tag_mode, "append");+ assert!(!recursive);}_ => panic!("expected reindex command"),}diff --git a/docs/design/freshness-aware-parent-bubbling-design.md b/docs/design/freshness-aware-parent-bubbling-design.mdnew file mode 100644index 000000000..2f223e5c2--- /dev/null+++ b/docs/design/freshness-aware-parent-bubbling-design.md@@ -0,0 +1,357 @@+# 设计草案:基于 Freshness 的上级摘要冒泡策略++状态:讨论稿++关联 RFC:`docs/design/l0-l1-okf-sidecars-rfc.md`++## 摘要++本文继续细化 L0/L1 OKF sidecar RFC 中的 `Freshness-Aware Parent Bubbling`。目标是在不引入复杂调度基础设施、不扩大 freshness 数据模型的前提下,减少没有实际收益的上级摘要生成、模型调用和逐级写放大。++首版策略只做两层判断:++1. 子目录摘要完成后,先判断父目录实际使用的子目录 L0 正文是否发生变化;如果 L0 未变,停止冒泡。+2. 如果 L0 确实变化,则小目录立即刷新;宽目录只累计现有的 `pending_child_changes`,变化比例达到阈值后再刷新。文件的新增、删除和修改在这里统一视为一次直接子项变化。++对于宽目录,采样只是一次摘要生成过程中的有界输入手段,不是一个需要持久化、追踪或参与调度判断的“采样成员集合”。++首版不提供最长陈旧时间兜底,不维护唯一变化子项集合,也不调整现有 freshness 字段的定义。它是一套务实的成本控制策略,而不是严格的实时一致性协议。++## 当前实现与四个具体问题++当前 resource/skill 语义任务成功后,会执行以下流程:++1. 将父目录 sidecar 的 `pending_child_changes` 加一。+2. 立即为父目录入队一次非递归语义刷新。+3. 父目录刷新成功后,对更上一级重复同样的流程。++这个实现简单,但存在四个值得明确的问题。++### 1. 子目录 L0 未变时仍然冒泡++父目录生成摘要时,消费的是直接子目录的 L0 正文,而不是子目录 L1,也不是 sidecar metadata。++如果子目录重新生成后只有 L1 或 metadata 发生变化,而 L0 正文没有变化,那么父目录的实际输入没有改变。此时仍然刷新父目录属于无效冒泡。++这是首版最应优先解决的问题,因为判断依据明确、实现成本低,而且每一级目录都可以独立停止继续向上传播。++### 2. `pending_child_changes` 统计的是事件次数++当前实现对每次观察到的变化执行整数累加。因此,同一个热点子目录连续变化十次,会被计为十次 pending change,而不是一个发生变化的直接子项。++这与“唯一变化直接子项数”的理想语义并不完全一致。不过,OpenViking 中常规文件变化频率并不高;即使偶尔出现热点连续变化,它最多让目录更早达到刷新阈值,不会让摘要比现在更陈旧。++因此,首版有意容忍这个近似:++- 不持久化 changed child key;+- 不对跨事件的同一 URI 去重;+- 不引入集合截断、哈希冲突或额外 metadata;+- 继续将 `pending_child_changes` 当作简单的变化事件计数使用。++一次批量请求内部仍可对重复 URI 做自然去重,但不建立跨请求的唯一子项状态。++### 3. 采样发生在子项摘要工作之后++当前目录 DAG 会先生成或读取所有直接子项的摘要,最后才使用 `overview_sample_limit` 选出进入父目录 overview prompt 的部分输入。++这能够限制 prompt 大小,却没有避免未参与本次聚合的子项摘要工作。对于宽目录,如果我们的目标是降低重新摘要成本,就应当在调度本轮父目录聚合所需的子项摘要之前完成有界采样。++这里的采样是本轮生成过程中的临时决策,不形成持久化的“当前采样成员”概念,也不参与是否立即刷新的判断。++### 4. 仅使用变化比例可能长期不刷新++例如,一个包含 161 个直接子项的目录始终只有 3 个文件发生变化,那么它可能长期达不到 10% 的刷新阈值。++这是比例阈值的已知取舍。首版不为此引入最长陈旧时间、定时扫描、延迟消息或 dirty-directory registry,原因是这些机制会显著扩大实现和运维复杂度,而当前场景中的预期收益有限。++在没有后续变化的情况下,目录可以通过显式刷新、重新导入或其他自然语义任务获得更新。是否需要时间兜底,应在上线观察真实 pending 分布后再决定,先不讨论。++## 设计原则++- 比较父目录真正消费的语义输入,而不是比较包含 metadata 的原始 sidecar 字节。+- 子目录向上冒泡时,只以 L0 正文变化作为语义信号。+- 文件新增、删除和修改对于宽目录阈值统计是等价的。+- 不把“是否属于上次 sample”作为调度条件。+- 不持久化变化子项集合,只累计简单计数。+- 不改变现有 freshness 的四个字段及其基本含义。+- 显式刷新、首次导入和同步等待应保持可预测,不应被自动阈值静默延迟。+- 文件自身的解析、摘要和向量维护,与目录聚合摘要是否延迟分开处理。+- 首版复用现有持久队列、路径锁和 coalesce 机制,不新增时间调度系统。++## 非目标++首版明确不解决以下问题:++- 不保证 pending change 在固定时间内一定被聚合。+- 不精确统计唯一变化的直接子项数。+- 不记录或维护某个目录的持久化采样成员集合。+- 不根据新增、删除、修改设置不同权重。+- 不根据文件大小、类型或摘要差异程度计算加权变化率。++## 保持现有 Freshness 模型++继续使用 RFC 已定义的字段:++```yaml+freshness:+ total_entries: 161+ sampled_entries: 32+ unsampled_entries: 129+ pending_child_changes: 3+```++字段解释保持不变:++- `total_entries`:上一次成功生成目录摘要时观察到的直接子项总数。+- `sampled_entries`:上一次生成实际使用的直接子项数量。+- `unsampled_entries`:上一次生成未采样的直接子项数量。+- `pending_child_changes`:上一次生成完成后,已知发生变化、但尚未反映到当前正文中的直接子项数。++上述字段定义不变。首版只是在实现上使用轻量的事件累加来近似维护 `pending_child_changes`,暂不对跨事件的同一直接子项去重。因此实际计数可能被重复事件保守高估。该近似只用于判断变化规模是否值得触发一次父目录刷新,不应被当作精确审计数据。++新增和删除可能使当前真实直接子项数与 `total_entries` 暂时不一致。首版仍使用上一次成功生成记录的 `total_entries` 作为阈值分母;下一次成功刷新会重新列目录并修正这些计数。++## 语义变化判断++### 子目录变化++子目录语义任务开始前读取旧 L0 body,生成完成后取得新 L0 body,对规范化正文计算 digest:++```text+old_l0_digest = hash(normalize(old_l0_body))+new_l0_digest = hash(normalize(new_l0_body))+```++digest 不包含:++- YAML frontmatter;+- freshness;+- source;+- generated_by;+- 文件修改时间或其他存储属性。++决策规则:++- 新旧 L0 digest 相同:不标记父目录 pending,不为父目录入队,冒泡在当前层终止。+- 新旧 L0 digest 不同:向父目录上报一次普通的 direct-child change。+- 旧 L0 不存在或无法可靠解析:保守地视为发生变化。++L1 是否变化只决定当前目录自己的写回或向量维护,不决定是否继续向祖先冒泡。++### 直接文件变化++对于直接文件,新增、删除和修改都向所在目录贡献变化计数。首版不要求在入队前比较新旧文件摘要,因为这样会把语义生成工作前移到调度判断阶段,抵消低成本策略的收益。++一次批量操作中有多少个不同的 changed URI,就对本轮 pending 增加多少;后续独立事件再次修改同一个 URI,可以再次累加。++## 调度决策++策略输出只有三种:++```text+NOOP+MARK_PENDING+REFRESH_NOW+```++建议按以下顺序判断:++| 条件 | 决策 | 说明 |+| --- | --- | --- |+| 子目录新旧 L0 正文相同 | `NOOP` | 父目录实际输入没有变化 |+| 父目录不存在有效 sidecar | `REFRESH_NOW` | 没有可继续使用的摘要基线 |+| 首次导入或显式语义刷新 | `REFRESH_NOW` | 保持调用者意图 |+| 父目录上次记录的 `total_entries <= overview_sample_limit` | `REFRESH_NOW` | 小目录变化后直接刷新 |+| 宽目录累计变化率低于阈值 | `MARK_PENDING` | 只更新 freshness,不入队 |+| 宽目录累计变化率达到阈值 | `REFRESH_NOW` | 入队一次有界父目录刷新 |++这里没有以下特殊规则:++- sampled child 变化不要求立即刷新;+- 新增导致本轮临时 sample 变化不要求立即刷新;+- 删除导致本轮临时 sample 变化不要求立即刷新;+- 目录变化和文件变化不设置不同阈值。++对于宽目录,所有增删改都只是 `pending_child_changes` 的增量。++## 宽目录阈值++继续用 `semantic.overview_sample_limit` 区分小目录和宽目录,当前默认值为 32。++首版只新增一个比例配置:++```yaml+semantic:+ overview_sample_limit: 32+ freshness_refresh_ratio: 0.10+```++宽目录的判断为:++```text+pending_after = pending_before + current_change_count+change_ratio = pending_after / max(total_entries, 1)++refresh_now = change_ratio >= freshness_refresh_ratio+```++等价的整数阈值为:++```text+refresh_threshold = ceil(freshness_refresh_ratio * total_entries)+```++示例:++| 上次记录的直接子项数 | 10% 阈值 |+| ---: | ---: |+| 33 | 4 |+| 161 | 17 |+| 1000 | 100 |++首版不额外设置最小变化数或最大变化数,以减少配置项并保持“变化比例”含义直观。如果真实运行数据显示超宽目录等待过久或一次刷新积压过多,再考虑增加上限。++由于热点子项可重复累计,阈值可能比真实的唯一文件变化率更早达到。这是有意接受的保守偏差:它可能多触发一次刷新,但不会让目录更久不刷新。++代码实现时注意将公式的上述解释注释到代码。++## 达到阈值后的刷新方式++宽目录达到阈值后,不应只携带“最后一次变化的 URI”执行普通增量刷新。此前被延迟的变化没有持久化 URI 集合,仅保留了计数;只处理最后一次变化会遗漏先前事件。++因此,阈值触发的任务应被定义为一次当前目录的有界完整聚合:++1. 重新列举当前直接子项。+2. 根据 `overview_sample_limit` 选出本轮有界输入。+3. 为本轮选中的输入读取或生成当前摘要。+4. 生成新的 L1,并从 L1 正文提取 L0。+5. 写入最新的 `total_entries`、`sampled_entries` 和 `unsampled_entries`。+6. 消费本轮刷新开始时已经观察到的 pending 计数。++这里的“完整”是指从当前目录状态重新开始一次聚合决策,不是读取宽目录中的全部文件内容。实际进入目录摘要的输入仍受 `overview_sample_limit` 限制。++每次刷新都可以根据当时的目录状态重新进行确定性采样。系统不记录“上次 sample 中有哪些成员”,调度器也不基于 sample membership 做判断。++## 将采样前移++为了让宽目录阈值真正降低成本,应把本轮目录聚合采样前移到昂贵工作之前:++```text+列举直接子项+ -> 确定本轮有界 sample+ -> 只为本轮聚合准备 sample 所需的摘要输入+ -> 生成目录 L1/L0+```++采样算法只需要满足两个条件:++- 对同一个稳定目录重复执行时结果确定;+- 能够覆盖目录中不同位置的子项,而不是永远只取前 32 个。++可以继续使用现有的确定性保序采样。是否改成哈希采样不属于 freshness 冒泡首版的必要条件,因为我们不再赋予 sample membership 调度语义。++必须区分两类工作:++- 文件自身的解析、摘要或向量更新;+- 文件摘要作为输入参与父目录 L1/L0 聚合。++父目录聚合被延迟或采样,不能导致发生变化的文件失去自身应有的向量维护。采样前移只减少为“生成目录摘要”而进行的额外工作。++## Sidecar 写回结果++当前 sidecar 写回只返回成功与否,无法区分正文变化和 metadata 变化。建议返回结构化结果:++```python+AbstractOverviewWriteResult(+ wrote=True,+ overview_body_changed=True,+ abstract_body_changed=False,+)+```++语义如下:++- `wrote`:是否成功完成写回流程;+- `overview_body_changed`:L1 可见正文是否改变;+- `abstract_body_changed`:L0 可见正文是否改变。++metadata 从 `pending_child_changes > 0` 重置或减少,也可能造成 raw sidecar 变化,但这种变化不应被视为 L0/L1 语义变化。++后续行为:++- L0 正文改变:可以向父目录上报一次变化;+- 只有 L1 正文改变:只处理当前目录自己的写回和向量维护;+- L0/L1 正文都未改变:不需要重新向量化正文,也不继续冒泡;+- 只有 freshness 改变:只写 metadata。++### 标记和决策++在 sidecar exact-path lease 下:++1. 读取当前 `pending_child_changes`。+2. 加上本次 `current_change_count`。+3. 写回新计数。+4. 基于写回后的计数和现有 `total_entries` 做阈值判断。+5. 释放 lease 后再执行 enqueue。++这样 metadata 更新和调度判断来自同一个一致快照。并发事件即使同时到达,也不会简单覆盖彼此的计数。++## API 语义++以下操作默认绕过宽目录阈值,立即刷新:++- 首次资源导入;+- reindex 等触发的显式语义刷新;++普通后台文件变化可以被阈值延迟。如果一次操作只更新 freshness 而没有入队目录摘要,返回结果应明确表达:++```json+{+ "semantic_status": "deferred",+ "semantic_root_uri": "viking://resources/example"+}+```++此时文件自身的向量维护状态应单独表达,不能因为目录摘要被延迟就返回整体 `complete` 或错误地声称已经 `queued`。++## 实现边界++保持 `SemanticProcessor` 是 resource、skill 和 memory 语义处理的统一入口,不引入新的顶层 processor。++建议职责划分如下:++| 位置 | 职责 |+| --- | --- |+| `openviking/storage/queuefs/semantic_ops/freshness_policy.py` | 纯粹的 `NOOP` / `MARK_PENDING` / `REFRESH_NOW` 判断 |+| `openviking/storage/semantic_sidecar.py` | 在 lease 下原子累加、读取和消费现有 freshness 计数 |+| `SemanticDagExecutor` | 在宽目录聚合前完成本轮采样,并返回 L0/L1 正文变化结果 |+| `SemanticProcessor` | 根据 L0 是否变化决定是否继续向父目录冒泡 |+| content write、delete、resource 路径 | 将文件增删改统一记录为所在目录的变化计数 |++不新增 maintenance service、定时 sweep、延迟队列或 dirty-directory registry。++### 采样前移++- 宽目录在生成子项聚合输入前完成采样。+- 未进入本轮目录 sample 的子项不会仅为父目录聚合而产生额外摘要调用。+- 发生变化的文件仍然完成自身需要的向量维护。+- 稳定目录重复刷新产生确定性的采样结果。++### API 行为++- 自动延迟返回 `semantic_status: deferred`。+- 实际入队返回 `queued`,同步完成返回 `complete`。+- 目录聚合延迟与文件自身向量状态可以被调用方区分。++## 示例++假设一个目录上次生成时有 161 个直接子项,`overview_sample_limit=32`,刷新比例为 10%。++1. 子目录 `a/` 完成语义生成,但新旧 L0 相同:不修改父目录 freshness,也不继续冒泡。+2. 文件 `x.md`、`y.md` 和 `z.md` 发生修改:`pending_child_changes` 变为 3,低于阈值 17,不刷新目录摘要。+3. `x.md` 后续又被修改十次:pending 可以累计到 13。首版不做跨事件去重。+4. 再发生四次任意直接子项增删改后,pending 达到 17,触发一次父目录刷新。+5. 刷新重新列举当前目录并选择本轮最多 32 个输入,不关心这些输入是否属于某个历史 sample。+6. 刷新开始时捕获 pending snapshot;执行期间新增的变化计数会在写回后保留。+7. 如果刷新后的父目录 L0 仍然未变,则冒泡在父目录停止,不再刷新祖父目录。+8. 如果目录长期停留在 3 个 pending 且没有其他自然刷新,首版允许它继续保持这一 freshness 状态。diff --git a/docs/design/l0-l1-okf-sidecars-rfc.md b/docs/design/l0-l1-okf-sidecars-rfc.mdindex 6b80d1282..d947ddd71 100644--- a/docs/design/l0-l1-okf-sidecars-rfc.md+++ b/docs/design/l0-l1-okf-sidecars-rfc.md@@ -184,8 +184,8 @@ The current L0 extraction rule should continue to operate on the L1 body, not thIntroduce a small semantic-sidecar document helper near the existing sidecar write/read code:-- `render_semantic_sidecar(level, dir_uri, body, metadata) -> str`-- `parse_semantic_sidecar(raw) -> {metadata, body}`+- `render_abstract_overview(level, dir_uri, body, metadata) -> str`+- `parse_abstract_overview(raw) -> {metadata, body}`- `body_for_preview(raw) -> str`- `body_for_embedding(raw, whitelist=()) -> str`diff --git a/docs/en/api/12-content.md b/docs/en/api/12-content.mdindex d6fe199e2..d1f318ec1 100644--- a/docs/en/api/12-content.md+++ b/docs/en/api/12-content.md@@ -6,7 +6,7 @@ The Content API reads L0/L1/L2 content, writes text, and maintains semantic and### abstract()-Read L0 abstract (~100 tokens summary).+Read the L0 abstract (an approximately 100-token summary), excluding the OKF header.**Parameters**@@ -72,7 +72,7 @@ openviking abstract viking://resources/docs/### overview()-Read L1 overview, applies to directories.+Read the L1 overview for a directory, excluding the OKF header.**Parameters**@@ -137,7 +137,7 @@ openviking overview viking://resources/docs/### read()-Read L2 full content.+Read the complete text of an L0, L1, or L2 file.**Parameters**@@ -358,6 +358,7 @@ Each operation contains:- The batch holds one target tree lock while writing. Semantic processing starts only after every file is written and the lock is released, so `.overview.md` and `.abstract.md` are refreshed once for the batch.- An underlying I/O failure can still leave writes completed earlier in the batch visible.- Existing `.abstract.md` and `.overview.md` bodies may be replaced or appended. OpenViking preserves and validates protected OKF metadata and rebuilds only the directory's existing L0/L1 vectors for these operations.+- In the response body, `semantic_status` (`queued`, `complete`, or `deferred`) reports the directory aggregation status, while `vector_status` reports vector maintenance for changed files.**Python SDK**@@ -413,6 +414,8 @@ curl -X POST http://localhost:1933/api/v1/content/batch-write \"created": ["viking://resources/wiki/new.md"],"updated": [],"unchanged": [],+ "semantic_status": "complete",+ "vector_status": "complete","queue_status": {"Semantic": {"processed": 1,@@ -579,6 +582,7 @@ This API operates on existing `viking://...` content. It does not import new fil| mode | str | No | `vectors_only` | Reindex mode: `vectors_only`, `semantic_and_vectors`, or `prune_orphans` || wait | bool | No | `true` | Whether to wait for completion || dry_run | bool | No | `false` | Only valid with `mode="prune_orphans"`; report orphan vector records without deleting them |+| recursive | bool | No | `true` | Whether to process descendants recursively; `false` applies only to `semantic_and_vectors` on a `resource`, `memory`, or `skill` directory || tags | list[str] | No | `null` | Write tags to every successfully rebuilt vector record. Omit to preserve existing tags; an empty list with `replace` clears them || tag_mode | str | No | `replace` | Tag write mode: `replace` or `append` |@@ -609,6 +613,8 @@ For `resource` and `skill`, `semantic_and_vectors` refreshes directory/file semaFor `semantic_and_vectors`, semantic generation and vector rebuilding are sequenced by the reindex executor. The semantic refresh step does not enqueue its own background vectorization work; vectors are rebuilt by the reindex step so `wait=true` reflects the reindex operation itself.+For a `resource` or `memory` directory, `recursive=false` regenerates only the target directory's `.abstract.md` and `.overview.md`, then rebuilds only that directory's L0/L1 vectors. Child directories do not regenerate semantic artifacts, and neither child directories nor files are re-vectorized. The target aggregation still reads existing summaries from deterministically sampled child directories; sampled direct files are summarized as inputs to the target aggregation. For a `skill` target, `recursive=false` regenerates the skill directory's L0/L1 semantic artifacts and vectors from `SKILL.md`, but does not rebuild the `SKILL.md` L2 vector. This flag does not change existing behavior for `vectors_only`, `prune_orphans`, or namespace targets.+For `prune_orphans`, source existence is checked against the filesystem. If an entire directory is missing, vector records for files and semantic sidecars below that directory, such as `.abstract.md` and `.overview.md`, are pruned together. `dry_run` is rejected for other modes.When `tags` is provided, tags are included in the same upsert as each vector record produced by reindex; reindex does not call `set_tags` afterwards. Directory and namespace reindex operations apply tags to successfully rebuilt directory L0/L1 and leaf L2 records. `replace` overwrites existing tags, while `append` merges by key. When `tags` is omitted, `tag_mode` is ignored and existing tags remain unchanged. `prune_orphans` produces no vectors and ignores both fields.diff --git a/docs/en/concepts/03-context-layers.md b/docs/en/concepts/03-context-layers.mdindex 99c603d9c..627c3f0be 100644--- a/docs/en/concepts/03-context-layers.md+++ b/docs/en/concepts/03-context-layers.md@@ -146,7 +146,7 @@ API authentication guide covering OAuth 2.0, JWT tokens, and API keys.- `unsampled_entries`: direct entries not sampled, with `sampled + unsampled = total`.- `pending_child_changes`: known changed direct entries not yet reflected in the current body.-When the direct-entry count exceeds `semantic.sidecar_sample_size` (32 by default), OpenViking uses deterministic, order-preserving stable sampling. Repeated refreshes of an unchanged tree choose the same sample, avoiding noisy body rewrites and Git diffs.+When the direct-entry count exceeds `semantic.overview_sample_limit` (32 by default), OpenViking uses deterministic, order-preserving stable sampling. Repeated refreshes of an unchanged tree choose the same sample, avoiding noisy body rewrites and Git diffs.`pending_child_changes > 0` means the body is still readable but is known to lag behind lower-level changes. A successful parent refresh resets the value to 0 as part of the new coverage metadata.diff --git a/docs/en/concepts/06-extraction.md b/docs/en/concepts/06-extraction.mdindex 78183cd39..bf168da73 100644--- a/docs/en/concepts/06-extraction.md+++ b/docs/en/concepts/06-extraction.md@@ -126,7 +126,7 @@ L0/L1 are directory sidecars, not per-file sidecars. Parent-summary generation c### Freshness, Sampling, and Parent Refresh-Each generation records direct-child `total_entries`, `sampled_entries`, and `unsampled_entries`. When the direct-child count exceeds `semantic.sidecar_sample_size` (32 by default), OpenViking uses deterministic stable sampling. `pending_child_changes` increases when a known child change is not yet reflected in the parent body and resets to 0 after a successful refresh.+Each generation records direct-child `total_entries`, `sampled_entries`, and `unsampled_entries`. When the direct-child count exceeds `semantic.overview_sample_limit` (32 by default), OpenViking uses deterministic stable sampling. `pending_child_changes` increases when a known child change is not yet reflected in the parent body and resets to 0 after a successful refresh.Currently, each successful resource/skill semantic task schedules the next parent refresh and marks that parent pending before enqueue, continuing to the namespace-root boundary.@@ -141,7 +141,7 @@ Currently, each successful resource/skill semantic task schedules the next paren| `max_concurrent_llm` | 10 | Concurrent LLM calls || `max_images_per_call` | 10 | Max images per VLM call || `max_sections_per_call` | 20 | Max sections per VLM call |-| `sidecar_sample_size` | 32 | Maximum direct-child sample used for one directory summary |+| `overview_sample_limit` | 32 | Maximum direct-child sample used for one directory summary |## Code Skeleton Extractiondiff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.mdindex 9b7ea3732..faae8f5b1 100644--- a/docs/en/getting-started/05-cli-setup.md+++ b/docs/en/getting-started/05-cli-setup.md@@ -499,4 +499,6 @@ ov add-resource --help- `--mode semantic_and_vectors` — regenerate semantic artifacts (`.abstract.md`, `.overview.md`) before refreshing vectors.- `--mode prune_orphans` — remove vector records whose source files no longer exist. Add `--dry-run` to preview the cleanup without applying it.+`semantic_and_vectors` processes the full subtree by default. If child summaries already exist and only the target directory's `.abstract.md` / `.overview.md` need regeneration, add `--recursive=false`; this refreshes only the target directory semantics and its L0/L1 vectors.+There is no `semantic` or `full` mode alias.diff --git a/docs/zh/api/12-content.md b/docs/zh/api/12-content.mdindex 0b1ab09e2..079c13301 100644--- a/docs/zh/api/12-content.md+++ b/docs/zh/api/12-content.md@@ -6,7 +6,7 @@### abstract()-读取 L0 摘要(约 100 token 的概要)。+读取 L0 摘要(约 100 token 的概要),不包括 okf 文件头。**参数**@@ -72,7 +72,7 @@ openviking abstract viking://resources/docs/### overview()-读取 L1 概览,适用于目录。+读取 L1 概览,适用于目录,不包括 okf 文件头。**参数**@@ -137,7 +137,7 @@ openviking overview viking://resources/docs/### read()-读取 L2 完整内容。+读取 L0/L1/L2 文件完整文本内容。**参数**@@ -358,6 +358,7 @@ openviking write viking://resources/docs/api.md \- 写入期间整批共用一个目标 tree lock。所有文件写完并释放锁后才启动语义处理,因此 `.overview.md` / `.abstract.md` 每批只统一刷新一次。- 底层 I/O 中途失败时,本批次较早完成的写入仍可能已经可见。- 已存在的 `.abstract.md` / `.overview.md` 可以 replace 或 append;系统会保留并校验受保护的 OKF metadata,并只重建对应目录实际存在的 L0/L1 向量。+- 响应体中,通过 `semantic_status`(`queued`、`complete` 或 `deferred`)表达目录聚合状态,通过 `vector_status` 表达变化文件的向量维护状态。**Python SDK**@@ -413,6 +414,8 @@ curl -X POST http://localhost:1933/api/v1/content/batch-write \"created": ["viking://resources/wiki/new.md"],"updated": [],"unchanged": [],+ "semantic_status": "complete",+ "vector_status": "complete","queue_status": {"Semantic": {"processed": 1,@@ -579,6 +582,7 @@ ov set-tags viking://resources/project/ \| mode | str | 否 | `vectors_only` | 重建模式:`vectors_only`、`semantic_and_vectors` 或 `prune_orphans` || wait | bool | 否 | `true` | 是否等待任务完成 || dry_run | bool | 否 | `false` | 仅适用于 `mode="prune_orphans"`;只报告 orphan 向量记录,不实际删除 |+| recursive | bool | 否 | `true` | 是否递归处理下级内容;`false` 仅对 `resource`、`memory` 或 `skill` 目录的 `semantic_and_vectors` 生效 || tags | list[str] | 否 | `null` | 写入本次成功重建的全部向量记录。省略时保留已有 tags;空数组配合 `replace` 可清空 || tag_mode | str | 否 | `replace` | `tags` 的写入模式:`replace` 或 `append` |@@ -609,6 +613,8 @@ session 子树会被跳过。对于 `semantic_and_vectors`,语义刷新和向量重建由 reindex executor 串行编排。语义刷新阶段不会再额外向后台 embedding queue 投递自己的向量化任务;向量由 reindex 阶段统一重建,因此 `wait=true` 表示等待 reindex 操作本身完成。+对 `resource` 或 `memory` 目录设置 `recursive=false` 时,只重新生成目标目录的 `.abstract.md`、`.overview.md`,并重建该目录的 L0/L1 向量;下级目录不会重新生成语义产物,下级目录和文件也不会重新向量化。目标目录仍会读取本轮确定性采样命中的既有下级摘要;若采样命中直接文件,仍会为当前目录聚合准备这些文件的摘要。对 `skill` 目标设置 `recursive=false` 时,会根据 `SKILL.md` 重新生成 skill 目录的 L0/L1 语义产物及向量,但不会重建 `SKILL.md` 的 L2 向量。该参数不改变 `vectors_only`、`prune_orphans` 或 namespace 目标的既有行为。+对于 `prune_orphans`,源文件是否存在以当前文件系统为准。如果整个目录已经不存在,该目录下的正文文件向量和语义 sidecar 向量(例如 `.abstract.md`、`.overview.md`)会一起清理。`dry_run` 用在其他模式时会被拒绝。传入 `tags` 时,标签会随 reindex 生成的向量记录在同一次 upsert 中写入,不会在完成后额外调用 `set_tags`。目录或 namespace reindex 会把标签应用到本次成功重建的目录 L0/L1 和叶子 L2 记录。`replace` 覆盖已有标签,`append` 按 key 合并;省略 `tags` 时不校验 `tag_mode` 且不修改已有标签。`prune_orphans` 不生成向量,因此会忽略 `tags` 和 `tag_mode`。diff --git a/docs/zh/concepts/03-context-layers.md b/docs/zh/concepts/03-context-layers.mdindex 1b7d518cf..9ee7269e5 100644--- a/docs/zh/concepts/03-context-layers.md+++ b/docs/zh/concepts/03-context-layers.md@@ -146,7 +146,7 @@ API 认证指南,涵盖 OAuth 2.0、JWT 令牌和 API 密钥。- `unsampled_entries`:未采样的直接子项数,满足 `sampled + unsampled = total`。- `pending_child_changes`:已知发生变化、但尚未反映到当前正文中的直接子项数。-当直接子项超过 `semantic.sidecar_sample_size`(默认 32)时,系统使用确定性、保序的稳定采样。相同目录树重复刷新会选择相同样本,避免无意义的正文和 Git diff 抖动。+当直接子项超过 `semantic.overview_sample_limit`(默认 32)时,系统使用确定性、保序的稳定采样。相同目录树重复刷新会选择相同样本,避免无意义的正文和 Git diff 抖动。`pending_child_changes > 0` 表示正文仍然可读,但已知落后于下层变化。父目录刷新成功后,该值会随新的覆盖率元数据重置为 0。diff --git a/docs/zh/concepts/06-extraction.md b/docs/zh/concepts/06-extraction.mdindex bc6e9d280..60acb47df 100644--- a/docs/zh/concepts/06-extraction.md+++ b/docs/zh/concepts/06-extraction.md@@ -125,7 +125,7 @@ L0/L1 是目录级 sidecar,不是 per-file sidecar。生成父目录摘要时### Freshness、采样与父级刷新-每次生成都会记录直接子项的 `total_entries`、`sampled_entries` 和 `unsampled_entries`。直接子项超过 `semantic.sidecar_sample_size`(默认 32)时,系统使用确定性稳定采样。已知子项发生变化但父正文尚未刷新时,`pending_child_changes` 会递增;刷新成功后重置为 0。+每次生成都会记录直接子项的 `total_entries`、`sampled_entries` 和 `unsampled_entries`。直接子项超过 `semantic.overview_sample_limit`(默认 32)时,系统使用确定性稳定采样。已知子项发生变化但父正文尚未刷新时,`pending_child_changes` 会递增;刷新成功后重置为 0。当前每个成功的 resource/skill 语义任务都会继续安排父目录刷新,并在入队前将父目录标记为 pending。该行为会一直传播到 namespace 根边界。@@ -140,7 +140,7 @@ L0/L1 是目录级 sidecar,不是 per-file sidecar。生成父目录摘要时| `max_concurrent_llm` | 10 | 并发 LLM 调用数 || `max_images_per_call` | 10 | 单次 VLM 最大图片数 || `max_sections_per_call` | 20 | 单次 VLM 最大章节数 |-| `sidecar_sample_size` | 32 | 单个目录摘要使用的直接子项样本上限 |+| `overview_sample_limit` | 32 | 单个目录摘要使用的直接子项样本上限 |## 代码骨架提取diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.mdindex 1d43edc66..6b1c9d4cc 100644--- a/docs/zh/getting-started/05-cli-setup.md+++ b/docs/zh/getting-started/05-cli-setup.md@@ -499,4 +499,6 @@ ov add-resource --help- `--mode semantic_and_vectors` —— 先重新生成语义产物(`.abstract.md`、`.overview.md`),再刷新向量。- `--mode prune_orphans` —— 清理源文件已不存在的向量记录,加 `--dry-run` 可预览而不实际执行。+`semantic_and_vectors` 默认递归处理整个子树。对已经具有下级摘要、只需要重新生成目标目录 `.abstract.md` / `.overview.md` 的场景,可添加 `--recursive=false`;此时仅刷新目标目录语义产物和该目录的 L0/L1 向量。+没有 `semantic` 或 `full` 这样的模式别名。diff --git a/openviking/prompts/templates/semantic/overview_generation.yaml b/openviking/prompts/templates/semantic/overview_generation.yamlindex d717c525f..dc0f1ab62 100644--- a/openviking/prompts/templates/semantic/overview_generation.yaml+++ b/openviking/prompts/templates/semantic/overview_generation.yaml@@ -27,6 +27,11 @@ variables:description: "Language code for output (e.g., 'en', 'zh-CN', 'ja', 'ko', 'ru', 'ar')"required: true+ - name: "directory_coverage"+ type: "string"+ description: "Directory scale and sample coverage statement"+ default: ""+template: |Output Language: {{ output_language }}Write the entire overview consistently in {{ output_language }}; do not mix languages in headings, paragraphs, or list items.@@ -37,6 +42,9 @@ template: |[Directory Name]{{ dir_name }}+ [Directory Scale and Coverage]+ {{ directory_coverage }}+[Files and Their Summaries in Directory]{{ file_summaries }}@@ -53,7 +61,9 @@ template: |- When the summaries indicate a code repository, explain how subdirectories relate to the whole repo, such as services, libraries, apps, modules, or support folders.Faithfulness rules:- - Describe only what the provided summaries state; do not invent or generalize entities, facts, or relationships not present in them.+ - Describe only what the provided summaries state; do not invent entities, facts, or relationships not present in them.+ - When the coverage statement above indicates that only a sample of direct entries is shown, you MAY generalize from the sampled entries to characterize the directory as a whole (e.g. "the directory primarily covers X, Y, Z"), but such generalization must use hedging language such as "the sample shows", "primarily covers", "appears to contain", and must not claim that every entry has been examined.+ - Never describe specific content of entries that are not listed in the summaries above.- Before output, remove any named entity absent from the provided summaries—including organization, company, product, and brand names—and any unstated ownership, affiliation, or other relationship; never fill gaps with outside knowledge.Output in Markdown format, strictly following this structure:@@ -62,17 +72,25 @@ template: |2. **{{ "简要描述" if output_language == "zh-CN" else "Brief Description" }}** (plain text paragraph, 50-150 words):- Immediately following the title, without any H2 heading- - Explain what this is, what it's about, what it covers+ - Explain what this is, what it's about, and what it covers; when sampled, use hedging language to generalize from the sampled entries.- Include core keywords from the provided summaries for easy searching- Who it's suitable for, if stated in the provided summaries+ - Do not include entry counts, sample counts, unsampled counts, or other coverage statistics; keep this paragraph useful as a standalone retrieval abstract.++ 3. **{{ "目录覆盖" if output_language == "zh-CN" else "Directory Coverage" }}** (H2):+ - State the total number of direct entries and whether all entries are represented.+ - When sampled, state how many entries were sampled and how many were not individually examined.- 3. **{{ "快速导航" if output_language == "zh-CN" else "Quick Navigation" }}** (H2): Decision Tree style+ 4. **{{ "快速导航" if output_language == "zh-CN" else "Quick Navigation" }}** (H2): Decision Tree style- Guide with "What do you want to learn?" or "What do you want to do?"- Use → arrow to point to specific files or directories- **Use file number references**: such as [1], [2], [3]- Concise keyword descriptions+ - When sampled, introduce the list with a note that these are representative entries and the full directory contains more- 4. **{{ "详细说明" if output_language == "zh-CN" else "Detailed Description" }}** (H2): One H3 subsection for each file/subdirectory+ 5. **{{ "详细说明" if output_language == "zh-CN" else "Detailed Description" }}** (H2):+ - When sampled, begin with a one-sentence note stating that the following subsections cover only the sampled entries (X of Y), not the full directory.+ - One H3 subsection for each file/subdirectory- Use the file summaries or subdirectory summaries provided above as description contentTotal length: 400-800 wordsdiff --git a/openviking/retrieve/context_assembler/tiers.py b/openviking/retrieve/context_assembler/tiers.pyindex e17591937..20cdd562c 100644--- a/openviking/retrieve/context_assembler/tiers.py+++ b/openviking/retrieve/context_assembler/tiers.py@@ -26,7 +26,7 @@ from openviking.retrieve.context_assembler.params import (Tier,)from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils-from openviking.storage.semantic_sidecar import body_for_preview+from openviking.storage.abstract_overview import body_for_previewOVERVIEW_HEADING_LIMIT = 24OVERVIEW_PARAGRAPH_CHARS = 400diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.pyindex a39156aca..e175d276d 100644--- a/openviking/retrieve/hierarchical_retriever.py+++ b/openviking/retrieve/hierarchical_retriever.py@@ -22,8 +22,8 @@ from openviking.models.rerank import RerankClientfrom openviking.retrieve.memory_lifecycle import hotness_scorefrom openviking.retrieve.retrieval_stats import get_stats_collectorfrom openviking.server.identity import RequestContext+from openviking.storage.abstract_overview import body_for_previewfrom openviking.storage.expr import FilterExpr-from openviking.storage.semantic_sidecar import body_for_previewfrom openviking.storage.vikingdb_manager import VikingDBManager, VikingDBManagerProxyfrom openviking.telemetry import get_current_telemetryfrom openviking.utils.tags import normalize_search_tagsdiff --git a/openviking/server/routers/content.py b/openviking/server/routers/content.pyindex 7b94049c7..4912deeb1 100644--- a/openviking/server/routers/content.py+++ b/openviking/server/routers/content.py@@ -92,6 +92,7 @@ class ReindexRequest(BaseModel):mode: str = "vectors_only"wait: bool = Truedry_run: bool = False+ recursive: bool = Truetags: list[str] | None = Nonetag_mode: str = "replace"@@ -322,6 +323,8 @@ async def reindex("dry_run": body.dry_run,"ctx": ctx,}+ if not body.recursive:+ reindex_kwargs["recursive"] = Falseif body.tags is not None:reindex_kwargs["tags"] = body.tagsreindex_kwargs["tag_mode"] = body.tag_modediff --git a/openviking/service/core.py b/openviking/service/core.pyindex 119c878c5..baa7ce676 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -566,6 +566,7 @@ class OpenVikingService:mode: str = "vectors_only",wait: bool = True,dry_run: bool = False,+ recursive: bool = True,tags: list[str] | None = None,tag_mode: str = "replace",ctx: RequestContext | None = None,@@ -584,6 +585,8 @@ class OpenVikingService:"dry_run": dry_run,"ctx": effective_ctx,}+ if not recursive:+ execute_kwargs["recursive"] = Falseif tags is not None:execute_kwargs["tags"] = tagsexecute_kwargs["tag_mode"] = tag_modediff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.pyindex 407f828f3..fa683b1c3 100644--- a/openviking/service/fs_service.py+++ b/openviking/service/fs_service.py@@ -21,13 +21,14 @@ from openviking.resource.watch_storage import is_watch_task_control_urifrom openviking.server.identity import RequestContextfrom openviking.session.memory.memory_updater import MemoryUpdaterfrom openviking.session.memory.utils.content_visibility import visible_content+from openviking.storage.abstract_overview import (+ plan_abstract_overview_refresh,+ render_abstract_overview,+)from openviking.storage.content_write import ContentWriteCoordinatorfrom openviking.storage.queuefs import SemanticMsg, get_queue_managerfrom openviking.storage.queuefs.semantic_msg import build_semantic_coalesce_key-from openviking.storage.semantic_sidecar import (- mark_semantic_sidecars_pending,- render_semantic_sidecar,-)+from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessActionfrom openviking.storage.viking_fs import VikingFSfrom openviking.telemetry import get_current_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -35,6 +36,7 @@ from openviking.telemetry.resource_summary import build_queue_status_payloadfrom openviking.utils.embedding_utils import vectorize_directory_metafrom openviking_cli.exceptions import DeadlineExceededError, NotInitializedErrorfrom openviking_cli.utils import VikingURI, get_logger+from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)@@ -199,7 +201,7 @@ class FSService:directory_uri, abstract_uri = self._resolve_directory_uris(uri)await viking_fs.write_file(abstract_uri,- render_semantic_sidecar(+ render_abstract_overview(ContextLevel.ABSTRACT,directory_uri,abstract,@@ -257,6 +259,7 @@ class FSService:result = await viking_fs.rm(uri, recursive=recursive, ctx=ctx)await self._sync_watch_after_rm(uri, account_id=ctx.account_id, context_type=context_type)queue_status = None+ refresh_action: Optional[FreshnessAction] = Nonerequest_registered = Falsetelemetry_id = get_current_telemetry().telemetry_idtry:@@ -264,11 +267,12 @@ class FSService:if wait and telemetry_id:get_request_wait_tracker().register_request(telemetry_id)request_registered = True- await self._enqueue_delete_refresh(+ refresh_action = await self._enqueue_delete_refresh(root_uri=refresh_parent_uri,deleted_uri=uri,context_type=context_type,ctx=ctx,+ force_refresh=wait,)if self._resource_memory_link_service and context_type == "resource":cleanup_result = await self._resource_memory_link_service.before_resource_delete(@@ -290,7 +294,7 @@ class FSService:directory_uri=cleanup_overview_uri,ctx=ctx,)- if refresh_parent_uri and wait:+ if refresh_parent_uri and wait and refresh_action is not FreshnessAction.MARK_PENDING:queue_status = await self._wait_for_refresh(timeout=timeout)finally:if request_registered:@@ -299,9 +303,10 @@ class FSService:result["memory_cleanup"] = cleanup_resultif refresh_parent_uri and isinstance(result, dict):result["semantic_root_uri"] = refresh_parent_uri- result["semantic_status"] = self._semantic_refresh_status(- wait=wait,- queue_status=queue_status,+ result["semantic_status"] = (+ "deferred"+ if refresh_action is FreshnessAction.MARK_PENDING+ else self._semantic_refresh_status(wait=wait, queue_status=queue_status))if queue_status is not None:result["queue_status"] = queue_status@@ -382,18 +387,25 @@ class FSService:deleted_uri: str,context_type: str,ctx: RequestContext,- ) -> None:- await mark_semantic_sidecars_pending(+ force_refresh: bool = False,+ ) -> FreshnessAction:+ semantic_config = get_openviking_config().semantic+ decision = await plan_abstract_overview_refresh(viking_fs=self._viking_fs,dir_uri=root_uri,changed_entries=1,ctx=ctx,+ overview_sample_limit=getattr(semantic_config, "overview_sample_limit", 32),+ refresh_ratio=getattr(semantic_config, "freshness_refresh_ratio", 0.10),+ force_refresh=force_refresh,)+ if decision.action is not FreshnessAction.REFRESH_NOW:+ return decision.actiontry:queue_manager = get_queue_manager()except RuntimeError as exc:logger.warning("QueueManager not available, skipping delete refresh: %s", exc)- return+ return decision.actionsemantic_queue = queue_manager.get_queue(queue_manager.SEMANTIC, allow_create=True)telemetry_id = get_current_telemetry().telemetry_idmsg = SemanticMsg(@@ -424,6 +436,7 @@ class FSService:if telemetry_id:get_request_wait_tracker().mark_semantic_failed(telemetry_id, msg.id, str(exc))raise+ return decision.actionasync def _wait_for_refresh(self, *, timeout: Optional[float]) -> Dict[str, Any]:telemetry_id = get_current_telemetry().telemetry_iddiff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.pyindex 9ffe35f6b..857ac8f02 100644--- a/openviking/service/reindex_executor.py+++ b/openviking/service/reindex_executor.py@@ -29,11 +29,11 @@ from openviking.server.identity import RequestContextfrom openviking.service.task_tracker import get_task_trackerfrom openviking.service.task_work_index import bind_task_contextfrom openviking.session.memory.utils.memory_file_utils import MemoryFileUtils+from openviking.storage.abstract_overview import body_for_preview, embedding_text_for_bodyfrom openviking.storage.expr import And, Eq, Or, PathScopefrom openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverterfrom openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor-from openviking.storage.semantic_sidecar import body_for_preview, embedding_text_for_bodyfrom openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import get_current_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -180,6 +180,7 @@ class ReindexExecutor:mode: str,wait: bool,dry_run: bool = False,+ recursive: bool = True,tags: list[str] | None = None,tag_mode: str = "replace",ctx: RequestContext,@@ -212,6 +213,7 @@ class ReindexExecutor:object_type=object_type,mode=mode,dry_run=dry_run,+ recursive=recursive,ingest_options=ingest_options,ctx=ctx,)@@ -236,6 +238,7 @@ class ReindexExecutor:object_type=object_type,mode=mode,dry_run=dry_run,+ recursive=recursive,ingest_options=ingest_options,ctx=ctx,)@@ -482,6 +485,7 @@ class ReindexExecutor:object_type: str,mode: str,dry_run: bool = False,+ recursive: bool = True,ingest_options: IngestOptions | None = None,ctx: RequestContext,) -> dict[str, Any]:@@ -544,23 +548,20 @@ class ReindexExecutor:run=run,)elif object_type == "resource":- await self._reindex_resource(- uri=uri,- mode=mode,- run=run,- )+ resource_kwargs = {"uri": uri, "mode": mode, "run": run}+ if not recursive:+ resource_kwargs["recursive"] = False+ await self._reindex_resource(**resource_kwargs)elif object_type == "skill":- await self._reindex_skill(- uri=uri,- mode=mode,- run=run,- )+ skill_kwargs = {"uri": uri, "mode": mode, "run": run}+ if not recursive:+ skill_kwargs["recursive"] = False+ await self._reindex_skill(**skill_kwargs)elif object_type == "memory":- await self._reindex_memory(- uri=uri,- mode=mode,- run=run,- )+ memory_kwargs = {"uri": uri, "mode": mode, "run": run}+ if not recursive:+ memory_kwargs["recursive"] = False+ await self._reindex_memory(**memory_kwargs)else:raise OpenVikingError(f"Unsupported reindex type: {object_type}",@@ -602,6 +603,7 @@ class ReindexExecutor:object_type: str,mode: str,dry_run: bool = False,+ recursive: bool = True,ingest_options: IngestOptions | None = None,ctx: RequestContext,) -> None:@@ -615,6 +617,7 @@ class ReindexExecutor:object_type=object_type,mode=mode,dry_run=dry_run,+ recursive=recursive,ingest_options=ingest_options,ctx=ctx,)@@ -938,19 +941,26 @@ class ReindexExecutor:uri: str,mode: str,run: _ReindexRunContext,+ recursive: bool = True,) -> None:counters = run.countersctx = run.ctxif mode == "semantic_and_vectors":- await self._run_semantic_processor(- uri=uri,- context_type="resource",- ctx=ctx,- lock=run.lock,- )+ semantic_kwargs = {+ "uri": uri,+ "context_type": "resource",+ "ctx": ctx,+ "lock": run.lock,+ }+ if not recursive:+ semantic_kwargs["recursive"] = False+ await self._run_semantic_processor(**semantic_kwargs)+ vector_kwargs = {"uri": uri, "counters": counters, "ctx": ctx}+ if not recursive:+ vector_kwargs["recursive"] = Falseawait self._reindex_resource_vectors(**self._with_ingest_options(- {"uri": uri, "counters": counters, "ctx": ctx},+ vector_kwargs,run.ingest_options,))@@ -968,11 +978,19 @@ class ReindexExecutor:uri: str,mode: str,run: _ReindexRunContext,+ recursive: bool = True,) -> None:counters = run.countersctx = run.ctxif mode == "semantic_and_vectors":await self._regenerate_skill_semantics(uri=uri, ctx=ctx)+ vector_kwargs = {"uri": uri, "counters": counters, "ctx": ctx}+ if not recursive:+ vector_kwargs["recursive"] = False+ await self._reindex_skill_vectors(+ **self._with_ingest_options(vector_kwargs, run.ingest_options)+ )+ returnawait self._reindex_skill_vectors(**self._with_ingest_options({"uri": uri, "counters": counters, "ctx": ctx},@@ -986,21 +1004,28 @@ class ReindexExecutor:uri: str,mode: str,run: _ReindexRunContext,+ recursive: bool = True,) -> None:counters = run.countersctx = run.ctxif mode == "semantic_and_vectors":stat = await get_viking_fs().stat(uri, ctx=ctx)if stat.get("isDir", stat.get("is_dir")):- await self._run_semantic_processor(- uri=uri,- context_type="memory",- ctx=ctx,- lock=run.lock,- )+ semantic_kwargs = {+ "uri": uri,+ "context_type": "memory",+ "ctx": ctx,+ "lock": run.lock,+ }+ if not recursive:+ semantic_kwargs["recursive"] = False+ await self._run_semantic_processor(**semantic_kwargs)+ vector_kwargs = {"uri": uri, "counters": counters, "ctx": ctx}+ if not recursive:+ vector_kwargs["recursive"] = Falseawait self._reindex_memory_vectors(**self._with_ingest_options(- {"uri": uri, "counters": counters, "ctx": ctx},+ vector_kwargs,run.ingest_options,))@@ -1019,6 +1044,7 @@ class ReindexExecutor:context_type: str,ctx: RequestContext,lock: dict | None = None,+ recursive: bool = True,) -> None:processor = SemanticProcessor(max_concurrent_llm=get_openviking_config().vlm.max_concurrent,@@ -1027,12 +1053,15 @@ class ReindexExecutor:msg = SemanticMsg(uri=uri,context_type=context_type,- recursive=True,+ recursive=recursive,account_id=owner_ctx.account_id,user_id=owner_ctx.user.user_id,peer_id=owner_ctx.user.user_id,role=str(ctx.role),skip_vectorization=True,+ generation_trigger="reindex",+ use_hierarchical_aggregation=context_type == "memory",+ propagate_to_parent=recursive,)await processor.on_dequeue({"data": msg.to_json()}, lock=lock)@@ -1042,6 +1071,7 @@ class ReindexExecutor:uri: str,counters: _ReindexCounters,ctx: RequestContext,+ recursive: bool = True,ingest_options: IngestOptions | None = None,) -> None:viking_fs = get_viking_fs()@@ -1050,7 +1080,7 @@ class ReindexExecutor:raise NotFoundError(uri, "resource")stat = await viking_fs.stat(uri, ctx=ctx)is_dir = stat.get("isDir", stat.get("is_dir")) if isinstance(stat, dict) else False- if is_dir:+ if is_dir and recursive:entries = await self._tree_all(viking_fs, uri, show_all_hidden=True, ctx=ctx)else:entries = []@@ -1451,6 +1481,7 @@ class ReindexExecutor:uri: str,counters: _ReindexCounters,ctx: RequestContext,+ recursive: bool = True,ingest_options: IngestOptions | None = None,) -> None:viking_fs = get_viking_fs()@@ -1518,7 +1549,7 @@ class ReindexExecutor:counters.warnings.append(f"Failed to reindex {uri} L1 vector: {exc}")skill_file_uri = f"{uri}/SKILL.md"- if await viking_fs.exists(skill_file_uri, ctx=ctx):+ if recursive and await viking_fs.exists(skill_file_uri, ctx=ctx):counters.scanned_records += 1skill_content = await self._safe_read_text(skill_file_uri, ctx=ctx)if skill_content:@@ -1546,13 +1577,18 @@ class ReindexExecutor:uri: str,counters: _ReindexCounters,ctx: RequestContext,+ recursive: bool = True,ingest_options: IngestOptions | None = None,) -> None:viking_fs = get_viking_fs()if await viking_fs.exists(uri, ctx=ctx):stat = await viking_fs.stat(uri, ctx=ctx)if stat.get("isDir", stat.get("is_dir")):- entries = await self._tree_all(viking_fs, uri, show_all_hidden=False, ctx=ctx)+ entries = (+ await self._tree_all(viking_fs, uri, show_all_hidden=False, ctx=ctx)+ if recursive+ else []+ )directory_uris = {uri}for entry in entries:entry_uri = entry.get("uri")diff --git a/openviking/service/resource_memory_link_service.py b/openviking/service/resource_memory_link_service.pyindex 4e7711070..a9c2f49b6 100644--- a/openviking/service/resource_memory_link_service.py+++ b/openviking/service/resource_memory_link_service.py@@ -32,7 +32,7 @@ from openviking.session.memory.utils.resource_refs import (resource_ref_matches,unlink_resource_references_from_memory,)-from openviking.storage.semantic_sidecar import body_for_preview+from openviking.storage.abstract_overview import body_for_previewfrom openviking.storage.viking_fs import VikingFS, get_viking_fsfrom openviking.storage.vikingdb_manager import VikingDBManagerfrom openviking_cli.exceptions import NotFoundErrordiff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.pyindex 40a7c5b16..f6414d0cc 100644--- a/openviking/session/memory/memory_updater.py+++ b/openviking/session/memory/memory_updater.py@@ -40,7 +40,7 @@ from openviking.session.memory.utils.resource_refs import ()from openviking.session.memory.utils.template_utils import TemplateUtilsfrom openviking.session.memory.utils.uri import render_template-from openviking.storage.semantic_sidecar import freshness_metadata, render_semantic_sidecar+from openviking.storage.abstract_overview import freshness_metadata, render_abstract_overviewfrom openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import tracerfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -1619,7 +1619,7 @@ class MemoryUpdater:try:await viking_fs.write_file(overview_path,- render_semantic_sidecar(+ render_abstract_overview(ContextLevel.OVERVIEW,directory,rendered,diff --git a/openviking/session/session.py b/openviking/session/session.pyindex e5c22b1c4..ac1e6e07a 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -44,7 +44,7 @@ from openviking.session.tool_result_synopsis import (ToolResultSynopsis,generate_tool_result_synopsis,)-from openviking.storage.semantic_sidecar import body_for_preview, render_semantic_sidecar+from openviking.storage.abstract_overview import body_for_preview, render_abstract_overviewfrom openviking.telemetry import get_current_telemetry, tracerfrom openviking.telemetry.request_wait_tracker import get_request_wait_trackerfrom openviking.utils.model_retry import is_retryable_api_error, retry_async@@ -2470,7 +2470,7 @@ class Session:abstract = self._extract_abstract_from_summary(summary)await self._viking_fs.write_file(uri=f"{archive_uri}/.abstract.md",- content=render_semantic_sidecar(+ content=render_abstract_overview(ContextLevel.ABSTRACT,archive_uri,abstract,@@ -2485,7 +2485,7 @@ class Session:)await self._viking_fs.write_file(uri=f"{archive_uri}/.overview.md",- content=render_semantic_sidecar(+ content=render_abstract_overview(ContextLevel.OVERVIEW,archive_uri,summary,@@ -5213,7 +5213,7 @@ class Session:)await viking_fs.write_file(uri=f"{self._session_uri}/.abstract.md",- content=render_semantic_sidecar(+ content=render_abstract_overview(ContextLevel.ABSTRACT,self._session_uri,abstract,@@ -5229,7 +5229,7 @@ class Session:)await viking_fs.write_file(uri=f"{self._session_uri}/.overview.md",- content=render_semantic_sidecar(+ content=render_abstract_overview(ContextLevel.OVERVIEW,self._session_uri,overview,diff --git a/openviking/session/skill/skill_operation_updater.py b/openviking/session/skill/skill_operation_updater.pyindex c84fedab3..2ac7da7f4 100644--- a/openviking/session/skill/skill_operation_updater.py+++ b/openviking/session/skill/skill_operation_updater.py@@ -14,8 +14,8 @@ from openviking.server.identity import RequestContextfrom openviking.session.memory.dataclass import ResolvedOperation, ResolvedOperationsfrom openviking.session.memory.memory_type_registry import MemoryTypeRegistryfrom openviking.session.memory.merge_op import MergeOpFactory+from openviking.storage.abstract_overview import body_for_previewfrom openviking.storage.content_write import ContentWriteCoordinator-from openviking.storage.semantic_sidecar import body_for_previewfrom openviking.storage.viking_fs import VikingFS, get_viking_fsfrom openviking.utils.skill_processor import SkillProcessorfrom openviking_cli.exceptions import NotFoundErrordiff --git a/openviking/storage/semantic_sidecar.py b/openviking/storage/abstract_overview.pysimilarity index 54%rename from openviking/storage/semantic_sidecar.pyrename to openviking/storage/abstract_overview.pyindex 79b89623e..f11c16f8b 100644--- a/openviking/storage/semantic_sidecar.py+++ b/openviking/storage/abstract_overview.py@@ -1,6 +1,6 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0-"""OKF documents and atomic writeback for generated semantic sidecars.+"""OKF documents and atomic writeback for generated abstract overviews.Only .abstract.md and .overview.md use this module. Ordinary Markdown keepsits frontmatter as user content and is never parsed implicitly.@@ -8,8 +8,9 @@ its frontmatter as user content and is never parsed implicitly.from __future__ import annotations+import hashlibfrom dataclasses import dataclass-from typing import Any, Callable, Dict, Mapping, Optional, Sequence, TypeVar+from typing import TYPE_CHECKING, Any, Callable, Dict, Mapping, Optional, Sequence, TypeVarimport yaml@@ -18,9 +19,12 @@ from openviking.server.error_mapping import is_not_found_errorfrom openviking.server.identity import RequestContextfrom openviking_cli.utils.logger import get_logger+if TYPE_CHECKING:+ from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessDecision+logger = get_logger(__name__)-SEMANTIC_SIDECAR_FILENAMES = frozenset({".abstract.md", ".overview.md"})+ABSTRACT_OVERVIEW_FILENAMES = frozenset({".abstract.md", ".overview.md"})EMBEDDING_METADATA_FIELDS = ("directory",)_METADATA_ORDER = ("directory", "source", "generated_by", "freshness")_MAX_SOURCE_URI_CHARS = 4096@@ -28,16 +32,16 @@ _MAX_LABEL_CHARS = 128_T = TypeVar("_T")-class SemanticSidecarFormatError(ValueError):- """A generated semantic sidecar has invalid OKF frontmatter."""+class AbstractOverviewFormatError(ValueError):+ """A generated abstract overview has invalid OKF frontmatter."""-class SemanticSidecarMetadataError(SemanticSidecarFormatError):+class AbstractOverviewMetadataError(AbstractOverviewFormatError):"""A public write attempted to change protected sidecar metadata."""@dataclass(frozen=True)-class SemanticSidecarDocument:+class AbstractOverviewDocument:"""Parsed machine metadata and visible Markdown body."""metadata: Dict[str, Any]@@ -45,28 +49,40 @@ class SemanticSidecarDocument:legacy: bool = False-def is_semantic_sidecar_uri(uri: str) -> bool:+@dataclass(frozen=True)+class AbstractOverviewWriteResult:+ """Visible-body changes produced by one successful sidecar writeback."""++ wrote: bool+ overview_body_changed: bool = False+ abstract_body_changed: bool = False++ def __bool__(self) -> bool:+ return self.wrote+++def is_abstract_overview_uri(uri: str) -> bool:"""Return whether uri names one of the two generated sidecars."""- return uri.rstrip("/").rsplit("/", 1)[-1] in SEMANTIC_SIDECAR_FILENAMES+ return uri.rstrip("/").rsplit("/", 1)[-1] in ABSTRACT_OVERVIEW_FILENAMESdef _normalize_directory_uri(dir_uri: str) -> str:value = str(dir_uri or "").strip()if not value:- raise SemanticSidecarFormatError("semantic sidecar directory must not be empty")+ raise AbstractOverviewFormatError("abstract overview directory must not be empty")if not value.startswith("viking://"):- raise SemanticSidecarFormatError("semantic sidecar directory must be a viking:// URI")+ raise AbstractOverviewFormatError("abstract overview directory must be a viking:// URI")return value.rstrip("/") + "/"def _bounded_string(value: Any, *, field: str, limit: int) -> str:if not isinstance(value, str) or not value.strip():- raise SemanticSidecarFormatError(f"semantic sidecar {field} must be a non-empty string")+ raise AbstractOverviewFormatError(f"abstract overview {field} must be a non-empty string")normalized = value.strip()if len(normalized) > limit:- raise SemanticSidecarFormatError(- f"semantic sidecar {field} exceeds the {limit}-character policy limit"+ raise AbstractOverviewFormatError(+ f"abstract overview {field} exceeds the {limit}-character policy limit")return normalized@@ -86,7 +102,7 @@ def _normalize_metadata(metadata: Mapping[str, Any]) -> Dict[str, Any]:source = metadata.get("source")if source is not None:if not isinstance(source, Mapping) or not {"kind", "uri"}.issubset(source):- raise SemanticSidecarFormatError("semantic sidecar source must contain kind and uri")+ raise AbstractOverviewFormatError("abstract overview source must contain kind and uri")normalized["source"] = {"kind": _bounded_string(source["kind"], field="source.kind", limit=_MAX_LABEL_CHARS),"uri": _bounded_string(source["uri"], field="source.uri", limit=_MAX_SOURCE_URI_CHARS),@@ -98,8 +114,8 @@ def _normalize_metadata(metadata: Mapping[str, Any]) -> Dict[str, Any]:"component","trigger",}.issubset(generated_by):- raise SemanticSidecarFormatError(- "semantic sidecar generated_by must contain component and trigger"+ raise AbstractOverviewFormatError(+ "abstract overview generated_by must contain component and trigger")normalized["generated_by"] = {"component": _bounded_string(@@ -123,7 +139,7 @@ def _normalize_metadata(metadata: Mapping[str, Any]) -> Dict[str, Any]:"pending_child_changes",}if not isinstance(freshness, Mapping) or not required.issubset(freshness):- raise SemanticSidecarFormatError("semantic sidecar freshness has an invalid field set")+ raise AbstractOverviewFormatError("abstract overview freshness has an invalid field set")counters: Dict[str, int] = {}for field in ("total_entries",@@ -133,20 +149,20 @@ def _normalize_metadata(metadata: Mapping[str, Any]) -> Dict[str, Any]:):value = freshness[field]if isinstance(value, bool) or not isinstance(value, int) or value < 0:- raise SemanticSidecarFormatError(- f"semantic sidecar freshness.{field} must be a non-negative integer"+ raise AbstractOverviewFormatError(+ f"abstract overview freshness.{field} must be a non-negative integer")counters[field] = valueif counters["sampled_entries"] + counters["unsampled_entries"] != counters["total_entries"]:- raise SemanticSidecarFormatError(- "semantic sidecar freshness sampled + unsampled must equal total"+ raise AbstractOverviewFormatError(+ "abstract overview freshness sampled + unsampled must equal total")normalized["freshness"] = countersreturn {field: normalized[field] for field in _METADATA_ORDER if field in normalized}-def parse_semantic_sidecar(raw: str | bytes) -> SemanticSidecarDocument:+def parse_abstract_overview(raw: str | bytes) -> AbstractOverviewDocument:"""Parse OKF Markdown while accepting frontmatter-free legacy content.A leading delimiter opts a generated sidecar into strict OKF parsing.@@ -157,15 +173,15 @@ def parse_semantic_sidecar(raw: str | bytes) -> SemanticSidecarDocument:try:text = raw.decode("utf-8")except UnicodeDecodeError as exc:- raise SemanticSidecarFormatError("semantic sidecar is not valid UTF-8") from exc+ raise AbstractOverviewFormatError("abstract overview is not valid UTF-8") from excelif isinstance(raw, str):text = rawelse:- raise TypeError("semantic sidecar content must be str or bytes")+ raise TypeError("abstract overview content must be str or bytes")lines = text.splitlines(keepends=True)if not lines or lines[0].rstrip("\r\n") != "---":- return SemanticSidecarDocument(metadata={}, body=text, legacy=True)+ return AbstractOverviewDocument(metadata={}, body=text, legacy=True)closing_index: Optional[int] = Nonefor index in range(1, len(lines)):@@ -173,28 +189,28 @@ def parse_semantic_sidecar(raw: str | bytes) -> SemanticSidecarDocument:closing_index = indexbreakif closing_index is None:- raise SemanticSidecarFormatError("semantic sidecar frontmatter is not closed")+ raise AbstractOverviewFormatError("abstract overview frontmatter is not closed")try:loaded = yaml.safe_load("".join(lines[1:closing_index]))except yaml.YAMLError as exc:- raise SemanticSidecarFormatError(f"invalid semantic sidecar YAML: {exc}") from exc+ raise AbstractOverviewFormatError(f"invalid abstract overview YAML: {exc}") from excif loaded is None:loaded = {}if not isinstance(loaded, Mapping):- raise SemanticSidecarFormatError("semantic sidecar frontmatter must be a YAML object")+ raise AbstractOverviewFormatError("abstract overview frontmatter must be a YAML object")if "directory" not in loaded:- raise SemanticSidecarFormatError("semantic sidecar frontmatter must contain directory")+ raise AbstractOverviewFormatError("abstract overview frontmatter must contain directory")body = "".join(lines[closing_index + 1 :])if body.startswith("\r\n"):body = body[2:]elif body.startswith("\n"):body = body[1:]- return SemanticSidecarDocument(metadata=_normalize_metadata(loaded), body=body, legacy=False)+ return AbstractOverviewDocument(metadata=_normalize_metadata(loaded), body=body, legacy=False)-def render_semantic_sidecar(+def render_abstract_overview(level: int | ContextLevel,dir_uri: str,body: str,@@ -205,11 +221,11 @@ def render_semantic_sidecar(try:resolved_level = ContextLevel(int(level))except (TypeError, ValueError) as exc:- raise SemanticSidecarFormatError(f"invalid semantic sidecar level: {level}") from exc+ raise AbstractOverviewFormatError(f"invalid abstract overview level: {level}") from excif resolved_level not in {ContextLevel.ABSTRACT, ContextLevel.OVERVIEW}:- raise SemanticSidecarFormatError("semantic sidecars only support L0 and L1")+ raise AbstractOverviewFormatError("abstract overviews only support L0 and L1")if not isinstance(body, str):- raise TypeError("semantic sidecar body must be a string")+ raise TypeError("abstract overview body must be a string")merged: Dict[str, Any] = dict(metadata or {})merged["directory"] = _normalize_directory_uri(dir_uri)@@ -222,7 +238,7 @@ def render_semantic_sidecar(return f"---\n{frontmatter}\n---\n\n{body.strip()}\n"-def prepare_semantic_sidecar_write(+def prepare_abstract_overview_write(uri: str,current_raw: str | bytes,requested_raw: str | bytes,@@ -242,14 +258,14 @@ def prepare_semantic_sidecar_write("""if mode not in {"replace", "append"}:- raise ValueError(f"unsupported semantic sidecar write mode: {mode}")- if not is_semantic_sidecar_uri(uri):- raise ValueError(f"not a semantic sidecar URI: {uri}")+ raise ValueError(f"unsupported abstract overview write mode: {mode}")+ if not is_abstract_overview_uri(uri):+ raise ValueError(f"not an abstract overview URI: {uri}")- current = parse_semantic_sidecar(current_raw)- requested = parse_semantic_sidecar(requested_raw)+ current = parse_abstract_overview(current_raw)+ requested = parse_abstract_overview(requested_raw)if not requested.legacy and requested.metadata != current.metadata:- raise SemanticSidecarMetadataError("cannot modify protected semantic sidecar metadata")+ raise AbstractOverviewMetadataError("cannot modify protected abstract overview metadata")requested_body = requested.bodybody = current.body + requested_body if mode == "append" else requested_body@@ -260,13 +276,13 @@ def prepare_semantic_sidecar_write(# metadata as a side effect. Legacy sidecars have no metadata baseline,# so their first body edit naturally migrates them using the target URI.dir_uri = current.metadata.get("directory") or uri.rstrip("/").rsplit("/", 1)[0]- return render_semantic_sidecar(level, dir_uri, body, current.metadata)+ return render_abstract_overview(level, dir_uri, body, current.metadata)def body_for_preview(raw: str | bytes) -> str:- """Return only user-visible Markdown from a semantic sidecar."""+ """Return only user-visible Markdown from an abstract overview."""- document = parse_semantic_sidecar(raw)+ document = parse_abstract_overview(raw)if document.legacy:return document.body# Rendering adds one canonical terminal newline to the stored document.@@ -280,7 +296,7 @@ def body_for_embedding() -> str:"""Return body plus explicitly whitelisted stable metadata."""- document = parse_semantic_sidecar(raw)+ document = parse_abstract_overview(raw)selected = {field: document.metadata[field] for field in whitelist if field in document.metadata}@@ -298,7 +314,14 @@ def body_for_embedding(def embedding_text_for_body(level: int | ContextLevel, dir_uri: str, body: str) -> str:"""Build embedding text for a freshly generated visible body."""- return body_for_embedding(render_semantic_sidecar(level, dir_uri, body))+ return body_for_embedding(render_abstract_overview(level, dir_uri, body))+++def semantic_body_digest(body: str) -> str:+ """Hash normalized visible Markdown, excluding all OKF metadata."""++ normalized = body.replace("\r\n", "\n").replace("\r", "\n").strip()+ return hashlib.sha256(normalized.encode("utf-8")).hexdigest()def deterministic_sample(items: Sequence[_T], limit: int) -> list[_T]:@@ -333,12 +356,12 @@ def freshness_metadata(async def _read_existing_document(viking_fs: Any, uri: str, ctx: Optional[RequestContext]-) -> Optional[SemanticSidecarDocument]:+) -> Optional[AbstractOverviewDocument]:raw = await _raw_if_exists(viking_fs, uri, ctx)- return parse_semantic_sidecar(raw) if raw is not None else None+ return parse_abstract_overview(raw) if raw is not None else None-async def write_semantic_sidecars(+async def write_abstract_overview(*,viking_fs: Any,dir_uri: str,@@ -347,9 +370,10 @@ async def write_semantic_sidecars(ctx: Optional[RequestContext],is_stale: Callable[[], bool],metadata: Optional[Mapping[str, Any]] = None,+ consume_pending: Optional[int] = None,lock: Optional[Dict[str, Any]] = None,log_prefix: str = "[Semantic]",-) -> bool:+) -> AbstractOverviewWriteResult:"""Render and atomically write sidecars while preserving source metadata.Exact equality is checked under the lock so stable refreshes do not touch@@ -358,7 +382,7 @@ async def write_semantic_sidecars(if is_stale():logger.info("%s Skipping stale semantic write for %s", log_prefix, dir_uri)- return False+ return AbstractOverviewWriteResult(wrote=False)overview_uri = f"{dir_uri}/.overview.md"abstract_uri = f"{dir_uri}/.abstract.md"@@ -373,7 +397,7 @@ async def write_semantic_sidecars(try:if is_stale():logger.info("%s Skipping stale semantic write for %s", log_prefix, dir_uri)- return False+ return AbstractOverviewWriteResult(wrote=False)existing_overview = await _read_existing_document(viking_fs, overview_uri, ctx)existing_abstract = await _read_existing_document(viking_fs, abstract_uri, ctx)@@ -383,10 +407,37 @@ async def write_semantic_sidecars(merged_metadata["source"] = existing.metadata["source"]break- rendered_overview = render_semantic_sidecar(+ # A refresh consumes only the counter observed when that refresh+ # started. Changes arriving during generation remain pending.+ requested_freshness = merged_metadata.get("freshness")+ if isinstance(requested_freshness, Mapping):+ current_pending = 0+ for existing in (existing_overview, existing_abstract):+ freshness = existing.metadata.get("freshness") if existing else None+ if isinstance(freshness, Mapping):+ current_pending = max(+ current_pending, int(freshness.get("pending_child_changes", 0))+ )+ next_freshness = dict(requested_freshness)+ consumed = current_pending if consume_pending is None else max(consume_pending, 0)+ next_freshness["pending_child_changes"] = max(+ current_pending - consumed, 0+ )+ merged_metadata["freshness"] = next_freshness++ overview_body_changed = (+ existing_overview is None+ or semantic_body_digest(existing_overview.body) != semantic_body_digest(overview)+ )+ abstract_body_changed = (+ existing_abstract is None+ or semantic_body_digest(existing_abstract.body) != semantic_body_digest(abstract)+ )++ rendered_overview = render_abstract_overview(ContextLevel.OVERVIEW, dir_uri, overview, merged_metadata)- rendered_abstract = render_semantic_sidecar(+ rendered_abstract = render_abstract_overview(ContextLevel.ABSTRACT, dir_uri, abstract, merged_metadata)current_overview = await _raw_if_exists(viking_fs, overview_uri, ctx)@@ -400,7 +451,11 @@ async def write_semantic_sidecars(await viking_fs.write_file(abstract_uri, rendered_abstract, ctx=ctx, lease_ref=sidecar_lease)- return True+ return AbstractOverviewWriteResult(+ wrote=True,+ overview_body_changed=overview_body_changed,+ abstract_body_changed=abstract_body_changed,+ )finally:if owns_lease:await viking_fs._async_agfs.pathlock_release(sidecar_lease)@@ -423,52 +478,157 @@ async def _raw_if_exists(viking_fs: Any, uri: str, ctx: Optional[RequestContext]raise-async def mark_semantic_sidecars_pending(+async def plan_abstract_overview_refresh(*,viking_fs: Any,dir_uri: str,changed_entries: int,ctx: Optional[RequestContext],-) -> None:- """Increment pending changes while leaving visible sidecar bodies untouched.-- Legacy documents have no freshness baseline and are left alone until their- next natural refresh migrates them to OKF. Both sidecars are updated under- one exact-path lease so their counters remain symmetric.+ l0_body_changed: bool = True,+ force_refresh: bool = False,+ overview_sample_limit: int = 32,+ refresh_ratio: float = 0.10,+) -> FreshnessDecision:+ """Atomically record direct-child changes and choose refresh scheduling.++ Both sidecars receive the same counter snapshot under one exact-path lease.+ A missing or legacy baseline is refreshed immediately and migrated by the+ ensuing semantic task."""-- if changed_entries <= 0:- return+ # Lazy import keeps this low-level sidecar module importable by VikingFS+ # while queuefs itself imports VikingFS during package initialization.+ from openviking.storage.queuefs.semantic_ops.freshness_policy import (+ FreshnessAction,+ FreshnessDecision,+ decide_parent_refresh,+ )++ if changed_entries <= 0 or not l0_body_changed:+ return FreshnessDecision(FreshnessAction.NOOP, 0, 0)uris = [f"{dir_uri.rstrip('/')}/.overview.md",f"{dir_uri.rstrip('/')}/.abstract.md",]- preliminary = [await _raw_if_exists(viking_fs, uri, ctx) for uri in uris]- if not any(- raw is not None- and not parse_semantic_sidecar(raw).legacy- and "freshness" in parse_semantic_sidecar(raw).metadata- for raw in preliminary+ # Missing/legacy sidecars have no counter to update and must refresh now.+ # Avoid acquiring exact paths in that common migration case; if a baseline+ # appears immediately afterwards, the queued full refresh safely replaces it.+ preliminary = [await _read_existing_document(viking_fs, uri, ctx) for uri in uris]+ if not all(+ document is not None+ and not document.legacy+ and isinstance(document.metadata.get("freshness"), Mapping)+ for document in preliminary):- return-+ return decide_parent_refresh(+ l0_body_changed=True,+ has_freshness_baseline=False,+ total_entries=0,+ pending_before=0,+ current_change_count=changed_entries,+ overview_sample_limit=overview_sample_limit,+ refresh_ratio=refresh_ratio,+ force_refresh=force_refresh,+ )lock_paths = [viking_fs._uri_to_path(uri, ctx=ctx) for uri in uris]lease = await viking_fs._async_agfs.pathlock_acquire_exact_batch(lock_paths)try:- for level, uri in zip((ContextLevel.OVERVIEW, ContextLevel.ABSTRACT), uris, strict=True):- raw = await _raw_if_exists(viking_fs, uri, ctx)- if raw is None:+ documents = [await _read_existing_document(viking_fs, uri, ctx) for uri in uris]+ baselines = [+ document.metadata["freshness"]+ for document in documents+ if document is not None+ and not document.legacy+ and isinstance(document.metadata.get("freshness"), Mapping)+ ]+ if len(baselines) != len(uris):+ return decide_parent_refresh(+ l0_body_changed=True,+ has_freshness_baseline=False,+ total_entries=0,+ pending_before=0,+ current_change_count=changed_entries,+ overview_sample_limit=overview_sample_limit,+ refresh_ratio=refresh_ratio,+ force_refresh=force_refresh,+ )++ baseline = baselines[0]+ decision = decide_parent_refresh(+ l0_body_changed=True,+ has_freshness_baseline=True,+ total_entries=int(baseline["total_entries"]),+ # A mismatch should not normally exist, but preserving the larger+ # counter is safer than losing an already-observed change.+ pending_before=max(int(item["pending_child_changes"]) for item in baselines),+ current_change_count=changed_entries,+ overview_sample_limit=overview_sample_limit,+ refresh_ratio=refresh_ratio,+ force_refresh=force_refresh,+ )+ for level, uri, document in zip(+ (ContextLevel.OVERVIEW, ContextLevel.ABSTRACT), uris, documents, strict=True+ ):+ if document is None or document.legacy:continue- document = parse_semantic_sidecar(raw)freshness = document.metadata.get("freshness")- if document.legacy or not isinstance(freshness, Mapping):+ if not isinstance(freshness, Mapping):continuemetadata = dict(document.metadata)updated_freshness = dict(freshness)- updated_freshness["pending_child_changes"] += changed_entries+ updated_freshness["pending_child_changes"] = decision.pending_aftermetadata["freshness"] = updated_freshness- rendered = render_semantic_sidecar(level, dir_uri, document.body, metadata)+ rendered = render_abstract_overview(level, dir_uri, document.body, metadata)+ raw = await _raw_if_exists(viking_fs, uri, ctx)if rendered != raw:await viking_fs.write_file(uri, rendered, ctx=ctx, lease_ref=lease)+ return decisionfinally:await viking_fs._async_agfs.pathlock_release(lease)+++async def read_abstract_overview_pending_snapshot(+ *,+ viking_fs: Any,+ dir_uri: str,+ ctx: Optional[RequestContext],+ lock: Optional[Dict[str, Any]] = None,+) -> int:+ """Read the pending counter captured at the start of an aggregation."""++ uris = [+ f"{dir_uri.rstrip('/')}/.overview.md",+ f"{dir_uri.rstrip('/')}/.abstract.md",+ ]+ owns_lease = lock is None+ snapshot_lease = lock+ if owns_lease:+ lock_paths = [viking_fs._uri_to_path(uri, ctx=ctx) for uri in uris]+ snapshot_lease = await viking_fs._async_agfs.pathlock_acquire_exact_batch(lock_paths)+ try:+ pending_values = []+ for uri in uris:+ document = await _read_existing_document(viking_fs, uri, ctx)+ freshness = document.metadata.get("freshness") if document else None+ if document is not None and not document.legacy and isinstance(freshness, Mapping):+ pending_values.append(int(freshness["pending_child_changes"]))+ return max(pending_values, default=0)+ finally:+ if owns_lease:+ await viking_fs._async_agfs.pathlock_release(snapshot_lease)+++async def mark_abstract_overview_pending(+ *,+ viking_fs: Any,+ dir_uri: str,+ changed_entries: int,+ ctx: Optional[RequestContext],+) -> None:+ """Compatibility wrapper for callers that only need the metadata mark."""++ await plan_abstract_overview_refresh(+ viking_fs=viking_fs,+ dir_uri=dir_uri,+ changed_entries=changed_entries,+ ctx=ctx,+ )diff --git a/openviking/storage/content_write.py b/openviking/storage/content_write.pyindex e68082242..fb829bd2d 100644--- a/openviking/storage/content_write.py+++ b/openviking/storage/content_write.py@@ -8,6 +8,7 @@ import base64import binasciiimport osfrom collections import defaultdict+from dataclasses import dataclassfrom typing import Any, Dict, Optionalfrom openviking.core.namespace import (@@ -30,15 +31,16 @@ from openviking.session.memory.utils.resource_refs import (RESOURCE_REF_SOURCE_CONTENT_WRITE,sync_memory_resource_refs,)+from openviking.storage.abstract_overview import (+ AbstractOverviewFormatError,+ is_abstract_overview_uri,+ plan_abstract_overview_refresh,+ prepare_abstract_overview_write,+)from openviking.storage.errors import LockAcquisitionError, ResourceBusyErrorfrom openviking.storage.queuefs import SemanticMsg, get_queue_managerfrom openviking.storage.queuefs.semantic_msg import build_semantic_coalesce_key-from openviking.storage.semantic_sidecar import (- SemanticSidecarFormatError,- is_semantic_sidecar_uri,- mark_semantic_sidecars_pending,- prepare_semantic_sidecar_write,-)+from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessActionfrom openviking.storage.viking_fs import VikingFSfrom openviking.telemetry import get_current_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -55,6 +57,7 @@ from openviking_cli.exceptions import (ResourceExhaustedError,)from openviking_cli.utils import VikingURI+from openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)@@ -82,6 +85,28 @@ _BATCH_MAX_TOTAL_BYTES = 16 * 1024 * 1024_USER_MANAGED_SUBTREES = frozenset({"skills", "peers", "privacy", "sessions"})+@dataclass(frozen=True)+class _BatchRefreshOutcome:+ queue_status: Optional[Dict[str, Any]]+ semantic_actions: tuple[FreshnessAction, ...] = ()+ memory_refreshed: bool = False+ embedding_requested: bool = False++ def statuses(self, *, wait: bool) -> tuple[str, str]:+ if self.semantic_actions:+ semantic_status = (+ "deferred"+ if all(action is FreshnessAction.MARK_PENDING for action in self.semantic_actions)+ else ("complete" if wait else "queued")+ )+ else:+ semantic_status = "complete" if self.memory_refreshed else "skipped"++ vector_work = bool(self.semantic_actions) or self.embedding_requested+ vector_status = ("complete" if wait else "queued") if vector_work else "skipped"+ return semantic_status, vector_status++class ContentWriteCoordinator:"""Write a file (create or modify) and trigger downstream maintenance."""@@ -129,7 +154,7 @@ class ContentWriteCoordinator:written_bytes = len(content.encode("utf-8"))telemetry_id = get_current_telemetry().telemetry_id- if context_type == "memory" and not is_semantic_sidecar_uri(normalized_uri):+ if context_type == "memory" and not is_abstract_overview_uri(normalized_uri):return await self._write_memory_with_refresh(uri=normalized_uri,root_uri=root_uri,@@ -209,10 +234,10 @@ class ContentWriteCoordinator:if write_mode == "upsert":write_mode = "replace" if exists else "create"- if is_semantic_sidecar_uri(uri):+ if is_abstract_overview_uri(uri):if not exists:raise InvalidArgumentError(- f"cannot create generated semantic sidecar directly: {uri}"+ f"cannot create generated abstract overview directly: {uri}")if write_mode == "create" and exists:raise AlreadyExistsError(uri, "file")@@ -243,7 +268,7 @@ class ContentWriteCoordinator:breakif existed:updated.append(uri)- if is_semantic_sidecar_uri(uri):+ if is_abstract_overview_uri(uri):parent = VikingURI(uri).parentif parent is not None:sidecar_directories.add(parent.uri)@@ -259,6 +284,7 @@ class ContentWriteCoordinator:assert lock_releasedtelemetry_id = get_current_telemetry().telemetry_idrequest_registered = False+ refresh_outcome: Optional[_BatchRefreshOutcome] = Nonetry:if refresh_kinds or sidecar_directories:if wait and telemetry_id:@@ -269,7 +295,7 @@ class ContentWriteCoordinator:await self._vectorize_semantic_directory(directory_uri=directory_uri, ctx=ctx)- queue_status = (+ refresh_result = (await self._refresh_batch(refresh_kinds=refresh_kinds,ctx=ctx,@@ -284,6 +310,13 @@ class ContentWriteCoordinator:else None))+ if isinstance(refresh_result, _BatchRefreshOutcome):+ refresh_outcome = refresh_result+ queue_status = refresh_result.queue_status+ else:+ # Preserve compatibility for tests/extensions replacing+ # the private refresh hook with its historical result.+ queue_status = refresh_resultexcept Exception as exc:if write_error is not None:logger.error(@@ -316,13 +349,18 @@ class ContentWriteCoordinator:if write_error is not None:raise write_error- return {+ result = {"root_uri": normalized_root,"created": created,"updated": updated,"unchanged": unchanged,"queue_status": queue_status,}+ if refresh_outcome is not None:+ semantic_status, vector_status = refresh_outcome.statuses(wait=wait)+ result["semantic_status"] = semantic_status+ result["vector_status"] = vector_status+ return resultdef _validate_uri_path(self, uri: str, *, field_name: str) -> str:try:@@ -451,7 +489,7 @@ class ContentWriteCoordinator:wait: bool,timeout: Optional[float],telemetry_id: str,- ) -> Optional[Dict[str, Any]]:+ ) -> _BatchRefreshOutcome:resource_groups: dict[tuple[str, str], dict[str, list[str]]] = defaultdict(lambda: {"added": [], "modified": []})@@ -465,13 +503,16 @@ class ContentWriteCoordinator:refresh_root = await self._resolve_root_uri(uri, ctx=ctx, anchor_to_parent=True)resource_groups[(refresh_root, context_type)][change_type].append(uri)+ semantic_actions = []for (refresh_root, context_type), changes in sorted(resource_groups.items()):- await self._enqueue_semantic_refresh_changes(+ action = await self._enqueue_semantic_refresh_changes(root_uri=refresh_root,context_type=context_type,changes=changes,ctx=ctx,+ force_refresh=wait,)+ semantic_actions.append(action)embedding_requested = Falsefor directory_uri, uris in sorted(memory_groups.items()):@@ -493,13 +534,23 @@ class ContentWriteCoordinator:embedding_requested = embedding_requested or requestedif not wait or (not resource_groups and not embedding_requested):- return None+ return _BatchRefreshOutcome(+ queue_status=None,+ semantic_actions=tuple(semantic_actions),+ memory_refreshed=bool(memory_groups),+ embedding_requested=embedding_requested,+ )queue_status = await self._wait_for_request(telemetry_id=telemetry_id,timeout=timeout,)self._raise_refresh_errors(queue_status)- return queue_status+ return _BatchRefreshOutcome(+ queue_status=queue_status,+ semantic_actions=tuple(semantic_actions),+ memory_refreshed=bool(memory_groups),+ embedding_requested=embedding_requested,+ )async def _enqueue_semantic_refresh_changes(self,@@ -510,14 +561,23 @@ class ContentWriteCoordinator:ctx: RequestContext,target_uri: str = "",recursive: bool = False,- ) -> None:+ force_refresh: bool = False,+ ) -> FreshnessAction:changed_entries = len({uri for values in changes.values() for uri in values})- await mark_semantic_sidecars_pending(+ semantic_config = get_openviking_config().semantic+ decision = await plan_abstract_overview_refresh(viking_fs=self._viking_fs,dir_uri=root_uri,changed_entries=changed_entries,ctx=ctx,+ overview_sample_limit=getattr(semantic_config, "overview_sample_limit", 32),+ refresh_ratio=getattr(semantic_config, "freshness_refresh_ratio", 0.10),+ force_refresh=force_refresh,)+ aggregate_directory = decision.action is FreshnessAction.REFRESH_NOW+ has_live_files = any(changes.get(kind) for kind in ("added", "modified"))+ if not aggregate_directory and not has_live_files:+ return decision.actionqueue_manager = get_queue_manager()semantic_queue = queue_manager.get_queue(queue_manager.SEMANTIC, allow_create=True)telemetry = get_current_telemetry()@@ -538,7 +598,7 @@ class ContentWriteCoordinator:account_id=ctx.account_id,user_id=ctx.user.user_id,)- if context_type in {"resource", "skill"}+ if aggregate_directory and context_type in {"resource", "skill"}else ""),changes={@@ -547,6 +607,7 @@ class ContentWriteCoordinator:if changes.get(change_type)},generation_trigger="content_write",+ aggregate_directory=aggregate_directory,)if msg.telemetry_id:get_request_wait_tracker().register_semantic_root(msg.telemetry_id, msg.id)@@ -556,6 +617,7 @@ class ContentWriteCoordinator:if msg.telemetry_id:get_request_wait_tracker().mark_semantic_failed(msg.telemetry_id, msg.id, str(exc))raise+ return decision.action@staticmethoddef _raise_refresh_errors(queue_status: Dict[str, Any]) -> None:@@ -710,12 +772,13 @@ class ContentWriteCoordinator:post_process_started = Falselock_released = Falsevector_enqueued = False+ refresh_action: Optional[FreshnessAction] = Nonetry:if mode != "create":previous_content = await self._viking_fs.read_file(uri, ctx=ctx)- elif is_semantic_sidecar_uri(uri):+ elif is_abstract_overview_uri(uri):raise InvalidArgumentError(- f"cannot create generated semantic sidecar directly: {uri}"+ f"cannot create generated abstract overview directly: {uri}")if wait and telemetry_id:get_request_wait_tracker().register_request(telemetry_id)@@ -728,8 +791,8 @@ class ContentWriteCoordinator:existing_raw=previous_content,)content_written = True- if is_semantic_sidecar_uri(uri):- vector_enqueued = await self._vectorize_semantic_sidecar(uri=uri, ctx=ctx)+ if is_abstract_overview_uri(uri):+ vector_enqueued = await self._vectorize_abstract_overview(uri=uri, ctx=ctx)post_process_started = Trueelif processing_mode == VECTORS_ONLY:vector_enqueued = await self._vectorize_written_file(@@ -739,12 +802,13 @@ class ContentWriteCoordinator:)post_process_started = Trueelse:- await self._enqueue_semantic_refresh(+ refresh_action = await self._enqueue_semantic_refresh(root_uri=root_uri,changed_uri=uri,context_type=context_type,ctx=ctx,change_type="added" if mode == "create" else "modified",+ force_refresh=wait,)post_process_started = Trueawait self._viking_fs._async_agfs.pathlock_release(lease)@@ -755,7 +819,7 @@ class ContentWriteCoordinator:else None)result_kwargs = {}- if is_semantic_sidecar_uri(uri):+ if is_abstract_overview_uri(uri):_, vector_status = (self._refresh_statuses(wait=wait, queue_status=queue_status)if vector_enqueued@@ -777,6 +841,16 @@ class ContentWriteCoordinator:"semantic_status": "skipped","vector_status": vector_status,}+ elif refresh_action is FreshnessAction.MARK_PENDING:+ # Changed-file semantic/vector work may still be queued, while+ # the directory aggregation itself is intentionally deferred.+ _, vector_status = self._refresh_statuses(+ wait=wait, queue_status=queue_status+ )+ result_kwargs = {+ "semantic_status": "deferred",+ "vector_status": vector_status,+ }return self._build_write_result(uri=uri,root_uri=root_uri,@@ -845,7 +919,7 @@ class ContentWriteCoordinator:ctx=ctx,)- async def _vectorize_semantic_sidecar(self, *, uri: str, ctx: RequestContext) -> bool:+ async def _vectorize_abstract_overview(self, *, uri: str, ctx: RequestContext) -> bool:"""Re-index a manually edited L0/L1 body without regenerating it."""parent = VikingURI(uri).parent@@ -941,8 +1015,8 @@ class ContentWriteCoordinator:timeout: Optional[float],processing_mode: ProcessingMode,) -> Dict[str, Any]:- if is_semantic_sidecar_uri(uri):- raise InvalidArgumentError(f"cannot create generated semantic sidecar directly: {uri}")+ if is_abstract_overview_uri(uri):+ raise InvalidArgumentError(f"cannot create generated abstract overview directly: {uri}")self._validate_create_extension(uri)stat = await self._safe_stat(uri, ctx=ctx, allow_not_found=True)@@ -994,13 +1068,13 @@ class ContentWriteCoordinator:lease_ref: Optional[Dict[str, Any]] = None,existing_raw: Optional[str] = None,) -> None:- if is_semantic_sidecar_uri(uri):+ if is_abstract_overview_uri(uri):current_raw = (existing_rawif existing_raw is not Noneelse await self._viking_fs.read_file(uri, ctx=ctx))- rendered = self._prepare_semantic_sidecar_content(+ rendered = self._prepare_abstract_overview_content(uri=uri,current_raw=current_raw,requested_raw=content,@@ -1042,12 +1116,12 @@ class ContentWriteCoordinator:await self._viking_fs.write_file(uri, content, ctx=ctx, lease_ref=lease_ref)@staticmethod- def _prepare_semantic_sidecar_content(+ def _prepare_abstract_overview_content(*, uri: str, current_raw: str | bytes, requested_raw: str | bytes, mode: str) -> str:try:- return prepare_semantic_sidecar_write(uri, current_raw, requested_raw, mode=mode)- except SemanticSidecarFormatError as exc:+ return prepare_abstract_overview_write(uri, current_raw, requested_raw, mode=mode)+ except AbstractOverviewFormatError as exc:raise InvalidArgumentError(str(exc)) from excasync def _enqueue_semantic_refresh(@@ -1060,14 +1134,16 @@ class ContentWriteCoordinator:change_type: str = "modified",target_uri: str = "",recursive: bool = False,- ) -> None:- await self._enqueue_semantic_refresh_changes(+ force_refresh: bool = False,+ ) -> FreshnessAction:+ return await self._enqueue_semantic_refresh_changes(root_uri=root_uri,context_type=context_type,ctx=ctx,changes={change_type: [changed_uri]},target_uri=target_uri,recursive=recursive,+ force_refresh=force_refresh,)async def _wait_for_queues(self, *, timeout: Optional[float]) -> Dict[str, Any]:diff --git a/openviking/storage/ovpack/operations.py b/openviking/storage/ovpack/operations.pyindex ef9fabf53..e3e3137ea 100644--- a/openviking/storage/ovpack/operations.py+++ b/openviking/storage/ovpack/operations.py@@ -74,7 +74,7 @@ from openviking_cli.utils.uri import VikingURIlogger = get_logger(__name__)-OPTIONAL_SEMANTIC_SIDECARS = frozenset({".abstract.md", ".overview.md"})+OPTIONAL_ABSTRACT_OVERVIEW_FILES = frozenset({".abstract.md", ".overview.md"})def _index_records_by_level(@@ -144,11 +144,11 @@ def _exportable_entries(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:return exportable-def _is_optional_semantic_sidecar(entry: dict[str, Any]) -> bool:+def _is_optional_abstract_overview(entry: dict[str, Any]) -> bool:if entry.get("isDir"):return Falserel_path = str(entry.get("rel_path") or "")- return leaf_name(rel_path) in OPTIONAL_SEMANTIC_SIDECARS+ return leaf_name(rel_path) in OPTIONAL_ABSTRACT_OVERVIEW_FILESasync def _filter_existing_optional_sidecars(@@ -159,7 +159,7 @@ async def _filter_existing_optional_sidecars() -> list[dict[str, Any]]:filtered: list[dict[str, Any]] = []for entry in entries:- if not _is_optional_semantic_sidecar(entry):+ if not _is_optional_abstract_overview(entry):filtered.append(entry)continue@@ -172,7 +172,7 @@ async def _filter_existing_optional_sidecars(if exists:filtered.append(entry)else:- logger.info(f"[ovpack] Skipping missing semantic sidecar: {uri}")+ logger.info(f"[ovpack] Skipping missing abstract overview: {uri}")return filtereddiff --git a/openviking/storage/queuefs/semantic_dag.py b/openviking/storage/queuefs/semantic_dag.pyindex 2eeae9534..655143acc 100644--- a/openviking/storage/queuefs/semantic_dag.py+++ b/openviking/storage/queuefs/semantic_dag.py@@ -13,12 +13,14 @@ from weakref import WeakKeyDictionaryfrom openviking.parse.parsers.media import get_media_typefrom openviking.server.identity import RequestContextfrom openviking.service.task_work_index import bind_task_context, get_task_context-from openviking.storage.semantic_sidecar import (- SemanticSidecarFormatError,+from openviking.storage.abstract_overview import (+ AbstractOverviewFormatError,+ AbstractOverviewWriteResult,body_for_preview,deterministic_sample,freshness_metadata,- write_semantic_sidecars,+ read_abstract_overview_pending_snapshot,+ write_abstract_overview,)from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fsfrom openviking.telemetry import bind_telemetry, get_current_telemetry@@ -47,6 +49,9 @@ class DirNode:file_summaries: List[Optional[Dict[str, str]]]children_abstracts: List[Optional[Dict[str, str]]]pending: int+ pending_snapshot: int = 0+ sampled_children_dirs: Optional[Set[str]] = None+ sampled_file_paths: Optional[Set[str]] = Nonedispatched: bool = Falseoverview_scheduled: bool = Falselock: asyncio.Lock = field(default_factory=asyncio.Lock)@@ -167,6 +172,7 @@ class SemanticDagExecutor:coalesce_version: int = 0,source: Optional[Dict[str, str]] = None,generation_trigger: str = "semantic_refresh",+ aggregate_directory: bool = True,):self._processor = processorself._context_type = context_type@@ -183,6 +189,7 @@ class SemanticDagExecutor:self._coalesce_version = coalesce_versionself._source = dict(source) if source else Noneself._generation_trigger = generation_trigger+ self._aggregate_directory = aggregate_directoryself._task_context = get_task_context()self._telemetry = get_current_telemetry()self._stale = False@@ -207,6 +214,7 @@ class SemanticDagExecutor:self._dir_change_status: Dict[str, bool] = {}self._overview_cache: Dict[str, Dict[str, str]] = {}self._overview_cache_lock = asyncio.Lock()+ self._root_write_result = AbstractOverviewWriteResult(wrote=False)async def run(self, root_uri: str) -> None:"""Run DAG execution starting from root_uri."""@@ -357,12 +365,53 @@ class SemanticDagExecutor:try:children_dirs, file_paths = await self._list_dir(dir_uri, "_dispatch_dir")+ sample_limit = getattr(+ get_openviking_config().semantic,+ "overview_sample_limit",+ 32,+ )+ direct_entries = sorted(+ [("directory", uri) for uri in children_dirs]+ + [("file", uri) for uri in file_paths],+ key=lambda item: item[1].rsplit("/", 1)[-1],+ )+ sampled_entries = deterministic_sample(direct_entries, sample_limit)+ sampled_children_dirs = {+ uri for kind, uri in sampled_entries if kind == "directory"+ }+ sampled_file_paths = {uri for kind, uri in sampled_entries if kind == "file"}+ pending_snapshot = (+ await read_abstract_overview_pending_snapshot(+ viking_fs=self._viking_fs,+ dir_uri=dir_uri,+ ctx=self._ctx,+ lock=self._lock,+ )+ if self._aggregate_directory+ else 0+ )file_index = {path: idx for idx, path in enumerate(file_paths)}child_index = {path: idx for idx, path in enumerate(children_dirs)}+ # Recursive/initial work still maintains every file. Incremental+ # parent aggregation prepares only sampled inputs plus files that+ # changed and therefore need their own vector maintenance.+ required_file_paths = (+ set(file_paths)+ if self._recursive+ else (+ set(file_paths) & self._changed_paths+ if not self._aggregate_directory+ else (+ sampled_file_paths | (set(file_paths) & self._changed_paths)+ if self._incremental_update+ else sampled_file_paths+ )+ )+ )if self._recursive:- pending = len(children_dirs) + len(file_paths)+ pending = len(children_dirs) + len(required_file_paths)else:- pending = len(file_paths)+ pending = len(required_file_paths)node = DirNode(uri=dir_uri,@@ -373,6 +422,9 @@ class SemanticDagExecutor:file_summaries=[None] * len(file_paths),children_abstracts=[None] * len(children_dirs),pending=pending,+ pending_snapshot=pending_snapshot,+ sampled_children_dirs=sampled_children_dirs,+ sampled_file_paths=sampled_file_paths,dispatched=True,)self._nodes[dir_uri] = node@@ -382,6 +434,8 @@ class SemanticDagExecutor:return Falsefor file_path in file_paths:+ if file_path not in required_file_paths:+ continueself._schedule_file(dir_uri, file_path)if children_dirs:@@ -521,7 +575,7 @@ class SemanticDagExecutor:if file_name in existing_summaries:return {"name": file_name, "summary": existing_summaries[file_name]}- except SemanticSidecarFormatError:+ except AbstractOverviewFormatError:raiseexcept Exception as e:logger.debug(f"Failed to read existing summary from overview.md for {file_path}: {e}")@@ -577,7 +631,7 @@ class SemanticDagExecutor:overview = await self._viking_fs.read_file(f"{target_path}/.overview.md", ctx=self._ctx)abstract = await self._viking_fs.read_file(f"{target_path}/.abstract.md", ctx=self._ctx)return body_for_preview(overview), body_for_preview(abstract)- except SemanticSidecarFormatError:+ except AbstractOverviewFormatError:raiseexcept Exception:return None, None@@ -592,20 +646,35 @@ class SemanticDagExecutor:if self._incremental_update:content_changed = await self._check_file_content_changed(file_path)self._file_change_status[file_path] = content_changed+ node = self._nodes.get(parent_uri)+ regenerate_sampled_summary = bool(+ self._aggregate_directory+ and node is not None+ and node.pending_snapshot > 0+ and node.sampled_file_paths is not None+ and file_path in node.sampled_file_paths+ )- if not content_changed:+ if not content_changed and not regenerate_sampled_summary:summary_dict = await self._read_existing_summary(file_path)if summary_dict is not None:need_vectorize = Falseelse:self._file_change_status[file_path] = True+ elif not content_changed:+ # Pending freshness only records a count, not the changed+ # child URIs. Once that debt triggers aggregation, rebuild+ # every sampled input instead of trusting the old L1 body.+ # Deferred messages already maintained file vectors, so+ # this forced summary rebuild does not imply vector work.+ need_vectorize = Falseelse:self._file_change_status[file_path] = Trueif summary_dict is None:summary_dict = await self._processor._generate_single_file_summary(file_path, llm_sem=self._llm_sem, ctx=self._ctx)- except SemanticSidecarFormatError:+ except AbstractOverviewFormatError:# A generated sidecar that opted into OKF must never be treated as# an empty file summary; doing so would silently feed metadata or# corrupted YAML into a later regeneration.@@ -657,7 +726,9 @@ class SemanticDagExecutor:async with node.lock:idx = node.file_index.get(file_path)- if idx is not None:+ if idx is not None and (+ node.sampled_file_paths is None or file_path in node.sampled_file_paths+ ):node.file_summaries[idx] = summary_dictnode.pending -= 1if node.pending == 0 and not node.overview_scheduled:@@ -671,7 +742,9 @@ class SemanticDagExecutor:child_name = child_uri.split("/")[-1]async with node.lock:idx = node.child_index.get(child_uri)- if idx is not None:+ if idx is not None and (+ node.sampled_children_dirs is None or child_uri in node.sampled_children_dirs+ ):node.children_abstracts[idx] = {"name": child_name, "abstract": abstract}node.pending -= 1if node.pending == 0 and not node.overview_scheduled:@@ -687,6 +760,8 @@ class SemanticDagExecutor:def _finalize_file_summaries(self, node: DirNode) -> List[Dict[str, str]]:summaries: List[Dict[str, str]] = []for idx, file_path in enumerate(node.file_paths):+ if node.sampled_file_paths is not None and file_path not in node.sampled_file_paths:+ continueitem = node.file_summaries[idx]if item is None:summaries.append({"name": file_path.split("/")[-1], "summary": ""})@@ -734,6 +809,11 @@ class SemanticDagExecutor:async def _finalize_children_abstracts(self, node: DirNode) -> List[Dict[str, str]]:results: List[Dict[str, str]] = []for idx, child_uri in enumerate(node.children_dirs):+ if (+ node.sampled_children_dirs is not None+ and child_uri not in node.sampled_children_dirs+ ):+ continueitem = node.children_abstracts[idx]if item is None:try:@@ -758,7 +838,8 @@ class SemanticDagExecutor:*,total_entries: int,sampled_entries: int,- ) -> bool:+ consume_pending: int,+ ) -> AbstractOverviewWriteResult:metadata: Dict[str, Any] = {"generated_by": {"component": "SemanticProcessor",@@ -768,7 +849,7 @@ class SemanticDagExecutor:}if dir_uri == self._root_uri and self._source:metadata["source"] = self._source- wrote = await write_semantic_sidecars(+ wrote = await write_abstract_overview(viking_fs=self._viking_fs,dir_uri=dir_uri,overview=overview,@@ -776,10 +857,11 @@ class SemanticDagExecutor:ctx=self._ctx,is_stale=self._is_stale,metadata=metadata,+ consume_pending=consume_pending,lock=self._lock,log_prefix="[SemanticDag]",)- if not wrote:+ if not wrote.wrote:self._stale = Truereturn wrote@@ -787,6 +869,15 @@ class SemanticDagExecutor:node = self._nodes.get(dir_uri)if not node:return+ if not self._aggregate_directory:+ # Deferred aggregation still ran changed-file work. Finish without+ # touching directory sidecars or their vectors.+ self._stats.done_nodes += 1+ self._stats.in_progress_nodes = max(0, self._stats.in_progress_nodes - 1)+ self._release_dir_node(dir_uri)+ if dir_uri == self._root_uri and self._root_done:+ self._root_done.set()+ returnneed_vectorize = Truechildren_changed = Trueshould_write = True@@ -811,24 +902,18 @@ class SemanticDagExecutor:# entries whose summaries failed. Those entries remain visible# as unsampled coverage instead of disappearing from the count.total_entries = len(node.file_paths) + len(node.children_dirs)- sample_limit = getattr(- get_openviking_config().semantic,- "sidecar_sample_size",- 32,- )- tagged_inputs = sorted(- [("file", item) for item in file_summaries]- + [("directory", item) for item in children_abstracts],- key=lambda tagged: str(tagged[1].get("name") or ""),- )- sampled_inputs = deterministic_sample(tagged_inputs, sample_limit)- file_summaries = [item for kind, item in sampled_inputs if kind == "file"]- children_abstracts = [item for kind, item in sampled_inputs if kind == "directory"]+ # Sampling happened in _dispatch_dir, before summary work was+ # scheduled. Only the prepared bounded inputs reach the prompt.+ sampled_entries = len(file_summaries) + len(children_abstracts)overview = self._select_direct_media_overview(node, file_summaries)if overview is None:async with self._llm_sem:overview = await self._processor._generate_overview(- dir_uri, file_summaries, children_abstracts+ dir_uri,+ file_summaries,+ children_abstracts,+ total_files=len(node.file_paths),+ total_children=len(node.children_dirs),)overview, abstract = self._processor._normalize_overview_generation(overview)@@ -843,16 +928,19 @@ class SemanticDagExecutor:overview,abstract,total_entries=total_entries,- sampled_entries=len(sampled_inputs),+ sampled_entries=sampled_entries,+ consume_pending=node.pending_snapshot,)- if not wrote:+ if dir_uri == self._root_uri:+ self._root_write_result = wrote+ if not wrote.wrote:need_vectorize = False- except SemanticSidecarFormatError:+ except AbstractOverviewFormatError:raiseexcept Exception:logger.info(f"[SemanticDag] {dir_uri} write failed, skipping")- except SemanticSidecarFormatError:+ except AbstractOverviewFormatError:raiseexcept Exception as e:logger.error(f"Failed to generate overview for {dir_uri}: {e}", exc_info=True)@@ -899,6 +987,12 @@ class SemanticDagExecutor:done_nodes=self._stats.done_nodes,)+ @property+ def root_write_result(self) -> AbstractOverviewWriteResult:+ """Visible-body changes produced for the executor root."""++ return self._root_write_result+if False: # pragma: no cover - for type checkers onlyfrom openviking.storage.queuefs.semantic_processor import SemanticProcessordiff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.pyindex 8c87f80a0..1199d6596 100644--- a/openviking/storage/queuefs/semantic_msg.py+++ b/openviking/storage/queuefs/semantic_msg.py@@ -36,6 +36,11 @@ class SemanticMsg:When True, the processor will collect all subdirectory info andenqueue them for processing (bottom-up order).When False, only the specified directory will be processed.+ use_hierarchical_aggregation: Route memory directories through the+ shared directory DAG instead of the specialized flat memory+ update path.+ propagate_to_parent: Whether a completed directory refresh may enqueue+ a freshness refresh for its parent."""id: str # UUID@@ -63,6 +68,9 @@ class SemanticMsg:)source: Optional[Dict[str, str]] = Nonegeneration_trigger: str = "semantic_refresh"+ aggregate_directory: bool = True+ use_hierarchical_aggregation: bool = False+ propagate_to_parent: bool = Truedef __init__(self,@@ -85,6 +93,9 @@ class SemanticMsg:changes: Optional[Dict[str, List[str]]] = None,source: Optional[Dict[str, str]] = None,generation_trigger: str = "semantic_refresh",+ aggregate_directory: bool = True,+ use_hierarchical_aggregation: bool = False,+ propagate_to_parent: bool = True,):self.id = str(uuid4())self.uri = uri@@ -106,6 +117,9 @@ class SemanticMsg:self.changes = changesself.source = dict(source) if source else Noneself.generation_trigger = generation_trigger+ self.aggregate_directory = bool(aggregate_directory)+ self.use_hierarchical_aggregation = bool(use_hierarchical_aggregation)+ self.propagate_to_parent = bool(propagate_to_parent)def to_dict(self) -> Dict[str, Any]:"""Convert object to dictionary."""@@ -160,6 +174,9 @@ class SemanticMsg:changes=data.get("changes"),source=data.get("source"),generation_trigger=data.get("generation_trigger", "semantic_refresh"),+ aggregate_directory=data.get("aggregate_directory", True),+ use_hierarchical_aggregation=data.get("use_hierarchical_aggregation", False),+ propagate_to_parent=data.get("propagate_to_parent", True),)if "id" in data and data["id"]:obj.id = data["id"]diff --git a/openviking/storage/queuefs/semantic_ops/__init__.py b/openviking/storage/queuefs/semantic_ops/__init__.pynew file mode 100644index 000000000..f221d1ec9--- /dev/null+++ b/openviking/storage/queuefs/semantic_ops/__init__.py@@ -0,0 +1 @@+"""Pure operators used by semantic queue orchestration."""diff --git a/openviking/storage/queuefs/semantic_ops/freshness_policy.py b/openviking/storage/queuefs/semantic_ops/freshness_policy.pynew file mode 100644index 000000000..728dfff04--- /dev/null+++ b/openviking/storage/queuefs/semantic_ops/freshness_policy.py@@ -0,0 +1,62 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Pure policy for freshness-aware directory summary refreshes."""++from __future__ import annotations++from dataclasses import dataclass+from enum import Enum+++class FreshnessAction(str, Enum):+ """Scheduling result for one direct-child semantic change."""++ NOOP = "noop"+ MARK_PENDING = "mark_pending"+ REFRESH_NOW = "refresh_now"+++@dataclass(frozen=True)+class FreshnessDecision:+ """Policy output plus the counter snapshot used to reach it."""++ action: FreshnessAction+ pending_after: int+ total_entries: int+++def decide_parent_refresh(+ *,+ l0_body_changed: bool,+ has_freshness_baseline: bool,+ total_entries: int,+ pending_before: int,+ current_change_count: int,+ overview_sample_limit: int,+ refresh_ratio: float,+ force_refresh: bool = False,+) -> FreshnessDecision:+ """Decide whether a parent aggregation should run.++ ``pending_child_changes`` intentionally counts events rather than unique+ children. For wide directories the equivalent integer threshold is+ ``ceil(refresh_ratio * total_entries)``; comparing the ratio directly+ avoids carrying another derived configuration value.+ """++ if not l0_body_changed or current_change_count <= 0:+ return FreshnessDecision(FreshnessAction.NOOP, pending_before, total_entries)++ pending_after = pending_before + current_change_count+ if not has_freshness_baseline:+ return FreshnessDecision(FreshnessAction.REFRESH_NOW, pending_after, total_entries)+ if force_refresh or total_entries <= overview_sample_limit:+ return FreshnessDecision(FreshnessAction.REFRESH_NOW, pending_after, total_entries)++ change_ratio = pending_after / max(total_entries, 1)+ action = (+ FreshnessAction.REFRESH_NOW+ if change_ratio >= refresh_ratio+ else FreshnessAction.MARK_PENDING+ )+ return FreshnessDecision(action, pending_after, total_entries)diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.pyindex 6f98ea3ec..d6748272d 100644--- a/openviking/storage/queuefs/semantic_processor.py+++ b/openviking/storage/queuefs/semantic_processor.py@@ -33,20 +33,22 @@ from openviking.parse.parsers.media.utils import (from openviking.prompts import render_promptfrom openviking.server.identity import RequestContext, Rolefrom openviking.service.task_work_index import detach_task_context+from openviking.storage.abstract_overview import (+ AbstractOverviewFormatError,+ AbstractOverviewWriteResult,+ body_for_preview,+ deterministic_sample,+ freshness_metadata,+ plan_abstract_overview_refresh,+ write_abstract_overview,+)from openviking.storage.errors import LockAcquisitionErrorfrom openviking.storage.queuefs.named_queue import DequeueHandlerBasefrom openviking.storage.queuefs.semantic_dag import DagStats, SemanticDagExecutorfrom openviking.storage.queuefs.semantic_lock import SemanticLockScopefrom openviking.storage.queuefs.semantic_msg import SemanticMsg, build_semantic_coalesce_key+from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessActionfrom openviking.storage.queuefs.semantic_queue import is_semantic_msg_stale-from openviking.storage.semantic_sidecar import (- SemanticSidecarFormatError,- body_for_preview,- deterministic_sample,- freshness_metadata,- mark_semantic_sidecars_pending,- write_semantic_sidecars,-)from openviking.storage.viking_fs import LS_ALL_NODES, SyncDiff, get_viking_fsfrom openviking.telemetry import bind_telemetry, bind_telemetry_stage, resolve_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -240,9 +242,13 @@ class SemanticProcessor(DequeueHandlerBase):returnself.report_success()- async def _enqueue_parent_refresh(self, msg: SemanticMsg, uri: str) -> None:+ async def _enqueue_parent_refresh(+ self, msg: SemanticMsg, uri: str, *, l0_body_changed: bool+ ) -> None:if msg.context_type not in {"resource", "skill"}:return+ if not msg.propagate_to_parent:+ returnparent = VikingURI(uri).parentif parent is None:return@@ -253,12 +259,29 @@ class SemanticProcessor(DequeueHandlerBase):or parent_uri == uri.rstrip("/")):return- await mark_semantic_sidecars_pending(+ semantic_config = get_openviking_config().semantic+ decision = await plan_abstract_overview_refresh(viking_fs=get_viking_fs(),dir_uri=parent_uri,changed_entries=1,ctx=self._ctx_from_semantic_msg(msg),+ l0_body_changed=l0_body_changed,+ # This helper handles automatic upward propagation only. Manual+ # refresh/ingest bypasses the threshold for its requested root,+ # not for every ancestor reached afterwards.+ force_refresh=False,+ overview_sample_limit=getattr(semantic_config, "overview_sample_limit", 32),+ refresh_ratio=getattr(semantic_config, "freshness_refresh_ratio", 0.10),)+ if decision.action is not FreshnessAction.REFRESH_NOW:+ logger.debug(+ "Parent semantic refresh %s for %s (pending=%d, total=%d)",+ decision.action.value,+ parent_uri,+ decision.pending_after,+ decision.total_entries,+ )+ returnfrom openviking.storage.queuefs import get_queue_manager@@ -315,15 +338,35 @@ class SemanticProcessor(DequeueHandlerBase):self.report_success()return Noneif is_semantic_msg_stale(msg):- logger.info(- "Skipping stale semantic message: uri=%s version=%s",- msg.uri,- msg.coalesce_version,- )- if msg.telemetry_id and msg.id:- get_request_wait_tracker().mark_semantic_done(msg.telemetry_id, msg.id)- self.report_success()- return None+ live_file_changes = {+ kind: list(msg.changes.get(kind, []))+ for kind in ("added", "modified")+ if msg.changes and msg.changes.get(kind)+ }+ if msg.generation_trigger == "content_write" and live_file_changes:+ # Coalescing replaces directory aggregation, not per-file+ # maintenance. Let the newest message aggregate while this+ # one still summarizes/vectorizes its changed files.+ logger.info(+ "Downgrading stale semantic message to file-only work: "+ "uri=%s version=%s",+ msg.uri,+ msg.coalesce_version,+ )+ msg.aggregate_directory = False+ msg.changes = live_file_changes+ msg.coalesce_key = ""+ msg.coalesce_version = 0+ else:+ logger.info(+ "Skipping stale semantic message: uri=%s version=%s",+ msg.uri,+ msg.coalesce_version,+ )+ if msg.telemetry_id and msg.id:+ get_request_wait_tracker().mark_semantic_done(msg.telemetry_id, msg.id)+ self.report_success()+ return None# Circuit breaker: if API is known-broken, re-enqueue and waittry:self._circuit_breaker.check()@@ -365,7 +408,10 @@ class SemanticProcessor(DequeueHandlerBase):),)try:- if msg.context_type == "memory":+ # Regular memory writes keep their specialized update path.+ # Callers must explicitly opt into directory aggregation; the+ # trigger remains descriptive metadata, not an algorithm switch.+ if msg.context_type == "memory" and not msg.use_hierarchical_aggregation:await self._process_memory_directory(msg,ctx=current_ctx,@@ -433,6 +479,7 @@ class SemanticProcessor(DequeueHandlerBase):coalesce_version=msg.coalesce_version,source=msg.source,generation_trigger=msg.generation_trigger,+ aggregate_directory=msg.aggregate_directory,)await executor.run(run_uri)self._cache_dag_stats(@@ -440,8 +487,19 @@ class SemanticProcessor(DequeueHandlerBase):run_uri,executor.get_stats(),)- if not executor.stale:- await self._enqueue_parent_refresh(msg, target_uri or msg.uri)+ if not executor.stale and msg.aggregate_directory:+ write_result = getattr(+ executor,+ "root_write_result",+ AbstractOverviewWriteResult(+ wrote=True, abstract_body_changed=True+ ),+ )+ await self._enqueue_parent_refresh(+ msg,+ target_uri or msg.uri,+ l0_body_changed=write_result.abstract_body_changed,+ )finally:await semantic_lock.close()get_request_wait_tracker().mark_semantic_done(msg.telemetry_id, msg.id)@@ -582,7 +640,7 @@ class SemanticProcessor(DequeueHandlerBase):logger.info(f"Parsed {len(existing_summaries)} existing summaries from overview.md")- except SemanticSidecarFormatError:+ except AbstractOverviewFormatError:raiseexcept Exception as e:logger.debug(f"No existing overview.md found for {dir_uri}: {e}")@@ -674,12 +732,16 @@ class SemanticProcessor(DequeueHandlerBase):completed_summaries = [s for s in file_summaries if s is not None]sample_limit = getattr(get_openviking_config().semantic,- "sidecar_sample_size",+ "overview_sample_limit",32,)sampled_summaries = deterministic_sample(completed_summaries, sample_limit)generated_content = await self._generate_overview(- dir_uri, sampled_summaries, [], llm_sem=llm_sem+ dir_uri,+ sampled_summaries,+ [],+ llm_sem=llm_sem,+ total_files=len(file_paths),)overview, abstract = self._normalize_overview_generation(generated_content)@@ -697,13 +759,22 @@ class SemanticProcessor(DequeueHandlerBase):)except Exception as e:raise RuntimeError(f"Failed to write abstract/overview for {dir_uri}: {e}") from e- if not wrote_semantics:+ if not wrote_semantics.wrote:returnlogger.info(f"Generated abstract.md and overview.md for {dir_uri}")if msg.skip_vectorization:logger.info(f"Skipping vectorization for {dir_uri} (requested via SemanticMsg)")return+ if not (+ wrote_semantics.overview_body_changed+ or wrote_semantics.abstract_body_changed+ ):+ logger.info(+ "Skipping directory vectorization for %s (visible semantics unchanged)",+ dir_uri,+ )+ returnawait self._vectorize_directory(uri=dir_uri,context_type="memory",@@ -725,8 +796,8 @@ class SemanticProcessor(DequeueHandlerBase):lock: Optional[Dict[str, Any]] = None,total_entries: int = 0,sampled_entries: int = 0,- ) -> bool:- return await write_semantic_sidecars(+ ) -> AbstractOverviewWriteResult:+ return await write_abstract_overview(viking_fs=viking_fs,dir_uri=dir_uri,overview=overview,@@ -1127,6 +1198,8 @@ class SemanticProcessor(DequeueHandlerBase):file_summaries: List[Dict[str, str]],children_abstracts: List[Dict[str, str]],llm_sem: Optional[asyncio.Semaphore] = None,+ total_files: Optional[int] = None,+ total_children: Optional[int] = None,) -> str:"""Generate raw directory overview model output.@@ -1137,8 +1210,13 @@ class SemanticProcessor(DequeueHandlerBase):Args:dir_uri: Directory URI- file_summaries: File summary list- children_abstracts: Subdirectory summary list+ file_summaries: File summary list (only entries participating in+ this aggregation, i.e. already sampled when applicable)+ children_abstracts: Subdirectory summary list (sampled when applicable)+ total_files: Total direct files in the directory (may exceed+ ``len(file_summaries)`` when the directory was sampled)+ total_children: Total direct subdirectories (may exceed+ ``len(children_abstracts)`` when sampled)Returns:Markdown overview content generated by the model.@@ -1154,6 +1232,27 @@ class SemanticProcessor(DequeueHandlerBase):from openviking.session.memory.utils.language import resolve_output_language+ # Build coverage statement so the model knows the directory scale+ # and whether the provided summaries represent all entries or a sample.+ total_files = len(file_summaries) if total_files is None else total_files+ total_children = len(children_abstracts) if total_children is None else total_children+ total_direct = total_files + total_children+ provided = len(file_summaries) + len(children_abstracts)+ if total_direct <= provided:+ directory_coverage = (+ f"Total direct entries: {total_direct}. "+ "All direct entries are represented in the summaries below."+ )+ else:+ directory_coverage = (+ f"Total direct entries: {total_direct} "+ f"({total_files} files, {total_children} subdirectories).\n"+ f"Summaries provided for this aggregation: {provided}.\n"+ f"Direct entries not individually shown: {total_direct - provided}.\n"+ "Coverage: sampled. The summaries below are representative "+ "entries; generalize cautiously and do not treat them as exhaustive."+ )+# Build file index mapping and summary stringfile_index_map = {}file_summaries_lines = []@@ -1199,6 +1298,7 @@ class SemanticProcessor(DequeueHandlerBase):file_index_map,llm_sem=llm_sem,output_language=output_language,+ directory_coverage=directory_coverage,)elif over_budget:# Few files but long summaries → truncate summaries to fit budget@@ -1221,6 +1321,7 @@ class SemanticProcessor(DequeueHandlerBase):children_abstracts_str,file_index_map,output_language=output_language,+ directory_coverage=directory_coverage,)else:overview = await self._single_generate_overview(@@ -1229,6 +1330,7 @@ class SemanticProcessor(DequeueHandlerBase):children_abstracts_str,file_index_map,output_language=output_language,+ directory_coverage=directory_coverage,)return overview@@ -1240,6 +1342,7 @@ class SemanticProcessor(DequeueHandlerBase):children_abstracts_str: str,file_index_map: Dict[int, str],output_language: str = "en",+ directory_coverage: str = "",) -> str:"""Generate overview from a single prompt (small directories)."""config = get_openviking_config()@@ -1253,6 +1356,7 @@ class SemanticProcessor(DequeueHandlerBase):"file_summaries": file_summaries_str,"children_abstracts": children_abstracts_str,"output_language": output_language,+ "directory_coverage": directory_coverage,},)@@ -1278,6 +1382,7 @@ class SemanticProcessor(DequeueHandlerBase):file_index_map: Dict[int, str],llm_sem: Optional[asyncio.Semaphore] = None,output_language: str = "en",+ directory_coverage: str = "",) -> str:"""Generate overview by batching file and subdirectory summaries.@@ -1321,6 +1426,7 @@ class SemanticProcessor(DequeueHandlerBase):"file_summaries": "\n".join(batch_lines) or "None","children_abstracts": "\n".join(child_lines) or "None","output_language": output_language,+ "directory_coverage": directory_coverage,},)batch_prompts.append((batch_idx, prompt, batch_index_map))@@ -1358,6 +1464,7 @@ class SemanticProcessor(DequeueHandlerBase):"file_summaries": combined,"children_abstracts": "None","output_language": output_language,+ "directory_coverage": directory_coverage,},)with bind_telemetry_stage("resource_summarize"):diff --git a/openviking/storage/viking_fs/_semantic.py b/openviking/storage/viking_fs/_semantic.pyindex f89cf0300..4b7999696 100644--- a/openviking/storage/viking_fs/_semantic.py+++ b/openviking/storage/viking_fs/_semantic.py@@ -3,13 +3,13 @@"""Semantic retrieval mixin for VikingFS."""import asyncio-from typing import Any, Dict, List, Optional, Union+from typing import Dict, List, Optional, Unionfrom openviking.core.context import ContextLevelfrom openviking.core.retrieval_targets import resolve_retrieval_targetsfrom openviking.server.error_mapping import is_not_found_error, map_exceptionfrom openviking.server.identity import RequestContext-from openviking.storage.semantic_sidecar import body_for_preview, render_semantic_sidecar+from openviking.storage.abstract_overview import body_for_preview, render_abstract_overviewfrom openviking.storage.viking_fs._base import (_ensure_non_empty_search_query,logger,@@ -454,7 +454,7 @@ class _SemanticMixin:abstract_uri = f"{uri}/.abstract.md"await self.write_file(abstract_uri,- render_semantic_sidecar(+ render_abstract_overview(ContextLevel.ABSTRACT,uri,abstract,@@ -472,7 +472,7 @@ class _SemanticMixin:overview_uri = f"{uri}/.overview.md"await self.write_file(overview_uri,- render_semantic_sidecar(+ render_abstract_overview(ContextLevel.OVERVIEW,uri,overview,diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.pyindex 25e710396..bc6a3fdb0 100644--- a/openviking/utils/embedding_utils.py+++ b/openviking/utils/embedding_utils.py@@ -26,9 +26,9 @@ from openviking.parse.parsers.media.utils import (from openviking.parse.parsers.upload_utils import is_text_filefrom openviking.server.identity import RequestContextfrom openviking.service.task_work_index import TaskWorkRejected+from openviking.storage.abstract_overview import body_for_preview, embedding_text_for_bodyfrom openviking.storage.queuefs import get_queue_managerfrom openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter-from openviking.storage.semantic_sidecar import body_for_preview, embedding_text_for_bodyfrom openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fsfrom openviking.telemetry.request_wait_tracker import get_request_wait_trackerfrom openviking.utils.embedding_input import truncate_embedding_inputdiff --git a/openviking_cli/utils/config/parser_config.py b/openviking_cli/utils/config/parser_config.pyindex 1eec73c1e..abcdce746 100644--- a/openviking_cli/utils/config/parser_config.py+++ b/openviking_cli/utils/config/parser_config.py@@ -750,9 +750,12 @@ class SemanticConfig:overview_batch_size: int = 50"""Maximum number of file summaries per batch when splitting oversized prompts."""- sidecar_sample_size: int = 32+ overview_sample_limit: int = 32"""Maximum direct-child summaries used in one generated directory sidecar."""+ freshness_refresh_ratio: float = 0.10+ """Pending direct-child change ratio that refreshes a wide directory."""+abstract_max_chars: int = 256"""Maximum characters for generated abstracts."""@@ -767,8 +770,10 @@ class SemanticConfig:"""Character overlap between adjacent memory chunks for context continuity."""def __post_init__(self):- if self.sidecar_sample_size <= 0:- raise ValueError("sidecar_sample_size must be positive")+ if self.overview_sample_limit <= 0:+ raise ValueError("overview_sample_limit must be positive")+ if not 0 < self.freshness_refresh_ratio <= 1:+ raise ValueError("freshness_refresh_ratio must be in the range (0, 1]")if self.memory_chunk_chars <= 0:raise ValueError("memory_chunk_chars must be positive")if self.memory_chunk_overlap < 0:diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.pyindex afe8fac45..6029aa60d 100644--- a/sdk/python/openviking_sdk/client.py+++ b/sdk/python/openviking_sdk/client.py@@ -1617,10 +1617,18 @@ class AsyncHTTPClient:mode: str = "vectors_only",wait: bool = True,dry_run: bool = False,+ recursive: bool = True,tags: Optional[List[str]] = None,tag_mode: str = "replace",) -> Dict[str, Any]:- payload = {"uri": uri, "mode": mode, "wait": wait, "dry_run": dry_run}+ payload = {+ "uri": uri,+ "mode": mode,+ "wait": wait,+ "dry_run": dry_run,+ }+ if not recursive:+ payload["recursive"] = Falseif tags is not None:payload["tags"] = tagspayload["tag_mode"] = tag_mode@@ -2568,6 +2576,7 @@ class SyncHTTPClient:mode: str = "vectors_only",wait: bool = True,dry_run: bool = False,+ recursive: bool = True,tags: Optional[List[str]] = None,tag_mode: str = "replace",) -> Dict[str, Any]:@@ -2577,6 +2586,8 @@ class SyncHTTPClient:"wait": wait,"dry_run": dry_run,}+ if not recursive:+ kwargs["recursive"] = Falseif tags is not None:kwargs["tags"] = tagskwargs["tag_mode"] = tag_modediff --git a/tests/client/test_rebuild_clients.py b/tests/client/test_rebuild_clients.pyindex 66141798c..77b76cfaf 100644--- a/tests/client/test_rebuild_clients.py+++ b/tests/client/test_rebuild_clients.py@@ -176,6 +176,55 @@ def test_sync_http_client_reindex_forwards_to_async_client():)+async def test_async_http_client_reindex_sends_non_recursive_flag():+ client = AsyncHTTPClient(url="http://localhost:1933")+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))+ client._http = fake_http+ with patch.object(client, "_handle_response", return_value={"status": "completed"}):+ await client.reindex(+ "viking://resources/demo",+ mode="semantic_and_vectors",+ recursive=False,+ )++ fake_http.post.assert_awaited_once_with(+ "/api/v1/content/reindex",+ json={+ "uri": "viking://resources/demo",+ "mode": "semantic_and_vectors",+ "wait": True,+ "dry_run": False,+ "recursive": False,+ },+ )+++def test_sync_http_client_reindex_forwards_non_recursive_flag():+ client = SyncHTTPClient(url="http://localhost:1933")+ with patch.object(+ client._async_client,+ "reindex",+ new_callable=Mock,+ return_value={"status": "completed"},+ ) as mock_reindex:+ with patch(+ "openviking_sdk.client.run_async", return_value={"status": "completed"}+ ):+ client.reindex(+ "viking://resources/demo",+ mode="semantic_and_vectors",+ recursive=False,+ )++ mock_reindex.assert_called_once_with(+ uri="viking://resources/demo",+ mode="semantic_and_vectors",+ wait=True,+ dry_run=False,+ recursive=False,+ )++def test_sync_http_client_batch_add_messages_forwards_to_async_client():client = SyncHTTPClient(url="http://localhost:1933")messages = [diff --git a/tests/misc/test_ovpack_import_policy.py b/tests/misc/test_ovpack_import_policy.pyindex 23d58071e..b82fb291a 100644--- a/tests/misc/test_ovpack_import_policy.py+++ b/tests/misc/test_ovpack_import_policy.py@@ -539,7 +539,7 @@ def test_index_consistency_report_limits_public_and_error_records():@pytest.mark.asyncio-async def test_export_ovpack_writes_v3_manifest_with_semantic_sidecars(+async def test_export_ovpack_writes_v3_manifest_with_abstract_overviews(temp_ovpack_path: Path, request_ctx: RequestContext):await export_ovpack(@@ -580,7 +580,7 @@ async def test_export_ovpack_writes_v3_manifest_with_semantic_sidecars(@pytest.mark.asyncio-async def test_export_ovpack_skips_missing_semantic_sidecars(+async def test_export_ovpack_skips_missing_abstract_overviews(temp_ovpack_path: Path,request_ctx: RequestContext,):@@ -672,7 +672,7 @@ async def test_backup_restore_contract(@pytest.mark.asyncio-async def test_backup_skips_missing_semantic_sidecars(+async def test_backup_skips_missing_abstract_overviews(temp_ovpack_path: Path,request_ctx: RequestContext,):diff --git a/tests/misc/test_semantic_config.py b/tests/misc/test_semantic_config.pyindex 6b47450ac..78e36a9b3 100644--- a/tests/misc/test_semantic_config.py+++ b/tests/misc/test_semantic_config.py@@ -14,13 +14,20 @@ def test_semantic_config_defaults():assert config.max_file_content_chars == 30000assert config.max_overview_prompt_chars == 60000assert config.overview_batch_size == 50- assert config.sidecar_sample_size == 32+ assert config.overview_sample_limit == 32+ assert config.freshness_refresh_ratio == 0.10assert config.abstract_max_chars == 256assert config.overview_max_chars == 4000assert config.memory_chunk_chars == 2000assert config.memory_chunk_overlap == 200[email protected]("ratio", [0, -0.1, 1.1])+def test_freshness_refresh_ratio_must_be_a_probability(ratio):+ with pytest.raises(ValueError, match="freshness_refresh_ratio"):+ SemanticConfig(freshness_refresh_ratio=ratio)++def test_semantic_config_custom_values():"""Test custom values override defaults."""config = SemanticConfig(diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.pyindex d06dc52f7..5d695b19a 100644--- a/tests/retrieve/test_hierarchical_retriever_rerank.py+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py@@ -12,7 +12,7 @@ import pytestfrom openviking.core.context import ContextLevelfrom openviking.retrieve.hierarchical_retriever import HierarchicalRetriever, RetrieverModefrom openviking.server.identity import RequestContext, Role-from openviking.storage.semantic_sidecar import render_semantic_sidecar+from openviking.storage.abstract_overview import render_abstract_overviewfrom openviking.utils.token_estimation import estimate_text_tokensfrom openviking_cli.retrieve.types import ContextType, TypedQueryfrom openviking_cli.session.user_id import UserIdentifier@@ -668,7 +668,7 @@ async def test_convert_to_matched_contexts_defaults_tags_and_body_previews():uri,1.0,level=int(ContextLevel.ABSTRACT),- abstract=render_semantic_sidecar(+ abstract=render_abstract_overview(ContextLevel.ABSTRACT, uri, "Visible abstract.", metadata),),@@ -676,7 +676,7 @@ async def test_convert_to_matched_contexts_defaults_tags_and_body_previews():uri,0.9,level=int(ContextLevel.OVERVIEW),- abstract=render_semantic_sidecar(+ abstract=render_abstract_overview(ContextLevel.OVERVIEW, uri, "# Visible overview", metadata),),diff --git a/tests/server/test_admin_rebuild_api.py b/tests/server/test_admin_rebuild_api.pyindex 9a9b1cc4f..ca7557bfa 100644--- a/tests/server/test_admin_rebuild_api.py+++ b/tests/server/test_admin_rebuild_api.py@@ -255,6 +255,35 @@ async def test_reindex_resource_vectors_only_wait_false(monkeypatch):assert "reason" not in response.result+async def test_reindex_passes_non_recursive_to_service(monkeypatch):+ from openviking.server.routers.content import ReindexRequest, reindex++ seen = {}++ class FakeService:+ async def reindex(self, **kwargs):+ seen.update(kwargs)+ return {"status": "completed"}++ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ monkeypatch.setattr("openviking.server.routers.content.get_service", lambda: FakeService())++ await reindex(+ body=ReindexRequest(+ uri="viking://resources/demo",+ mode="semantic_and_vectors",+ recursive=False,+ ),+ ctx=ctx,+ )++ assert seen["recursive"] is False++@pytest.mark.asyncioasync def test_reindex_prune_orphans_passes_dry_run_to_service(monkeypatch):from openviking.server.routers.content import ReindexRequest, reindex@@ -1391,6 +1420,170 @@ async def test_reindex_memory_semantic_and_vectors_rebuilds_full_subtree(monkeypassert seen["vectors"] == ["viking://user/default/memories"]+async def test_reindex_resource_non_recursive_limits_semantics_and_vectors(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor, _ReindexCounters++ seen = {}++ async def fake_run_semantic_processor(self, **kwargs):+ seen["semantic"] = kwargs++ async def fake_reindex_resource_vectors(self, **kwargs):+ seen["vectors"] = kwargs++ monkeypatch.setattr(ReindexExecutor, "_run_semantic_processor", fake_run_semantic_processor)+ monkeypatch.setattr(ReindexExecutor, "_reindex_resource_vectors", fake_reindex_resource_vectors)++ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ await ReindexExecutor()._reindex_resource(+ uri="viking://resources/demo",+ mode="semantic_and_vectors",+ recursive=False,+ run=_make_reindex_run(ctx, _ReindexCounters()),+ )++ assert seen["semantic"]["recursive"] is False+ assert seen["vectors"]["recursive"] is False+++async def test_reindex_memory_non_recursive_limits_semantics_and_vectors(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor, _ReindexCounters++ seen = {}++ async def fake_run_semantic_processor(self, **kwargs):+ seen["semantic"] = kwargs++ async def fake_reindex_memory_vectors(self, **kwargs):+ seen["vectors"] = kwargs++ class FakeVikingFS:+ async def stat(self, uri, ctx=None):+ return {"isDir": True}++ monkeypatch.setattr(ReindexExecutor, "_run_semantic_processor", fake_run_semantic_processor)+ monkeypatch.setattr(ReindexExecutor, "_reindex_memory_vectors", fake_reindex_memory_vectors)+ monkeypatch.setattr("openviking.service.reindex_executor.get_viking_fs", lambda: FakeVikingFS())++ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ await ReindexExecutor()._reindex_memory(+ uri="viking://user/alice/memories/preferences",+ mode="semantic_and_vectors",+ recursive=False,+ run=_make_reindex_run(ctx, _ReindexCounters()),+ )++ assert seen["semantic"]["recursive"] is False+ assert seen["vectors"]["recursive"] is False+++async def test_reindex_skill_non_recursive_limits_vectors_to_directory(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor, _ReindexCounters++ seen = {}++ async def fake_regenerate_skill_semantics(self, **kwargs):+ seen["semantic"] = kwargs++ async def fake_reindex_skill_vectors(self, **kwargs):+ seen["vectors"] = kwargs++ monkeypatch.setattr(+ ReindexExecutor, "_regenerate_skill_semantics", fake_regenerate_skill_semantics+ )+ monkeypatch.setattr(ReindexExecutor, "_reindex_skill_vectors", fake_reindex_skill_vectors)++ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ await ReindexExecutor()._reindex_skill(+ uri="viking://user/alice/skills/demo",+ mode="semantic_and_vectors",+ recursive=False,+ run=_make_reindex_run(ctx, _ReindexCounters()),+ )++ assert seen["semantic"]["uri"] == "viking://user/alice/skills/demo"+ assert seen["vectors"]["recursive"] is False+++async def test_reindex_skill_vectors_only_ignores_non_recursive_flag(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor, _ReindexCounters++ seen = {}++ async def fake_reindex_skill_vectors(self, **kwargs):+ seen.update(kwargs)++ monkeypatch.setattr(ReindexExecutor, "_reindex_skill_vectors", fake_reindex_skill_vectors)++ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ await ReindexExecutor()._reindex_skill(+ uri="viking://user/alice/skills/demo",+ mode="vectors_only",+ recursive=False,+ run=_make_reindex_run(ctx, _ReindexCounters()),+ )++ assert "recursive" not in seen+++async def test_reindex_resource_vectors_non_recursive_skips_tree(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor, _ReindexCounters++ seen = {}++ class FakeVikingFS:+ async def exists(self, uri, ctx=None):+ return True++ async def stat(self, uri, ctx=None):+ return {"isDir": True}++ async def fail_tree_all(*args, **kwargs):+ raise AssertionError("non-recursive vector rebuild must not walk descendants")++ async def fake_reindex_from_entries(self, **kwargs):+ seen.update(kwargs)++ monkeypatch.setattr("openviking.service.reindex_executor.get_viking_fs", lambda: FakeVikingFS())+ monkeypatch.setattr(ReindexExecutor, "_tree_all", fail_tree_all)+ monkeypatch.setattr(+ ReindexExecutor,+ "_reindex_resource_vectors_from_entries",+ fake_reindex_from_entries,+ )++ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ await ReindexExecutor()._reindex_resource_vectors(+ uri="viking://resources/demo",+ counters=_ReindexCounters(),+ ctx=ctx,+ recursive=False,+ )++ assert seen["directories"] == ["viking://resources/demo"]+ assert seen["files"] == []++@pytest.mark.asyncioasync def test_reindex_executor_infers_skill_supports_semantic_and_vectors():from openviking.service.reindex_executor import ReindexExecutor@@ -1970,6 +2163,82 @@ async def test_reindex_semantic_processor_runs_with_skip_vectorization(monkeypatmsg = json.loads(seen["payload"]["data"])assert msg["skip_vectorization"] is True+ assert msg["recursive"] is True+ assert msg["use_hierarchical_aggregation"] is False+ assert msg["propagate_to_parent"] is True+++async def test_reindex_semantic_processor_passes_non_recursive_message(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor++ seen = {}++ class FakeSemanticProcessor:+ def __init__(self, **_kwargs):+ pass++ async def on_dequeue(self, payload, lock=None):+ seen["payload"] = payload++ monkeypatch.setattr(+ "openviking.service.reindex_executor.SemanticProcessor",+ FakeSemanticProcessor,+ )+ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ await ReindexExecutor()._run_semantic_processor(+ uri="viking://resources/demo",+ context_type="resource",+ ctx=ctx,+ recursive=False,+ )++ import json++ msg = json.loads(seen["payload"]["data"])+ assert msg["recursive"] is False+ assert msg["use_hierarchical_aggregation"] is False+ assert msg["propagate_to_parent"] is False+++async def test_reindex_semantic_processor_sets_memory_aggregation_policy(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor++ seen = {}++ class FakeSemanticProcessor:+ def __init__(self, **_kwargs):+ pass++ async def on_dequeue(self, payload, lock=None):+ seen["payload"] = payload++ monkeypatch.setattr(+ "openviking.service.reindex_executor.SemanticProcessor",+ FakeSemanticProcessor,+ )+ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )++ await ReindexExecutor()._run_semantic_processor(+ uri="viking://user/alice/memories/preferences",+ context_type="memory",+ ctx=ctx,+ recursive=False,+ )++ import json++ msg = json.loads(seen["payload"]["data"])+ assert msg["generation_trigger"] == "reindex"+ assert msg["use_hierarchical_aggregation"] is True+ assert msg["propagate_to_parent"] is False@pytest.mark.asyncio@@ -2105,7 +2374,7 @@ async def test_reindex_resource_vector_text_summary_first_skips_content_read(mon@pytest.mark.asyncioasync def test_reindex_file_summary_reads_existing_record_as_uri_owner(monkeypatch):from openviking.service.reindex_executor import ReindexExecutor- from openviking.storage.semantic_sidecar import render_semantic_sidecar+ from openviking.storage.abstract_overview import render_abstract_overviewcaptured = {}@@ -2133,7 +2402,7 @@ async def test_reindex_file_summary_reads_existing_record_as_uri_owner(monkeypatassert summary == "owner summary"assert captured["ctx"].user.user_id == "bob"- raw = render_semantic_sidecar(+ raw = render_abstract_overview(ContextLevel.OVERVIEW,"viking://resources/demo","# Demo\n\n## image.png\nVisible file summary.",@@ -2839,6 +3108,60 @@ async def test_reindex_skill_l2_falls_back_to_skill_content_when_abstract_missinassert seen["viking://user/skills/my_skill/SKILL.md"]["abstract"] == "skill abstract"+async def test_reindex_skill_vectors_non_recursive_skips_skill_detail(monkeypatch):+ from openviking.service.reindex_executor import ReindexExecutor, _ReindexCounters++ class FakeVikingFS:+ async def exists(self, uri, ctx=None):+ raise AssertionError(f"must not inspect skill detail: {uri}")++ async def fake_read_directory_abstract(self, uri, *, ctx):+ return "skill abstract"++ async def fake_read_directory_overview(self, uri, *, ctx):+ return "skill overview"++ async def fake_safe_read_text(self, uri, *, ctx):+ raise AssertionError(f"must not read skill detail: {uri}")++ async def fake_skill_meta(self, *, uri, abstract, ctx):+ return {"name": "my_skill", "description": abstract}++ upserts = []++ async def fake_upsert_context(self, **kwargs):+ upserts.append((kwargs["uri"], kwargs["level"]))++ monkeypatch.setattr("openviking.service.reindex_executor.get_viking_fs", lambda: FakeVikingFS())+ monkeypatch.setattr(ReindexExecutor, "_read_directory_abstract", fake_read_directory_abstract)+ monkeypatch.setattr(ReindexExecutor, "_read_directory_overview", fake_read_directory_overview)+ monkeypatch.setattr(ReindexExecutor, "_safe_read_text", fake_safe_read_text)+ monkeypatch.setattr(ReindexExecutor, "_skill_meta", fake_skill_meta)+ monkeypatch.setattr(ReindexExecutor, "_upsert_context", fake_upsert_context)++ counters = _ReindexCounters()+ ctx = RequestContext(+ user=UserIdentifier(account_id="test", user_id="alice"),+ role=Role.ROOT,+ )+ uri = "viking://user/skills/my_skill"++ await ReindexExecutor()._reindex_skill_vectors(+ uri=uri,+ counters=counters,+ ctx=ctx,+ recursive=False,+ )++ assert upserts == [+ (uri, ContextLevel.ABSTRACT),+ (uri, ContextLevel.OVERVIEW),+ ]+ assert counters.scanned_records == 1+ assert counters.rebuilt_records == 2++@pytest.mark.asyncioasync def test_reindex_upsert_applies_empty_replace_tags_to_embedding_message(monkeypatch):from types import SimpleNamespacediff --git a/tests/server/test_content_batch_write.py b/tests/server/test_content_batch_write.pyindex 97666cc70..d1d6f9beb 100644--- a/tests/server/test_content_batch_write.py+++ b/tests/server/test_content_batch_write.py@@ -5,6 +5,7 @@ import pytestimport openviking.storage.content_write as content_write_modulefrom openviking.server.identity import RequestContext, Rolefrom openviking.storage.content_write import ContentWriteCoordinator+from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessActionfrom openviking_cli.exceptions import (AlreadyExistsError,InvalidArgumentError,@@ -183,6 +184,42 @@ async def test_batch_releases_tree_lock_before_one_aggregated_refresh(monkeypatcassert locks.releases == 1+async def test_batch_reports_deferred_directory_and_queued_file_vectors(monkeypatch):+ root = "viking://resources/wide"+ page = f"{root}/page.md"+ coordinator = ContentWriteCoordinator(_VFS(root))++ async def resolve_root(uri, **kwargs):+ del uri, kwargs+ return root++ async def enqueue(**kwargs):+ del kwargs+ return FreshnessAction.MARK_PENDING++ monkeypatch.setattr(coordinator, "_resolve_root_uri", resolve_root)+ monkeypatch.setattr(coordinator, "_enqueue_semantic_refresh_changes", enqueue)+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)++ result = await coordinator.batch_write(+ root_uri=root,+ operations=[+ {+ "uri": page,+ "content": "content",+ "mode": "create",+ }+ ],+ ctx=ctx,+ wait=False,+ )++ assert result["semantic_status"] == "deferred"+ assert result["vector_status"] == "queued"+ assert result["queue_status"] is None++@pytest.mark.asyncioasync def test_batch_upserts_binary_content(monkeypatch):root = "viking://resources/wiki"@@ -336,6 +373,7 @@ async def test_batch_refresh_groups_resource_and_memory_work(monkeypatch):async def enqueue(**kwargs):semantic_calls.append(kwargs)+ return FreshnessAction.MARK_PENDINGasync def overview(**kwargs):overview_calls.append(kwargs)@@ -349,7 +387,7 @@ async def test_batch_refresh_groups_resource_and_memory_work(monkeypatch):monkeypatch.setattr(content_write_module.MemoryUpdater, "refresh_schema_overview", overview)monkeypatch.setattr(content_write_module.MemoryUpdater, "refresh_file_embedding", embedding)ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)- await coordinator._refresh_batch(+ outcome = await coordinator._refresh_batch(refresh_kinds={"viking://resources/wiki/a.md": "added","viking://resources/wiki/b.md": "modified",@@ -369,6 +407,7 @@ async def test_batch_refresh_groups_resource_and_memory_work(monkeypatch):assert len(overview_calls) == 1assert overview_calls[0]["strict"] is Trueassert len(embedding_calls) == 2+ assert outcome.statuses(wait=False) == ("deferred", "queued")assert all(call["strict"] is True for call in embedding_calls)diff --git a/tests/server/test_content_write_service.py b/tests/server/test_content_write_service.pyindex b5bd30d9b..a5494d8d4 100644--- a/tests/server/test_content_write_service.py+++ b/tests/server/test_content_write_service.py@@ -4,6 +4,7 @@"""Service-level tests for content write coordination."""from types import SimpleNamespace+from unittest.mock import AsyncMockimport pytest@@ -13,6 +14,7 @@ from openviking.session.memory.utils import MemoryFileUtilsfrom openviking.session.memory.utils.content_visibility import visible_contentfrom openviking.storage.content_write import ContentWriteCoordinatorfrom openviking.storage.errors import LockAcquisitionError, ResourceBusyError+from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessActionfrom openviking_cli.exceptions import (AlreadyExistsError,DeadlineExceededError,@@ -460,6 +462,28 @@ async def test_resource_write_semantic_refresh_uses_coalesce_key(monkeypatch):assert queue.messages[0].lock_handoff is None+async def test_resource_write_wait_forces_directory_refresh(monkeypatch):+ file_uri = "viking://resources/demo/doc.md"+ root_uri = "viking://resources/demo"+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)+ coordinator = ContentWriteCoordinator(+ viking_fs=_FakeVikingFS(file_uri=file_uri, root_uri=root_uri)+ )+ enqueue = AsyncMock(return_value=FreshnessAction.REFRESH_NOW)+ monkeypatch.setattr(coordinator, "_enqueue_semantic_refresh", enqueue)+ monkeypatch.setattr(coordinator, "_wait_for_request", AsyncMock(return_value=None))++ await coordinator.write(+ uri=file_uri,+ content="updated",+ ctx=ctx,+ wait=True,+ )++ assert enqueue.await_args.kwargs["force_refresh"] is True++@pytest.mark.asyncioasync def test_write_timeout_after_enqueue_releases_resource_lock(monkeypatch):file_uri = "viking://resources/demo/doc.md"diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.pyindex 941b31d5e..afe848db9 100644--- a/tests/service/test_fs_service.py+++ b/tests/service/test_fs_service.py@@ -230,6 +230,7 @@ async def test_resource_rm_enqueues_parent_delete_refresh_and_waits(request_contdeleted_uri=uri,context_type="resource",ctx=request_context,+ force_refresh=True,)service._wait_for_refresh.assert_awaited_once_with(timeout=12.0)assert result["semantic_root_uri"] == "viking://resources/images/2026/06/10"diff --git a/tests/session/memory/test_memory_updater.py b/tests/session/memory/test_memory_updater.pyindex 6d623011d..2de3d7dec 100644--- a/tests/session/memory/test_memory_updater.py+++ b/tests/session/memory/test_memory_updater.py@@ -37,7 +37,7 @@ from openviking.session.memory.utils import (MemoryFileUtils,parse_memory_file_with_fields,)-from openviking.storage.semantic_sidecar import parse_semantic_sidecar+from openviking.storage.abstract_overview import parse_abstract_overviewfrom openviking_cli.exceptions import NotFoundErrorfrom openviking_cli.session.user_id import UserIdentifier@@ -317,7 +317,7 @@ class TestMemoryUpdater:await updater.generate_overview("events", directory, ctx, extract_context=None)- document = parse_semantic_sidecar(viking_fs.store[overview_uri])+ document = parse_abstract_overview(viking_fs.store[overview_uri])assert document.metadata["generated_by"] == {"component": "MemoryUpdater","trigger": "memory_update",diff --git a/tests/session/test_session_context.py b/tests/session/test_session_context.pyindex 4aede5653..626d4e04c 100644--- a/tests/session/test_session_context.py+++ b/tests/session/test_session_context.py@@ -15,8 +15,8 @@ from openviking.server.identity import RequestContextfrom openviking.service.core import OpenVikingServicefrom openviking.service.task_tracker import get_task_trackerfrom openviking.session import Session+from openviking.storage.abstract_overview import body_for_previewfrom openviking.storage.queuefs import QueueManager, SessionCommitMsg, get_queue_manager-from openviking.storage.semantic_sidecar import body_for_previewfrom openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.config.vlm_config import VLMConfigdiff --git a/tests/storage/test_abstract_overview_freshness.py b/tests/storage/test_abstract_overview_freshness.pynew file mode 100644index 000000000..e6d0ae31d--- /dev/null+++ b/tests/storage/test_abstract_overview_freshness.py@@ -0,0 +1,153 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++import asyncio++import pytest++from openviking.core.context import ContextLevel+from openviking.storage.abstract_overview import (+ freshness_metadata,+ parse_abstract_overview,+ plan_abstract_overview_refresh,+ render_abstract_overview,+ write_abstract_overview,+)+from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessAction+++class _FakeFS:+ def __init__(self, files):+ self.files = dict(files)+ self._async_agfs = self+ self._lock = asyncio.Lock()++ async def read_file(self, uri, ctx=None):+ if uri not in self.files:+ raise KeyError(uri)+ return self.files[uri]++ async def write_file(self, uri, content, ctx=None, lease_ref=None):+ self.files[uri] = content++ def _uri_to_path(self, uri, ctx=None):+ return uri++ async def pathlock_acquire_exact_batch(self, paths):+ await self._lock.acquire()+ return {"paths": paths}++ async def pathlock_release(self, lease):+ self._lock.release()+ return None+++def _files(dir_uri, *, total=161, pending=3):+ metadata = {"freshness": freshness_metadata(total, min(total, 32), pending)}+ return {+ f"{dir_uri}/.overview.md": render_abstract_overview(+ ContextLevel.OVERVIEW, dir_uri, "overview", metadata+ ),+ f"{dir_uri}/.abstract.md": render_abstract_overview(+ ContextLevel.ABSTRACT, dir_uri, "abstract", metadata+ ),+ }+++async def test_pending_increment_and_threshold_decision_share_one_snapshot():+ dir_uri = "viking://resources/wide"+ fs = _FakeFS(_files(dir_uri, pending=15))++ first = await plan_abstract_overview_refresh(+ viking_fs=fs,+ dir_uri=dir_uri,+ changed_entries=1,+ ctx=None,+ overview_sample_limit=32,+ refresh_ratio=0.10,+ )+ second = await plan_abstract_overview_refresh(+ viking_fs=fs,+ dir_uri=dir_uri,+ changed_entries=1,+ ctx=None,+ overview_sample_limit=32,+ refresh_ratio=0.10,+ )++ assert first.action is FreshnessAction.MARK_PENDING+ assert second.action is FreshnessAction.REFRESH_NOW+ for raw in fs.files.values():+ assert parse_abstract_overview(raw).metadata["freshness"][+ "pending_child_changes"+ ] == 17+++async def test_write_result_ignores_metadata_only_changes_and_preserves_new_pending():+ dir_uri = "viking://resources/wide"+ fs = _FakeFS(_files(dir_uri, pending=5))++ result = await write_abstract_overview(+ viking_fs=fs,+ dir_uri=dir_uri,+ overview="overview",+ abstract="abstract",+ ctx=None,+ is_stale=lambda: False,+ metadata={"freshness": freshness_metadata(160, 32)},+ consume_pending=3,+ )++ assert result.wrote+ assert not result.overview_body_changed+ assert not result.abstract_body_changed+ for raw in fs.files.values():+ freshness = parse_abstract_overview(raw).metadata["freshness"]+ assert freshness == freshness_metadata(160, 32, pending=2)+++async def test_concurrent_pending_marks_do_not_overwrite_each_other():+ dir_uri = "viking://resources/wide"+ fs = _FakeFS(_files(dir_uri, pending=3))++ await asyncio.gather(+ *(+ plan_abstract_overview_refresh(+ viking_fs=fs,+ dir_uri=dir_uri,+ changed_entries=1,+ ctx=None,+ overview_sample_limit=32,+ refresh_ratio=1.0,+ )+ for _ in range(10)+ )+ )++ for raw in fs.files.values():+ assert parse_abstract_overview(raw).metadata["freshness"][+ "pending_child_changes"+ ] == 13+++async def test_partial_sidecar_baseline_refreshes_immediately():+ dir_uri = "viking://resources/wide"+ files = _files(dir_uri, pending=3)+ files.pop(f"{dir_uri}/.abstract.md")+ fs = _FakeFS(files)++ decision = await plan_abstract_overview_refresh(+ viking_fs=fs,+ dir_uri=dir_uri,+ changed_entries=1,+ ctx=None,+ overview_sample_limit=32,+ refresh_ratio=1.0,+ )++ assert decision.action is FreshnessAction.REFRESH_NOW+ assert decision.pending_after == 1diff --git a/tests/storage/test_content_write_processing_mode.py b/tests/storage/test_content_write_processing_mode.pyindex 5658c3b80..68737f530 100644--- a/tests/storage/test_content_write_processing_mode.py+++ b/tests/storage/test_content_write_processing_mode.py@@ -9,11 +9,12 @@ import pytestfrom openviking.core.context import ContextLevelfrom openviking.server.identity import RequestContext, Rolefrom openviking.storage import content_write as content_write_module-from openviking.storage.content_write import ContentWriteCoordinator-from openviking.storage.semantic_sidecar import (- parse_semantic_sidecar,- render_semantic_sidecar,+from openviking.storage.abstract_overview import (+ parse_abstract_overview,+ render_abstract_overview,)+from openviking.storage.content_write import ContentWriteCoordinator+from openviking.storage.queuefs.semantic_ops.freshness_policy import FreshnessActionfrom openviking_cli.session.user_id import UserIdentifier@@ -43,7 +44,7 @@ class _FakeVikingFS:def _sidecar(level=ContextLevel.ABSTRACT, body="Original body."):- return render_semantic_sidecar(+ return render_abstract_overview(level,"viking://resources/demo",body,@@ -129,8 +130,8 @@ async def test_direct_write_skips_semantic_refresh_for_vectors_only_and_sidecar_)written = sidecar_fs.write_file.await_args.args[1]- assert parse_semantic_sidecar(written).body == "Updated body only.\n"- assert parse_semantic_sidecar(written).metadata == parse_semantic_sidecar(current).metadata+ assert parse_abstract_overview(written).body == "Updated body only.\n"+ assert parse_abstract_overview(written).metadata == parse_abstract_overview(current).metadatasidecar_coordinator._enqueue_semantic_refresh.assert_not_awaited()vectorize_directory.assert_awaited_once()assert sidecar_result["semantic_status"] == "skipped"@@ -196,6 +197,31 @@ async def test_vectors_only_write_wait_reports_skipped_when_nothing_enqueued(monassert result["vector_status"] == "skipped"+async def test_automatic_wide_directory_delay_reports_deferred(monkeypatch, ctx):+ fake_fs = _FakeVikingFS()+ coordinator = ContentWriteCoordinator(viking_fs=fake_fs)+ coordinator._enqueue_semantic_refresh = AsyncMock(+ return_value=FreshnessAction.MARK_PENDING+ )++ result = await coordinator._write_direct_with_refresh(+ uri="viking://resources/wide/demo.md",+ root_uri="viking://resources/wide",+ content="updated",+ mode="replace",+ context_type="resource",+ wait=False,+ timeout=None,+ ctx=ctx,+ written_bytes=7,+ telemetry_id="",+ )++ assert result["semantic_status"] == "deferred"+ assert result["vector_status"] == "queued"++@pytest.mark.asyncio@pytest.mark.parametrize(("overview_refreshed", "expected_overview_status"),diff --git a/tests/storage/test_freshness_policy.py b/tests/storage/test_freshness_policy.pynew file mode 100644index 000000000..9e52f7599--- /dev/null+++ b/tests/storage/test_freshness_policy.py@@ -0,0 +1,44 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++import pytest++from openviking.storage.queuefs.semantic_ops.freshness_policy import (+ FreshnessAction,+ decide_parent_refresh,+)+++def _decide(**overrides):+ values = {+ "l0_body_changed": True,+ "has_freshness_baseline": True,+ "total_entries": 161,+ "pending_before": 3,+ "current_change_count": 1,+ "overview_sample_limit": 32,+ "refresh_ratio": 0.10,+ }+ values.update(overrides)+ return decide_parent_refresh(**values)+++def test_unchanged_l0_stops_bubbling_without_incrementing_pending():+ decision = _decide(l0_body_changed=False)++ assert decision.action is FreshnessAction.NOOP+ assert decision.pending_after == 3+++ ("overrides", "expected"),+ [+ ({"has_freshness_baseline": False}, FreshnessAction.REFRESH_NOW),+ ({"total_entries": 32}, FreshnessAction.REFRESH_NOW),+ ({"force_refresh": True}, FreshnessAction.REFRESH_NOW),+ ({}, FreshnessAction.MARK_PENDING),+ ({"pending_before": 16}, FreshnessAction.REFRESH_NOW),+ ],+)+def test_refresh_policy_boundaries(overrides, expected):+ assert _decide(**overrides).action is expecteddiff --git a/tests/storage/test_semantic_dag_incremental.py b/tests/storage/test_semantic_dag_incremental.pyindex bd0f7541b..908d72119 100644--- a/tests/storage/test_semantic_dag_incremental.py+++ b/tests/storage/test_semantic_dag_incremental.py@@ -3,17 +3,19 @@import refrom types import SimpleNamespace-from unittest.mock import MagicMock+from unittest.mock import AsyncMock, MagicMockimport pytestfrom openviking.core.context import ContextLevelfrom openviking.server.identity import RequestContext, Role-from openviking.storage.queuefs.semantic_dag import SemanticDagExecutor-from openviking.storage.semantic_sidecar import (- parse_semantic_sidecar,- render_semantic_sidecar,+from openviking.storage.abstract_overview import (+ deterministic_sample,+ freshness_metadata,+ parse_abstract_overview,+ render_abstract_overview,)+from openviking.storage.queuefs.semantic_dag import SemanticDagExecutorfrom openviking_cli.session.user_id import UserIdentifier@@ -76,7 +78,7 @@ class _FakeProcessor:self.summarized_files.append(file_path)return {"name": file_path.split("/")[-1], "summary": "summary"}- async def _generate_overview(self, dir_uri, file_summaries, children_abstracts):+ async def _generate_overview(self, dir_uri, file_summaries, children_abstracts, **kwargs):lines = ["FILES:"]for item in file_summaries:name = item.get("name", "")@@ -145,7 +147,7 @@ async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypafile_contents={f"{root_uri}/a.txt": "new content",f"{root_uri}/b.txt": "unchanged",- f"{root_uri}/.overview.md": render_semantic_sidecar(+ f"{root_uri}/.overview.md": render_abstract_overview(ContextLevel.OVERVIEW,root_uri,"FILES:\n- a.txt: old-a\n- b.txt: old-b",@@ -162,7 +164,7 @@ async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypamonkeypatch.setattr("openviking.storage.queuefs.semantic_dag.get_viking_fs", lambda: fake_fs)monkeypatch.setattr("openviking.storage.queuefs.semantic_dag.get_openviking_config",- lambda: SimpleNamespace(semantic=SimpleNamespace(sidecar_sample_size=32)),+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=32)),)processor = _FakeProcessor(fake_fs)@@ -182,10 +184,114 @@ async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypaassert processor.summarized_files == [f"{root_uri}/a.txt"]assert processor.vectorized_files == [f"{root_uri}/a.txt"]assert processor.sync_calls == []- overview = parse_semantic_sidecar(fake_fs._file_contents[f"{root_uri}/.overview.md"]).body+ overview = parse_abstract_overview(fake_fs._file_contents[f"{root_uri}/.overview.md"]).bodyassert "- a.txt: summary" in overviewassert "- b.txt: old-b" in overview+async def test_pending_refresh_rebuilds_every_sampled_file_summary(monkeypatch):+ root_uri = "viking://resources/wide"+ file_names = [f"file-{idx:03}.txt" for idx in range(40)]+ file_paths = [f"{root_uri}/{name}" for name in file_names]+ sampled_paths = deterministic_sample(file_paths, 4)+ changed_path = f"{root_uri}/file-020.txt"+ old_overview = "FILES:\n" + "\n".join(+ f"- {name}: old-summary" for name in file_names+ )+ metadata = {"freshness": freshness_metadata(40, 4, pending=4)}+ fake_fs = _FakeVikingFS(+ tree={+ root_uri: [{"name": name, "isDir": False} for name in file_names],+ },+ file_contents={+ **dict.fromkeys(file_paths, "content"),+ f"{root_uri}/.overview.md": render_abstract_overview(+ ContextLevel.OVERVIEW, root_uri, old_overview, metadata+ ),+ f"{root_uri}/.abstract.md": render_abstract_overview(+ ContextLevel.ABSTRACT, root_uri, "old abstract", metadata+ ),+ },+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_dag.get_viking_fs", lambda: fake_fs+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_dag.get_openviking_config",+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=4)),+ )++ processor = _FakeProcessor(fake_fs)+ ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)+ executor = SemanticDagExecutor(+ processor=processor,+ context_type="resource",+ max_concurrent_llm=2,+ ctx=ctx,+ incremental_update=True,+ target_uri=root_uri,+ recursive=False,+ changes={"modified": [changed_path]},+ )++ await executor.run(root_uri)++ assert set(processor.summarized_files) == set(sampled_paths) | {changed_path}+ assert processor.vectorized_files == [changed_path]+ overview = parse_abstract_overview(+ fake_fs._file_contents[f"{root_uri}/.overview.md"]+ )+ assert overview.metadata["freshness"]["pending_child_changes"] == 0+++async def test_directory_vectorization_retries_after_matching_sidecar_write(monkeypatch):+ root_uri = "viking://resources/root"+ file_path = f"{root_uri}/a.txt"+ fake_fs = _FakeVikingFS(+ tree={root_uri: [{"name": "a.txt", "isDir": False}]},+ file_contents={+ file_path: "new content",+ f"{root_uri}/.overview.md": render_abstract_overview(+ ContextLevel.OVERVIEW, root_uri, "FILES:\n- a.txt: old-summary"+ ),+ f"{root_uri}/.abstract.md": render_abstract_overview(+ ContextLevel.ABSTRACT, root_uri, "old abstract"+ ),+ },+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_dag.get_viking_fs", lambda: fake_fs+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_dag.get_openviking_config",+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=32)),+ )++ processor = _FakeProcessor(fake_fs)+ vectorize_directory = AsyncMock(side_effect=[RuntimeError("temporary failure"), None])+ processor._vectorize_directory = vectorize_directory+ ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)++ def make_executor():+ return SemanticDagExecutor(+ processor=processor,+ context_type="resource",+ max_concurrent_llm=2,+ ctx=ctx,+ incremental_update=True,+ target_uri=root_uri,+ recursive=False,+ changes={"modified": [file_path]},+ )++ with pytest.raises(RuntimeError, match="temporary failure"):+ await make_executor().run(root_uri)+ await make_executor().run(root_uri)++ assert vectorize_directory.await_count == 2++if __name__ == "__main__":pytest.main([__file__])diff --git a/tests/storage/test_semantic_dag_skip_files.py b/tests/storage/test_semantic_dag_skip_files.pyindex 10859e669..7331e7bfe 100644--- a/tests/storage/test_semantic_dag_skip_files.py+++ b/tests/storage/test_semantic_dag_skip_files.py@@ -39,7 +39,7 @@ class _FakeProcessor:self.summarized_files.append(file_path)return {"name": file_path.split("/")[-1], "summary": "summary"}- async def _generate_overview(self, dir_uri, file_summaries, children_abstracts):+ async def _generate_overview(self, dir_uri, file_summaries, children_abstracts, **kwargs):return "overview"def _normalize_overview_generation(self, overview):diff --git a/tests/storage/test_semantic_dag_stats.py b/tests/storage/test_semantic_dag_stats.pyindex 396565070..fdbe00863 100644--- a/tests/storage/test_semantic_dag_stats.py+++ b/tests/storage/test_semantic_dag_stats.py@@ -13,6 +13,7 @@ from openviking.service.task_work_index import (bind_task_context,get_task_context,)+from openviking.storage.abstract_overview import parse_abstract_overviewfrom openviking.storage.queuefs.named_queue import NamedQueuefrom openviking.storage.queuefs.semantic_dag import (DagStats,@@ -20,7 +21,6 @@ from openviking.storage.queuefs.semantic_dag import (SemanticDagExecutor,SemanticNodeScheduler,)-from openviking.storage.semantic_sidecar import parse_semantic_sidecarfrom openviking.telemetry import (OperationTelemetry,bind_telemetry,@@ -30,8 +30,9 @@ from openviking_cli.session.user_id import UserIdentifierclass _FakeVikingFS:- def __init__(self, tree):+ def __init__(self, tree, abstracts=None):self._tree = tree+ self._abstracts = abstracts or {}self.writes = []self._async_agfs = self@@ -42,6 +43,9 @@ class _FakeVikingFS:async def write_file(self, path, content, ctx=None, lease_ref=None):self.writes.append((path, content))+ async def abstract(self, uri, ctx=None):+ return self._abstracts.get(uri, "")+async def pathlock_acquire_exact_batch(self, paths):return {"paths": paths}@@ -57,15 +61,19 @@ class _FakeProcessor:self.vectorized_dirs = []self.vectorized_files = []self.vectorized_contexts = {}+ self.summarized_files = []+ self.overview_inputs = []self.verify_streaming = verify_streamingasync def _generate_single_file_summary(self, file_path, llm_sem=None, ctx=None):+ self.summarized_files.append(file_path)result = {"name": file_path.split("/")[-1], "summary": "summary"}if self.verify_streaming:result["content"] = "x" * 100_000return result- async def _generate_overview(self, dir_uri, file_summaries, children_abstracts):+ async def _generate_overview(self, dir_uri, file_summaries, children_abstracts, **kwargs):+ self.overview_inputs.append((dir_uri, file_summaries, children_abstracts, kwargs))if self.verify_streaming:assert all("content" not in item for item in file_summaries)assert all(@@ -145,10 +153,10 @@ class _ScheduledExecutor:self.failure = exc-def _patch_semantic_config(monkeypatch, *, sidecar_sample_size=32):+def _patch_semantic_config(monkeypatch, *, overview_sample_limit=32):monkeypatch.setattr("openviking.storage.queuefs.semantic_dag.get_openviking_config",- lambda: SimpleNamespace(semantic=SimpleNamespace(sidecar_sample_size=sidecar_sample_size)),+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=overview_sample_limit)),)@@ -232,6 +240,116 @@ async def test_semantic_dag_bounds_active_node_work(monkeypatch):assert max_running <= 3+async def test_incremental_wide_directory_samples_before_summary_work(monkeypatch):+ root_uri = "viking://resources/wide"+ tree = {+ root_uri: [{"name": f"file-{idx:03}.txt", "isDir": False} for idx in range(40)],+ }+ fake_fs = _FakeVikingFS(tree)+ monkeypatch.setattr("openviking.storage.queuefs.semantic_dag.get_viking_fs", lambda: fake_fs)+ _patch_semantic_config(monkeypatch, overview_sample_limit=4)++ processor = _FakeProcessor()+ ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)+ executor = SemanticDagExecutor(+ processor=processor,+ context_type="resource",+ max_concurrent_llm=2,+ ctx=ctx,+ incremental_update=True,+ target_uri=root_uri,+ recursive=False,+ changes={"modified": [f"{root_uri}/file-020.txt"]},+ skip_vectorization=True,+ )++ await executor.run(root_uri)++ # Four deterministic aggregation inputs plus the changed file, when it is+ # outside that sample, are the only files that need summary preparation.+ assert len(processor.summarized_files) <= 5+ assert executor.get_stats().total_nodes <= 6+++async def test_non_recursive_memory_samples_files_and_reads_child_abstracts(monkeypatch):+ root_uri = "viking://user/alice/memories"+ child_a = f"{root_uri}/a-child"+ child_d = f"{root_uri}/d-child"+ tree = {+ root_uri: [+ {"name": "a-child", "isDir": True},+ {"name": "b.md", "isDir": False},+ {"name": "c.md", "isDir": False},+ {"name": "d-child", "isDir": True},+ {"name": "e.md", "isDir": False},+ {"name": "f.md", "isDir": False},+ ],+ child_a: [{"name": "nested.md", "isDir": False}],+ child_d: [{"name": "nested.md", "isDir": False}],+ }+ fake_fs = _FakeVikingFS(tree, abstracts={child_a: "child a abstract"})+ monkeypatch.setattr("openviking.storage.queuefs.semantic_dag.get_viking_fs", lambda: fake_fs)+ _patch_semantic_config(monkeypatch, overview_sample_limit=3)++ processor = _FakeProcessor()+ ctx = RequestContext(user=UserIdentifier("acc1", "alice"), role=Role.USER)+ executor = SemanticDagExecutor(+ processor=processor,+ context_type="memory",+ max_concurrent_llm=2,+ ctx=ctx,+ recursive=False,+ skip_vectorization=True,+ generation_trigger="reindex",+ )++ await executor.run(root_uri)++ assert processor.summarized_files == [f"{root_uri}/c.md", f"{root_uri}/f.md"]+ assert executor.get_stats().total_nodes == 3+ assert processor.vectorized_files == []+ assert processor.vectorized_dirs == []+ _, file_summaries, child_abstracts, coverage = processor.overview_inputs[-1]+ assert [item["name"] for item in file_summaries] == ["c.md", "f.md"]+ assert child_abstracts == [{"name": "a-child", "abstract": "child a abstract"}]+ assert coverage["total_files"] == 4+ assert coverage["total_children"] == 2+++async def test_deferred_aggregation_processes_only_changed_files(monkeypatch):+ root_uri = "viking://resources/wide"+ changed = f"{root_uri}/file-020.txt"+ tree = {+ root_uri: [{"name": f"file-{idx:03}.txt", "isDir": False} for idx in range(40)],+ }+ fake_fs = _FakeVikingFS(tree)+ monkeypatch.setattr("openviking.storage.queuefs.semantic_dag.get_viking_fs", lambda: fake_fs)+ _patch_semantic_config(monkeypatch, overview_sample_limit=4)++ processor = _FakeProcessor()+ ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)+ executor = SemanticDagExecutor(+ processor=processor,+ context_type="resource",+ max_concurrent_llm=2,+ ctx=ctx,+ incremental_update=True,+ target_uri=root_uri,+ recursive=False,+ changes={"modified": [changed]},+ aggregate_directory=False,+ )++ await executor.run(root_uri)++ assert processor.vectorized_files == [changed]+ assert processor.vectorized_dirs == []+ assert executor.get_stats().total_nodes == 2++@pytest.mark.asyncioasync def test_semantic_dag_shares_node_scheduler_across_roots(monkeypatch):root_a = "viking://resources/root-a"@@ -364,14 +482,14 @@ async def test_semantic_dag_skip_vectorization_does_not_schedule_tasks(monkeypatf"{root_uri}/.overview.md",f"{root_uri}/.abstract.md",]- assert [parse_semantic_sidecar(raw).body.strip() for _, raw in fake_fs.writes] == [+ assert [parse_abstract_overview(raw).body.strip() for _, raw in fake_fs.writes] == ["overview","abstract","overview","abstract",]assert all(- parse_semantic_sidecar(raw).metadata["generated_by"]["component"] == "SemanticProcessor"+ parse_abstract_overview(raw).metadata["generated_by"]["component"] == "SemanticProcessor"for _, raw in fake_fs.writes)assert processor.vectorized_dirs == []diff --git a/tests/storage/test_semantic_msg_ingest_options.py b/tests/storage/test_semantic_msg_ingest_options.pyindex a9f279ee5..53d1922dd 100644--- a/tests/storage/test_semantic_msg_ingest_options.py+++ b/tests/storage/test_semantic_msg_ingest_options.py@@ -30,6 +30,9 @@ def test_semantic_msg_serializes_ingest_options():"uri": "https://example.com/acme/demo.git",}assert restored.generation_trigger == "resource_ingest"+ assert restored.aggregate_directory is True+ assert restored.use_hierarchical_aggregation is False+ assert restored.propagate_to_parent is Truedef test_semantic_msg_reads_legacy_search_tag_fields():@@ -46,3 +49,28 @@ def test_semantic_msg_reads_legacy_search_tag_fields():search_tags=["team=search"],search_tag_mode="append",)+ assert msg.aggregate_directory is True+++def test_semantic_msg_round_trips_deferred_aggregation_flag():+ msg = SemanticMsg(+ uri="viking://resources/wide",+ context_type="resource",+ aggregate_directory=False,+ )++ assert SemanticMsg.from_json(msg.to_json()).aggregate_directory is False+++def test_semantic_msg_round_trips_hierarchical_aggregation_policy():+ msg = SemanticMsg(+ uri="viking://user/alice/memories",+ context_type="memory",+ use_hierarchical_aggregation=True,+ propagate_to_parent=False,+ )++ restored = SemanticMsg.from_json(msg.to_json())++ assert restored.use_hierarchical_aggregation is True+ assert restored.propagate_to_parent is Falsediff --git a/tests/storage/test_semantic_parent_bubbling.py b/tests/storage/test_semantic_parent_bubbling.pynew file mode 100644index 000000000..4550c5be8--- /dev/null+++ b/tests/storage/test_semantic_parent_bubbling.py@@ -0,0 +1,68 @@+# 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.storage.queuefs.semantic_msg import SemanticMsg+from openviking.storage.queuefs.semantic_ops.freshness_policy import (+ FreshnessAction,+ FreshnessDecision,+)+from openviking.storage.queuefs.semantic_processor import SemanticProcessor+++async def test_unchanged_l0_does_not_mark_or_enqueue_parent(monkeypatch):+ plan = AsyncMock(+ return_value=FreshnessDecision(FreshnessAction.NOOP, pending_after=3, total_entries=161)+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.plan_abstract_overview_refresh", plan+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.get_openviking_config",+ lambda: SimpleNamespace(+ semantic=SimpleNamespace(overview_sample_limit=32, freshness_refresh_ratio=0.10)+ ),+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.get_viking_fs",+ lambda: SimpleNamespace(),+ )+ get_queue_manager = AsyncMock(side_effect=AssertionError("parent must not be enqueued"))+ monkeypatch.setattr(+ "openviking.storage.queuefs.get_queue_manager", get_queue_manager+ )++ msg = SemanticMsg(uri="viking://resources/root/child", context_type="resource")+ await SemanticProcessor()._enqueue_parent_refresh(+ msg, msg.uri, l0_body_changed=False+ )++ assert plan.await_args.kwargs["l0_body_changed"] is False+ assert plan.await_args.kwargs["force_refresh"] is False+ get_queue_manager.assert_not_called()+++async def test_non_recursive_reindex_does_not_bubble_to_parent(monkeypatch):+ plan = AsyncMock(side_effect=AssertionError("non-recursive reindex must stop at target"))+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.plan_abstract_overview_refresh", plan+ )++ msg = SemanticMsg(+ uri="viking://resources/root/child",+ context_type="resource",+ recursive=False,+ generation_trigger="reindex",+ propagate_to_parent=False,+ )+ await SemanticProcessor()._enqueue_parent_refresh(+ msg, msg.uri, l0_body_changed=True+ )++ plan.assert_not_awaited()diff --git a/tests/storage/test_semantic_processor_l0_l1.py b/tests/storage/test_semantic_processor_l0_l1.pyindex 4cb04de90..abc58fe8f 100644--- a/tests/storage/test_semantic_processor_l0_l1.py+++ b/tests/storage/test_semantic_processor_l0_l1.py@@ -4,9 +4,9 @@from types import SimpleNamespacefrom openviking.core.context import ContextLevel+from openviking.storage.abstract_overview import render_abstract_overviewfrom openviking.storage.queuefs import semantic_processor as semantic_processor_modulefrom openviking.storage.queuefs.semantic_processor import SemanticProcessor-from openviking.storage.semantic_sidecar import render_semantic_sidecardef _patch_semantic_limits(monkeypatch, *, abstract_max_chars=256, overview_max_chars=4000):@@ -34,7 +34,7 @@ def test_markdown_overview_uses_brief_description_as_abstract(monkeypatch):assert overview == generatedassert abstract == "This brief description is the retrieval abstract."- raw = render_semantic_sidecar(+ raw = render_abstract_overview(ContextLevel.OVERVIEW,"viking://resources/demo",generated,@@ -65,6 +65,26 @@ def test_markdown_overview_extracts_multiline_brief_description(monkeypatch):assert abstract == "This is the first abstract line.\nThis is the second abstract line."+def test_directory_coverage_section_is_excluded_from_abstract(monkeypatch):+ _patch_semantic_limits(monkeypatch)+ processor = SemanticProcessor()+ generated = (+ "# docs-index\n\n"+ "OpenViking documentation covering agent context, retrieval, and operations.\n\n"+ "## Directory Coverage\n\n"+ "This directory contains 513 direct entries; 32 were sampled.\n\n"+ "## Quick Navigation\n\n"+ "- Read the getting-started guide"+ )++ overview, abstract = processor._normalize_overview_generation(generated)++ assert "513 direct entries" in overview+ assert abstract == (+ "OpenViking documentation covering agent context, retrieval, and operations."+ )++def test_index_references_are_replaced_inside_markdown_overview(monkeypatch):_patch_semantic_limits(monkeypatch)processor = SemanticProcessor()diff --git a/tests/storage/test_semantic_processor_language.py b/tests/storage/test_semantic_processor_language.pyindex dff9cfa2f..7861f48a0 100644--- a/tests/storage/test_semantic_processor_language.py+++ b/tests/storage/test_semantic_processor_language.py@@ -209,7 +209,8 @@ class TestOverviewGenerationFlow:)assert f"Output Language: {lang}" in promptassert "Output in Markdown format" in prompt- assert "Brief Description" in prompt+ expected_brief_heading = "简要描述" if lang == "zh-CN" else "Brief Description"+ assert expected_brief_heading in promptassert "abstract_max_chars" not in promptdef test_overview_generation_prompt_preserves_repository_hierarchy(self):@@ -237,12 +238,14 @@ class TestOverviewGenerationFlow:in prompt)assert (- "- Describe only what the provided summaries state; do not invent or generalize entities, facts, or relationships not present in them."+ "- Describe only what the provided summaries state; do not invent entities, facts, or relationships not present in them."in prompt)assert "Before output, remove any named entity absent from the provided summaries" in promptassert "never fill gaps with outside knowledge" in promptassert "Who it's suitable for, if stated in the provided summaries" in prompt+ assert "keep this paragraph useful as a standalone retrieval abstract" in prompt+ assert "**Directory Coverage** (H2)" in promptdef test_chinese_overview_uses_localized_headings(self):prompt = render_prompt(@@ -257,6 +260,8 @@ class TestOverviewGenerationFlow:assert "**快速导航** (H2)" in promptassert "**详细说明** (H2)" in prompt+ assert "**目录覆盖** (H2)" in prompt+ assert "**Directory Coverage** (H2)" not in promptassert "**Quick Navigation** (H2)" not in promptassert "**Detailed Description** (H2)" not in promptdiff --git a/tests/storage/test_semantic_processor_overview_batching.py b/tests/storage/test_semantic_processor_overview_batching.pyindex 3af2139ad..96244756f 100644--- a/tests/storage/test_semantic_processor_overview_batching.py+++ b/tests/storage/test_semantic_processor_overview_batching.py@@ -59,3 +59,42 @@ async def test_children_only_oversized_overview_is_batched(monkeypatch):assert "child-2" not in vlm.prompts[0]assert "child-2" in vlm.prompts[1]assert all(f"child-{index}" not in vlm.prompts[2] for index in range(3))+++async def test_sampled_overview_prompt_describes_full_directory_coverage(monkeypatch):+ vlm = RecordingVLM()+ config = SimpleNamespace(+ vlm=vlm,+ semantic=SimpleNamespace(+ max_overview_prompt_chars=10_000,+ overview_batch_size=32,+ ),+ output_language_override="en",+ )+ captured = {}+ monkeypatch.setattr(+ semantic_processor_module,+ "get_openviking_config",+ lambda: config,+ )++ def fake_render_prompt(_name, values):+ captured.update(values)+ return "prompt"++ monkeypatch.setattr(semantic_processor_module, "render_prompt", fake_render_prompt)++ await SemanticProcessor()._generate_overview(+ "viking://resources/docs_flat",+ file_summaries=[],+ children_abstracts=[{"name": "sample", "abstract": "summary"}],+ total_files=0,+ total_children=513,+ )++ coverage = captured["directory_coverage"]+ assert "Total direct entries: 513" in coverage+ assert "Summaries provided for this aggregation: 1" in coverage+ assert "Direct entries not individually shown: 512" in coverage+ assert "Coverage: sampled" in coveragediff --git a/tests/storage/test_semantic_processor_target_preexisting.py b/tests/storage/test_semantic_processor_target_preexisting.pyindex aa913d25b..a11c180f0 100644--- a/tests/storage/test_semantic_processor_target_preexisting.py+++ b/tests/storage/test_semantic_processor_target_preexisting.py@@ -123,6 +123,109 @@ async def test_target_source_syncs_before_semantic_dag(monkeypatch):assert _FakeDagExecutor.runs == ["viking://resources/org/repo"]+async def test_stale_content_write_keeps_file_work_without_directory_aggregation(monkeypatch):+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.get_viking_fs",+ lambda: _FakeVikingFS(),+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.SemanticDagExecutor",+ _FakeDagExecutor,+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",+ AsyncMock(return_value=SimpleNamespace(lock=None, close=AsyncMock())),+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.is_semantic_msg_stale",+ lambda msg: bool(msg.coalesce_key),+ )++ _FakeDagExecutor.calls = []+ _FakeDagExecutor.runs = []+ processor = SemanticProcessor()+ processor._enqueue_parent_refresh = AsyncMock()+ changed = "viking://resources/wiki/changed.md"+ msg = SemanticMsg(+ uri="viking://resources/wiki",+ context_type="resource",+ recursive=False,+ coalesce_key="resource|wiki",+ coalesce_version=1,+ changes={"modified": [changed], "deleted": ["viking://resources/wiki/old.md"]},+ generation_trigger="content_write",+ )++ await processor.on_dequeue(msg.to_dict())++ assert _FakeDagExecutor.calls[0]["aggregate_directory"] is False+ assert _FakeDagExecutor.calls[0]["changes"] == {"modified": [changed]}+ assert _FakeDagExecutor.calls[0]["coalesce_key"] == ""+ assert _FakeDagExecutor.runs == ["viking://resources/wiki"]+ processor._enqueue_parent_refresh.assert_not_awaited()++[email protected]("recursive", [False, True])+async def test_memory_reindex_uses_semantic_dag(monkeypatch, recursive):+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.get_viking_fs",+ lambda: _FakeVikingFS(),+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.SemanticDagExecutor",+ _FakeDagExecutor,+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",+ AsyncMock(return_value=SimpleNamespace(lock=None, close=AsyncMock())),+ )++ _FakeDagExecutor.calls = []+ _FakeDagExecutor.runs = []+ processor = SemanticProcessor()+ processor._process_memory_directory = AsyncMock()+ msg = SemanticMsg(+ uri="viking://user/alice/memories/preferences",+ context_type="memory",+ recursive=recursive,+ generation_trigger="reindex",+ use_hierarchical_aggregation=True,+ )++ await processor.on_dequeue(msg.to_dict())++ processor._process_memory_directory.assert_not_awaited()+ assert _FakeDagExecutor.calls[0]["context_type"] == "memory"+ assert _FakeDagExecutor.calls[0]["recursive"] is recursive+ assert _FakeDagExecutor.runs == [msg.uri]+++async def test_memory_trigger_does_not_select_hierarchical_aggregation(monkeypatch):+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.get_viking_fs",+ lambda: _FakeVikingFS(),+ )+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",+ AsyncMock(return_value=SimpleNamespace(lock=None, close=AsyncMock())),+ )++ processor = SemanticProcessor()+ processor._process_memory_directory = AsyncMock()+ msg = SemanticMsg(+ uri="viking://user/alice/memories/preferences",+ context_type="memory",+ generation_trigger="reindex",+ )++ await processor.on_dequeue(msg.to_dict())++ processor._process_memory_directory.assert_awaited_once()++@pytest.mark.asyncioasync def test_sync_wrapper_delegates_to_sync_tree_and_cleans_temp(monkeypatch):"""The wrapper calls viking_fs.sync_tree and then deletes the temp tree."""@@ -174,7 +277,7 @@ async def test_sync_wrapper_whole_tree_mv_for_new_target(monkeypatch):AsyncMock(),)- diff = await SemanticProcessor()._sync_topdown_recursive(+ await SemanticProcessor()._sync_topdown_recursive("viking://temp/import","viking://resources/root",lock=None,diff --git a/tests/storage/test_semantic_queue_memory_dedupe.py b/tests/storage/test_semantic_queue_memory_dedupe.pyindex bac539edb..f3782bb16 100644--- a/tests/storage/test_semantic_queue_memory_dedupe.py+++ b/tests/storage/test_semantic_queue_memory_dedupe.py@@ -8,11 +8,14 @@ from uuid import uuid4import pytest+from openviking.storage.abstract_overview import (+ AbstractOverviewWriteResult,+ parse_abstract_overview,+)from openviking.storage.queuefs.named_queue import NamedQueuefrom openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import SemanticProcessorfrom openviking.storage.queuefs.semantic_queue import SemanticQueue, is_semantic_msg_stale-from openviking.storage.semantic_sidecar import parse_semantic_sidecar@pytest.mark.asyncio@@ -141,10 +144,10 @@ class _FakeMemoryDirFS:]-def _patch_semantic_config(monkeypatch, *, sidecar_sample_size=32):+def _patch_semantic_config(monkeypatch, *, overview_sample_limit=32):monkeypatch.setattr("openviking.storage.queuefs.semantic_processor.get_openviking_config",- lambda: SimpleNamespace(semantic=SimpleNamespace(sidecar_sample_size=sidecar_sample_size)),+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=overview_sample_limit)),)@@ -199,7 +202,7 @@ async def test_stale_memory_semantic_write_is_skipped(monkeypatch):"viking://user/default/memories/preferences/.overview.md","viking://user/default/memories/preferences/.abstract.md",]- assert [parse_semantic_sidecar(raw).body.strip() for _, raw in viking_fs.writes] == [+ assert [parse_abstract_overview(raw).body.strip() for _, raw in viking_fs.writes] == ["latest overview","latest abstract",]@@ -222,7 +225,9 @@ async def test_memory_directory_summarizes_all_uncached_files(monkeypatch):async def write_semantics(**kwargs):del kwargs- return True+ return AbstractOverviewWriteResult(+ wrote=True, overview_body_changed=True, abstract_body_changed=True+ )monkeypatch.setattr("openviking.storage.queuefs.semantic_processor.get_viking_fs",@@ -270,7 +275,9 @@ async def test_memory_directory_vectorizes_changed_files_with_generated_summary(async def write_semantics(**kwargs):del kwargs- return True+ return AbstractOverviewWriteResult(+ wrote=True, overview_body_changed=True, abstract_body_changed=True+ )async def vectorize_single_file(**kwargs):captured_file_vectorize.append(kwargs)@@ -314,3 +321,44 @@ async def test_memory_directory_vectorizes_changed_files_with_generated_summary(assert captured_file_vectorize[0]["preserve_existing_created_at"] is Trueassert len(captured_directory_vectorize) == 1assert captured_directory_vectorize[0]["uri"] == dir_uri+++async def test_memory_directory_skips_vectorization_when_visible_semantics_are_unchanged(+ monkeypatch,+):+ processor = SemanticProcessor(max_concurrent_llm=4)+ vectorize_directory = AsyncMock()+ vectorize_file = AsyncMock()++ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_processor.get_viking_fs",+ lambda: _FakeMemoryDirFS(),+ )+ _patch_semantic_config(monkeypatch)+ monkeypatch.setattr(+ processor,+ "_generate_single_file_summary",+ AsyncMock(return_value={"name": "file.md", "summary": "summary"}),+ )+ monkeypatch.setattr(processor, "_generate_overview", AsyncMock(return_value="overview"))+ monkeypatch.setattr(+ processor, "_normalize_overview_generation", lambda overview: (overview, "abstract")+ )+ monkeypatch.setattr(+ processor,+ "_write_memory_directory_semantics",+ AsyncMock(return_value=AbstractOverviewWriteResult(wrote=True)),+ )+ monkeypatch.setattr(processor, "_vectorize_single_file", vectorize_file)+ monkeypatch.setattr(processor, "_vectorize_directory", vectorize_directory)++ await processor._process_memory_directory(+ SemanticMsg(+ uri="viking://user/default/memories/preferences",+ context_type="memory",+ )+ )++ assert vectorize_file.await_count == 2+ vectorize_directory.assert_not_awaited()diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.pyindex e95338e32..1efe1a980 100644--- a/tests/unit/test_vectorize_file_strategy.py+++ b/tests/unit/test_vectorize_file_strategy.py@@ -562,7 +562,7 @@ async def test_vectorize_directory_meta_l1_abstract_is_overview(monkeypatch):"""L1 records must carry the overview in the abstract scalar so Reranksees L1 text instead of the L0 abstract."""from openviking.core.context import ContextLevel- from openviking.storage.semantic_sidecar import render_semantic_sidecar+ from openviking.storage.abstract_overview import render_abstract_overviewqueue = DummyQueue()monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))@@ -582,8 +582,8 @@ async def test_vectorize_directory_meta_l1_abstract_is_overview(monkeypatch):}await embedding_utils.vectorize_directory_meta(uri=uri,- abstract=render_semantic_sidecar(ContextLevel.ABSTRACT, uri, "Visible abstract.", metadata),- overview=render_semantic_sidecar(ContextLevel.OVERVIEW, uri, overview, metadata),+ abstract=render_abstract_overview(ContextLevel.ABSTRACT, uri, "Visible abstract.", metadata),+ overview=render_abstract_overview(ContextLevel.OVERVIEW, uri, overview, metadata),ctx=DummyReq(),)