spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/functions/timers.ts

@@ -1,12 +1,28 @@
 // CIL[BEGIN stable_id="~/.framework/functions/timers.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/timers.ts"]
-// CIL[DOC-MACRO purpose="Import shared utilities used by timer Netlify function handlers."]
-// CIL[DOC-RESPONSIBILITY responsibility="Set up module-level imports for middleware, database access, audit logging, and permission helpers."]
-// CIL[DOC-CONTEXT module="timers" layer=".framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts"]
-// CIL[DOC-CONTRACT inputs="None" outputs="None" errors="None" side_effects="None"]
-// CIL[DOC-MICRO logic_summary="Imports createHandler, joins, adminDb, emitLog, sanitizeRecordData, and isSystemAdmin." notable_decisions="Uses shared handlers for both admin and account-scoped queries."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
-// CIL[DOC-AUDIENCE audience="Spine framework internal Netlify function handlers that manage scheduled timers."]
+/**
+ * @module   timers
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module provides timer-related functionalities within the application, leveraging shared middleware and database utilities. It is designed to handle various timer operations, ensuring proper logging and permission checks. INVARIANT: All timer operations must be executed by authenticated users with appropriate permissions.
+ *
+ * @seeAlso middleware.ts (provides request handling capabilities).
+ * @seeAlso db.ts (contains database access utilities).
+ * @seeAlso auditing.ts (handles logging of operations).
+ * @seeAlso permissions.ts (ensures proper access control).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 
 
@@ -17,21 +33,63 @@ import { joins, adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
 import { sanitizeRecordData } from './_shared/permissions'
 import { isSystemAdmin } from './_shared/principal'
-// CIL[DOC-VECTOR type="context" content="purpose='Import shared utilities used by timer Netlify function handlers.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/functions/timers.ts:module_header:module_header"]
+
+// Interval resolution mirrors public.update_timer_after_run (migration
+// 071_timer_interval_keys.sql): config.interval_minutes (minutes) wins,
+// then config.interval_seconds (seconds → minutes). A parseable
+// config.run_at / config.schedule datetime is the fallback so 'once'
+// timers can be armed too.
+// CIL[BEGIN stable_id="~/.framework/functions/timers.ts:intervalMinutesFromConfig:function" type="function" identity="intervalMinutesFromConfig" parent="~/.framework/functions/timers.ts"]
+function intervalMinutesFromConfig(config: any): number | null {
+  const minutes = Number(config?.interval_minutes)
+  if (Number.isFinite(minutes) && minutes > 0) return minutes
+  const seconds = Number(config?.interval_seconds)
+  if (Number.isFinite(seconds) && seconds > 0) return seconds / 60
+  return null
+}
+// CIL[END stable_id="~/.framework/functions/timers.ts:intervalMinutesFromConfig:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/timers.ts:computeNextExecution:function" type="function" identity="computeNextExecution" parent="~/.framework/functions/timers.ts"]
+function computeNextExecution(config: any): string | null {
+  const minutes = intervalMinutesFromConfig(config)
+  if (minutes !== null) {
+    return new Date(Date.now() + minutes * 60_000).toISOString()
+  }
+  // Date.parse is too lenient (it parses cron text like '*/5 * * * *'
+  // into a date), so only ISO-shaped values are accepted as a one-shot
+  // fire time.
+  const raw = config?.run_at ?? config?.schedule
+  if (typeof raw !== 'string' || !/^\d{4}-\d{2}-\d{2}/.test(raw)) return null
+  const runAt = Date.parse(raw)
+  return Number.isFinite(runAt) ? new Date(runAt).toISOString() : null
+}
+// CIL[END stable_id="~/.framework/functions/timers.ts:computeNextExecution:function"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/timers.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/timers.ts"]
-// CIL[DOC-MACRO purpose="List timers for the current account with optional filters."]
-// CIL[DOC-RESPONSIBILITY responsibility="Return a filtered, sanitized list of timer records scoped to the calling account."]
-// CIL[DOC-CONTEXT module="timers" layer=".framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/timers.ts"]
-// CIL[DOC-CONTRACT inputs="ctx.query may include app_id, timer_type, and is_active." outputs="Array of sanitized timer records." errors="Account context required; database query errors." side_effects="None"]
-// CIL[DOC-MICRO logic_summary="Builds a timers query, applies optional equality filters, and sanitizes each returned record." notable_decisions="Falls back to ctx.db unless the caller is a system admin."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
+/**
+ * The 'list' constant retrieves a list of timers based on query parameters and the user's account context. It ensures that only authorized users can access the timer data.
+ *
+ * @throws      Error — Account context required
+ * @sideEffects none
+ * @stability   internal
+ * @calls       isSystemAdmin, adminDb.from, sanitizeRecordData
+ * @cil-generated
+ */
 export const list = createHandler(async (ctx, _body) => {
   const { app_id, timer_type, is_active } = ctx.query || {}
 
@@ -67,21 +125,32 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// CIL[DOC-VECTOR type="context" content="purpose='List timers for the current account with optional filters.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/functions/timers.ts:list:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/timers.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/timers.ts"]
-// CIL[DOC-MACRO purpose="Fetch a single timer by ID."]
-// CIL[DOC-RESPONSIBILITY responsibility="Return a sanitized timer record matching the requested ID."]
-// CIL[DOC-CONTEXT module="timers" layer=".framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/timers.ts"]
-// CIL[DOC-CONTRACT inputs="ctx.query.id" outputs="Sanitized timer record." errors="Timer ID is required; not-found or database errors." side_effects="None"]
-// CIL[DOC-MICRO logic_summary="Queries the timers table by id and returns the sanitized record." notable_decisions="Uses system admin override to select the database connection."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
+/**
+ * Retrieves a timer record from the database based on a provided ID while ensuring that only authorized users can access the timer data.
+ *
+ * @throws      Error — Timer ID is required, Error — database query error.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('timers'), ctx.db.from('timers'), sanitizeRecordData
+ * @cil-generated
+ */
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -101,23 +170,34 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'timer')
 })
