Event Streaming & Action Router Subsystem (pkg/events)
1. Executive Summary & Architectural Overview
The Event Streaming & Action Router Subsystem (pkg/events) provides a high-throughput, in-memory, thread-safe publish-subscribe message router and localized policy inspection engine. It decouples the core microkernel, Content-Addressable Storage (CAS) layer, and peripheral listeners (such as state machine orchestrators and suspension handlers) without introducing heavy external message broker dependencies.
Instead of requiring expensive full-graph traversals on every state change, pkg/events introduces the Three-Fold Event Dispatch Spine:
- Bitmask Filter Routing: Microsecond-latency bitwise evaluation of high-frequency events (
EventTypeObjectMutated,EventTypeSuspensionTriggered). - Localized Policy Inspection: \(O(1)\) evaluation of domain invariants (e.g., verifying whether an object mutation moves a goal or milestone into an invalid or blocked state).
- Cascading Overlay Propagation: Deterministic re-publication of suspension and alert shapes directly into the router stream, instantly propagating shockwaves across dependent kernel controllers.
flowchart TD
Storage["Object Storage / CAS"] -->|Publish Shape| Router["events.Router"]
Router -->|RLock Evaluation| Inspectors{"Inspector Match"}
Inspectors -->|Bitmask Match| ChannelSub["Buffered Channel Subscribers"]
Inspectors -->|Policy Violation| PolicyInsp["PolicyInspector"]
PolicyInsp -->|"O(1) Cascade"| CascadePub["Cascade Publisher"]
CascadePub -->|Re-Publish SuspensionTriggered| Router
2. Core Concepts & Domain Model
2.1 The Event Shape (events.Shape)
Every mutation or lifecycle transition within the kernel emits a structured Shape. The Shape carries localized metadata sufficient for downstream inspectors to match without executing database queries:
| Field | Type | Description |
|---|---|---|
Type |
EventType |
Bitmask enum identifying the class of event (EventTypeSuspensionTriggered, EventTypeObjectMutated). |
TargetID |
string |
Target object identifier (e.g. GOAL-DEMO-001, BLI-DEMO-001). |
SourceID |
string |
Actor or subsystem originating the mutation (e.g. storage, scheduler, user-1). |
Kind |
string |
Canonical kernel object kind (goal, requirement, backlog_item, milestone). |
Namespace |
string |
Partition namespace (e.g. zqk:kernel, zqk:custom). |
Status |
string |
Effective status following mutation (active, blocked, completed, failed). |
Payload |
any |
Optional opaque payload for context-specific consumers. |
2.2 Event Bitmasks (events.EventType)
Event types are defined as bit flags enabling set operations in a single CPU cycle:
type EventType uint64
const (
EventTypeUnknown EventType = 0
EventTypeSuspensionTriggered EventType = 1 << 0
EventTypeObjectMutated EventType = 1 << 1
)
3. Router Architecture & Concurrency Model
3.1 Multiplexed Subscription & Non-Blocking Delivery
The Router coordinates delivery across arbitrary numbers of concurrent consumers. To protect kernel throughput from slow or stalled subscribers, channel delivery uses non-blocking select drops:
for inspector, channels := range r.subscribers {
if inspector.Inspect(s) {
for _, ch := range channels {
select {
case ch <- s:
default:
// Channel buffer full: drops to prevent pipeline stalling
}
}
}
}
3.2 Thread-Safe Mutex Topology
sync.RWMutex(r.mu):Publishacquires a read lock (r.mu.RLock()) to readcascadeInspectorsand evaluate channel subscribers.SubscribeandUnsubscribeacquire exclusive write locks (r.mu.Lock()).- Read-write lock separation guarantees high publish concurrency with zero race conditions under concurrent worker swarms.
4. Localized Policy Inspection & Cascading Overlays
4.1 \(O(1)\) Policy Invariant Check
The PolicyInspector evaluates declarative rules over object kinds, namespaces, and forbidden statuses:
cfg := events.PolicyInspectorConfig{
Kind: "milestone",
Namespace: "zqk:kernel",
DisallowedStatuses: []string{objects.ObjectStatusBlocked, objects.ObjectStatusError},
}
inspector := events.NewPolicyInspector(cfg)
When an object transitions into one of the DisallowedStatuses, PolicyInspector.Inspect(s) detects the violation immediately.
4.2 Cascading Suspension Wiring
By registering a policy inspector via router.SubscribeWithCascade(inspector, router), violations automatically re-emit an EventTypeSuspensionTriggered event into the router:
router.SubscribeWithCascade(inspector, router)
This achieves cascading safety boundaries across distributed components without coupling domain logic to low-level pub-sub machinery.
5. Verification & The Three-Fold Proof
The integrity of pkg/events is guaranteed across three rigorous verification dimensions:
5.1 Static Floor Invariant
- Criterion: Statement test coverage for
pkg/eventsmust meet or exceed 85.0% (achieving 100.0% statement coverage). - Rule Enforcement: Verified deterministically via Go test coverage instrumentation:
bash go test -cover ./pkg/events/...
5.2 Operational Dynamic Proof
- Criterion: Event router dispatch, subscriber filter matching, cascading overlays, and non-blocking buffer drops must execute deterministically across concurrent goroutines without deadlocks or races.
- Rule Enforcement: Verified under Go's race detector:
bash go test -race ./pkg/events/...
5.3 Negative Adversarial Boundary
- Criterion: Boundary conditions, channel overflow handling, unregistration of missing subscribers, zero-bitmask queries, and open-core release hygiene must pass without exceptions or prohibited studio nanos-hex identifiers.
- Rule Enforcement: Automated release payload scan:
bash sh scripts/open-core/check-public-release-payload.sh .
6. Operational Best Practices & Recipes
6.1 Creating a Subscriber Channel with Clean Teardown
router := events.NewRouter()
inspector := events.NewBitmaskInspector(events.EventTypeObjectMutated)
ch := make(chan events.Shape, 100)
router.Subscribe(inspector, ch)
defer func() {
router.Unsubscribe(inspector, ch)
close(ch)
}()
6.2 Monitoring Policy Violations with Cascades
policyInsp := events.NewPolicyInspector(events.PolicyInspectorConfig{
Kind: "backlog_item",
Namespace: "zqk:kernel",
DisallowedStatuses: []string{objects.ObjectStatusBlocked},
})
// Downstream listener for critical suspensions
suspCh := make(chan events.Shape, 50)
router.Subscribe(events.NewBitmaskInspector(events.EventTypeSuspensionTriggered), suspCh)
// Cascade inspector re-publishes to router
router.SubscribeWithCascade(policyInsp, router)