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 Event Contract

​

Purpose

​

Canonical Status Primitives

• pending
• progress
• blocked
• completed
• failed

​

Canonical Envelope

{
  eventId: string;
  eventType: string;
  schemaVersion: string;
  organizationId: string;
  domain: 'grant_lifecycle' | 'expense_audit' | 'agent_run' | 'billing' | 'compliance' | 'project' | 'extension';
  entityType: 'grant' | 'expense' | 'agent_run' | 'billing' | 'compliance' | 'project' | 'extension';
  entityId: string;
  status: 'pending' | 'progress' | 'blocked' | 'completed' | 'failed';
  reason?: string;
  occurredAt: ISO8601;
  sourceEventType: SystemEventType;
  source?: string;
  correlationId?: string;
  payload: Record<string, unknown>;
}

• source is required from producer helpers (emitCanonicalSystemEvent).
• correlationId is required for multi-step workflows and retries.
• version in system-event metadata is set to canonical contract version (1.0.0).

​

Canonical Taxonomy (Epic 1 Scope)

​

grant.lifecycle.*

• grant.lifecycle.added_to_pipeline
• grant.lifecycle.stage_changed
• grant.lifecycle.application_submitted
• grant.lifecycle.won
• grant.lifecycle.lost
• grant.lifecycle.report_due
• grant.lifecycle.report_submitted
• grant.lifecycle.disbursement_received

​

expense.audit.*

• expense.audit.submitted
• expense.audit.approved
• expense.audit.rejected

​

agent.run.*

• agent.run.started
• agent.run.step_completed
• agent.run.escalation_required
• agent.run.escalation_resolved
• agent.run.completed
• agent.run.failed
• agent.run.cancelled

​

Versioning and Compatibility Policy

• Current: 1.0.0
• Minimum supported: 1.0.0

1. Accept only the current major (1.x.x).
2. Reject versions lower than minimum supported.
3. Reject future major versions (2.x.x).

1. Breaking changes require a major version bump and migration plan.
2. Minor additions are backward-compatible and can be introduced in 1.x.
3. Contract tests must pass for all supported versions before release.

​

Governance

1. Update canonicalEventMap.ts and canonicalEventSchema.ts.
2. Add/adjust tests in canonicalEventSchema.test.ts, canonicalEventVersion.test.ts, and integration flow tests.
3. Update this document and event-catalog.md if taxonomy scope changes.
4. Announce migration guidance in release notes for any compatibility-impacting change.

​

Sign-off Record (Epic 1)