-// CIL[DOC-VECTOR type="context" content="purpose='Fetch a single timer by ID.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/functions/timers.ts:get:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/timers.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/timers.ts"]
-// CIL[DOC-MACRO purpose="Create a new timer record for the current account."]
-// CIL[DOC-RESPONSIBILITY responsibility="Insert a timer with the supplied fields and return the created record."]
-// CIL[DOC-CONTEXT module="timers" layer=".framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/timers.ts"]
-// CIL[DOC-CONTRACT inputs="body: app_id, name, description, timer_type, config, pipeline_id, metadata." outputs="Newly created timer record." errors="name and timer_type are required; User context required; database errors." side_effects="Inserts a row into timers; writes an audit log."]
-// CIL[DOC-MICRO logic_summary="Validates required fields, inserts a timer row with defaults, emits a creation audit log, and returns the row." notable_decisions="Stores undefined optional fields as null or empty objects."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
+/**
+ * Creates a new timer entry in the database based on the provided parameters, ensuring required fields are present and user context is valid. This function is essential for managing timer data within the application.
+ *
+ * @throws      Error — name and timer_type are required, Error — User context (person and account) required, Error — database insert error
+ * @sideEffects DB write to 'timers' table, emits a log event for timer creation
+ * @stability   internal
+ * @calls       ctx.db.from('timers'), emitLog
+ * @cil-generated
+ */
 export const create = createHandler(async (ctx, body) => {
-  const { app_id, name, description, timer_type, config, pipeline_id, metadata } = body
+  const { app_id, name, description, timer_type, config, pipeline_id, metadata, is_active, next_execution } = body
 
   if (!name || !timer_type) {
     throw new Error('name and timer_type are required')
@@ -127,7 +207,13 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data, error: err } = await ctx.db
+  const effectiveConfig = config || {}
+  // Omitted is_active falls through to the column DEFAULT (true); the
+  // arming computation mirrors that assumption.
+  const willBeActive = is_active !== false
+
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('timers')
     .insert({
       app_id: app_id || null,
@@ -135,10 +221,15 @@ export const create = createHandler(async (ctx, body) => {
       name,
       description: description || null,
       timer_type,
-      config: config || {},
+      config: effectiveConfig,
       pipeline_id: pipeline_id || null,
       metadata: metadata || {},
-      created_by: ctx.principal.id
+      is_active,
+      // Arm the timer server-side: get_due_timers requires next_execution
+      // IS NOT NULL and nothing else writes it, so a timer created without
+      // it could never fire. An explicit caller-supplied value wins.
+      next_execution: next_execution ?? (willBeActive ? computeNextExecution(effectiveConfig) : null),
+      created_by: ctx.principal.type === 'human' ? ctx.principal.id : null
     })
     .select()
     .single()
@@ -152,21 +243,32 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[DOC-VECTOR type="context" content="purpose='Create a new timer record for the current account.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/functions/timers.ts:create:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/timers.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/timers.ts"]
-// CIL[DOC-MACRO purpose="Update an existing timer's allowed fields."]
-// CIL[DOC-RESPONSIBILITY responsibility="Apply whitelisted field updates to a timer row and return the updated record."]
-// CIL[DOC-CONTEXT module="timers" layer=".framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/timers.ts"]
-// CIL[DOC-CONTRACT inputs="body or ctx.query with id; optional fields from allowed list." outputs="Updated timer record." errors="Timer ID is required; database errors." side_effects="Updates a timers row; writes an audit log."]
-// CIL[DOC-MICRO logic_summary="Extracts the id, builds an update payload from an allow-list, sets updated_at, and emits an update audit log." notable_decisions="Ignores id inside the body and does not re-validate allowed values beyond presence."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
+/**
+ * The 'update' constant defines a handler for updating timer records in the database. It ensures that a valid timer ID is provided and updates the specified fields accordingly.
+ *
+ * @throws      Error — Timer ID is required, Error — database update error
+ * @sideEffects Database update to 'timers' table, logging of the update event.
+ * @stability   internal
+ * @calls       ctx.db.from('timers'), emitLog
+ * @cil-generated
+ */
 export const update = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
   const { id: _bodyId, ...updates } = body || {}
@@ -175,13 +277,34 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('Timer ID is required')
   }
 
-  const allowed = ['name', 'description', 'config', 'pipeline_id', 'metadata', 'is_active', 'timer_type', 'app_id']
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  const allowed = ['name', 'description', 'config', 'pipeline_id', 'metadata', 'is_active', 'timer_type', 'app_id', 'next_execution']
   const updateData: Record<string, any> = { updated_at: new Date().toISOString() }
   for (const key of allowed) {
     if (updates[key] !== undefined) updateData[key] = updates[key]
   }
 
-  const { data, error: err } = await ctx.db
+  // Re-arm when schedule-relevant inputs change and the caller did not set
+  // next_execution explicitly — mirrors update_timer_after_run's interval
+  // resolution so API/UI-edited timers actually fire. Only ever writes a
+  // computed value; it never clears a next_execution it cannot recompute
+  // (e.g. one manually armed out-of-band for a cron timer).
+  if (updateData.next_execution === undefined && (updates.config !== undefined || updates.is_active !== undefined)) {
+    const { data: existing } = await db
+      .from('timers')
+      .select('config, is_active')
+      .eq('id', id)
+      .single()
+    const effectiveActive = updates.is_active ?? existing?.is_active ?? false
+    const effectiveConfig = updates.config ?? existing?.config ?? {}
+    if (effectiveActive) {
+      const computed = computeNextExecution(effectiveConfig)
+      if (computed) updateData.next_execution = computed
+    }
+  }
+
+  const { data, error: err } = await db
     .from('timers')
     .update(updateData)
     .eq('id', id)
@@ -197,21 +320,32 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[DOC-VECTOR type="context" content="purpose='Update an existing timer's allowed fields.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/functions/timers.ts:update:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/timers.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/timers.ts"]
-// CIL[DOC-MACRO purpose="Delete a timer by ID."]
-// CIL[DOC-RESPONSIBILITY responsibility="Remove a timer record from the database and confirm success."]
-// CIL[DOC-CONTEXT module="timers" layer=".framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/timers.ts"]
-// CIL[DOC-CONTRACT inputs="body or ctx.query with id." outputs="{ success: true }." errors="Timer ID is required; Timer not found; database errors." side_effects="Deletes a timers row; writes an audit log."]
-// CIL[DOC-MICRO logic_summary="Fetches the existing timer, deletes the row by id, and emits a deletion audit log." notable_decisions="Reads only name and timer_type before deletion for the audit payload."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
+/**
+ * The 'remove' constant defines a handler for deleting a timer from the database. It ensures that a valid timer ID is provided and logs the deletion event.
+ *
+ * @throws      Error — Timer ID is required, Error — Timer not found
+ * @sideEffects Database write to delete the timer, logging the deletion event.
+ * @stability   internal
+ * @calls       ctx.db.from('timers'), emitLog
+ * @cil-generated
+ */
 export const remove = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
 
@@ -219,7 +353,8 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('Timer ID is required')
   }
 
-  const { data: existing } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: existing } = await db
     .from('timers')
     .select('name, timer_type')
     .eq('id', id)
@@ -229,7 +364,7 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('Timer not found')
   }
 
