spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/tests/unit/security-definer-grants.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+
+// Regression guard for the SECURITY DEFINER RPC exposure fixed in migration
+// 075. Postgres grants EXECUTE on new functions to PUBLIC by default, and
+// Supabase's anon/authenticated roles inherit it — so every definer function
+// ships callable at /rest/v1/rpc/* with the anon key unless the migration
+// explicitly revokes it.
+//
+// This lint statically scans non-archived migrations and asserts that every
+// SECURITY DEFINER function either:
+//   a) is an allowlisted RLS helper (policies evaluate it as the querying
+//      role, so anon/authenticated MUST keep EXECUTE), or
+//   b) is revoked from PUBLIC/anon/authenticated in some migration
+//      (literal REVOKE statement or an entry in a revoke-list DO block), or
+//   c) was dropped.
+// It also asserts every definer function pins search_path — in its own body
+// or via a later ALTER FUNCTION — to close schema-shadowing on privileged code.
+
+const MIGRATIONS_DIR = join(__dirname, '../../migrations')
+
+// anon/authenticated must keep EXECUTE on these: every tenant RLS policy
+// evaluates them as the querying role. Revoking them would break isolation
+// schema-wide — get_accessible_accounts is pinned internally instead (075).
+const EXEC_ALLOWLIST = new Set([
+  'current_actor_id',
+  'get_accessible_accounts',
+])
+
+function migrationFiles(): string[] {
+  return readdirSync(MIGRATIONS_DIR)
+    .filter((f) => /^\d+_.*\.sql$/.test(f))
+    .sort()
+}
+
+interface DefinerDef {
+  name: string
+  file: string
+  hasSearchPath: boolean
+}
+
+// Find CREATE [OR REPLACE] FUNCTION public.name(...) blocks and keep those
+// declared SECURITY DEFINER.
+function findDefinerFunctions(file: string, content: string): DefinerDef[] {
+  const out: DefinerDef[] = []
+  const re = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+public\.(\w+)\s*\(/gi
+  let m: RegExpExecArray | null
+  while ((m = re.exec(content))) {
+    // A function body never spans another top-level CREATE; bound the slice.
+    const rest = content.slice(m.index)
+    const endMatch = rest.slice(1).search(/CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|TRIGGER|POLICY|UNIQUE|INDEX)|CREATE\s+(?:TABLE|POLICY|TRIGGER|INDEX)/i)
+    const body = endMatch === -1 ? rest : rest.slice(0, endMatch + 1)
+    if (/SECURITY\s+DEFINER/i.test(body)) {
+      out.push({
+        name: m[1],
+        file,
+        hasSearchPath: /search_path\s*(?:=|TO)\s*'?public'?/i.test(body),
+      })
+    }
+  }
+  return out
+}
+
+// Names that appear in any literal REVOKE ... ON FUNCTION public.name(...),
+// any DROP FUNCTION public.name, any ALTER FUNCTION public.name SET
+// search_path, or any DO-block that performs those via format()/EXECUTE with
+// signature entries like 'name(arg,arg)'.
+function collectCovered(
+  files: string[],
+  contents: Map<string, string>,
+): { revoked: Set<string>; dropped: Set<string>; pathed: Set<string> } {
+  const revoked = new Set<string>()
+  const dropped = new Set<string>()
+  const pathed = new Set<string>()
+
+  for (const file of files) {
+    const content = contents.get(file)!
+
+    for (const m of content.matchAll(/REVOKE\s+\w+\s+ON\s+FUNCTION\s+public\.(\w+)\s*\(/gi)) {
+      revoked.add(m[1])
+    }
+    for (const m of content.matchAll(/DROP\s+FUNCTION\s+(?:IF\s+EXISTS\s+)?public\.(\w+)\s*\(/gi)) {
+      dropped.add(m[1])
+    }
+    for (const m of content.matchAll(/ALTER\s+FUNCTION\s+public\.(\w+)\s*\([^)]*\)\s*SET\s+search_path/gi)) {
+      pathed.add(m[1])
+    }
+
+    // DO $$ ... $$ blocks that EXECUTE grant-management statements against a
+    // signature list: the signature literals inside the block name the covered
+    // functions (075 pattern).
+    for (const block of content.matchAll(/DO\s+\$\$[\s\S]*?END\s+\$\$;/gi)) {
+      const b = block[0]
+      const doesRevoke = /REVOKE/i.test(b)
+      const doesPath = /ALTER\s+FUNCTION[\s\S]*search_path|search_path[\s\S]*ALTER\s+FUNCTION/i.test(b)
+      if (!doesRevoke && !doesPath) continue
+      for (const m of b.matchAll(/'([a-z_]+)\(([^']*)\)'/g)) {
+        if (doesRevoke) revoked.add(m[1])
+        if (doesPath) pathed.add(m[1])
+      }
+    }
+  }
+
+  return { revoked, dropped, pathed }
+}
+
+describe('SECURITY DEFINER grant hygiene', () => {
+  const files = migrationFiles()
+  const contents = new Map(files.map((f) => [f, readFileSync(join(MIGRATIONS_DIR, f), 'utf8')]))
+  const { revoked, dropped, pathed } = collectCovered(files, contents)
+
+  const definers: DefinerDef[] = files.flatMap((f) => findDefinerFunctions(f, contents.get(f)!))
+  const uniqueNames = [...new Set(definers.map((d) => d.name))]
+
+  it('finds the definer functions we know about', () => {
+    expect(uniqueNames).toEqual(
+      expect.arrayContaining([
+        'match_embeddings',
+        'get_account_apps',
+        'get_accessible_accounts',
+        'current_actor_id',
+        'rebuild_kb_cache',
+        'revoke_embeddings_for_item',
+        'cleanup_old_logs',
+      ]),
+    )
+  })
+
+  it('every definer function is revoked, dropped, or an allowlisted RLS helper', () => {
+    const exposed = uniqueNames.filter(
+      (n) => !EXEC_ALLOWLIST.has(n) && !revoked.has(n) && !dropped.has(n),
+    )
+    expect(
+      exposed,
+      `SECURITY DEFINER functions still executable by PUBLIC/anon/authenticated — ` +
+        `add "REVOKE ALL ON FUNCTION public.<sig> FROM PUBLIC, anon, authenticated" ` +
+        `to a migration, or extend the EXEC_ALLOWLIST if it is an RLS helper:\n  ${exposed.join('\n  ')}`,
+    ).toEqual([])
+  })
+
+  it('every definer function pins search_path', () => {
+    const missing = uniqueNames.filter((n) => {
+      const defs = definers.filter((d) => d.name === n)
+      const anyDefHasPath = defs.some((d) => d.hasSearchPath)
+      return !anyDefHasPath && !pathed.has(n)
+    })
+    expect(
+      missing,
+      `SECURITY DEFINER functions without a pinned search_path — ` +
+        `add SET search_path = public to the definition or ALTER FUNCTION:\n  ${missing.join('\n  ')}`,
+    ).toEqual([])
+  })
+})

