[refactor-design] iter46 cluster-046-workflow-file-catalog-query-port: Workflow catalog 查询现场扫文件 + singleton 缓存事实

[loning]

Workflow catalog 查询现场扫文件并缓存业务事实

一段话说清楚

现在 workflow catalog/capabilities 查询不是读取已经物化好的目录视图,而是在查询方法里现场扫目录、读 YAML、解析 workflow,再用单例内存缓存结果。同一个查询结果取决于当前进程看到的文件系统和本地缓存,而不是 actor 或 projection 已提交的事实。

多实例部署时不同进程可能看到不同目录、不同缓存水位,接口还会返回一个本地生成时间(GeneratedAtUtc = DateTimeOffset.UtcNow),让调用方误以为这是权威刷新时间。Workflow definition 的事实来源变成"谁刚好处理了这次查询"。

违反:

• CLAUDE「查询始终走 readmodel:对外查询只读 readmodel;不暴露 actor 内部状态、state mirror payload 或 event replay 为查询主路径」
• CLAUDE「禁止 query-time replay/priming」
• CLAUDE「禁止中间层维护 entity/actor 等 ID → 上下文/事实状态的进程内映射(Dictionary/ConcurrentDictionary/HashSet/Queue)」
• CLAUDE「单线程事实源:禁止 lock/Monitor/ConcurrentDictionary 作为并发补丁维护事实状态」
• CLAUDE「查询诚实:readmodel 必须暴露权威源版本或刷新戳;禁止在弱读结果上暗示强一致」

Evidence

• src/workflow/Aevatar.Workflow.Infrastructure/Workflows/FileBackedWorkflowCatalogPort.cs:78-80:_cacheLock、_workflowFileDiscoveryCache、_parsedWorkflowCache on singleton port
• src/workflow/Aevatar.Workflow.Infrastructure/Workflows/FileBackedWorkflowCatalogPort.cs:92-151:ListWorkflowCatalog / GetWorkflowDetail / GetCapabilities 现场 discover files / read registry YAML / parse definitions / load connector config
• src/workflow/Aevatar.Workflow.Infrastructure/Workflows/FileBackedWorkflowCatalogPort.cs:457-566:从目录 discover files + mutate process caches under lock (_cacheLock)
• src/workflow/Aevatar.Workflow.Infrastructure/DependencyInjection/ServiceCollectionExtensions.cs:40-44:registers infrastructure singleton as both IWorkflowCatalogPort and IWorkflowCapabilitiesPort
• src/workflow/Aevatar.Workflow.Application/Queries/WorkflowExecutionQueryApplicationService.cs:12-20:injects those query ports as application read surface

Fix Boundary

Keep scope to workflow catalog/capabilities read path。Do NOT add new authoring features or change DSL semantics:

• Replace FileBackedWorkflowCatalogPort as online query source with materialized workflow catalog/capabilities readmodel
• Move file discovery/import into explicit startup activation, catalog actor command, or projection materializer(this decision needs maintainer input — ownership contract change)
• Query app service should read versioned/freshness-bearing document, not enumerate files or parse YAML in request path
• Remove process-local _workflowFileDiscoveryCache, _parsedWorkflowCache, _cacheLock from online query port
• Add guard/tests to prevent Directory.EnumerateFiles, _parser.Parse, AevatarConnectorConfig.LoadConnectors() reappearing inside workflow query ports

为什么需要 design 决策

修复不是机械改名,需要决定 file-backed workflow 的权威事实拥有者:

1. WorkflowGAgent 拥有 definition facts(docs 现有说法)?
2. 单独 WorkflowCatalogActor(新 actor — 可能命中 hardcoded trigger Feature/cqrs projection suite #2)?
3. Startup-time materializer(workflow registry → projection readmodel on app start)?
4. 影响热加载、user home workflows、repo workflows、capabilities 文档版本号、多实例部署一致性

需要回答的问题

加 auto-loop-resume 前请回答:

• Fact owner:WorkflowGAgent per-definition / WorkflowCatalogActor aggregate(新 actor 警告)/ startup materializer / projection-driven?
• File discovery:startup activation 一次性 / catalog actor command / projection materializer?
• Hot reload:支持 / 不支持(只 startup 加载)?
• Multi-source:user home + repo + registry 谁负责合并?
• Version/watermark:GeneratedAtUtc 改用 commit version / projection watermark?
• Scope 拆分:单 cluster 还是拆 N?

Auto-loop 行为

phase9-auto-solve;maintainer 评论 RESET round;auto-loop-resume = 最新评论作 design decision。

📢 cc 原作者

@loning @eanzhao

⟦AI:AUTO-LOOP⟧

[loning]

📊 状态卡片 — Phase 9 r1 三 solver 派出

维度	值
Issue	#871 cluster-046-workflow-file-catalog-query-port
来源	iter46 audit
阶段	Phase 9 r1(3 solver + meta-judge)
是否需要 maintainer 介入	❌ 否(等共识)

🤖 controller status banner

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Phase 9 Solver — minimal (round r1)

SOLVER_DONE:minimal:propose:startup materialize file-backed workflow catalog once into a freshness-bearing readmodel; query ports read it only, no new actor

raw

---
solver: minimal
issue: 871
round: r1
verdict: propose
---

# Phase 9 Solver minimal - issue #871

## Verdict

`propose`。最小合规方案是：**不新增 `WorkflowCatalogActor`，把现有 file-backed catalog 逻辑拆成 startup-time materializer + readmodel query port**。

现有 `WorkflowGAgent` 已经是每个 workflow definition 的事实 owner；本 issue 不扩大到 authoring/热更新/新 catalog aggregate actor。file-backed workflow 仍然是启动期输入源，启动完成后被物化为一个只读 catalog/capabilities readmodel。在线 `IWorkflowCatalogPort` / `IWorkflowCapabilitiesPort` 只读该 readmodel，不再扫文件、读 YAML、解析 workflow 或加载 connector config。

## Decision answers

| 问题 | minimal 决策 |
|---|---|
| Fact owner | 单个 workflow definition 事实仍归属现有 `WorkflowGAgent`；catalog/capabilities 是启动期物化出的查询副本，不新增业务事实 owner。 |
| File discovery | 只在 startup activation/materialization 做一次。复用现有 `WorkflowDefinitionBootstrapHostedService` / `WorkflowDefinitionFileLoader` 所在阶段，将 file + registry + connector config 一次性转成 readmodel。 |
| Hot reload | 不支持。file-backed definitions 是 startup-loaded configuration；变更文件后重启/重新启动 materializer 才可见。 |
| Multi-source | startup materializer 负责按现有目录与 duplicate policy 合并 user home / repo / cwd / app / builtin registry；query port 不再合并来源。 |
| Version/watermark | `GeneratedAtUtc = DateTimeOffset.UtcNow` 不能在 query 时生成。readmodel 写入 `MaterializedAtUtc` 与确定性 `SourceFingerprint`，并在 DTO 暴露为刷新戳/水位；若后续接入 `WorkflowGAgent` committed version，可升级为 authority version。 |
| Scope split | 单 cluster 可完成：新增 readmodel + startup materializer + query reader + guards/tests；不引入新 actor、不改 DSL、不做热加载。 |

## Minimal implementation plan

1. 新增 workflow catalog readmodel 类型。
   - 放在 workflow projection/readmodel 边界，例如 `WorkflowCatalogDocument`。
   - 文档 id 固定为 `workflow-catalog`.
   - 字段包含 `SchemaVersion`、`MaterializedAtUtc`、`SourceFingerprint`、`Items`、`Details`、`Capabilities`。
   - `Details` 按 workflow name 建 typed map/list，承载现有 `WorkflowCatalogItemDetail` 所需内容。

2. 把 `FileBackedWorkflowCatalogPort` 的拼装能力降级为 startup materializer 内部 builder。
   - 保留 parser、source classification、primitive/capability 构造逻辑，但只允许 startup materializer 调用。
   - 删除在线端口上的 `_cacheLock`、`_workflowFileDiscoveryCache`、`_parsedWorkflowCache`。
   - `Directory.EnumerateFiles`、`WorkflowParser.Parse`、`AevatarConnectorConfig.LoadConnectors()` 只能出现在 startup loader/materializer/builder，不得出现在 query port。

3. 启动期物化。
   - `WorkflowDefinitionBootstrapHostedService.StartAsync` 继续先调用 `WorkflowDefinitionFileLoader.LoadInto(...)` 注册 file-backed definitions。
   - 随后调用 `WorkflowCatalogStartupMaterializer.MaterializeAsync(...)`：
     - 从 `IWorkflowDefinitionCatalog.GetNames()/GetDefinition()` 读取启动期 registry；
     - 从同一启动期目录发现结果解析 source kind；
     - 一次性解析 YAML；
     - 一次性读取 connector config；
     - 计算 `SourceFingerprint`，例如对 workflow name + yaml + source kind + connector config 的稳定排序内容取 hash；
     - 写入 `WorkflowCatalogDocument`。
   - materializer 失败应 fail startup 或明确记录不可用状态；不要在 query 时补跑。

4. 在线 query port 改为 readmodel reader。
   - 新增/替换 `ReadModelWorkflowCatalogPort : IWorkflowCatalogPort, IWorkflowCapabilitiesPort`。
   - `ListWorkflowCatalog()` 读取 `WorkflowCatalogDocument` 并返回 `Items` 排序结果。
   - `GetWorkflowDetail(name)` 从 document 的 detail map/list 查找。
   - `GetCapabilities()` 返回 document 内已物化 capabilities；`GeneratedAtUtc` 映射为 readmodel 的 `MaterializedAtUtc`，不在方法内取 `UtcNow`。
   - document 缺失时返回空 catalog + 明确 freshness 缺失，或抛出启动配置错误；不要 fallback 到文件扫描。

5. DI 边界。
   - `AddWorkflowDefinitionFileSource` 注册 `WorkflowCatalogStartupMaterializer` 和 readmodel store。
   - `IWorkflowCatalogPort` / `IWorkflowCapabilitiesPort` 指向 readmodel-backed port，不再指向 `FileBackedWorkflowCatalogPort`。
   - 若保留 `FileBackedWorkflowCatalogPort` 名称，应改名为 `WorkflowCatalogStartupMaterializer` / `WorkflowCatalogDocumentBuilder`，避免 query-port 语义误导。

6. Guards/tests。
   - 单元测试：启动 materializer 写出完整 catalog/detail/capabilities；query port 只读 document。
   - 单元测试：document `GeneratedAtUtc`/freshness 来自 materializer，不随连续查询变化。
   - 静态 guard：workflow query ports 不得包含 `Directory.EnumerateFiles`、`WorkflowParser.Parse`、`AevatarConnectorConfig.LoadConnectors()`、`lock (`、`_cacheLock`、`ParsedWorkflowCacheEntry`、`FileDiscoveryCacheEntry`。
   - DI 测试更新：`IWorkflowCatalogPort` / `IWorkflowCapabilitiesPort` 解析为 readmodel-backed port。

## Evidence cite

- issue #871 body 指出 `FileBackedWorkflowCatalogPort` 在查询方法里现场扫目录、读 YAML、解析 workflow，并用 singleton 内存缓存结果。
- `.refactor-loop/runs/audit-iter-46.md` cluster-046 指出旧模式是 catalog/capabilities query port 在 query execution 中 discover files / parse YAML / load connector config / cache；新模式要求 query ports read materialized readmodels with explicit version/freshness。
- `src/workflow/Aevatar.Workflow.Infrastructure/Workflows/FileBackedWorkflowCatalogPort.cs` 当前 `ListWorkflowCatalog` / `GetWorkflowDetail` / `GetCapabilities` 调用 `DiscoverWorkflowFiles()`、`TryGetCachedDefinition()`、`AevatarConnectorConfig.LoadConnectors()`。
- 同文件当前有 `_cacheLock`、`_workflowFileDiscoveryCache`、`_parsedWorkflowCache`，命中 MIDDLE-STATE 与 ACTOR-LOCK 风险。
- `src/workflow/Aevatar.Workflow.Infrastructure/Workflows/WorkflowDefinitionBootstrapHostedService.cs` 已有启动期加载阶段，可作为 minimal materialization hook。
- `src/workflow/Aevatar.Workflow.Application.Abstractions/Workflows/IWorkflowDefinitionCatalog.cs` 明确当前 definition catalog 是 startup-loaded configuration cache；这支持 minimal 方案选择“不支持 hot reload”。
- `src/workflow/README.md` 与 `src/workflow/Aevatar.Workflow.Core/WorkflowGAgent.cs` 已表达 `WorkflowGAgent` 是 workflow definition facts owner。
- `rg` 未发现 workflow 侧现有 `WorkflowCatalogActor` / `WorkflowCatalogGAgent`；新增 actor 会扩大本 cluster。
- CLAUDE.md 要求查询走 readmodel、禁止 query-time priming、禁止 lock/ConcurrentDictionary 维护事实状态、readmodel 诚实暴露刷新戳。

## Tradeoffs

- 优点：最小 blast radius；复用现有启动加载链路；不新增 actor；不改 workflow DSL；在线查询路径立即满足 readmodel-only。
- 代价：多实例一致性仍依赖每个节点相同启动输入源；这是当前 `IWorkflowDefinitionCatalog` 已声明的部署约束，不在本 issue 内升级为分布式 catalog authority。
- 风险：如果产品需要运行时热加载或跨节点动态 authoring，本方案不足；那应另开设计，使用 `WorkflowGAgent` command/event 或 catalog aggregate actor，而不是让 query port 现场扫文件。
- intentional deferral：不做 hot reload、不新增 `WorkflowCatalogActor`、不调整 workflow authoring 语义、不把 connector config 改成独立 actor-owned fact。

## Verification

实现 PR 应至少运行：

- `dotnet test test/Aevatar.Workflow.Host.Api.Tests/Aevatar.Workflow.Host.Api.Tests.csproj --nologo`
- `dotnet test test/Aevatar.Workflow.Application.Tests/Aevatar.Workflow.Application.Tests.csproj --nologo`
- `bash tools/ci/test_stability_guards.sh`
- `bash tools/ci/query_projection_priming_guard.sh`
- `bash tools/ci/projection_state_version_guard.sh`
- `bash tools/ci/projection_state_mirror_current_state_guard.sh`
- `bash tools/ci/architecture_guards.sh`
- `dotnet build aevatar.slnx --nologo`

SOLVER_DONE:minimal:propose:startup materialize file-backed workflow catalog once into a freshness-bearing readmodel; query ports read it only, no new actor

⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Phase 9 Solver — delete (round r1)

Role: delete
Issue: #871 cluster-046-workflow-file-catalog-query-port

Decision: propose

Delete FileBackedWorkflowCatalogPort as an online query source. File-backed workflow YAML can remain only as an import/bootstrap input, not as a read-path authority. The existing docs and code already identify WorkflowGAgent as the definition fact owner; no WorkflowCatalogActor exists today, and adding one as the first move would create a second aggregate unless a real catalog-owned business fact is identified.

SOLVER_DONE:delete:propose:delete-online-file-backed-catalog-query-port-keep-file-yaml-as-import-only-to-workflowgagent-readmodels

raw

Evidence Read

• Issue [refactor-design] iter46 cluster-046-workflow-file-catalog-query-port: Workflow catalog 查询现场扫文件 + singleton 缓存事实 #871 body: workflow catalog/capabilities queries enumerate files, parse YAML, load connector config, cache in singleton memory, and stamp GeneratedAtUtc = DateTimeOffset.UtcNow.
• .refactor-loop/runs/audit-iter-46.md cluster-046: same evidence, rule ids RM-QUERY-READMODEL, MIDDLE-STATE, ACTOR-LOCK, RM-HONESTY.
• CLAUDE.md: queries read readmodels; query-time replay/priming is forbidden; middle-layer process dictionaries must not hold workflow/session facts; actor state is the single-threaded fact source; weak reads must expose authority-aligned version/watermark.
• src/workflow/README.md: WorkflowGAgent owns workflow definition facts, WorkflowRunGAgent owns run facts, and workflow read side uses the unified Projection Pipeline.
• Grep found WorkflowGAgent but no WorkflowCatalogActor in src/workflow.

Current Shape

FileBackedWorkflowCatalogPort is registered as the online implementation for both IWorkflowCatalogPort and IWorkflowCapabilitiesPort when file sources are enabled:

• src/workflow/Aevatar.Workflow.Infrastructure/DependencyInjection/ServiceCollectionExtensions.cs:40-44

Its read methods do runtime work that belongs outside query execution:

• ListWorkflowCatalog() calls DiscoverWorkflowFiles() and then reads/parses registry YAML.
• GetWorkflowDetail() parses YAML and computes edges during the query call.
• GetCapabilities() calls DiscoverWorkflowFiles(), AevatarConnectorConfig.LoadConnectors(), and returns a local wall-clock GeneratedAtUtc.

The process-local state is explicit:

• _cacheLock
• _workflowFileDiscoveryCache
• _parsedWorkflowCache

The mutation path is under lock (_cacheLock) around file discovery and parsed workflow cache writes. This is not actor-owned state and not a readmodel.

Delete Position

The file-backed catalog query port is not necessary as a runtime read source. It duplicates information already loaded into startup registry/bootstrap and conflicts with the repository's definition-actor architecture.

Delete:

1. FileBackedWorkflowCatalogPort entirely.
2. Its DI replacement from AddWorkflowDefinitionFileSource.
3. Any online query-port code that calls Directory.EnumerateFiles, _parser.Parse, File.ReadAllText, or AevatarConnectorConfig.LoadConnectors() to answer catalog/capability queries.
4. Tests that assert read-path file discovery/cache behavior.

Keep, but narrow:

1. WorkflowDefinitionFileLoader as import-only infrastructure.
2. WorkflowDefinitionBootstrapHostedService only if it dispatches/binds startup definitions into the authoritative definition actors, or is treated as a temporary migration step until that binding is done.
3. File paths/source kind as import provenance, captured during import and then emitted through actor/projection facts. Do not rediscover them during queries.

Fact Owner

Use existing WorkflowGAgent per definition as the fact owner.

Rationale:

• WorkflowGAgent already persists WorkflowName, WorkflowYaml, InlineWorkflowYamls, Compiled, CompilationError, and Version.
• WorkflowGAgent already parses/validates at bind time, so moving catalog detail derivation to committed-state projection avoids a second query-time parser.
• The repo docs explicitly say one workflow definition corresponds to one WorkflowGAgent.
• There is no existing WorkflowCatalogActor.

Do not add WorkflowCatalogActor in this issue unless the final design identifies a real aggregate fact that is not derivable from definition actor readmodels. A list endpoint is not enough reason; listing can be readmodel index/query behavior over definition documents.

File-Backed Workflow Necessity

File-backed workflows appear to be a product/developer feature: repo workflows, user home workflows, and capability discovery are live surfaces. Deleting the feature outright is too broad for #871.

The delete proposal is therefore:

• delete file-backed as query-time behavior;
• keep file-backed as import-only behavior.

Import-only means:

1. startup or explicit reload command enumerates configured directories;
2. each YAML file is normalized into a BindWorkflowDefinitionEvent on the canonical WorkflowGAgent id;
3. WorkflowGAgent commits definition state/version;
4. committed-state projection writes actor-scoped workflow definition/catalog documents;
5. query ports read those documents/indexes only.

Hot reload should not be implicit file polling in query methods. If retained, it should be an explicit command/import run that produces the same actor events as startup.

Readmodel Shape

Add a workflow definition/catalog current-state readmodel projected from WorkflowGAgent committed state. It should expose at least:

• definition actor id;
• workflow name;
• source/provenance (builtin, repo, home, app, cwd, turing, file) captured at import;
• YAML or a stable detail DTO, depending on public API decision;
• compiled/invalid status and compilation error;
• definition version from WorkflowGAgent.State.Version;
• observed/materialized timestamp from committed envelope timestamp, not DateTimeOffset.UtcNow in query;
• catalog fields currently computed by BuildCatalogItem, BuildDefinition, ComputeEdges, and workflow capability mapping.

Capability document freshness should be derived from the readmodel set's source versions or projection watermark. If connectors remain external host config, their capability import must likewise happen at startup/explicit reload and expose a host config version/watermark; do not call LoadConnectors() from the query port.

Multi-Source Merge

Merge order and duplicate policy belong to import/bootstrap, not query:

• user home + repo + app/cwd/turing directories are resolved during import;
• duplicate handling remains explicit via WorkflowDefinitionDuplicatePolicy;
• the winning entry binds the canonical definition actor;
• source/provenance travels with the bind/import event or typed projection input.

This makes multi-node consistency honest: either all nodes import the same files and produce the same actor facts, or the readmodel reveals the committed version/source that won. Query results no longer depend on which process handled the request.

Guard/Tests

Add guard coverage after implementation:

• no Directory.EnumerateFiles in *WorkflowCatalog*Query*, *WorkflowCatalogPort*, or workflow query application services;
• no WorkflowParser.Parse in workflow catalog/capability query ports;
• no AevatarConnectorConfig.LoadConnectors() in query ports;
• no _cacheLock, Dictionary<string, ParsedWorkflowCacheEntry>, or FileDiscoveryCacheEntry in workflow catalog query implementations;
• query DTOs expose actor-aligned version/watermark instead of local GeneratedAtUtc.

Scope Answer

This should be one design decision, then implementation can split:

1. actor/import path: bind file definitions to WorkflowGAgent;
2. projection/readmodel path: materialize workflow definition/catalog documents;
3. query/API path: replace catalog/capability ports with document-backed reads and delete FileBackedWorkflowCatalogPort;
4. guard/test path: prevent regression.

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Phase 9 Solver — structural (round r1)

SOLVER_DONE:structural:propose:bind-file-backed-definitions-into-WorkflowGAgent-at-startup-and-serve-catalog-capabilities-from-versioned-projection-readmodels

raw

Phase 9 Solver — structural — issue #871 round r1

Decision

Propose the structural fix.

Use the existing per-definition WorkflowGAgent as the authority for workflow definition facts. Do not add a WorkflowCatalogActor for this issue: catalog is a query shape over definition actors, not a separate business entity with independent facts.

File-backed workflow discovery becomes write-side bootstrap/materialization work:

1. Discover built-in, repo, and user-home workflow YAML during startup activation or a background materializer.
2. Resolve each workflow name to the stable WorkflowDefinitionActorId.Format(name).
3. Dispatch/bind the YAML into that WorkflowGAgent through the normal actor command/event path.
4. Let committed state publication feed the existing Projection Pipeline.
5. Query catalog/capabilities from materialized projection documents only.

Evidence Read

• Issue [refactor-design] iter46 cluster-046-workflow-file-catalog-query-port: Workflow catalog 查询现场扫文件 + singleton 缓存事实 #871 says FileBackedWorkflowCatalogPort currently scans files, parses YAML, loads connector config, and uses singleton process-local caches during query.
• .refactor-loop/runs/audit-iter-46.md cluster-046 identifies the same violation: query-time file discovery/parsing plus _cacheLock, _workflowFileDiscoveryCache, and _parsedWorkflowCache.
• src/workflow/Aevatar.Workflow.Infrastructure/Workflows/FileBackedWorkflowCatalogPort.cs confirms the online query methods call DiscoverWorkflowFiles(), _parser.Parse(...), and AevatarConnectorConfig.LoadConnectors().
• grep confirms no WorkflowCatalogActor exists.
• src/workflow/Aevatar.Workflow.Core/WorkflowGAgent.cs already names itself "Workflow definition actor" and owns WorkflowYaml, WorkflowName, ScopeId, Compiled, CompilationError, and Version.
• CLAUDE.md requires Query -> ReadModel, no query-time priming/replay, no middle-layer process-local fact maps, no lock as a fact-state patch, and readmodel freshness/version honesty.

Target Structure

Fact owner

WorkflowGAgent remains the sole authority for each workflow definition.

Required state/event shape:

• Keep BindWorkflowDefinitionEvent as the write fact.
• Extend the actor-owned state/root, if needed, with typed definition summary fields that are stable query semantics:
  • normalized workflow name
  • source kind/source label, if source is business-visible
  • description
  • compiled flag and compilation error
  • required primitives
  • required connectors
  • workflow calls
  • catalog classification fields that are business-visible
• Do not put these in a generic bag.
• Do not make projection parse YAML to rediscover these facts if WorkflowGAgent can determine them while applying/compiling the definition.

Projection readmodels

Add actor-scoped current-state readmodels under workflow projection, for example:

• WorkflowDefinitionCatalogDocument
  • key: DefinitionActorId
  • authority: WorkflowGAgent
  • fields: catalog item/detail data, YAML if the current public detail API still returns YAML, compiled status, source fields, query summary fields
  • freshness: AuthorityVersion = state_event.Version, LastEventId, ProjectedAtUtc
• WorkflowDefinitionCapabilityDocument
  • key: DefinitionActorId
  • authority: WorkflowGAgent
  • fields: workflow capability rows already derived from the committed definition state
  • freshness: same authority version fields

If a single capabilities response is still required, build it by reading these projection documents and mapping them to the existing DTO. That mapping may sort/filter; it must not parse YAML, scan directories, load connector files, or mutate process caches.

For primitive and connector capability sections, remove request-time WorkflowCoreModulePack/AevatarConnectorConfig.LoadConnectors() construction from the query port. Materialize those stable runtime capabilities at startup into a versioned projection document or actor-owned capability definition before the API serves them. If maintainers decide connector capability is truly mutable business state, introduce a narrow capability-owner actor in a separate issue; do not hide it inside FileBackedWorkflowCatalogPort.

Query port

Replace FileBackedWorkflowCatalogPort with a projection-backed query port in the projection/infrastructure boundary:

• ListWorkflowCatalog() reads WorkflowDefinitionCatalogDocument documents.
• GetWorkflowDetail(name) looks up the normalized name in readmodels, preferably by an indexed field or explicit name document, not by scanning files.
• GetCapabilities() reads workflow capability documents plus the pre-materialized runtime capability document.
• The port exposes freshness honestly:
  • per catalog item/detail: DefinitionActorId, AuthorityVersion, LastEventId, ProjectedAtUtc
  • capabilities document: a list of source watermarks, not a fake DateTimeOffset.UtcNow
  • if GeneratedAtUtc must remain for API compatibility in one pass, populate it from projection ProjectedAtUtc and mark/rename it in the same PR or immediate follow-up.

Do not expose a single global StateVersion for a multi-definition catalog unless there is an aggregate actor that owns that exact aggregate fact. Per-definition versions are independent.

Startup/file discovery

Replace WorkflowDefinitionBootstrapHostedService -> WorkflowDefinitionCatalog.Register(...) as the query authority with a write-side activation path:

• The loader may still enumerate files during startup/background materialization.
• The loader outputs typed bootstrap commands/records, not a read cache.
• Duplicate policy and multi-source merge are resolved before dispatch.
• The resulting authoritative facts live in the destination WorkflowGAgent state after commit.
• Hot reload is out of scope for the first structural fix; if needed later, file watcher events should dispatch the same bind/update command and wait for projection observation asynchronously.

Multi-source rule:

• Keep a deterministic precedence order: built-in -> repo/workflows -> configured user-home dirs, with the existing duplicate policy (throw/skip/override) made explicit in the startup materializer.
• The query path never re-merges sources.

Files/Areas To Change

• Delete or fully retire src/workflow/Aevatar.Workflow.Infrastructure/Workflows/FileBackedWorkflowCatalogPort.cs from online query registration.
• Update src/workflow/Aevatar.Workflow.Infrastructure/DependencyInjection/ServiceCollectionExtensions.cs so file-source registration wires startup activation/materialization, not query ports.
• Add workflow definition catalog/capability readmodel proto + partials under src/workflow/Aevatar.Workflow.Projection/ReadModels/.
• Add projectors under src/workflow/Aevatar.Workflow.Projection/Projectors/ using CommittedStateEventEnvelope.TryUnpackState<WorkflowState>() and state_event.Version.
• Register document metadata/providers/query ports in workflow projection DI and hosting provider extensions.
• Update WorkflowExecutionQueryApplicationService dependencies only if the abstraction shape changes to expose watermarks.
• Update public query DTOs in Aevatar.Workflow.Application.Abstractions.Queries to carry authority freshness.
• Add tests around startup activation, projector overwrite/version, and query-port no-file/no-parse behavior.
• Add a guard that fails if workflow query ports contain Directory.EnumerateFiles, _parser.Parse, AevatarConnectorConfig.LoadConnectors, _cacheLock, _parsedWorkflowCache, or _workflowFileDiscoveryCache.

Rejected Alternatives

• Keep FileBackedWorkflowCatalogPort and just remove TTL cache: rejected. Query would still be rebuilding facts from filesystem/YAML instead of readmodels.
• Add WorkflowCatalogActor immediately: rejected for this issue. The catalog is a read shape over per-definition facts. A new aggregate actor is only justified if the product needs a single independently versioned catalog fact.
• Use a singleton distributed cache as the read source: rejected. It replaces process-local state with infrastructure-local state but still bypasses actor-owned authority and projection freshness.
• Query WorkflowGAgent directly for each definition: rejected. That is generic actor query/reply in another form; external queries must read readmodels.

Verification Plan

• Unit tests:
  • startup materializer dispatches file definitions to stable WorkflowGAgent ids and does not populate a query cache.
  • projector writes WorkflowDefinitionCatalogDocument with AuthorityVersion == state_event.Version.
  • stale projection writes do not overwrite newer documents.
  • query port returns catalog/detail/capabilities from readmodels without invoking file discovery, parser, or connector config loader.
• Integration/API tests:
  • /api/.../workflow catalog returns the same rows as before, plus freshness fields.
  • capabilities response uses projection watermarks instead of UtcNow.
• Guards:
  • bash tools/ci/query_projection_priming_guard.sh
  • bash tools/ci/projection_state_version_guard.sh
  • bash tools/ci/projection_state_mirror_current_state_guard.sh
  • bash tools/ci/architecture_guards.sh
  • new/extended workflow catalog query guard described above.

Escalation Triggers

• Escalate only if maintainers require a single globally versioned workflow catalog document. That requires an explicit aggregate actor owning the aggregate fact; it should not be smuggled into a query port.
• Escalate if hot reload must be in the same PR. Hot reload changes lifecycle semantics and should use the same write command plus projection observation, not request-time file reads.

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Phase 9 Meta-judge — r1 verdict: consensus

META_JUDGE_DONE:consensus:WorkflowGAgent remains per-definition authority; file-backed workflow YAML is startup/import input only; online catalog/capabilities queries read freshness-bearing readmodels:no new WorkflowCatalogActor; retire FileBackedWorkflowCatalogPort as an online query source; move discovery/parsing/connector loading to startup/import materialization; project WorkflowGAgent committed definition state into catalog/capability readmodels with authority version or projection watermark; query ports only map/sort readmodel documents; add guards against Directory.EnumerateFiles, WorkflowParser.Parse, AevatarConnectorConfig.LoadConnectors, _cacheLock, _workflowFileDiscoveryCache, and _parsedWorkflowCache in workflow query ports

raw

Meta-judge result for issue #871, cluster-046-workflow-file-catalog-query-port, round r1.

Verdict: consensus.

I read all three solver artifacts in full:

• .refactor-loop/runs/solver-minimal-issue-871.md
• .refactor-loop/runs/solver-structural-issue-871.md
• .refactor-loop/runs/solver-delete-issue-871.md

Structural validation:

• The structural artifact is genuinely about cluster-046, not stale old-cluster content.
• It names FileBackedWorkflowCatalogPort, issue [refactor-design] iter46 cluster-046-workflow-file-catalog-query-port: Workflow catalog 查询现场扫文件 + singleton 缓存事实 #871, cluster-046 evidence, workflow YAML discovery/parsing, connector config loading, workflow catalog/capabilities query ports, and WorkflowGAgent.
• It explicitly says not to add WorkflowCatalogActor for this issue.
• The artifact marker observed in the file is aligned: SOLVER_DONE:structural:propose:bind-file-backed-definitions-into-WorkflowGAgent-at-startup-and-serve-catalog-capabilities-from-versioned-projection-readmodels.
• Therefore the suspicious marker wording noted in the prompt is not the operative substance of the artifact.

Consensus framing:

• Existing per-definition WorkflowGAgent remains the authority for workflow definition facts.
• File-backed YAML remains only a startup/import/bootstrap input, not an online query authority.
• The online FileBackedWorkflowCatalogPort behavior must be deleted or retired from DI as the implementation of IWorkflowCatalogPort / IWorkflowCapabilitiesPort.
• Query ports must read materialized catalog/capability readmodels only.
• File discovery, YAML parsing, duplicate/source merge, and connector capability loading happen during startup/import/materialization, not inside request-time query methods.
• Read responses must expose honest freshness: authority version, projection watermark, or materialized timestamp, not query-time DateTimeOffset.UtcNow.
• Hot reload and a globally versioned aggregate catalog are out of scope unless separately designed.

Concrete plan:

1. Replace online FileBackedWorkflowCatalogPort registration with a readmodel-backed catalog/capability query port.
2. Move file discovery, YAML parsing, source precedence, duplicate policy, and connector config capability extraction to startup/import materialization.
3. Bind/import file-backed definitions into the existing WorkflowGAgent authority path where feasible; at minimum materialize startup-loaded definitions into explicit freshness-bearing readmodel documents without request-time rescans.
4. Project committed WorkflowGAgent definition state into actor-scoped catalog/detail/capability readmodels with authority-aligned versions or projection watermarks.
5. Map ListWorkflowCatalog, GetWorkflowDetail, and GetCapabilities from those documents only.
6. Delete process-local fact caches from the online read path: _cacheLock, _workflowFileDiscoveryCache, _parsedWorkflowCache.
7. Add tests/guards preventing Directory.EnumerateFiles, WorkflowParser.Parse, AevatarConnectorConfig.LoadConnectors, _cacheLock, _workflowFileDiscoveryCache, and _parsedWorkflowCache from reappearing in workflow query ports.

Hardcoded trigger audit:

• No solver marker is escalate.
• The issue labels do not include design-philosophy.
• The consensus plan does not add a new actor type. In particular, it rejects WorkflowCatalogActor for this issue.
• The consensus plan does not add a new envelope kind.
• The consensus plan does not add a new Projection Pipeline phase.
• The consensus plan does not require docs/canon/* vocabulary changes.
• Therefore the no-new-actor hardcoded trigger does not fire.

POSTED:meta-judge:issue-871:r1:#871 (comment)

⟦AI:AUTO-LOOP⟧

[loning]

✅ 共识卡片 — Phase 9 r1 consensus reached

维度	值
Issue	#871 cluster-046-workflow-file-catalog-query-port
Round	r1(共识 1 轮)
选定 framing	consensus(WorkflowGAgent per-definition authority + readmodel facade + no new actor)
Solver 投票	minimal: propose · structural: propose(aligned despite confusing marker)· delete: propose
Meta-judge 仲裁	retire FileBackedWorkflowCatalogPort online;file discovery/parsing 改 startup/import time;query ports read readmodels;projection from WorkflowGAgent committed state;exposed freshness watermark;guards 防 Directory.EnumerateFiles/WorkflowParser.Parse/LoadConnectors/lock/cache 复活
是否需要 maintainer 介入	❌ 否

📦 worktree:/Users/auric/aevatar-wt-iter46-cluster-046-workflow-file-catalog-query-port

🤖 controller consensus card

⟦AI:AUTO-LOOP⟧

[loning]

📊 codex 进展 phase9-issue871-r1-delete (⏳ 进行中; 已跑 8 min)

+- query DTOs expose actor-aligned version/watermark instead of local `GeneratedAtUtc`.
+
+## Scope Answer
+
+This should be one design decision, then implementation can split:
+
+1. actor/import path: bind file definitions to `WorkflowGAgent`;
+2. projection/readmodel path: materialize workflow definition/catalog documents;
+3. query/API path: replace catalog/capability ports with document-backed reads and delete `FileBackedWorkflowCatalogPort`;
+4. guard/test path: prevent regression.
+
+</details>
+
+⟦AI:AUTO-LOOP⟧
+
+POSTED:https://github.com/aevatarAI/aevatar/issues/871#issuecomment-4524395281

tokens used
91,167
Done.

Created [solver-delete-issue-871.md](/Users/auric/aevatar/.refactor-loop/runs/solver-delete-issue-871.md) with:

`SOLVER_DONE:delete:propose:delete-online-file-backed-catalog-query-port-keep-file-yaml-as-import-only-to-workflowgagent-readmodels`

自动更新每 10 分钟;edit-in-place 不堆评论;codex 完成后此 comment 自动删除(per Auric "完成后删掉就好了 否则太占空间")。
🤖 controller progress reporter

[loning]

📊 codex 进展 phase9-issue871-r1-judge (⏳ 进行中; 已跑 4 min)

+6. Delete process-local fact caches from the online read path: `_cacheLock`, `_workflowFileDiscoveryCache`, `_parsedWorkflowCache`.
+7. Add tests/guards preventing `Directory.EnumerateFiles`, `WorkflowParser.Parse`, `AevatarConnectorConfig.LoadConnectors`, `_cacheLock`, `_workflowFileDiscoveryCache`, and `_parsedWorkflowCache` from reappearing in workflow query ports.
+
+Hardcoded trigger audit:
+
+- No solver marker is `escalate`.
+- The issue labels do not include `design-philosophy`.
+- The consensus plan does not add a new actor type. In particular, it rejects `WorkflowCatalogActor` for this issue.
+- The consensus plan does not add a new envelope kind.
+- The consensus plan does not add a new Projection Pipeline phase.
+- The consensus plan does not require `docs/canon/*` vocabulary changes.
+- Therefore the no-new-actor hardcoded trigger does not fire.
+
+</details>
+
+POSTED:meta-judge:issue-871:r1:https://github.com/aevatarAI/aevatar/issues/871#issuecomment-4524398916
+
+⟦AI:AUTO-LOOP⟧

tokens used
31,079
Consensus verdict posted to issue #871:

https://github.com/aevatarAI/aevatar/issues/871#issuecomment-4524398916

自动更新每 10 分钟;edit-in-place 不堆评论;codex 完成后此 comment 自动删除(per Auric "完成后删掉就好了 否则太占空间")。
🤖 controller progress reporter