Skip to main content

Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Canonical Events API

Reference for the canonical event/status APIs in src/shared/events.

​
Overview

Canonical events normalize cross-feature state into one status model:
  • pending
  • progress
  • blocked
  • completed
  • failed
Primary consumers: Grants, Projects, Compliance, Billing, Agents, Extensions.

​
Main Exports

Source: src/shared/events/index.ts

​
Contracts

  • CanonicalStatus
  • CanonicalStatusDomain
  • CanonicalStatusProjection
  • CanonicalEventEnvelope
  • CanonicalEntityType
  • CanonicalStatusSummary
  • CanonicalConsumer
  • CanonicalProjectionFreshness

​
Event Mapping and Validation

  • toCanonicalEventEnvelope(event: SystemEvent): CanonicalEventEnvelope | null
  • getCanonicalMappedEventTypes(): SystemEventType[]
  • getCriticalCanonicalEventTypes(): SystemEventType[]
  • canonicalEventEnvelopeSchema
  • getCanonicalSchemaVersion(): string
  • getCanonicalMinSupportedSchemaVersion(): string
  • isSupportedCanonicalSchemaVersion(version: string): boolean

​
Projection APIs

  • canonicalStatusProjectionService.ingestSystemEvent(event)
  • canonicalStatusProjectionService.getStatus(organizationId, entityType, entityId)
  • canonicalStatusProjectionService.listByOrganization(organizationId)
  • canonicalStatusProjectionService.subscribe(listener)
  • summarizeCanonicalStatuses(projections, filters?)
  • selectCanonicalSummaryForConsumer(consumer, projections, entityIds?)
  • selectCanonicalFreshnessForConsumer(consumer, projections, { entityIds?, now? })

​
React Hooks

  • useCanonicalStatus(organizationId, entityType, entityId)
  • useCanonicalStatuses(organizationId)
  • useCanonicalProjectionHealth(organizationId)

​
Extension Consumer APIs

  • createExtensionEventBus(extensionId).getCanonicalStatus(organizationId, entityType, entityId)
  • createExtensionEventBus(extensionId).listCanonicalStatuses(organizationId)
  • createExtensionEventBus(extensionId).getCanonicalFreshness(organizationId, consumer?)
  • createExtensionEventBus(extensionId).isCanonicalFresh(organizationId, consumer?)

​
Projection Health Utility

  • computeCanonicalProjectionHealth(projections, stats, now?)

​
Producer Helper

  • emitCanonicalSystemEvent({ eventBus, type, organizationId, userId, severity, payload, source, correlationId? })

​
Canonical Domains

  • grant_lifecycle
  • expense_audit
  • agent_run
  • billing
  • compliance
  • project
  • extension

​
Canonical Consumers

  • grants
  • projects
  • compliance
  • billing
  • extensions
  • agents

​
Fast Usage Examples

​
Producer

await emitCanonicalSystemEvent({
  eventBus,
  type: SystemEventType.AGENT_TASK_COMPLETED,
  organizationId,
  userId,
  severity: EventSeverity.INFO,
  payload: { runId },
  source: 'AgentExecutionService',
  correlationId: runId,
});

​
Consumer (React)

const projection = useCanonicalStatus(orgId, 'agent_run', runId);

​
Consumer (Summary)

const projections = useCanonicalStatuses(orgId);
const summary = summarizeCanonicalStatuses(projections, {
  domains: ['agent_run'],
});

​
Consumer (Coordinated Feature Summary)

const projections = useCanonicalStatuses(orgId);
const summary = selectCanonicalSummaryForConsumer('billing', projections);
const freshness = selectCanonicalFreshnessForConsumer('billing', projections);
  • docs/engineering/architecture/canonical-event-contract.md
  • docs/engineering/architecture/event-catalog.md
  • docs/engineering/testing/canonical-events-testing.md