package/.framework/tests/unit/system-context-denial.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi } from 'vitest'
+
+// F-051: requireSystemContextWithAudit's ctx overload used to return a
+// Netlify response object on denial; handlers returned it as `result`, so
+// createHandler wrapped it as {data:{statusCode:403}} under HTTP 200. It now
+// throws a statusCode-carrying error which the catch path maps to a real
+// HTTP status. These tests exercise the real createHandler end-to-end for
+// security.ts and tests.ts.
+
+const principalRef = vi.hoisted(() => ({ principal: null as any }))
+
+vi.mock('../../functions/_shared/principal.ts', () => ({
+  resolvePrincipal: vi.fn(async () => principalRef.principal),
+  isSystemAdmin: (p: any) =>
+    !!p?.roles?.some((r: any) => r === 'system_admin' || r?.slug === 'system_admin'),
+  getPrincipalDb: () => ({}),
+}))
+
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: {
+    from: () => {
+      const builder: any = {}
+      for (const m of [
+        'select', 'eq', 'in', 'is', 'ilike', 'filter', 'not', 'order', 'limit',
+        'update', 'insert', 'upsert', 'delete', 'neq', 'or', 'contains', 'gte',
+        'lte', 'lt', 'range', 'textSearch',
+      ]) {
+        builder[m] = () => builder
+      }
+      builder.single = () => Promise.resolve({ data: null, error: null })
+      builder.maybeSingle = () => Promise.resolve({ data: null, error: null })
+      builder.then = (res: any, rej: any) =>
+        Promise.resolve({ data: [], error: null }).then(res, rej)
+      return builder
+    },
+    rpc: vi.fn(async () => ({ data: null, error: null })),
+    auth: { admin: {} },
+  },
+  getUserDb: vi.fn(() => ({})),
+}))
+
+vi.mock('../../functions/_shared/audit.ts', () => ({
+  emitAudit: vi.fn(async () => {}),
+  emitSpan: vi.fn(async () => {}),
+  emitLog: vi.fn(async () => {}),
+  emitActivity: vi.fn(async () => {}),
+}))
+
+vi.mock('../../functions/_shared/security.ts', () => ({
+  isBlockedRequest: vi.fn(async () => null),
+  isBlockedIp: vi.fn(async () => false),
+  touchPersonGeo: vi.fn(async () => {}),
+}))
+
+vi.mock('../../functions/_shared/geo.ts', () => ({
+  getClientGeo: vi.fn(() => ({ ip: '127.0.0.1' })),
+}))
+
+import { requireSystemContextWithAudit } from '../../functions/_shared/middleware'
+import { handler as securityHandler } from '../../functions/security'
+import { handler as testsHandler } from '../../functions/tests'
+
+const memberPrincipal = {
+  id: 'p-member',
+  type: 'human',
+  accountId: 'acct-1',
+  roles: ['member'],
+  provenance: { sourceType: 'jwt', createdBy: null, invokedAt: new Date().toISOString() },
+}
+
+const adminPrincipal = {
+  ...memberPrincipal,
+  id: 'p-admin',
+  roles: ['system_admin'],
+}
+
+const event = (queryStringParameters: Record<string, string> = {}) => ({
+  headers: {},
+  httpMethod: 'GET',
+  path: '/api/x',
+  queryStringParameters,
+  body: null,
+})
+
+describe('requireSystemContextWithAudit ctx overload (F-051)', () => {
+  it('throws a statusCode 403 error for a non-admin principal', () => {
+    const ctx = { principal: memberPrincipal, accountId: 'acct-1' }
+    try {
+      requireSystemContextWithAudit(ctx as any)
+      expect.unreachable('should have thrown')
+    } catch (err: any) {
+      expect(err).toBeInstanceOf(Error)
+      expect(err.statusCode).toBe(403)
+      expect(err.message).toBe('System context required')
+    }
+  })
+
+  it('throws a statusCode 401 error for an anonymous principal', () => {
+    const ctx = { principal: { id: 'anonymous', type: 'machine' }, accountId: null }
+    try {
+      requireSystemContextWithAudit(ctx as any)
+      expect.unreachable('should have thrown')
+    } catch (err: any) {
+      expect(err.statusCode).toBe(401)
+      expect(err.message).toBe('Authentication required')
+    }
+  })
+
+  it('returns null and stamps triggeredBy for a system_admin principal', () => {
+    const ctx: any = { principal: { ...adminPrincipal }, accountId: 'acct-1' }
+    expect(requireSystemContextWithAudit(ctx, 'suite')).toBeNull()
+    expect(ctx.triggeredBy).toBe('suite')
+  })
+})
+
+describe('denied responses are real HTTP errors (F-051)', () => {
+  it('tests.ts returns HTTP 403 — not a 200-wrapped response object', async () => {
+    principalRef.principal = memberPrincipal
+    const res = await testsHandler(event({ action: 'list' }), {})
+    expect(res.statusCode).toBe(403)
+    const body = JSON.parse(res.body)
+    expect(body.error).toBe('System context required')
+    expect(body.data).toBeNull()
+    // Regression shape: previously {statusCode:200, body:{data:{statusCode:403}}}
+    expect(body.data?.statusCode).toBeUndefined()
+  })
+
+  it('security.ts returns HTTP 403 — not a 200-wrapped response object', async () => {
+    principalRef.principal = memberPrincipal
+    const res = await securityHandler(event({ action: 'blocklist' }), {})
+    expect(res.statusCode).toBe(403)
+    const body = JSON.parse(res.body)
+    expect(body.error).toBe('System context required')
+    expect(body.data).toBeNull()
+  })
+
+  it('tests.ts still serves a system_admin principal with HTTP 200', async () => {
+    principalRef.principal = adminPrincipal
+    const res = await testsHandler(event({ action: 'list' }), {})
+    expect(res.statusCode).toBe(200)
+    const body = JSON.parse(res.body)
+    expect(body.error).toBeNull()
+    expect(body.data.data).toEqual([])
+  })
+})

