Clarify StreamingProxy projection lease scope semantics

[louis4li]

---

id: cluster-triage-streamingproxy-projection-lease-scope-semantics
severity: medium
requires_design: true

来源

本 issue 由 maintainer 手动开，triage codex 深度调研补 evidence。

核心问题

StreamingProxyRoomSessionRuntimeLease.ScopeId 当前返回 RootEntityId，而 RootEntityId 是 room actor id，不是业务 scope id。这个错位不是单点命名问题：通用 IProjectionPortSessionLease、EventSinkProjectionLifecyclePortBase 和 ProjectionSessionEventHub 都把第一维命名为 ScopeId，但 StreamingProxy 的生产投影链路实际传入 actor id，导致 projection session lease/transport contract 可以被 future consumers 误用。

Evidence

1. StreamingProxy lease 把 actor id 同时暴露为 ActorId 与 ScopeId

agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionRuntimeLease.cs:19

public string ActorId => RootEntityId;

public string SessionId { get; }

public StreamingProxyRoomSessionProjectionContext Context { get; }

public string ScopeId => RootEntityId;

违反点：ActorId 和 ScopeId 都返回 RootEntityId，字段名表达两个不同语义。

2. StreamingProxy session context 没有业务 scope id

agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionProjectionContext.cs:5

public sealed class StreamingProxyRoomSessionProjectionContext : IProjectionSessionContext
{
    public required string SessionId { get; init; }

    public required string RootActorId { get; init; }

    public required string ProjectionKind { get; init; }
}

违反点：context 只提供 RootActorId、SessionId、ProjectionKind；lease 却被通用 contract 要求提供 ScopeId，于是把 actor id alias 成 scope id。

3. 通用 projection session lease contract 强制使用 ScopeId 命名

src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Ports/IProjectionPortSessionLease.cs:6

public interface IProjectionPortSessionLease
{
    string ScopeId { get; }

    string SessionId { get; }
}

违反点：这是通用 projection sink subscription orchestration contract，但第一维并不总是业务 scope；在 StreamingProxy、Workflow、Scripting、GAgentDraftRun 等 actor-scoped session lease 中，现有实现普遍返回 actor id。

4. Lifecycle base 将错误语义继续传给 session hub

src/Aevatar.CQRS.Projection.Core/Orchestration/EventSinkProjectionLifecyclePortBase.cs:51

return await _sessionEventHub.SubscribeAsync(
    portLease.ScopeId,
    portLease.SessionId,
    evt => sink.PushAsync(evt, CancellationToken.None),
    ct).ConfigureAwait(false);

违反点：ScopeId 被作为 session event hub 的分区 key 传播，隐藏了真实第一维是 actor/session owner key。

5. Session event hub API/transport message 也叫 ScopeId

src/Aevatar.CQRS.Projection.Core/Streaming/ProjectionSessionEventHub.cs:30

