Events¶

Target Architecture — Final-State Design

This page defines the final-state messaging contracts of the Knowledge Platform. All messages travel in the canonical event envelope over MassTransit on Azure Service Bus (the primary messaging stack).

The Knowledge Platform is event-driven end to end. Commands (VerbNoun) express intent and are handled by exactly one aggregate; domain events (NounVerbPastTense) are facts emitted after a state change and published within the platform; integration events are domain events promoted to cross-platform contracts. Every message carries the canonical envelope (eventId, eventType, tenantId, projectId, moduleId, traceId, correlationId, causationId, occurredAt, payload), which is what makes knowledge ingestion and context assembly fully traceable and replayable.

Commands¶

Commands are imperative and not part of the public event stream.

Command (`VerbNoun`)	Handled by	Effect
`IngestArtifact`	`KnowledgeIngestionService`	Begin the ingestion pipeline for an artifact
`IngestRepository`	`CodebaseKnowledgeService`	Queue a `CodeIndexJob` for a repository
`IngestDocumentation`	`DocumentationKnowledgeService`	Ingest a documentation source
`RegisterPromptTemplate`	`PromptMemoryService`	Register/version a prompt template
`RecordDecision`	`DecisionMemoryService`	Persist an architectural decision
`RecordRuntimeSignal`	`RuntimeMemoryService`	Persist a runtime signal/incident/feedback
`EmbedChunks`	`EmbeddingService`	Create and run an `EmbeddingJob`
`BuildContextPackage`	`ContextBuilderService`	Assemble a Context Package
`ClassifyMemory`	`MemoryClassificationService`	Assign classification + sensitivity
`RedactMemory`	`MemoryRedactionService`	Produce a redacted projection
`EvaluateMemoryAccess`	`MemoryPolicyService`	Evaluate access policy
`AssessKnowledgeQuality`	`KnowledgeQualityService`	Score a record against quality rules
`PromoteKnowledgePattern`	`PatternCatalogService`	Promote a recurring solution to a pattern
`ReplayKnowledge`	`KnowledgeReplayService`	Re-drive a knowledge/signal timeline

Domain Events¶

Emitted within the platform after an aggregate state change.

Domain Event (`NounVerbPastTense`)	Emitting Service	Payload highlights
`MemoryRecordCreated`	`KnowledgeIngestionService`	`memoryRecordId`, `artifactId`, `contentHash`
`ArtifactIngested`	`ArtifactMemoryService`	`artifactId`, `version`, `storageRef`
`ArtifactVersionCreated`	`ArtifactMemoryService`	`artifactId`, `version`, `supersedes`
`ArtifactSnapshotCaptured`	`ArtifactMemoryService`	`artifactSnapshotId`, `atTraceId`
`MemoryClassified`	`MemoryClassificationService`	`memoryRecordId`, `classification`, `labels`
`MemoryRedacted`	`MemoryRedactionService`	`memoryRecordId`, `audience`, `redactions`
`EmbeddingCompleted`	`EmbeddingService`	`embeddingJobId`, `vectorDocumentId`, `modelVersion`
`EmbeddingFailed`	`EmbeddingService`	`embeddingJobId`, `reason`, `attempt`
`EmbeddingRefreshed`	`EmbeddingService`	`vectorDocumentId`, `fromModel`, `toModel`
`VectorDocumentUpserted`	`VectorMemoryService`	`vectorDocumentId`, `collection`, `chunks`
`KnowledgeNodeUpserted`	`KnowledgeGraphService`	`nodeId`, `nodeType`, `ref`
`KnowledgeEdgeUpserted`	`KnowledgeGraphService`	`edgeId`, `from`, `to`, `edgeType`
`GraphProjectionUpdated`	`KnowledgeGraphService`	`graphProjectionId`, `scope`
`RepositoryIndexed`	`CodebaseKnowledgeService`	`codeIndexJobId`, `commit`
`CodeSymbolExtracted`	`CodebaseKnowledgeService`	`codeSymbolId`, `kind`, `filePath`
`CodeDependencyGraphBuilt`	`CodebaseKnowledgeService`	`codeIndexJobId`, `edgeCount`
`DocumentationIndexed`	`DocumentationKnowledgeService`	`memoryRecordId`, `sourceRef`
`PromptTemplateRegistered`	`PromptMemoryService`	`promptTemplateId`, `version`
`PromptRunRecorded`	`PromptMemoryService`	`promptRunId`, `promptVersionId`, `outcome`
`DecisionRecorded`	`DecisionMemoryService`	`decisionRecordId`, `status`
`DecisionAlternativeAdded`	`DecisionMemoryService`	`decisionRecordId`, `alternativeId`
`RuntimeSignalRecorded`	`RuntimeMemoryService`	`runtimeSignalId`, `kind`, `linkedArtifactId`
`IncidentMemoryCaptured`	`RuntimeMemoryService`	`incidentMemoryId`, `severity`
`FeedbackItemRecorded`	`RuntimeMemoryService`	`feedbackItemId`, `source`, `sentiment`
`KnowledgePatternDiscovered`	`PatternCatalogService`	`knowledgePatternId`, `confidence`, `occurrences`
`PatternVersionPublished`	`PatternCatalogService`	`knowledgePatternId`, `version`
`MemoryAccessEvaluated`	`MemoryPolicyService`	`policyDecisionId`, `effects[]`
`KnowledgeQualityAssessed`	`KnowledgeQualityService`	`assessmentId`, `score`, `violations`
`ContextBuildRequested`	`ContextBuilderService`	`contextBuildRequestId`, `intent`
`ContextPackageBuilt`	`ContextBuilderService`	`contextPackageId`, `tokensUsed`, `policyDecisionId`
`KnowledgeConflictDetected`	`ConflictDetectionWorker`	`conflictId`, `recordA`, `recordB`
`MemoryMarkedStale`	`StaleMemoryWorker`	`memoryRecordId`, `reason`
`KnowledgeReplayCompleted`	`KnowledgeReplayService`	`replayId`, `recordsRebuilt`

