Agent Skills
› NeverSight/learn-skills.dev
› eventing-hub
eventing-hub
GitHub指导Black-Tortoise项目的事件溯源实现，涵盖事件Schema定义、追加后发布流程、因果追踪及安全订阅机制。适用于涉及src/app/eventing、EventBus或事件处理器的开发场景。
Trigger Scenarios
修改 src/app/eventing 目录下的文件
使用 EventBus 进行事件发布或订阅
编写事件处理器或投影逻辑
Install
npx skills add NeverSight/learn-skills.dev --skill eventing-hub -g -y
SKILL.md
Frontmatter
{
"name": "eventing-hub",
"description": "Event-sourcing and EventBus directives for Black-Tortoise, covering structured event schemas, append-before-publish flow, causality\/id rules, and safe subscribers; use when touching src\/app\/eventing, EventBus, or any event handlers\/projections."
}
Eventing Hub Master Guide
Intent
Describe event contracts, persistence/publish order, and consumer safety for the shared EventBus described in src/app/eventing/AGENTS.md and .github/instructions/20-ddd-event-sourcing-copilot-instructions.md.
Event Schema
- Declare events with a Type, Payload, Metadata, and Semantics structure; keep payloads immutable and document any allowed mutations in the metadata.
- Use a
correlationIdto tie related events, and assign acausationIdthat points to the triggering event (null only for root events). - Emit only typed events from the Aggregates/Application services; do not publish raw DTOs or Firebase objects.
Append → Publish → React
- Persist every outcome (Append) before invoking the
EventBuspublish step; never wrap append/publish inPromise.allor parallel flows to avoid causality gaps. - After the append promise resolves, publish the event and let downstream stores/projections react via the global
EventBussingleton. - Reactions should be limited to simple projections or side effects; long-running work belongs to dedicated use cases handled by the Application layer.
Causality Tracking & Immutability
- Maintain causation/correlation IDs for every published event; log them for tracing and include them in metadata for audit tooling.
- Treat emitted events as read-only facts; consumers may inspect but must never mutate payload or metadata objects.
- Use
Object.freeze()or deep copies when broadcasting to ensure immutability guarantees reach all subscribers.
Safe Subscriptions
- Convert the RxJS stream behind
EventBusinto signals at the Application boundary usingtoSignal()before exposing data to Presentation stores. - Guard subscriptions with
takeUntilDestroyed()or signal-based cleanup so that event handlers do not leak after a component/store is destroyed. - Prefer
@ngrx/signalsstores for reacting to events; theirwithMethodshandlers should callpatchStatebased on event payloads rather than mutating the store directly.
Validation & Monitoring
- Validate payload schemas before append, using domain value objects to enforce invariants (Domain layer) and rejecting invalid data early.
- Emit audit events when Append or Publish steps fail so
docs/AUDIT-*trackers capture the problem context. - Feed causality IDs into any observability tooling to verify the Append→Publish→React chain during CI or runtime tracing.
Version History
- e0220ca Current 2026-07-05 21:26