public Task PublishAsync(
    string scopeId,
    string sessionId,
    TEvent evt,
    CancellationToken ct = default)
{
    ...
    var stream = _streamProvider.GetStream(ResolveStreamId(scopeId, sessionId));
    var message = new ProjectionSessionEventTransportMessage
    {
        ScopeId = scopeId,
        SessionId = sessionId,
        EventType = _codec.GetEventType(evt),
        Payload = _codec.Serialize(evt),
    };

违反点：transport 第一维被命名/序列化为 ScopeId，但 StreamingProxy projector 传入的是 RootActorId。

6. StreamingProxy projector 明确用 RootActorId 作为第一维

agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionEventProjector.cs:30

return
[
    new ProjectionSessionEventEntry<StreamingProxyRoomSessionEnvelope>(
        context.RootActorId,
        context.SessionId,
        new StreamingProxyRoomSessionEnvelope
        {
            Envelope = envelope,
        }),
];

违反点：投影入口本身表达的是 actor-scoped session key；下游却把这个 key 命名成 ScopeId。

7. 测试已经固化 actor id as ScopeId

test/Aevatar.AI.Tests/NyxIdChatEndpointsCoverageTests.cs:2466

sessionHub.Published.Should().HaveCount(3);
sessionHub.Published[0].Event.TextMessageContent.Delta.Should().Be("delta-1");
sessionHub.Published[1].Event.EventCase.Should().Be(AGUIEvent.EventOneofCase.TextMessageEnd);
sessionHub.Published[2].Event.EventCase.Should().Be(AGUIEvent.EventOneofCase.RunFinished);
sessionHub.Published.Should().OnlyContain(x => x.ScopeId == "actor-1" && x.SessionId == "session-1");

违反点：测试层也接受了 ScopeId == actor id，后续修复必须同步改测试语义。

违反条款

AGENTS.md:

API 字段单一语义：一个字段只能表达一个含义，禁止同字段承载“名称查找 + inline 内容”等双重语义。

追踪标识与目标身份必须分离：commandId/correlationId 用于追踪一次请求，actorId 用于标识处理实体；禁止把追踪 ID 与目标身份混成同一语义，也不得假设二者天然一一对应。

命名必须跟随职责语义：接口、类型、目录命名应描述职责与边界，而不是绑定暂时实现路径；一旦底层实现可替换，命名不得泄露 runtime/stream/protocol 偶然细节。

CLAUDE.md:

API 字段单一语义：一个字段只表达一个含义，禁止双重语义（如"名称查找 + inline 内容"）。

身份与事实分离：稳定 ID 只负责寻址与复用键；可变绑定必须显式建模、显式读取。

命名跟随职责：接口/类型/目录命名描述职责边界，不泄露 runtime/stream/protocol 偶然细节。

新原则

Projection session event 的第一维应按真实职责命名为 actor/session owner key（例如 RootActorId / OwnerActorId / SessionOwnerId，由 solver 统一决策），不得继续用 ScopeId 承载 actor id。若某个 projection session 确实需要业务 scope id，应作为独立 typed field 显式建模，而不是复用 transport partition key。

Fix boundary

scope_paths:

• agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionRuntimeLease.cs
• agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionProjectionContext.cs
• agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionEventProjector.cs
• agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionProjectionPort.cs
• agents/Aevatar.GAgents.StreamingProxy/ServiceCollectionExtensions.cs
• src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Ports/IProjectionPortSessionLease.cs
• src/Aevatar.CQRS.Projection.Core/Orchestration/EventSinkProjectionLifecyclePortBase.cs
• src/Aevatar.CQRS.Projection.Core/Streaming/ProjectionSessionEventHub.cs
• src/Aevatar.CQRS.Projection.Core/projection_session_event_transport.proto
• src/Aevatar.Scripting.Projection/Orchestration/ScriptExecutionRuntimeLease.cs
• src/Aevatar.Scripting.Projection/Orchestration/ScriptEvolutionRuntimeLease.cs
• src/workflow/Aevatar.Workflow.Projection/Orchestration/WorkflowExecutionRuntimeLease.cs
• src/platform/Aevatar.GAgentService.Projection/Orchestration/GAgentDraftRunRuntimeLease.cs
• src/platform/Aevatar.GAgentService.Projection/Orchestration/ScriptServiceAguiRuntimeLease.cs
• test/Aevatar.AI.Tests/NyxIdChatEndpointsCoverageTests.cs
• test/Aevatar.CQRS.Projection.Core.Tests/ProjectionPortBaseCoverageTests.cs
• test/Aevatar.CQRS.Projection.Core.Tests/ProjectionRuntimeRegistrationTests.cs
• test/Aevatar.GAgentService.Tests/Projection/GAgentDraftRunProjectionInfrastructureTests.cs
• test/Aevatar.Workflow.Host.Api.Tests/WorkflowExecutionProjectionPortTests.cs
• test/Aevatar.Workflow.Host.Api.Tests/WorkflowProjectionReadModelCoverageTests.cs

Decision questions

1. 通用 IProjectionPortSessionLease 的第一维应命名为 RootActorId、OwnerActorId、SessionOwnerId 还是更贴近 projection scope key 的名称？
2. ProjectionSessionEventTransportMessage.ScopeId 是否需要 proto 字段演进为新字段，并 reserve/兼容旧字段，还是仅在 internal API 层 rename？
3. StreamingProxy/NyxIdChat/Workflow/Scripting/GAgentService projection session leases 是否应一次性统一，避免只修 StreamingProxy 后保留同类错位？
4. 如果部分 session event consumer 真需要业务 scope id，是否新增独立 typed field，而不是复用 transport key？
5. 是否需要补一个 architecture guard，禁止 IProjectionPortSessionLease.ScopeId => RootEntityId 或 ScopeId == actor-id 的回归？

original_authors

• agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionRuntimeLease.cs: louis.li
• agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionEventProjector.cs: louis.li
• agents/Aevatar.GAgents.StreamingProxy/ServiceCollectionExtensions.cs: history shows StreamingProxy projection/session registration work around Unify AGUI streaming through projection sessions
• src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Ports/IProjectionPortSessionLease.cs: history shows event sink/projection lifecycle abstraction introduction
• src/Aevatar.CQRS.Projection.Core/Streaming/ProjectionSessionEventHub.cs: history shows projection session transport/codec evolution

cc

原作者信息已记录在 original_authors，本条不添加直接提及。

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Triage codex — accept: cluster-triage-streamingproxy-projection-lease-scope-semantics

This was generated by AI during triage.

TL;DR:

• Accept，推荐 cluster: cluster-triage-streamingproxy-projection-lease-scope-semantics
• 调研发现 StreamingProxyRoomSessionRuntimeLease.ScopeId => RootEntityId，actor id 与 business scope id 语义混用。
• 交集 evidence 覆盖 StreamingProxy + projection + lease + scope，并扩散到 IProjectionPortSessionLease、EventSinkProjectionLifecyclePortBase、ProjectionSessionEventHub。
• 共整理 7 条 file:line evidence；命中 AGENTS/CLAUDE 的字段单一语义、身份分离、命名跟随职责条款。
• 非 docs-only / tooling-only / product feature / 外部仓库内部改动；未发现 open auto-loop duplicate。

Investigation artifact 摘要

Title tokens:

• Clarify
• StreamingProxy
• projection
• lease
• scope
• semantics

关键 grep:

• StreamingProxy 在 src/ 仅命中 mainnet host composition，但生产实现位于 agents/Aevatar.GAgents.StreamingProxy/。
• projection 命中 203 个 src cs 文件；lease 命中 108 个；scope 命中 312 个。
• 强交集文件包括 agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionRuntimeLease.cs、StreamingProxyRoomSessionEventProjector.cs、ServiceCollectionExtensions.cs、src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Ports/IProjectionPortSessionLease.cs、src/Aevatar.CQRS.Projection.Core/Orchestration/EventSinkProjectionLifecyclePortBase.cs。

核心 evidence:

• StreamingProxyRoomSessionRuntimeLease.cs:19-25: ActorId 与 ScopeId 都返回 RootEntityId。
• StreamingProxyRoomSessionProjectionContext.cs:5-11: context 没有业务 scope id，只包含 SessionId、RootActorId、ProjectionKind。
• IProjectionPortSessionLease.cs:6-10: 通用 lease contract 强制第一维叫 ScopeId。
• EventSinkProjectionLifecyclePortBase.cs:51-56: lifecycle base 继续把 portLease.ScopeId 传给 session event hub。
• ProjectionSessionEventHub.cs:30-52: hub API/transport message 都使用 ScopeId，但 StreamingProxy projector 传的是 RootActorId。
• StreamingProxyRoomSessionEventProjector.cs:30-39: projector 明确以 context.RootActorId 作为 session event entry 第一维。
• NyxIdChatEndpointsCoverageTests.cs:2466-2470: 测试已固化 ScopeId == "actor-1"。

Git history:

• 最近 30 天 StreamingProxy 相关 commits 包括 #1063 fold lifecycle facade into StreamingProxyGAgent、#1054 收窄 projection ensure/rebuild。
• StreamingProxyRoomSessionRuntimeLease.cs 与 StreamingProxyRoomSessionEventProjector.cs 的主要历史作者记录为 louis.li。

命中条款:

• AGENTS.md: “API 字段单一语义：一个字段只能表达一个含义，禁止同字段承载“名称查找 + inline 内容”等双重语义。”
• AGENTS.md: “追踪标识与目标身份必须分离：commandId/correlationId 用于追踪一次请求，actorId 用于标识处理实体；禁止把追踪 ID 与目标身份混成同一语义，也不得假设二者天然一一对应。”
• CLAUDE.md: “命名跟随职责：接口/类型/目录命名描述职责边界，不泄露 runtime/stream/protocol 偶然细节。”

完整 artifact:

• .refactor-loop/runs/triage-issue-377-investigation.md
• .refactor-loop/runs/triage-issue-377.md

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Structural solver — propose: projection session key 语义改名

TL;DR

• 这是什么: issue 377 是 projection session transport 第一维被命名成 ScopeId，但实际承载 RootActorId 的契约语义错位。
• 结论: 推荐第一片不引入新抽象，直接把 lease / hub / entry / proto 字段统一改为 RootActorId，业务 ScopeId 若需要必须另建 typed 字段。
• 需要 maintainer 做什么: 若同意 wire-compatible proto 字段 rename，就进入实现；只有要新增 envelope / pipeline phase / actor topology 时才升级决策。

---

详细说明

IProjectionPortSessionLease 是 projection session 观察端口的 lease contract；IProjectionSessionEventHub 是 session event 的发布/订阅通道。当前两者都把第一维叫 ScopeId，但 evidence 里 StreamingProxyRoomSessionEventProjector 传入的是 context.RootActorId，Workflow/Scripting/GAgentDraftRun/NyxID Chat runtime lease 也都是 ScopeId => RootEntityId。这不是只改 StreamingProxy 的问题；只改一个实现会保留通用 port 的误导性 interface。

推荐第一片是一次性语义改名，不新增 ProjectionSessionKey 值对象：把 IProjectionPortSessionLease.ScopeId 改成 RootActorId，把 ProjectionSessionEventEntry.ScopeId、IProjectionSessionEventHub.PublishAsync/SubscribeAsync(scopeId, ...)、ProjectionSessionEventHub.ResolveStreamId 的参数同步改名，projection_session_event_transport.proto 将 tag 1 从 scope_id wire-compatible rename 为 root_actor_id。这样不改变 stream cardinality、不增加 actor hop，也不引入新的 projection phase。

方案	代价	结论
第一片: 纯改名	约 18-24 文件，~+90/-90 LOC，0 新抽象	推荐，能直接消除 ScopeId == actorId
后续: ProjectionSessionKey 值对象	额外约 +45 LOC，改 3 个 public signatures	只有当后续继续出现 tuple 传参错误时再做
不推荐: 只修 StreamingProxy	约 3-5 文件	通用 IProjectionPortSessionLease 仍诱导误用

---

📎 完整 codex 原始输出(存档备查)

---

solver: structural
issue: 377
cluster: issue-377-design
verdict: propose

CLAUDE clause violated (quoted verbatim)

API 字段单一语义：一个字段只表达一个含义，禁止双重语义（如"名称查找 + inline 内容"）。

身份与事实分离：稳定 ID 只负责寻址与复用键；可变绑定必须显式建模、显式读取。

命名跟随职责：接口/类型/目录命名描述职责边界，不泄露 runtime/stream/protocol 偶然细节。

Recommended framing

这是 projection session identity contract 的命名错误，不是 StreamingProxy 的局部字段 bug。应把 session event transport 的第一维按真实来源统一命名为 RootActorId：它来自 ProjectionRuntimeScopeKey.RootActorId / IProjectionSessionContext.RootActorId，用于定位 actor-owned session stream；业务 ScopeId 若以后确实需要参与鉴权、查询或路由，应作为独立 typed field 出现在对应业务 context/event 中，不能复用 transport partition key。这样修复的是 interface 本身，调用方不需要靠注释记住“这里的 ScopeId 其实是 actor id”。

Concrete plan

• New abstractions (if any): first slice none. Later optional ProjectionSessionKey readonly record struct in Projection Core only if reviewers want to collapse the (RootActorId, SessionId) tuple after the rename has landed; it has at least 3 concrete callers (IProjectionPortSessionLease, IProjectionSessionEventHub, ProjectionSessionEventEntry) but is not required for the first slice.
• Files:
  • src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Ports/IProjectionPortSessionLease.cs: rename ScopeId to RootActorId; update summary.
  • src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Streaming/IProjectionSessionEventHub.cs: rename parameters from scopeId to rootActorId; update summary.
  • src/Aevatar.CQRS.Projection.Core/Orchestration/EventSinkProjectionLifecyclePortBase.cs: subscribe with portLease.RootActorId.
  • src/Aevatar.CQRS.Projection.Core/Orchestration/ProjectionSessionEventProjectorBase.cs: rename ProjectionSessionEventEntry.ScopeId to RootActorId and publish by root actor id.
  • src/Aevatar.CQRS.Projection.Core/Streaming/ProjectionSessionEventHub.cs: rename API/local variables/log fields/stream id helper to root actor id.
  • src/Aevatar.CQRS.Projection.Core/projection_session_event_transport.proto: wire-compatible rename field 1 from scope_id to root_actor_id; keep tag number 1; keep reserved field 4 and legacy_payload.
  • agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionRuntimeLease.cs: implement RootActorId => RootEntityId; delete ScopeId alias.
  • agents/Aevatar.GAgents.NyxidChat/NyxIdChatProjectionSession.cs: same rename for the runtime lease.
  • src/Aevatar.Scripting.Projection/Orchestration/ScriptExecutionRuntimeLease.cs: same rename.
  • src/Aevatar.Scripting.Projection/Orchestration/ScriptEvolutionRuntimeLease.cs: same rename.
  • src/workflow/Aevatar.Workflow.Projection/Orchestration/WorkflowExecutionRuntimeLease.cs: same rename.
  • src/platform/Aevatar.GAgentService.Projection/Orchestration/GAgentDraftRunRuntimeLease.cs: same rename.
  • src/platform/Aevatar.GAgentService.Projection/Orchestration/ScriptServiceAguiRuntimeLease.cs: same rename.
  • Tests/fakes: update recording hubs and assertions in test/Aevatar.CQRS.Projection.Core.Tests/ProjectionHotspotCoverageTests.cs, test/Aevatar.CQRS.Projection.Core.Tests/ProjectionPortBaseCoverageTests.cs, test/Aevatar.CQRS.Projection.Core.Tests/ProjectionRuntimeRegistrationTests.cs, test/Aevatar.Workflow.Host.Api.Tests/WorkflowExecutionProjectionPortTests.cs, test/Aevatar.AI.Tests/NyxIdChatEndpointsCoverageTests.cs, test/Aevatar.AI.Tests/NyxIdChatProjectionSessionTests.cs, test/Aevatar.AI.Tests/StreamingProxyCoverageTests.cs, plus any compile-discovered fakes under GAgentService/Scripting projection tests.
• LOC delta: first slice ~+90 / -90, mostly renames and test recorder tuple/member names; net close to zero. Later ProjectionSessionKey slice ~+45 / -30 if chosen.
• Tests to add:
  • ProjectionSessionEventHub_ShouldRouteByRootActorIdAndSessionId: publish/subscribe with root actor id A and B; only matching root actor id and session id is delivered.
  • EventSinkProjectionLifecyclePortBase_ShouldSubscribeWithLeaseRootActorId: attach sink records RootActorId, proving lifecycle does not pass business scope.
  • StreamingProxyRoomSessionEventProjector_ShouldPublishUsingRootActorId: context RootActorId=room-actor and SessionId=session-1 produces entry/hub call keyed by root actor id.
  • Update existing Workflow/NyxID/StreamingProxy tests from LastScopeId / tuple ScopeId to LastRootActorId / tuple RootActorId; assertions remain behavior-based.
• proto changes (if any): src/Aevatar.CQRS.Projection.Core/projection_session_event_transport.proto, field number 1 renamed from scope_id to root_actor_id; no tag change, no new envelope kind, no new pipeline phase.
• Runtime cost: +0 actor inbox hops, +0 stream hops, +0 steady-state allocations for first slice; stream id string remains one interpolation per publish/subscribe; protobuf binary size unchanged because tag 1 and value remain the same.
• First slice: no-new-abstraction narrow plan: rename existing session lease/hub/entry/proto field to RootActorId, update all current actor-scoped implementations and tests, keep stream key shape identical.
• Later design slice: optional ProjectionSessionKey(RootActorId, SessionId) value object only if a follow-up review finds repeated tuple misuse after the rename; optional typed business ScopeId field only for a concrete session consumer that actually needs business scope semantics.

Risks

• This framing touches more files than the minimal StreamingProxy-only fix because the bug is in the shared port/hub vocabulary; the tradeoff is one compile-driven rename instead of preserving a misleading public contract.
• Renaming proto field 1 is binary wire-compatible, but proto JSON/text names change. If any out-of-repo or persisted text-form consumer depends on scope_id, that needs explicit migration or a two-field compatibility slice. Current evidence points to internal protobuf transport, not an external adapter boundary.
• RootActorId is intentionally chosen over SessionOwnerId because the existing projection runtime key and contexts already use RootActorId; inventing a broader term now would be extra vocabulary without new semantics.

Escalation triggers (if any)

• ESCALATE_REASON:envelope-kind:only-if-reviewers-require-a-new-projection-session-envelope-instead-of-renaming-existing-transport
• ESCALATE_REASON:pipeline-phase:only-if-solution-adds-a-session-identity-normalization-phase
• ESCALATE_REASON:docs-canon:only-if-changing-repo-wide-scope-vocabulary-in-docs-canon
• ESCALATE_REASON:actor-lifecycle:only-if-changing-projection-session-actor-identity-or-topology
• ESCALATE_REASON:cross-cluster:only-if-this-must-edit-an-in-flight-pr-for-nyxidchat-workflow-scripting-or-gagentservice
• ESCALATE_REASON:prod-benchmark:only-if-transport-has-non-binary-cross-version-consumers-that-local-tests-cannot-measure

Reasoning trace (internal — for meta-judge)

• Why this structure beats a documented exception: a comment saying ScopeId means actor id would preserve the misleading interface and future consumers would still compile against the wrong semantic name.
• Why I picked this abstraction over alternatives: I did not pick a new abstraction for slice 1; the existing projection runtime already has RootActorId, and a rename is enough to make the current interface honest.
• What I cannot decide alone: whether proto text/JSON compatibility for scope_id matters outside this repo; if yes, implementation should use a short compatibility migration instead of direct generated-property rename.

SOLVER_DONE:structural:propose:rename-projection-session-key-to-root-actor-id:first-slice=no-new-abstraction-rename-lease-hub-entry-proto-field

⟦AI:AUTO-LOOP⟧

[loning]

🤖 delete solver：不删投影会话能力，建议删掉 ScopeId alias 层

TL;DR

• 这是什么：issue 377 的 deletion-first 评估，结论是 projection session event 是活链路，不能整段删除。
• 现在结论：分类为“真实需要但过度抽象”，建议删除 IProjectionPortSessionLease 与各 runtime lease 的 ScopeId => RootEntityId alias，统一改用已有 RootActorId + SessionId。
• 下一步：controller 可让 minimal/structural 按这个 first slice 执行；若坚持删除整个 session hub，会切断 StreamingProxy、NyxIdChat、Workflow、Scripting、GAgentService 的实时观察链路。

---

详细说明

反向追调用链后，IProjectionSessionEventHub（projection session 事件发布/订阅通道）不是孤立工具：StreamingProxyRoomInteraction、NyxIdChatInteraction、WorkflowRunObservationLifecycle、GAgentDraftRunObservationLifecycle、ScriptServiceRunInteraction 都通过 attach-existing projection session 绑定 live sink。删掉整个 hub 或 projection port 会让这些用户可见的流式交互在 dispatch 前直接变成 ProjectionUnavailable，所以不能判定为 dead code / orphan feature。

可删的是额外的 lease alias：IProjectionPortSessionLease.ScopeId 没有独立事实来源，当前 7 个实现里主要都是 ScopeId => RootEntityId。仓库已有 typed context：IProjectionMaterializationContext.RootActorId 与 IProjectionSessionContext.SessionId。因此 first slice 不需要新抽象：删除 IProjectionPortSessionLease，让 lifecycle base 从 IProjectionContextRuntimeLease<TContext>.Context.RootActorId/SessionId 取键；同时把 session event entry / hub / internal proto 的第一维命名从 ScopeId/scope_id 改成 RootActorId/root_actor_id，proto tag 1 保持不变。

---

📎 完整 codex 原始输出(存档备查，completion marker 由 solver final 单独输出)

---
solver: delete
issue: 377
cluster: issue-377-design
verdict: propose
---

## Classification
(d) Genuinely needed but over-built

## Recommended action
不要删除 Projection Session Event 这条能力链路；它正在承载 StreamingProxy/NyxIdChat/Workflow/Scripting/GAgentService 的实时事件观察。应删除的是把 `RootActorId` 伪装成 `ScopeId` 的重复抽象层：移除 `IProjectionPortSessionLease` 和各 runtime lease 上的 `ScopeId => RootEntityId`，调用方改为读取已有 typed context 的 `RootActorId + SessionId`。同时把 `ProjectionSessionEventEntry`、`IProjectionSessionEventHub`、`ProjectionSessionEventTransportMessage` 的第一维命名收敛为 `RootActorId/root_actor_id`；proto tag 1 可保持不变，避免新增传输字段。

## Concrete plan (if propose)
- Files to delete: `src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Ports/IProjectionPortSessionLease.cs`
- Caller migrations: `EventSinkProjectionLifecyclePortBase.AttachLiveSinkAsync` → `runtimeLease.Context.RootActorId` / `runtimeLease.Context.SessionId` through existing `IProjectionContextRuntimeLease<TContext>` + `IProjectionSessionContext`
- Caller migrations: `EventSinkProjectionRuntimeRegistration` → remove `IProjectionPortSessionLease` generic constraint; retain `IProjectionContextRuntimeLease<TContext>` constraint
- Caller migrations: `StreamingProxyRoomSessionRuntimeLease`, `NyxIdChatSessionRuntimeLease`, `WorkflowExecutionRuntimeLease`, `GAgentDraftRunRuntimeLease`, `ScriptServiceAguiRuntimeLease`, `ScriptExecutionRuntimeLease`, `ScriptEvolutionRuntimeLease` → remove `IProjectionPortSessionLease` implementation and delete `ScopeId => RootEntityId`
- Caller migrations: `ProjectionSessionEventProjectorBase` / all derived session projectors → rename `ProjectionSessionEventEntry.ScopeId` to `RootActorId`, keep value source as existing `context.RootActorId`
- Caller migrations: `IProjectionSessionEventHub` / `ProjectionSessionEventHub` → rename parameters/logging/stream key variable from `scopeId` to `rootActorId`
- Caller migrations: `projection_session_event_transport.proto` → rename field 1 from `scope_id` to `root_actor_id` without changing tag number; update generated references from `ScopeId` to `RootActorId`
- Tests to delete: none; update assertions in projection session tests that currently assert `ScopeId == actor id`
- LOC delta: -34
- First slice: delete `IProjectionPortSessionLease` and runtime-lease `ScopeId` aliases; migrate lifecycle base to existing typed context; no new abstraction
- Later design slice: none required if the same change also renames session event entry/hub/proto first dimension to `RootActorId`; if split mechanically, do the rename immediately after first slice in the same controller run, not as a deferred feature

## Reverse-evidence (why this is safe to delete)
- Whole feature is not safe to delete: `rg -l "IProjectionSessionEventHub" --type cs` shows live users in StreamingProxy, NyxIdChat, Workflow, Scripting, and GAgentService projection ports/projectors.
- The alias interface is safe to delete: `rg -l "IProjectionPortSessionLease" --type cs` found only repo-local production/test implementations and the lifecycle base; every production implementation also carries `IProjectionContextRuntimeLease<TContext>` with `Context.RootActorId` and `Context.SessionId`.
- No external repo dependency on the alias: `../NyxID` exists and was checked for projection-session terms; no NyxID surface requires `IProjectionPortSessionLease` or `ProjectionSessionEventTransportMessage`.
- No HTTP endpoint or external route disappears: Mainnet composes `AddStreamingProxy` / `AddNyxIdChat`; the plan preserves those composition roots and only changes internal projection key naming.
- Tests covering the path are load-bearing for live streaming behavior, not for the alias name; they should be updated, not deleted.
- Original intent from git history supports keeping the feature: `a46ca89fb` introduced StreamingProxy projection sessions to unify AGUI streaming; `bc6e492e1` introduced event sink lifecycle abstractions. The bad part is the generic `ScopeId` naming, not the projection session mechanism.

## Risks
- If an out-of-repo binary package compiles directly against `IProjectionPortSessionLease`, deleting it is a source break; repo-local `git grep` cannot prove external consumers do not exist.
- If rolling deployment mixes old and new services, old code writes generated property `ScopeId` while new code reads `RootActorId`; wire tag 1 remains compatible, but mixed-version source-level expectations need one-shot deployment or a short compatibility adapter.
- If some future projection session truly needs business `scope_id` in addition to actor owner id, it must be added as a separate typed field, not reused as the stream partition key.

## Escalation triggers (if any)
- none for repo-local implementation; watch external package consumers of `Aevatar.CQRS.Projection.Core.Abstractions` if this library is published independently

## Reasoning trace (internal — for meta-judge)
- Why I claim this can be deleted: `IProjectionPortSessionLease.ScopeId` duplicates `IProjectionMaterializationContext.RootActorId`; implementations return `RootEntityId`, so the abstraction creates semantic confusion without carrying independent state.
- What I checked to verify safety: issue 377 body/comments, audit iter 290, CLAUDE deletion-first clause, `rg -l` callers for `IProjectionPortSessionLease`, `IProjectionSessionEventHub`, `ProjectionSessionEventEntry`, production call paths, git history for the StreamingProxy lease and core lease abstraction, and a narrow NyxID sibling repo search.
- What I cannot decide alone: whether package-level source compatibility for `Aevatar.CQRS.Projection.Core.Abstractions` matters outside this repository; repo rules prefer deletion over compatibility shells, but package publication policy is not visible from the issue.

⟦AI:AUTO-LOOP⟧

[loning]

📊 状态卡片 — solver 派出

维度	值
阶段	派出 codex(role=solver)
codex log	phase9-issue377-r2-structural-retry.log
工作目录	/Users/auric/aevatar
timeout	3600s(~60 min 上限)
上下文	r2 structural stream disconnect EXIT=1; 重派 retry
下一步自动会做	1. 三 solver SOLVER_DONE:... 2. controller 派 meta-judge r 3. consensus → implement / converge → fresh round
是否需要人介入	❌ 否(自动推进)

🤖 controller status banner

⟦AI:AUTO-LOOP⟧

[loning]

📊 状态卡片 — solver 派出

维度	值
阶段	派出 codex(role=solver)
codex log	phase9-issue377-r2-delete-retry.log
工作目录	/Users/auric/aevatar
timeout	3600s(~60 min 上限)
上下文	r2 delete stream disconnect EXIT=1; 重派 retry
下一步自动会做	1. 三 solver SOLVER_DONE:... 2. controller 派 meta-judge r 3. consensus → implement / converge → fresh round
是否需要人介入	❌ 否(自动推进)

🤖 controller status banner

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Structural solver r2 — choose delete first slice

TL;DR

• 这是什么: 回答 r2 convergence：第一片到底 rename 还是 delete IProjectionPortSessionLease。
• 现在结论是什么: 选 delete，不保留 ScopeId alias；同时保留已收敛的 proto tag 1 改名为 root_actor_id。
• controller 下一步: 可按 no-new-abstraction first slice 实现；只有出现外部包 source-compat 或文本 proto 消费者时再升级人工决策。

---

详细说明

IProjectionPortSessionLease 现在只把已有的 Context.RootActorId + Context.SessionId 再包装成 ScopeId + SessionId，没有新增不变量。IProjectionContextRuntimeLease<TContext> 是 runtime lease 到 typed context 的现有契约，IProjectionSessionContext 已经要求 RootActorId 和 SessionId；因此保留 lease interface 并把 ScopeId rename 成 RootActorId 只是把重复抽象洗干净，删除它才符合 CLAUDE 的“删除优先”和“接口不泄露偶然细节”。

方案	文件/LOC 代价	结构结果
删除 first slice	约 22-26 文件，~+120/-155 LOC	去掉 alias seam，lifecycle 直接读 typed session context
rename first slice	约 20-24 文件，~+95/-95 LOC	名字正确，但保留一个只转发 context 的浅接口
新 ProjectionSessionKey	额外 +40-55 LOC	现在不需要；没有新的 named extension point

---

📎 完整 codex 原始输出(存档备查)

---
solver: structural
issue: 377
cluster: issue-377-design
verdict: propose
---

## CLAUDE clause violated (quoted verbatim)
> API 字段单一语义：一个字段只表达一个含义，禁止双重语义（如"名称查找 + inline 内容"）。

> 身份与事实分离：稳定 ID 只负责寻址与复用键；可变绑定必须显式建模、显式读取。

> 命名跟随职责：接口/类型/目录命名描述职责边界，不泄露 `runtime/stream/protocol` 偶然细节。

> 删除优先：空转发、重复抽象、无业务价值代码直接删除，不保留兼容空壳。

## Recommended framing
选择 delete-first，而不是 rename-first。`IProjectionPortSessionLease` 当前没有独立业务事实：所有生产实现都已经持有 `IProjectionContextRuntimeLease<TContext>`，而 `TContext : IProjectionSessionContext` 已经强类型提供 `RootActorId + SessionId`。把 `ScopeId` 改名成 `RootActorId` 虽能修正命名，但会保留一个只转发 context 的浅接口；从 CLAUDE 结构口径看，应删除该 alias seam，让 `EventSinkProjectionLifecyclePortBase` 直接读取 runtime lease 的 typed session context。`ProjectionSessionEventHub` / `ProjectionSessionEventEntry` / proto tag 1 仍同步改为 `RootActorId/root_actor_id`，因为 transport 第一维的真实职责已经 settled。

## Concrete plan
- New abstractions (if any): none. Use existing `IProjectionContextRuntimeLease<TContext>` + `IProjectionSessionContext`; no `ProjectionSessionKey` in first slice.
- Files:
  - `src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Ports/IProjectionPortSessionLease.cs`: delete.
  - `src/Aevatar.CQRS.Projection.Core/Orchestration/EventSinkProjectionLifecyclePortBase.cs`: replace `IProjectionPortSessionLease` cast with `IProjectionContextRuntimeLease<IProjectionSessionContext>` cast; subscribe with `context.RootActorId` and `context.SessionId`.
  - `src/Aevatar.CQRS.Projection.Core/DependencyInjection/EventSinkProjectionRuntimeRegistration.cs`: remove `IProjectionPortSessionLease` generic constraint; retain `IProjectionContextRuntimeLease<TContext>` and `TContext : IProjectionSessionContext`.
  - `src/Aevatar.CQRS.Projection.Core.Abstractions/Abstractions/Streaming/IProjectionSessionEventHub.cs`: rename `scopeId` parameters to `rootActorId`.
  - `src/Aevatar.CQRS.Projection.Core/Streaming/ProjectionSessionEventHub.cs`: rename validation, stream id helper, message assignment, filtering, and logs from `scopeId` to `rootActorId`.
  - `src/Aevatar.CQRS.Projection.Core/Orchestration/ProjectionSessionEventProjectorBase.cs`: rename `ProjectionSessionEventEntry.ScopeId` to `RootActorId`; publish by root actor id.
  - `src/Aevatar.CQRS.Projection.Core/projection_session_event_transport.proto`: rename field 1 `scope_id` to `root_actor_id`; keep tag number 1.
  - `agents/Aevatar.GAgents.StreamingProxy/StreamingProxyRoomSessionRuntimeLease.cs`: remove `IProjectionPortSessionLease` and `ScopeId => RootEntityId`.
  - `agents/Aevatar.GAgents.NyxidChat/NyxIdChatProjectionSession.cs`: remove `IProjectionPortSessionLease` and `ScopeId => RootEntityId`.
  - `src/workflow/Aevatar.Workflow.Projection/Orchestration/WorkflowExecutionRuntimeLease.cs`: remove `IProjectionPortSessionLease` and `ScopeId => RootEntityId`.
  - `src/Aevatar.Scripting.Projection/Orchestration/ScriptExecutionRuntimeLease.cs`: remove `IProjectionPortSessionLease` and `ScopeId => RootEntityId`.
  - `src/Aevatar.Scripting.Projection/Orchestration/ScriptEvolutionRuntimeLease.cs`: remove `IProjectionPortSessionLease` and `ScopeId => RootEntityId`.
  - `src/platform/Aevatar.GAgentService.Projection/Orchestration/GAgentDraftRunRuntimeLease.cs`: remove `IProjectionPortSessionLease` and `ScopeId => RootEntityId`.
  - `src/platform/Aevatar.GAgentService.Projection/Orchestration/ScriptServiceAguiRuntimeLease.cs`: remove `IProjectionPortSessionLease` and `ScopeId => RootEntityId`.
  - Tests/fakes: update `ProjectionPortBaseCoverageTests`, `ProjectionRuntimeRegistrationTests`, `ProjectionHotspotCoverageTests`, `NyxIdChatEndpointsCoverageTests`, `NyxIdChatProjectionSessionTests`, `StreamingProxyCoverageTests`, `WorkflowExecutionProjectionPortTests`, `WorkflowProjectionReadModelCoverageTests`, `GAgentDraftRunProjectionInfrastructureTests`, `ScriptServiceAguiProjectionPortTests`, `ScriptEvolutionProjectionPortTests` as compile-discovered.
- LOC delta: first slice ~+120 / -155, net ~-35. The negative delta comes from deleting the interface plus 7 production `ScopeId` aliases and test aliases; the rename churn is near-neutral.
- Tests to add:
  - `EventSinkProjectionLifecyclePortBase_ShouldSubscribeUsingTypedSessionContext`: a runtime lease implementing only `IProjectionContextRuntimeLease<TestSessionContext>` attaches a sink and hub records `RootActorId=session-owner` / `SessionId=session-1`.
  - `EventSinkProjectionRuntimeRegistration_ShouldNotRequireProjectionPortSessionLease`: DI registration resolves activation/release/attach lookup for a session runtime lease without the deleted interface.
  - `ProjectionSessionEventHub_ShouldRouteByRootActorIdAndSessionId`: publish root actor A/B with same session id; subscriber for A receives only A.
  - `ProjectionSessionEventProjectorBase_ShouldSkipEntriesWithoutRootActorIdOrSessionId`: protects the renamed entry invariant, not a line-bump test.
  - Update existing Workflow/NyxID/StreamingProxy/GAgentService/Scripting tests from `ScopeId == actor id` to `RootActorId == actor id` behavior assertions.
- proto changes (if any): `src/Aevatar.CQRS.Projection.Core/projection_session_event_transport.proto`, field 1: `string root_actor_id = 1;`; keep field number 1 and existing payload/session/event tags. This is binary protobuf compatible; text/JSON field name changes.
- Runtime cost: +0 actor inbox hops, +0 stream hops, +0 durable writes. Attach path adds one interface cast to `IProjectionContextRuntimeLease<IProjectionSessionContext>` and two property reads; allocation delta 0. Publish/subscribe stream id interpolation remains one string per call, same as current.
- First slice: delete `IProjectionPortSessionLease`, remove all `ScopeId => RootEntityId` aliases, have lifecycle base read existing typed session context, and rename session event hub/entry/proto first dimension to `RootActorId/root_actor_id`. No new abstraction.
- Later design slice: none required now. Only add `ProjectionSessionKey(RootActorId, SessionId)` later if a second concrete misuse appears after the alias is gone, or if a named extension point needs a single value object across hub, entry, and lifecycle APIs.

## Risks
- Delete-first is a source break for any out-of-repo consumer compiling directly against `Aevatar.CQRS.Projection.Core.Abstractions`; repo-local evidence shows only internal callers, but package publication policy is not visible from this issue.
- The proto tag rename is binary-compatible but not text/JSON-compatible. If any persisted text proto or JSON adapter expects `scope_id`, implementation needs a short compatibility adapter at the Host/Adapter boundary, not a second internal field.
- Structural cleanup touches more files than rename-first. Keep it bounded by deleting only the alias interface and not introducing `ProjectionSessionKey`, new actor type, new envelope kind, or a new projection phase.

## Escalation triggers (if any)
- ESCALATE_REASON:external-package-compat:Core.Abstractions has known out-of-repo source consumers of IProjectionPortSessionLease
- ESCALATE_REASON:prod-benchmark:text-or-json-proto-consumers-depend-on-scope_id-name-and-cannot-be-measured-locally
- ESCALATE_REASON:docs-canon:maintainer-wants-repo-wide-scope-vocabulary-changed-in-docs-canon
- ESCALATE_REASON:actor-lifecycle:implementation-starts-changing-session-scope-actor-identity-or-topology
- ESCALATE_REASON:cross-cluster:same projection session files are owned by another in-flight cluster PR

## Reasoning trace (internal — for meta-judge)
- Why this structure beats a documented exception: a comment or rename leaves an extra shallow interface whose only job is to restate `Context.RootActorId` and `Context.SessionId`; future consumers still have one more place to encode the wrong semantic split.
- Why I picked this abstraction over alternatives: I picked no new abstraction. The existing `IProjectionSessionContext` is the named extension point for actor-scoped session projection context, and covariance on `IProjectionContextRuntimeLease<out TContext>` lets the lifecycle base consume it without knowing each concrete context type.
- What I cannot decide alone: whether package-level source compatibility or text proto compatibility matters outside repo-local code. If yes, escalate before implementation; otherwise delete-first is the cleaner CLAUDE-aligned slice.

SOLVER_DONE:structural:propose:delete-IProjectionPortSessionLease-and-rename-session-transport-root-actor-id:first-slice=delete-alias-interface-use-existing-typed-session-context-plus-root_actor_id-proto-rename

⟦AI:AUTO-LOOP⟧