Integration Events¶

Domain events promoted to versioned cross-platform contracts (consumed outside the Knowledge Platform). These appear in the factory-wide Event Catalog.

Integration Event	Consumed by	Purpose
`ContextPackageBuilt`	Agent Mesh, Observability & Feedback	Signals a context is ready; enables context-to-outcome attribution
`ArtifactIngested`	Control Plane, Template & Library Platform	Confirms an artifact is now reusable knowledge
`KnowledgePatternDiscovered`	Template & Library Platform, Marketplace	Candidate reuse / marketplace listing
`RuntimeSignalRecorded`	Control Plane	Feeds the improvement loop and re-planning
`MemoryAccessEvaluated`	Governance, Security & Compliance	Centralised access audit
`KnowledgeConflictDetected`	Control Plane	Triggers human review of contradictory knowledge

Topics and Subscriptions¶

Events are published to Azure Service Bus topics; selected envelope fields are mirrored to broker application properties (cs-event-type, cs-tenant-id, cs-trace-id, cs-correlation-id) for filtering without deserialization.

Topic	Publishers	Typical subscribers
`knowledge.ingestion`	Ingestion, Artifact, Classification	Chunking, Embedding, Graph, Quality workers
`knowledge.embedding`	`EmbeddingService`	`VectorMemoryService`, retry/refresh workers
`knowledge.graph`	`KnowledgeGraphService`	`ContextBuilderService`, conflict detection
`knowledge.context`	`ContextBuilderService`	Agent Mesh, Observability
`knowledge.governance`	Policy, Classification, Redaction, Quality	Context Builder, Governance platform
`knowledge.runtime`	`RuntimeMemoryService`	Conflict detection, Control Plane
`knowledge.pattern`	`PatternCatalogService`	Template & Library, Marketplace

Event Flow¶

flowchart LR
    Cmd["BuildContextPackage (command)"] --> CB["ContextBuilderService"]
    CB -->|"ContextBuildRequested"| Topic1["knowledge.context"]
    CB -->|"ContextPackageBuilt"| Topic1
    Topic1 --> AM["Agent Mesh"]
    Topic1 --> OBS["Observability &amp; Feedback"]

    Art["ArtifactCreated (Agent Mesh)"] --> Ingest["KnowledgeIngestionService"]
    Ingest -->|"MemoryRecordCreated"| Topic2["knowledge.ingestion"]
    Topic2 --> Embed["EmbeddingService"]
    Embed -->|"EmbeddingCompleted"| Topic3["knowledge.embedding"]
    Topic3 --> VM["VectorMemoryService"]

    Sig["RuntimeSignalReceived"] --> RT["RuntimeMemoryService"]
    RT -->|"RuntimeSignalRecorded"| Topic4["knowledge.runtime"]
    Topic4 --> Conflict["ConflictDetectionWorker"]
    Conflict -->|"KnowledgeConflictDetected"| CP["Control Plane"]

Hold "Alt" / "Option" to enable pan & zoom

Consumer Rules¶

Idempotency on eventId; workers additionally key on the idempotency key.
Tenant guard — every handler asserts tenantId before touching a store.
Trace propagation — traceId/correlationId flow into OTEL spans and Serilog context.
Forward compatibility — tolerate unknown payload fields and unknown eventType values (ignore-and-log).
Immutable once published — required for Knowledge Replay.