Skip to main content

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.

Version: 1.0.0
Status: 🔨 In Progress
Last Updated: 2026-02-23
Spec: PM-19 PM-Triggered Business Rule Automation
Constitution Reference: Section 1.3 (Integration Patterns), Section 12 (Automation Governance)

​
Overview

PM-19 extends the FW-03 Automation Engine to support PM events as automation triggers. Billing admins can create rules that run when claim status changes (e.g. denied), charge is approved, or payment is posted. The automation executor subscribes to the cl_pm_events channel and matches rules by trigger_type and trigger_config.
Note on channel naming: The cl_pm_events channel uses a cl_ prefix because it was originally established for CL↔PM cross-core events. PM-only events reuse this channel for consistency with EVENT_CONTRACTS.md. A future rename to pm_events may be considered if the channel scope is formalized.
Key behavior:
  • Trigger type: pm_event (stored as trigger_type: 'pm_event' in fw_automation_rules)
  • Trigger config (JSONB): { "event_type": string, "new_status"?: string, "payer_id"?: string | null }
  • Channel: cl_pm_events (EVENT_CONTRACTS)
  • Governance: All executions logged to fw_automation_logs; circuit breaker and dry-run per constitution §12.

​
Quick Reference

I need to…PatternLocation
Trigger automation when claims are deniedPM event trigger with event_type + new_status filterEvent types available as triggers
Scope rule execution to payerOptional payer_id filter in trigger configTrigger config shape (FW-03 rule)
Validate tenant-safe executionMatch rule.organization_id to event orgMulti-tenancy and security
Verify run behavior and outcomesAutomation execution logsfw_automation_logs and FW-03 runtime

​
Decision Tree

  1. Receive PM event on cl_pm_events.
  2. Load rules where trigger_type = 'pm_event'.
  3. Match trigger_config.event_type to payload event_type.
  4. Apply optional filters (new_status, payer_id) when configured.
  5. Execute actions for matching rules and persist run logs to fw_automation_logs.

​
Pattern Library

  • Event subscriber pattern: FW-03 consumes PM events and drives automation dispatch.
  • Publisher pattern: PM-07/PM-08/PM-09 emit domain events with automation-ready payloads.
  • Contract-first pattern: Payload shape governed by EVENT_CONTRACTS.md.

​
Common Mistakes

PitfallImpactFix
Missing organization_id in payloadCross-tenant rule leakage riskRequire organization_id on every PM automation event
Treating omitted filters as hard requirementsRules never matchOmitted new_status/payer_id means wildcard match
Using null and omitted inconsistently for payer filtersInconsistent rule behaviorNormalize filter semantics in builder and executor

​
Pre-Flight Checklist

  • Event payload includes organization_id.
  • Rule execution enforces rule.organization_id = event.organization_id.
  • Runtime writes execution trails to fw_automation_logs.
  • Dry-run/circuit-breaker behavior validated for high-volume bursts.
  • Payload schema matches EVENT_CONTRACTS.md definitions.

​
Integration Points

Owner / ComponentPatternStatusPurpose
FW-03 Automation EngineEvent subscriber📝 PlannedSubscribes to cl_pm_events; matches rules by trigger_type/trigger_config; executes actions; logs to fw_automation_logs
PM-07Event publisher📝 PlannedPublishes charge_approved / charge_status_changed when charge status transitions
PM-08Event publisher📝 PlannedPublishes claim_submitted, claim_status_changed, optionally claim_created, denial_received
PM-09Event publisher📝 PlannedPublishes payment_posted, write_off_approved
EVENT_CONTRACTSContract doc📝 PlannedPayload schemas and “PM events as automation triggers” subsection; PM-19 reference

​
Event Contracts (Consumed by FW-03)

Payload schemas are defined in EVENT_CONTRACTS.md. This section summarizes the PM events as automation triggers contract for PM-19.

​
Event types available as triggers

Event TypeWhen PublishedPayload fields used for filtering
claim_submittedClaim status → submittedorganization_id, claim_id, payer_id
claim_status_changedClaim status changesorganization_id, claim_id, new_status, payer_id
claim_createdOptional: claim created (draft)organization_id, claim_id, payer_id
denial_receivedOptional: denial_codes updatedorganization_id, claim_id, payer_id
charge_approvedCharge status → approvedorganization_id, charge_id
charge_status_changedAny charge status changeorganization_id, charge_id, new_status
payment_postedPayment postedorganization_id, payment_id, claim_id
write_off_approvedWrite-off approvedorganization_id, approval_id, payment_id, write_off_amount (optional filter: claim_id)

​
Trigger config shape (FW-03 rule)

Stored in fw_automation_rules.trigger_config (or equivalent): 
interface PMEventTriggerConfig {
  event_type: 'claim_submitted' | 'claim_status_changed' | 'claim_created' | 'denial_received'
    | 'charge_approved' | 'charge_status_changed' | 'payment_posted' | 'write_off_approved';
  new_status?: string;   // e.g. 'denied', 'approved', 'paid'
  payer_id?: string | null;     // UUID or null; omit = any payer
}
Matching rules: Executor loads rules where trigger_type = 'pm_event' and trigger_config.event_type matches the event; then applies optional filters new_status and payer_id. Omitted filter = any value. Example rule (persisted for Executor to load and match): 
{
  organization_id: uuid,
  trigger_type: 'pm_event',
  trigger_config: {
    event_type: 'claim_status_changed',
    new_status: 'denied',
    payer_id: null  // omit or null = any payer
  },
  actions: [
    { type: 'send_notification', config: { template: 'claim_denied_alert', ... } },
    { type: 'create_task', config: { queue: 'denial_review', ... } }
  ]
}
The Executor subscribes to cl_pm_events, receives an event, loads rules where trigger_type = 'pm_event' and trigger_config.event_type matches (e.g. claim_status_changed), then applies optional filters (new_status, payer_id). Matching rules are executed in order; actions run with event payload for context.

​
Multi-tenancy and security

  • Event payloads MUST include organization_id.
  • Automation executor MUST only run rules where rule.organization_id = event.organization_id.
  • Payloads use IDs only (no PII/PHI); actions resolve display data via authorized APIs.

​
API Contracts

No new synchronous APIs. All integration is event-based (subscribe to cl_pm_events).

​
References