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 Testing

Testing guidance for canonical event/status contracts and projections.

​
Test Layers

​
1. Version Compatibility

File: src/shared/events/canonicalEventVersion.test.ts Verifies:
  • current version constant
  • minimum supported version
  • supported version matrix (1.x)
  • unsupported versions rejected (0.x, 2.x, invalid)

​
2. Envelope Schema Validation

File: src/shared/events/canonicalEventSchema.test.ts Verifies:
  • valid canonical envelope accepted
  • unsupported schemaVersion rejected
  • required fields and enums enforced via Zod

​
3. Projection Behavior

File: src/shared/events/statusProjectionService.test.ts Verifies:
  • mapped events produce expected canonical status
  • terminal state regression is blocked
  • organization-level listing works

​
4. Cross-Feature Integration Flow

File: src/shared/events/canonicalEventFlow.integration.test.ts Verifies end-to-end propagation for:
  • grant.lifecycle.*
  • expense.audit.*
  • agent.run.*
And asserts visibility through:
  • projection summary consumers
  • extension API consumer (createExtensionEventBus)

​
5. Consumer Cohesion + Freshness

File: src/shared/events/canonicalConsumers.integration.test.ts Verifies:
  • Grants/Projects/Compliance/Billing consumer summaries stay aligned
  • canonical freshness projection state (fresh/stale/empty)
  • entity-scoped consumer filters during fast-cutover reads

​
6. Projection Health Computation

File: src/shared/events/canonicalProjectionHealth.test.ts Verifies:
  • stale projection counting behavior
  • org projection count + stats passthrough

​
7. Extension API Freshness Helpers

File: src/shared/extension-api/extensionEventBus.test.ts Verifies:
  • extension-scoped freshness reads (getCanonicalFreshness)
  • degraded-mode boolean checks (isCanonicalFresh)

​
8. Canonical Event Coverage Guardrail

File: src/shared/events/canonicalEventMap.coverage.test.ts Verifies:
  • all critical event types (grant.lifecycle.*, expense.audit.*, agent.run.*) remain mapped
npm run test:run -- \
  src/shared/events/canonicalEventVersion.test.ts \
  src/shared/events/canonicalEventSchema.test.ts \
  src/shared/events/statusProjectionService.test.ts \
  src/shared/events/canonicalEventFlow.integration.test.ts \
  src/shared/events/canonicalConsumers.integration.test.ts \
  src/shared/events/canonicalProjectionHealth.test.ts \
  src/shared/extension-api/extensionEventBus.test.ts \
  src/shared/events/canonicalEventMap.coverage.test.ts

npx eslint \
  src/shared/events/canonicalEventVersion.ts \
  src/shared/events/canonicalEventSchema.ts \
  src/shared/events/canonicalEventMap.ts \
  src/shared/events/statusProjectionService.ts \
  src/shared/events/canonicalConsumers.ts

​
PR Gate Checklist

  • Canonical schema changes include updated tests
  • Event map changes include integration assertions
  • Version policy tests pass
  • Lint passes for touched canonical files