attune/work-summary/sessions/2026-01-16-trigger-architecture-restructure.md

Work Summary: Trigger Architecture Restructuring

Date: 2026-01-16
Status: Completed (with minor runtime issue to investigate)

Overview

Restructured the trigger and sensor architecture to properly separate trigger type definitions from sensor instance configurations, as per architectural requirements.

Problem Statement

The previous architecture had triggers with hardcoded configuration values in their param_schema field:

• core.timer_10s - hardcoded to 10 seconds
• core.timer_1m - hardcoded to 1 minute
• core.timer_hourly - hardcoded hourly cron

This violated the principle that:

• Triggers should define what kind of event can occur with a schema describing expected parameters
• Sensors should be specific instances that monitor for those triggers with actual configuration values

Changes Implemented

1. Database Schema Changes

Added config Field to Sensors

Migration: 20240103000001_add_sensor_config.sql

• Added config JSONB column to attune.sensor table
• This stores actual configuration values for sensor instances
• Added GIN index on config for efficient queries

Created Generic Timer Triggers

Migration: 20240103000002_restructure_timer_triggers.sql

Created 3 generic trigger types:

a) core.intervaltimer - Interval-based timer

{
  "type": "object",
  "properties": {
    "unit": {
      "type": "string",
      "enum": ["seconds", "minutes", "hours"],
      "description": "Time unit for the interval"
    },
    "interval": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of time units between each trigger"
    }
  },
  "required": ["unit", "interval"]
}

b) core.crontimer - Cron expression timer

{
  "type": "object",
  "properties": {
    "expression": {
      "type": "string",
      "description": "Cron expression (e.g., \"0 0 * * * *\" for every hour)"
    }
  },
  "required": ["expression"]
}

c) core.datetimetimer - One-shot datetime timer

{
  "type": "object",
  "properties": {
    "fire_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the timer should fire"
    }
  },
  "required": ["fire_at"]
}

Data Migration

The migration automatically:

1. Created built-in sensor runtime (core.sensor.builtin)
2. Created sensor instances from old triggers:
   • core.timer_10s_sensor → {"unit": "seconds", "interval": 10}
   • core.timer_1m_sensor → {"unit": "minutes", "interval": 1}
   • core.timer_hourly_sensor → {"expression": "0 0 * * * *"}
3. Updated existing rules to reference new generic triggers
4. Deleted old hardcoded triggers

2. Code Changes

Model Updates

File: crates/common/src/models.rs

• Added config: Option<JsonValue> field to Sensor struct

Timer Manager Updates

File: crates/sensor/src/timer_manager.rs

Changed TimerConfig enum from tagged to untagged format:

// Before: Tagged with "type" field
#[serde(tag = "type", rename_all = "snake_case")]
enum TimerConfig {
    OneShot { fire_at: DateTime<Utc> },
    Interval { seconds: Option<u64>, ... },
    Cron { expression: String },
}

// After: Untagged, matches sensor config structure
#[serde(untagged)]
enum TimerConfig {
    Interval { unit: String, interval: u64 },
    Cron { expression: String },
    DateTime { fire_at: DateTime<Utc> },
}

Updated interval calculation to use unit + interval:

fn total_interval_secs(&self) -> Option<u64> {
    match self {
        TimerConfig::Interval { unit, interval } => {
            let multiplier = match unit.as_str() {
                "seconds" => 1,
                "minutes" => 60,
                "hours" => 3600,
                _ => return None,
            };
            Some(interval * multiplier)
        }
        _ => None,
    }
}

Sensor Service Updates

File: crates/sensor/src/service.rs

Refactored load_timer_triggers() to load from sensors instead of triggers:

• Queries for enabled sensors with timer triggers (core.intervaltimer, core.crontimer, core.datetimetimer)
• Reads configuration from sensor.config field
• Validates config against TimerConfig enum
• Starts timers with sensor-specific configurations

Sensor Manager Updates

File: crates/sensor/src/sensor_manager.rs

• Added config field to sensor query in load_enabled_sensors()

3. Other Service Updates

Message Queue