package/.framework/tests/unit/system-cron.test.ts

@@ -0,0 +1,240 @@
+// Tests for system-cron's per-tick maintenance blocks (F-052).
+// Regression: when get_due_schedules returns zero rows the handler used to
+// return early, skipping due timers, threshold alerts, delivery retries,
+// and log cleanup. These tests exercise the handler with all shared deps
+// mocked; createHandler is stubbed to identity so a fabricated
+// RequestContext flows straight into the handler body.
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const {
+  rpcMock,
+  fromMock,
+  emitAuditMock,
+  runPipelineMock,
+  sweepMock,
+  retryMock,
+} = vi.hoisted(() => ({
+  rpcMock: vi.fn(),
+  fromMock: vi.fn(),
+  emitAuditMock: vi.fn(),
+  runPipelineMock: vi.fn(),
+  sweepMock: vi.fn(),
+  retryMock: vi.fn(),
+}))
+
+vi.mock('../../functions/_shared/middleware.ts', () => ({
+  createHandler: (fn: any) => fn,
+}))
+
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: { rpc: rpcMock, from: fromMock },
+}))
+
+vi.mock('../../functions/_shared/audit.ts', () => ({
+  emitAudit: emitAuditMock,
+}))
+
+vi.mock('../../functions/_shared/pipeline-runner.ts', () => ({
+  runPipeline: runPipelineMock,
+  sweepStaleExecutions: sweepMock,
+}))
+
+vi.mock('../../functions/_shared/retry-deliveries.ts', () => ({
+  retryPendingDeliveries: retryMock,
+}))
+
+import { handler } from '../../functions/system-cron.ts'
+
+function makeCtx() {
+  return {
+    requestId: 'test-req',
+    principal: {
+      id: 'system',
+      type: 'machine',
+      machineType: 'internal',
+      accountId: null,
+      scopes: ['*:*'],
+      isInternal: true,
+    },
+    db: {},
+    accountId: null,
+    appId: null,
+    query: {},
+    requestPath: '/.netlify/functions/system-cron',
+    headers: {},
+  }
+}
+
+// Per-RPC-name responses; anything not listed resolves to an empty list.
+function rpcImpl(overrides: Record<string, any> = {}) {
+  return (name: string) => {
+    if (name in overrides) {
+      const v = overrides[name]
+      return v instanceof Error ? Promise.reject(v) : Promise.resolve(v)
+    }
+    return Promise.resolve({ data: [], error: null })
+  }
+}
+
+// Chainable thenable query builder; terminal result is keyed by table name.
+function fromImpl(tableData: Record<string, any> = {}) {
+  return (table: string) => {
+    const result = table in tableData ? tableData[table] : { data: [], error: null }
+    const chain: any = {}
+    for (const m of ['select', 'eq', 'neq', 'lt', 'gt', 'or', 'in', 'order', 'limit', 'insert', 'update', 'single', 'maybeSingle']) {
+      chain[m] = vi.fn(() => chain)
+    }
+    chain.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR)
+    return chain
+  }
+}
+
+const RETRY_SUMMARY = {
+  outbound_retried: 0,
+  outbound_succeeded: 0,
+  outbound_failed: 0,
+  inbound_retried: 0,
+  inbound_succeeded: 0,
+  inbound_failed: 0,
+  errors: [],
+}
+
+describe('system-cron', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    sweepMock.mockResolvedValue(undefined)
+    retryMock.mockResolvedValue(RETRY_SUMMARY)
+  })
+
+  it('runs per-tick maintenance when no schedules are due', async () => {
+    rpcMock.mockImplementation(rpcImpl({
+      get_due_schedules: { data: [], error: null },
+      get_due_timers: { data: [], error: null },
+    }))
+    fromMock.mockImplementation(fromImpl({
+      threshold_alerts: { data: [], error: null },
+    }))
+
+    const res = await handler(makeCtx())
+    expect(res.statusCode).toBe(200)
+
+    // Every per-tick block still ran despite the empty schedule list.
+    expect(sweepMock).toHaveBeenCalledOnce()
+    expect(rpcMock).toHaveBeenCalledWith('get_due_timers', expect.anything())
+    expect(fromMock).toHaveBeenCalledWith('threshold_alerts')
+    expect(retryMock).toHaveBeenCalledOnce()
+
+    const body = JSON.parse(res.body)
+    expect(body.schedules_due).toBe(0)
+    expect(body.executed).toBe(0)
+    expect(body.results).toEqual([])
+    expect(body.thresholds_evaluated).toBe(0)
+    expect(body.deliveries_retried).toEqual(RETRY_SUMMARY)
+  })
+
+  it('executes due timers on a tick with no due schedules', async () => {
+    const timer = {
+      timer_id: 't1',
+      pipeline_id: 'p1',
+      account_id: 'a1',
+      name: 'nightly',
+      execution_count: 3,
+      created_by: 'u1',
+      app_id: null,
+    }
+    rpcMock.mockImplementation(rpcImpl({
+      get_due_schedules: { data: [], error: null },
+      get_due_timers: { data: [timer], error: null },
+      update_timer_after_run: { data: null, error: null },
+    }))
+    fromMock.mockImplementation(fromImpl({
+      threshold_alerts: { data: [], error: null },
+    }))
+    runPipelineMock.mockResolvedValue({ status: 'completed' })
+
+    const res = await handler(makeCtx())
+    expect(res.statusCode).toBe(200)
+
+    expect(runPipelineMock).toHaveBeenCalledWith(
+      'p1',
+      expect.objectContaining({ timer_id: 't1' }),
+      expect.objectContaining({ accountId: 'a1' }),
+    )
+    expect(rpcMock).toHaveBeenCalledWith('update_timer_after_run',
+      expect.objectContaining({ p_timer_id: 't1', p_success: true }))
+
+    const body = JSON.parse(res.body)
+    expect(body.schedules_due).toBe(0)
+    expect(body.executed).toBe(1)
+    expect(body.success).toBe(1)
+    expect(body.results[0].scheduleId).toBe('t1')
+    expect(retryMock).toHaveBeenCalledOnce()
+  })
+
+  it('still reaches delivery retries when the timer block throws', async () => {
+    rpcMock.mockImplementation(rpcImpl({
+      get_due_schedules: { data: [], error: null },
+      get_due_timers: new Error('rpc down'),
+    }))
+    fromMock.mockImplementation(fromImpl({
+      threshold_alerts: { data: [], error: null },
+    }))
+
+    const res = await handler(makeCtx())
+    expect(res.statusCode).toBe(200)
+    expect(retryMock).toHaveBeenCalledOnce()
+  })
+
+  it('still processes due schedules and then runs maintenance', async () => {
+    const schedule = {
+      schedule_id: 's1',
+      action_id: 'act1',
+      account_id: 'a1',
+      machine_principal_id: 'm1',
+      delegated_scopes: ['*:*'],
+      config: {},
+    }
+    const action = {
+      id: 'act1',
+      handler: 'send_email',
+      handler_module: 'functions',
+      config: {},
+      required_scopes: ['*:*'],
+    }
+    const machine = {
+      id: 'm1',
+      account_id: 'a1',
+      scopes: ['*:*'],
+      machine_type: 'internal',
+      is_internal: true,
+      created_by: 'u1',
+    }
+
+    rpcMock.mockImplementation(rpcImpl({
+      get_due_schedules: { data: [schedule], error: null },
+      get_due_timers: { data: [], error: null },
+      validate_schedule_creator: { data: { is_valid: true }, error: null },
+      update_schedule_after_run: { data: null, error: null },
+    }))
+    fromMock.mockImplementation(fromImpl({
+      actions: { data: action, error: null },
+      api_keys: { data: machine, error: null },
+      threshold_alerts: { data: [], error: null },
+      schedule_executions: { data: null, error: null },
+    }))
+
+    const res = await handler(makeCtx())
+    expect(res.statusCode).toBe(200)
+
+    const body = JSON.parse(res.body)
+    expect(body.schedules_due).toBe(1)
+    expect(body.executed).toBe(1)
+    expect(body.success).toBe(1)
+    expect(body.results[0].scheduleId).toBe('s1')
+
+    // Maintenance blocks still ran after schedule processing.
+    expect(rpcMock).toHaveBeenCalledWith('get_due_timers', expect.anything())
+    expect(fromMock).toHaveBeenCalledWith('threshold_alerts')
+    expect(retryMock).toHaveBeenCalledOnce()
+  })
+})