-  const { error: err } = await ctx.db
+  const { error: err } = await db
     .from('timers')
     .delete()
     .eq('id', id)
@@ -243,21 +378,32 @@ export const remove = createHandler(async (ctx, body) => {
 
   return { success: true }
 })
-// CIL[DOC-VECTOR type="context" content="purpose='Delete a timer by ID.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/functions/timers.ts:remove:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/timers.ts:toggle:constant" type="constant" identity="toggle" parent="~/.framework/functions/timers.ts"]
-// CIL[DOC-MACRO purpose="Toggle the active state of a timer."]
-// CIL[DOC-RESPONSIBILITY responsibility="Flip a timer's is_active flag and return the updated record."]
-// CIL[DOC-CONTEXT module="timers" layer=".framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/timers.ts"]
-// CIL[DOC-CONTRACT inputs="body or ctx.query with id." outputs="Updated timer record with toggled is_active." errors="Timer ID is required; Timer not found; database errors." side_effects="Updates is_active on a timers row; writes an audit log."]
-// CIL[DOC-MICRO logic_summary="Fetches the existing timer, inverts is_active, writes the new status, and emits a toggle audit log." notable_decisions="Also updates updated_at when toggling status."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
+/**
+ * The toggle function updates the active status of a timer based on its ID, ensuring the timer exists before making changes and logging the event. This function is essential for managing timer states in the application.
+ *
+ * @throws      Error — Timer ID is required, Error — Timer not found
+ * @sideEffects Database update to the timers table, logging of the toggle event.
+ * @stability   internal
+ * @calls       ctx.db.from('timers'), emitLog
+ * @cil-generated
+ */
 export const toggle = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
 