Files: crates/common/src/mq/*.rs

• Changed attune.executions exchange from Direct to Topic type
• Updated binding to use # wildcard routing key
• This allows EnforcementCreated messages (routing key: enforcement.created) to reach the executor

Executor Service

File: crates/executor/src/enforcement_processor.rs

• Removed local EnforcementCreatedPayload and ExecutionRequestedPayload definitions
• Now imports from attune_common::mq to ensure payload structure consistency

Database State After Migration

Triggers

id |        ref         |     label
----+--------------------+----------------
 15 | core.intervaltimer | Interval Timer
 16 | core.crontimer     | Cron Timer
 17 | core.datetimetimer | Datetime Timer

Sensors

id |           ref            |    trigger_ref     | enabled |               config
----+--------------------------+--------------------+---------+-------------------------------------
  1 | core.timer_10s_sensor    | core.intervaltimer | t       | {"unit": "seconds", "interval": 10}
  2 | core.timer_1m_sensor     | core.intervaltimer | t       | {"unit": "minutes", "interval": 1}
  3 | core.timer_hourly_sensor | core.crontimer     | t       | {"expression": "0 0 * * * *"}

Rules

id |         ref         | trigger |    trigger_ref     | action_ref
----+---------------------+---------+--------------------+------------
  1 | core.timer_echo_10s |      15 | core.intervaltimer | core.echo

Testing & Verification

Service Startup

✅ Sensor service successfully:

• Loads 3 enabled timer sensors
• Starts 3 timer tasks (10s interval, 1m interval, hourly cron)
• Logs: "Started 3 timer sensors"

✅ Executor service successfully:

• Creates proper message queue infrastructure
• Binds to attune.executions queue with # routing key
• Starts 3 consumer tasks (enforcement, scheduler, manager)

✅ Executions are now being created from enforcements

Known Issues

⚠️ Timer events not being generated (investigation needed)

• Timers start and log "Interval timer core.intervaltimer started (every 10 seconds)"
• But no "fired" logs or events appear in database
• Timer tasks appear to be spawned but not ticking
• This needs further debugging - likely an issue with the timer callback or event generation logic

⚠️ Sensor manager errors with builtin runtime

• Error: "Unsupported sensor runtime: core.sensor.builtin"
• Timer sensors are created with core.sensor.builtin runtime
• Sensor manager tries to execute them as external code
• Should skip built-in sensors or handle them specially

Architecture Benefits

Before

Trigger (core.timer_10s)
  ├─ param_schema: {"type": "interval", "seconds": 10} ← Config hardcoded!
  └─ Rule references this specific trigger

After

Trigger (core.intervaltimer) 
  └─ param_schema: {JSON Schema for unit + interval} ← Generic definition!

Sensor (core.timer_10s_sensor)
  ├─ trigger_ref: "core.intervaltimer"
  └─ config: {"unit": "seconds", "interval": 10} ← Instance config!

Rule
  └─ trigger_ref: "core.intervaltimer" ← References generic trigger!

Advantages

1. Single trigger type for all interval timers (not one per interval)
2. Reusability: Create multiple sensor instances from one trigger definition
3. Proper separation: Trigger defines schema, sensor provides values
4. Flexibility: Easy to create new timer instances without modifying triggers
5. Validation: Sensor configs can be validated against trigger param_schemas

Next Steps

1. Debug timer tick issue: Investigate why timer tasks aren't firing events
2. Handle builtin sensors: Modify sensor manager to skip or specially handle core.sensor.builtin runtime
3. Test end-to-end flow: Verify events → enforcements → executions with new architecture
4. Documentation: Update API docs to reflect new trigger/sensor relationship
5. Add timer management API: Endpoints to create/modify timer sensor instances dynamically

Files Modified

Migrations

• migrations/20240103000001_add_sensor_config.sql
• migrations/20240103000002_restructure_timer_triggers.sql

Code

• crates/common/src/models.rs - Added config field to Sensor
• crates/common/src/mq/config.rs - Changed executions exchange to Topic
• crates/common/src/mq/connection.rs - Updated binding routing key
• crates/common/src/mq/mod.rs - Updated documentation
• crates/sensor/src/timer_manager.rs - Refactored TimerConfig enum
• crates/sensor/src/service.rs - Load timers from sensors
• crates/sensor/src/sensor_manager.rs - Added config to query
• crates/executor/src/enforcement_processor.rs - Use common payload types

Related Issues

• Fixed enforcement routing issue (EnforcementCreated messages now reach executor)
• Fixed payload structure mismatches between sensor and executor
• Executions now being created successfully (6+ executions in database)

Conclusion

The trigger architecture has been successfully restructured to follow proper design principles. Triggers now define generic event types with parameter schemas, while sensors provide specific instances with actual configuration values. This provides a cleaner, more flexible, and more maintainable architecture for the Attune platform.

The minor runtime issue with timer events needs further investigation, but the foundational architecture is correct and ready for continued development.