package/.framework/tests/unit/timers.test.ts

@@ -0,0 +1,159 @@
+// Tests for F-056: timers created/activated via the API must be armed
+// (next_execution set) or they can never fire — get_due_timers requires
+// next_execution IS NOT NULL and system-cron is the only consumer.
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { fromMock } = vi.hoisted(() => ({ fromMock: vi.fn() }))
+
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: { from: fromMock, rpc: vi.fn() },
+  joins: {}
+}))
+
+vi.mock('../../functions/_shared/audit.ts', () => ({
+  emitLog: vi.fn().mockResolvedValue(undefined),
+  emitAudit: vi.fn().mockResolvedValue(undefined),
+  emitSpan: vi.fn().mockResolvedValue(undefined)
+}))
+
+vi.mock('../../functions/_shared/permissions.ts', () => ({
+  sanitizeRecordData: vi.fn((_ctx: any, record: any) => Promise.resolve(record))
+}))
+
+import { create, update, toggle } from '../../functions/timers.ts'
+
+// Chainable stand-in for the supabase-js query builder. Every call on a
+// table gets its own builder via a results queue on `db.from`, and all
+// insert/update payloads are recorded in `captured`.
+function makeBuilder(result: any, captured: Array<{ method: string; args: any[] }>) {
+  const b: any = {}
+  for (const m of ['select', 'insert', 'update', 'delete', 'eq', 'order']) {
+    b[m] = vi.fn((...args: any[]) => { captured.push({ method: m, args }); return b })
+  }
+  b.single = vi.fn(() => Promise.resolve(result))
+  b.maybeSingle = vi.fn(() => Promise.resolve(result))
+  b.then = (onFulfilled: any, onRejected?: any) => Promise.resolve(result).then(onFulfilled, onRejected)
+  return b
+}
+
+let captured: Array<{ method: string; args: any[] }>
+let fromResults: any[]
+
+function queueResult(result: any) {
+  fromResults.push(result)
+}
+
+const ctx: any = {
+  requestId: 'req-timer-test',
+  principal: { id: 'person-1', type: 'person', accountId: 'acct-1', roles: [{ slug: 'system_admin' }] },
+  accountId: 'acct-1',
+  appId: null,
+  db: {},
+  query: {}
+}
+
+beforeEach(() => {
+  captured = []
+  fromResults = []
+  fromMock.mockReset()
+  fromMock.mockImplementation(() =>
+    makeBuilder(fromResults.shift() ?? { data: { id: 'timer-1' }, error: null }, captured))
+})
+
+function insertPayload() {
+  return captured.find(c => c.method === 'insert')?.args[0]
+}
+function updatePayload() {
+  return captured.find(c => c.method === 'update')?.args[0]
+}
+const MIN = 60_000
+
+describe('timers.create — F-056 arming', () => {
+  it('arms next_execution from config.interval_minutes', async () => {
+    const before = Date.now()
+    await create(ctx, { name: 'n', timer_type: 'interval', config: { interval_minutes: 15 } })
+    const ts = Date.parse(insertPayload().next_execution)
+    expect(ts).toBeGreaterThanOrEqual(before + 15 * MIN)
+    expect(ts).toBeLessThanOrEqual(Date.now() + 15 * MIN + 1000)
+  })
+
+  it('arms next_execution from legacy config.interval_seconds', async () => {
+    const before = Date.now()
+    await create(ctx, { name: 'n', timer_type: 'interval', config: { interval_seconds: 3600 } })
+    const ts = Date.parse(insertPayload().next_execution)
+    expect(ts).toBeGreaterThanOrEqual(before + 60 * MIN)
+    expect(ts).toBeLessThanOrEqual(Date.now() + 60 * MIN + 1000)
+  })
+
+  it('lets an explicit next_execution win over the computed value', async () => {
+    const explicit = '2030-01-01T00:00:00.000Z'
+    await create(ctx, { name: 'n', timer_type: 'interval', config: { interval_minutes: 5 }, next_execution: explicit })
+    expect(insertPayload().next_execution).toBe(explicit)
+  })
+
+  it('arms a once timer from config.run_at', async () => {
+    const runAt = '2030-06-15T12:00:00.000Z'
+    await create(ctx, { name: 'n', timer_type: 'once', config: { run_at: runAt } })
+    expect(insertPayload().next_execution).toBe(runAt)
+  })
+
+  it('leaves next_execution null when the timer is created inactive', async () => {
+    await create(ctx, { name: 'n', timer_type: 'interval', is_active: false, config: { interval_minutes: 15 } })
+    expect(insertPayload().next_execution).toBeNull()
+    expect(insertPayload().is_active).toBe(false)
+  })
+
+  it('leaves next_execution null when no schedule is computable', async () => {
+    await create(ctx, { name: 'n', timer_type: 'cron', config: { schedule: '*/5 * * * *' } })
+    expect(insertPayload().next_execution).toBeNull()
+  })
+})
+
+describe('timers.update — F-056 arming', () => {
+  it('re-arms next_execution when config changes', async () => {
+    queueResult({ data: { config: { interval_minutes: 60 }, is_active: true }, error: null })
+    const before = Date.now()
+    await update(ctx, { id: 't1', config: { interval_minutes: 10 } })
+    const ts = Date.parse(updatePayload().next_execution)
+    expect(ts).toBeGreaterThanOrEqual(before + 10 * MIN)
+    expect(ts).toBeLessThanOrEqual(Date.now() + 10 * MIN + 1000)
+  })
+
+  it('arms next_execution when an inactive timer is activated via update', async () => {
+    queueResult({ data: { config: { interval_seconds: 600 }, is_active: false }, error: null })
+    const before = Date.now()
+    await update(ctx, { id: 't1', is_active: true })
+    const ts = Date.parse(updatePayload().next_execution)
+    expect(ts).toBeGreaterThanOrEqual(before + 10 * MIN)
+    expect(ts).toBeLessThanOrEqual(Date.now() + 10 * MIN + 1000)
+  })
+
+  it('passes through an explicit next_execution', async () => {
+    const explicit = '2031-03-03T03:03:03.000Z'
+    await update(ctx, { id: 't1', next_execution: explicit })
+    expect(updatePayload().next_execution).toBe(explicit)
+  })
+
+  it('does not touch next_execution for unrelated field updates', async () => {
+    await update(ctx, { id: 't1', name: 'renamed' })
+    expect(updatePayload().next_execution).toBeUndefined()
+  })
+})
+
+describe('timers.toggle — F-056 arming', () => {
+  it('arms next_execution when activating a never-scheduled timer', async () => {
+    queueResult({ data: { is_active: false, name: 'n', config: { interval_minutes: 30 }, next_execution: null }, error: null })
+    const before = Date.now()
+    await toggle(ctx, { id: 't1' })
+    const ts = Date.parse(updatePayload().next_execution)
+    expect(ts).toBeGreaterThanOrEqual(before + 30 * MIN)
+    expect(ts).toBeLessThanOrEqual(Date.now() + 30 * MIN + 1000)
+  })
+
+  it('does not clear next_execution when deactivating', async () => {
+    queueResult({ data: { is_active: true, name: 'n', config: { interval_minutes: 30 }, next_execution: '2030-01-01T00:00:00.000Z' }, error: null })
+    await toggle(ctx, { id: 't1' })
+    expect(updatePayload().is_active).toBe(false)
+    expect(updatePayload().next_execution).toBeUndefined()
+  })
+})