@@ -265,9 +411,10 @@ export const toggle = createHandler(async (ctx, body) => {
     throw new Error('Timer ID is required')
   }
 
-  const { data: existing } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: existing } = await db
     .from('timers')
-    .select('is_active, name')
+    .select('is_active, name, config, next_execution')
     .eq('id', id)
     .single()
 
@@ -277,12 +424,20 @@ export const toggle = createHandler(async (ctx, body) => {
 
   const newStatus = !existing.is_active
 
-  const { data, error: err } = await ctx.db
+  const updateFields: Record<string, any> = {
+    is_active: newStatus,
+    updated_at: new Date().toISOString()
+  }
+  // Re-arm on activation when the timer was never scheduled (e.g. created
+  // before next_execution became writable).
+  if (newStatus && !existing.next_execution) {
+    const armed = computeNextExecution(existing.config)
+    if (armed) updateFields.next_execution = armed
+  }
+
+  const { data, error: err } = await db
     .from('timers')
-    .update({ 
-      is_active: newStatus,
-      updated_at: new Date().toISOString()
-    })
+    .update(updateFields)
     .eq('id', id)
     .select()
     .single()
@@ -299,10 +454,58 @@ export const toggle = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[DOC-VECTOR type="context" content="purpose='Toggle the active state of a timer.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/functions/timers.ts:toggle:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/timers.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/timers.ts"]
+/**
+ * The handler processes various actions based on the query parameters from the context, providing a centralized entry point for handling different operations related to the resource. It delegates to specific functions for each action.
+ *
+ * @throws      Error — Unsupported action: {action}
+ * @sideEffects none
+ * @stability   internal
+ * @calls       list, get, create, update, remove, toggle
+ * @cil-generated
+ */
+export const handler = createHandler(async (ctx, body) => {
+  const { action } = ctx.query || {}
+
+  switch (action) {
+    case 'list':
+      return await list(ctx, body)
+    case 'get':
+      return await get(ctx, body)
+    case 'create':
+      return await create(ctx, body)
+    case 'update':
+      return await update(ctx, body)
+    case 'remove':
+      return await remove(ctx, body)
+    case 'toggle':
+      return await toggle(ctx, body)
+    default:
+      throw new Error(`Unsupported action: ${action}`)
+  }
+})
+// CIL[END stable_id="~/.framework/functions/timers.ts:handler:constant"]
+
+
+
+
+
+
+