> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# FM Consumer Verification Matrix

> This document tracks which event consumers have been verified to handle each FM-published event. Before a spec wave is considered "integration-ready", all cons…

**Status:** 🚧 In progress (FM-14 Phase 4 task; first verified row landed via 2026-04-18 audit)
**Last Updated:** 2026-04-18
**Owner:** FM
**Source:** [FM-14: Integration Contract Alignment](https://github.com/Encore-OS/encoreos/blob/development/specs/fm/specs/FM-14-integration-contract-alignment.md) Phase 4

> **Canonical-source statement (added 2026-04-18 by FM Audit & Optimization):**
> This document is the **canonical audit log** for FM event consumers. The high-level matrix in [`FM_INTEGRATION_CONTRACTS.md` § Consumer Verification Matrix](/architecture/integrations/FM_INTEGRATION_CONTRACTS#consumer-verification-matrix) is a **derived summary** for spec authors. When the two disagree, this document wins, and a docs PR should reconcile `FM_INTEGRATION_CONTRACTS.md`. The deep review on 2026-04-17 surfaced one such drift (`vendor_certification_expiring → PF-10` was ✅ in the summary but missing from this audit log); it is now reflected below in § "Wave 0 — Already-implemented FM events".

> **Platform Pattern Note:** This document is the FM prototype of a platform-wide Consumer Verification Matrix pattern proposed for generalization as a PF-level spec (`PF-Integration-Contract-Governance`). Other cores should adopt the same structure once the PF spec is authored. See FM-14 Phase 4 for the governance rationale.

***

## Purpose

This document tracks which event consumers have been verified to handle each FM-published event. Before a spec wave is considered "integration-ready", all consumer rows for that wave's events must have a verification status of ✅ Verified.

***

## How to mark a consumer ✅ Verified

A consumer row may be set to ✅ Verified only when **all** of the following hold:

1. The consumer handler exists in `supabase/functions/{handler-name}/index.ts` (or equivalent in-app subscriber) and is deployed to all environments where the publisher is enabled.
2. The handler is registered against the publisher event in `EVENT_CONTRACTS.md` and routes through the platform notification / event bus (no ad-hoc HTTP webhooks for cross-core).
3. At least one integration test in `tests/integration/` exercises the publisher → consumer path end-to-end (or a dedicated `tests/edge/` Deno test for edge handlers).
4. The handler honours tenant isolation (`organization_id` filter on every query, RLS-friendly client) and uses `_shared/auth.ts` (`verifyOrgAccess()` / `verifyOrgRole()`) instead of inline `pf_user_role_assignments` queries.
5. The handler emits an audit log entry (or otherwise produces a verifiable trace) on success and failure.
6. The row in this matrix is updated **and** the corresponding row in `FM_INTEGRATION_CONTRACTS.md § Consumer Verification Matrix` is updated in the **same** PR.

If any of the above is missing, the row remains 📝 Planned with the FM-CONSUMER-XXX tracking ID.

***

## Wave 0 — Already-implemented FM events

These rows reflect consumers that are wired today (not part of any forward-looking wave). They were missing from this document until the 2026-04-18 audit.

| Event                           | Publisher | Consumer              | Consumer Handler                                                 | Status     | Notes                                                                                                                                                                                  |
| ------------------------------- | --------- | --------------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vendor_certification_expiring` | FM-03     | PF-10 (Notifications) | `check-vendor-certifications` cron + PF-10 notification dispatch | ✅ Verified | Edge function `supabase/functions/check-vendor-certifications/index.ts`. Surfaced in `FM_INTEGRATION_CONTRACTS.md § Consumer Verification Matrix` as ✅; reconciled here on 2026-04-18. |

***

## Integration Readiness Gate Checklist

Before marking any FM spec as integration-complete, verify:

* [ ] All FM events for the spec are defined in `FM_INTEGRATION_CONTRACTS.md`
* [ ] All FM events for the spec are listed in `EVENT_CONTRACTS.md`
* [ ] All consumer rows in this document for those events are ✅ Verified
* [ ] RLS test stubs exist for all new tables in the spec
* [ ] Consumer handlers in FA / GR / PF-10 are implemented or stubbed with tracked issues
* [ ] `npm run verify:fm-integration-gates` passes

***

## Wave A Events (FM-06: Compliance & Inspections)

| Event                  | Publisher | Consumer                    | Consumer Handler              | Status             | Notes                                                                |
| ---------------------- | --------- | --------------------------- | ----------------------------- | ------------------ | -------------------------------------------------------------------- |
| `inspection_due`       | FM-06     | PF-10 (Notifications)       | `handleFmInspectionDue`       | 📝 FM-CONSUMER-001 | Handler stub: `supabase/functions/pf-handle-fm-inspection-due`       |
| `inspection_due`       | FM-06     | GR-03 (Compliance Tracking) | `handleFmInspectionDue`       | 📝 FM-CONSUMER-002 | Handler stub: `supabase/functions/gr-handle-fm-inspection-due`       |
| `inspection_failed`    | FM-06     | PF-10 (Notifications)       | `handleFmInspectionFailed`    | 📝 FM-CONSUMER-003 | Handler stub: `supabase/functions/pf-handle-fm-inspection-failed`    |
| `inspection_failed`    | FM-06     | GR-03 (Compliance Tracking) | `handleFmInspectionFailed`    | 📝 FM-CONSUMER-004 | Handler stub: `supabase/functions/gr-handle-fm-inspection-failed`    |
| `inspection_compliant` | FM-06     | GR-03 (Compliance Tracking) | `handleFmInspectionCompliant` | 📝 FM-CONSUMER-005 | Handler stub: `supabase/functions/gr-handle-fm-inspection-compliant` |

***

## Wave B Events (FM-07: Analytics, FM-09: Budgeting)

| Event                         | Publisher | Consumer              | Consumer Handler                  | Status             | Notes                                                                               |
| ----------------------------- | --------- | --------------------- | --------------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `facilities_report_generated` | FM-07     | PF-10 (Notifications) | `handleFacilitiesReportGenerated` | 📝 FM-CONSUMER-006 | Handler stub: `supabase/functions/pf-handle-facilities-report-generated`            |
| `budget_variance_alert`       | FM-09     | FA (Finance)          | `handleBudgetVarianceAlert`       | 📝 FM-CONSUMER-007 | Handler stub: `supabase/functions/fa-handle-budget-variance-alert` (requires FA-08) |
| `budget_variance_alert`       | FM-09     | PF-10 (Notifications) | `handleBudgetVarianceAlert`       | 📝 FM-CONSUMER-008 | Handler stub: `supabase/functions/pf-handle-budget-variance-alert`                  |

***

## Wave C Events (FM-12: Capital Planning)

| Event                      | Publisher | Consumer              | Consumer Handler               | Status             | Notes                                                                                  |
| -------------------------- | --------- | --------------------- | ------------------------------ | ------------------ | -------------------------------------------------------------------------------------- |
| `capital_project_approved` | FM-12     | FA (Finance)          | `handleCapitalProjectApproved` | 📝 FM-CONSUMER-009 | Handler stub: `supabase/functions/fa-handle-capital-project-approved` (requires FA-09) |
| `capital_project_approved` | FM-12     | PF-10 (Notifications) | `handleCapitalProjectApproved` | 📝 FM-CONSUMER-010 | Handler stub: `supabase/functions/pf-handle-capital-project-approved`                  |

***

## References

* [FM-14: Integration Contract Alignment](https://github.com/Encore-OS/encoreos/blob/development/specs/fm/specs/FM-14-integration-contract-alignment.md)
* [FM-15: Backlog Delivery Orchestration](https://github.com/Encore-OS/encoreos/blob/development/specs/fm/specs/FM-15-backlog-delivery-orchestration.md)
* [FM\_INTEGRATION\_CONTRACTS.md](/architecture/integrations/FM_INTEGRATION_CONTRACTS)
* [EVENT\_CONTRACTS.md](/architecture/integrations/EVENT_CONTRACTS)