// includes/services/tasks.php
private static function taskEventDispatch(PDO $conn, string $event, int $taskId, array $extra = []): void
{
    try {
        $rb = $conn->prepare("SELECT title, status_id, priority_id, assigned_analyst_id, due_date, ticket_id FROM tasks WHERE id = ?");
        $rb->execute([$taskId]);
        $taskRow = $rb->fetch(PDO::FETCH_ASSOC) ?: [];
        WorkflowEngine::dispatch($event, [
            'task' => array_merge([
                'id'          => $taskId,
                'title'       => $taskRow['title'] ?? null,
                'status_id'   => isset($taskRow['status_id']) ? (int)$taskRow['status_id'] : null,
                'priority_id' => isset($taskRow['priority_id']) ? (int)$taskRow['priority_id'] : null,
                'assignee_id' => isset($taskRow['assigned_analyst_id']) ? (int)$taskRow['assigned_analyst_id'] : null,
                'due_date'    => $taskRow['due_date'] ?? null,
                'ticket_id'   => !empty($taskRow['ticket_id']) ? (int)$taskRow['ticket_id'] : null,   // GH #274
            ], $extra),
        ]);
    } catch (Exception $wfEx) {
        error_log('Workflow dispatch error in task service (' . $event . '): ' . $wfEx->getMessage());
    }
}

/**
 * The ticket a task belongs to (tasks.ticket_id), or null - for task.created, whose payload
 * is built from the input rather than read back (GH #274).
 *
 * TRAP: it travels as task.ticket_id, never as a top-level `ticket` object. A `ticket` key
 * would make the event look like a ticket event: workflowEventTenantId() reads `ticket` first
 * (the task and its ticket can be in different companies), and the notification router and
 * search indexer both act on payload['ticket'].
 */
private static function taskTicketId(PDO $conn, int $taskId): ?int
{
    $s = $conn->prepare("SELECT ticket_id FROM tasks WHERE id = ?");
    $s->execute([$taskId]);
    $v = $s->fetchColumn();
    return $v ? (int)$v : null;
}

// includes/workflow_tenancy.php - workflowEventRecordTables(): the FIRST record found decides the event's company
'ticket'         => ['tickets',            'default'],
'task'           => ['tasks',              'default'],

// workflow/includes/engine.php - availableFields(), after $byTrigger is built
// GH #274: every task event carries the ticket the task belongs to (TasksService),
// so a task workflow can act on its ticket - or check it has one.
foreach ($byTrigger as $k => $f) {
    if (str_starts_with($k, 'task.') && !in_array('task.ticket_id', $f, true)) $byTrigger[$k][] = 'task.ticket_id';
}

private const FIELD_TYPES = [
    // …
    'task.id'                => 'numeric',
    'task.ticket_id'         => 'numeric',   // GH #274

public static function enrichPayloadForTemplates(PDO $conn, array $payload): array
{
    $payload = self::enrichWithLookupNames($conn, $payload);
    $payload = self::enrichWithReferences($conn, $payload);
    $payload = self::enrichWithTaskTicket($conn, $payload);   // GH #274
    return self::enrichWithLinks($conn, $payload);
}

/**
 * GH #274: {{task.ticket_number}}, {{task.ticket_subject}} and {{task.ticket_url}} beside
 * {{task.ticket_id}}. Kept under `task` on purpose - see TasksService::taskTicketId().
 * Never clobbers; a missing ticket (deleted, or none) simply adds nothing.
 */
public static function enrichWithTaskTicket(PDO $conn, array $payload): array
{
    $id = self::dotGet($payload, 'task.ticket_id');
    if ($id === null || $id === '' || !is_numeric($id) || (int)$id <= 0) return $payload;
    try {
        $st = $conn->prepare('SELECT ticket_number, subject FROM tickets WHERE id = ?');
        $st->execute([(int)$id]);
        $t = $st->fetch(PDO::FETCH_ASSOC);
    } catch (Throwable) { $t = false; }
    if (!$t) return $payload;
    if (self::dotGet($payload, 'task.ticket_number') === null) self::dotSet($payload, 'task.ticket_number', (string)$t['ticket_number']);
    if (self::dotGet($payload, 'task.ticket_subject') === null) self::dotSet($payload, 'task.ticket_subject', (string)$t['subject']);
    if (self::dotGet($payload, 'task.ticket_url') === null) {
        try {
            require_once dirname(__DIR__, 2) . '/includes/public_url.php';
            self::dotSet($payload, 'task.ticket_url', rtrim(publicBaseUrl($conn), '/') . '/' . self::RECORD_LINKS['ticket'] . (int)$id);
        } catch (Throwable) { /* a missing link must never break a run */ }
    }
    return $payload;
}

// availableVariables()
if (in_array('task.ticket_id', $fields, true)) {
    $vars[] = ['path' => 'task.ticket_number',  'label' => 'Task · Ticket number',  'note' => 'The reference of the ticket this task belongs to, e.g. ETC-623-64409. Empty when the task has no ticket.'];
    $vars[] = ['path' => 'task.ticket_subject', 'label' => 'Task · Ticket subject', 'note' => 'The subject of the ticket this task belongs to.'];
    $vars[] = ['path' => 'task.ticket_url',     'label' => 'Task · Ticket link',    'note' => 'The full address of the task\'s ticket in FreeITSM.'];
}

// availableActions() - the action list is built into $actions, then:
// GH #274: on a task trigger, a ticket-id arg starts as the TASK's ticket, so
// "task done -> note on its ticket" needs nothing typed. The editor applies it to
// new actions and swaps it when the trigger changes (workflow-editor.js).
foreach ($actions as &$a) {
    foreach ($a['args'] as &$arg) {
        if (is_array($arg) && ($arg['default'] ?? null) === '{{ticket.id}}') $arg['trigger_defaults'] = ['task.' => '{{task.ticket_id}}'];
    }
    unset($arg);
}
unset($a);
return $actions;

private static function executeAction(string $type, array $args, array $payload)
{
    // GH #274: a ticket action on a task workflow whose task has no ticket. Said plainly,
    // rather than "ticket_id is required", which reads like a broken workflow.
    if (isset($args['ticket_id']) && is_string($args['ticket_id']) && str_contains($args['ticket_id'], 'task.ticket_id')
        && trim(self::renderTemplate($args['ticket_id'], $payload)) === '' && $type !== 'create_task') {
        throw new Exception('This task is not linked to a ticket, so there is no ticket to act on. Add the condition "Task · Ticket" is not empty to run only for tasks that have one.');
    }
    switch ($type) {
        case 'set_task_status':     return self::action_set_task_status($args, $payload);    // GH #274
        case 'assign_task':         return self::action_assign_task($args, $payload);
        case 'add_task_comment':    return self::action_add_task_comment($args, $payload);
        // … every other action
    }
}

$taskIdArg = [   // GH #274
    'type'          => 'text',
    'label'         => 'Task ID',
    'default'       => '{{task.id}}',
    'supports_vars' => true,
    'required'      => true,
];
// …
'set_task_status' => [
    'label'       => 'Set task status',
    'description' => 'Change a task\'s status. Moving it to a closed status completes it, exactly as on screen: …',
    'args'        => [
        'task_id'   => $taskIdArg,
        'status_id' => ['type' => 'lookup', 'label' => 'New status', 'lookup' => 'task_status', 'required' => true],
    ],
],
'assign_task' => [
    'label' => 'Assign task to analyst', 'description' => '…',
    'args'  => ['task_id' => $taskIdArg, 'analyst_id' => ['type' => 'lookup', 'label' => 'Assign to', 'lookup' => 'analyst', 'required' => true]],
],
'add_task_comment' => [
    'label' => 'Add a comment to the task', 'description' => '…',
    'args'  => ['task_id' => $taskIdArg, 'comment' => ['type' => 'textarea', 'label' => 'Comment', 'required' => true, 'supports_vars' => true]],
],

const ACTION_MODULES = [
    'create_task'      => 'tasks',
    'set_task_status'  => 'tasks',   // GH #274
    'assign_task'      => 'tasks',
    'add_task_comment' => 'tasks',
    // …
];

/**
 * Who a task action acts as: nobody - the workflow - recorded in the task's history
 * as "workflow". No company scope of its own: assertRecordInRunCompany() is the
 * boundary, as for tickets.
 */
private static function taskActionContext(): ActorContext
{
    require_once dirname(__DIR__, 2) . '/includes/service_context.php';
    require_once dirname(__DIR__, 2) . '/includes/services/tasks.php';
    $name = 'Workflow';
    if (self::$ctxWorkflowId) {
        try {
            $st = connectToDatabase()->prepare('SELECT name FROM workflows WHERE id = ?');
            $st->execute([(int)self::$ctxWorkflowId]);
            $n = $st->fetchColumn();
            if ($n) $name = 'Workflow: ' . $n;
        } catch (Throwable) { /* the plain name will do */ }
    }
    return new ActorContext(0, null, 'workflow', 'en', mb_substr($name, 0, 100));
}

/** The task the action names, checked to exist and to be in the run's company. */
private static function taskForAction(PDO $conn, array $args, array $payload): int
{
    $taskId = self::argInt($args, 'task_id', $payload);
    if (!$taskId) throw new Exception('task_id is required');
    $st = $conn->prepare('SELECT 1 FROM tasks WHERE id = ?');
    $st->execute([$taskId]);
    if (!$st->fetchColumn()) throw new Exception("Unknown task_id: {$taskId}");
    self::assertRecordInRunCompany($conn, 'tasks', $taskId, 'task');
    return $taskId;
}

// includes/services/task_history.php
public static function actor(?ActorContext $ctx): array
{
    if ($ctx === null) return [null, 'system', null];
    if ($ctx->actorId > 0) {
        return [$ctx->actorId, $ctx->source === 'api' ? 'api' : 'analyst', $ctx->actorName !== '' ? $ctx->actorName : null];
    }
    $kind = in_array($ctx->source, ['portal', 'workflow', 'api'], true) ? $ctx->source : 'system';
    return [null, $kind, $ctx->actorName !== '' ? $ctx->actorName : null];
}

private static function action_set_task_status(array $args, array $payload): array
{
    $conn = connectToDatabase();
    $taskId = self::taskForAction($conn, $args, $payload);
    $statusId = self::argInt($args, 'status_id', $payload);
    if (!$statusId) throw new Exception('status_id is required');
    $st = $conn->prepare('SELECT name FROM task_statuses WHERE id = ?');
    $st->execute([$statusId]);
    $name = $st->fetchColumn();
    if ($name === false) throw new Exception("Unknown status_id: {$statusId}");
    try {
        TasksService::saveTask($conn, self::taskActionContext(), ['id' => $taskId, 'status_id' => $statusId]);
    } catch (ServiceError $e) {
        throw new Exception($e->getMessage());   // the completion gate's refusal becomes the step's failure
    }
    return ['task_id' => $taskId, 'status_id' => $statusId, 'status_name' => (string)$name];
}

private static function action_assign_task(array $args, array $payload): array
{
    $conn = connectToDatabase();
    $taskId = self::taskForAction($conn, $args, $payload);
    $analystId = self::argInt($args, 'analyst_id', $payload);
    if (!$analystId) throw new Exception('analyst_id is required');
    self::assertAnalystReachesRunCompany($conn, $analystId);
    $st = $conn->prepare('SELECT full_name FROM analysts WHERE id = ? AND COALESCE(is_active, 1) = 1');
    $st->execute([$analystId]);
    $name = $st->fetchColumn();
    if ($name === false) throw new Exception("Unknown or inactive analyst_id: {$analystId}");
    try {
        TasksService::saveTask($conn, self::taskActionContext(), ['id' => $taskId, 'assigned_analyst_id' => $analystId]);
    } catch (ServiceError $e) {
        throw new Exception($e->getMessage());
    }
    return ['task_id' => $taskId, 'analyst_id' => $analystId, 'analyst_name' => (string)$name];
}

private static function action_add_task_comment(array $args, array $payload): array
{
    $conn = connectToDatabase();
    $taskId = self::taskForAction($conn, $args, $payload);
    $text = self::argString($args, 'comment', $payload);
    if (trim($text) === '') throw new Exception('comment is required');
    try {
        $id = TasksService::createComment($conn, self::taskActionContext(), $taskId, $text);
    } catch (ServiceError $e) {
        throw new Exception($e->getMessage());
    } catch (PDOException $e) {
        throw new Exception('Run System -> Database Verify so a workflow can write a comment with no author: ' . $e->getMessage());
    }
    return ['task_id' => $taskId, 'comment_id' => $id, 'comment_length' => mb_strlen($text)];
}

// includes/services/tasks.php - createComment()
// No person (a workflow - GH #274) is NULL: System. Never 0, which the foreign key refuses.
$conn->prepare("INSERT INTO task_comments (task_id, analyst_id, comment, created_datetime) VALUES (?, ?, ?, UTC_TIMESTAMP())")
     ->execute([$taskId, $ctx->actorId > 0 ? $ctx->actorId : null, $text]);

// `task_comments.analyst_id` was NOT NULL, so a comment no person wrote - the
// workflow action "Add a comment to the task" (GitHub #274) - had no honest value,
// and 0 is refused by `fk_task_comments_analyst`. NULL means System, as it does on
// ticket notes (#281). Relaxing it invalidates no existing row; safe to re-run.
try {
    $tcCol = $conn->prepare(
        "SELECT IS_NULLABLE FROM information_schema.columns
         WHERE table_schema = ? AND table_name = 'task_comments' AND column_name = 'analyst_id'"
    );
    $tcCol->execute([$dbName]);
    $tcRow = $tcCol->fetch(PDO::FETCH_ASSOC);
    if ($tcRow && strtoupper($tcRow['IS_NULLABLE']) === 'NO') {
        $conn->exec("ALTER TABLE `task_comments` MODIFY `analyst_id` INT NULL");
        $results[] = ['table' => 'task_comments', 'status' => 'updated',
                      'details' => ["analyst_id: NOT NULL → NULL (a comment a workflow writes is System)"]];
    }
} catch (Exception $e) {
    // Non-fatal: comments keep working for people; only a workflow's comment is refused.
}

// workflow/includes/templates.php
'task_done_note_on_ticket' => [
    'name'        => 'When a task is done, note it on its ticket',
    'category'    => 'Tasks',
    'description' => 'When a task linked to a ticket is completed, writes an internal note on that ticket naming the task and who owned it - …',
    'trigger_event' => 'task.completed',
    'conditions'  => [
        ['field' => 'task.ticket_id', 'op' => 'is_not_empty', 'value' => ''],
    ],
    'actions'     => [
        [
            'type' => 'add_ticket_note',
            'args' => [
                'ticket_id' => '{{task.ticket_id}}',
                'note'      => "Task completed: {{task.title}} (owner: {{task.assignee_name}}).",
                'write_to'  => 'note',     // a real note by System (#268), not the history
                'shared'    => false,
            ],
        ],
    ],
],

// workflow/includes/engine.php
//   1. $activeWorkflowIds — the stack of workflow ids currently running.
//      A workflow already on the stack is refused re-entry. …
//   2. MAX_CHAIN_DEPTH — a hard ceiling on nesting depth (10).
//   3. MAX_RUNS_PER_REQUEST — a ceiling on total runs in one request (100).

// The example: a real workflow, fired by completing a ZZ task through TasksService
$conn->prepare("INSERT INTO workflows (name, trigger_event, conditions, actions, is_active) VALUES (?, 'task.completed', ?, ?, 1)")->execute([
    "$tag sample",
    json_encode($tpl['conditions']),
    json_encode([['type' => 'add_ticket_note', 'args' => ['ticket_id' => '{{task.ticket_id}}',
                  'note' => "$tag done: {{task.title}} on {{task.ticket_number}}", 'write_to' => 'note']]]),
]);
TasksService::saveTask($conn, $ctx, ['id' => $linked, 'status_id' => $closed]);
// → a ticket note "ZZ274-… done: ZZ274-… linked on <ticket number>", internal, analyst_id NULL
TasksService::saveTask($conn, $ctx, ['id' => $unlinked, 'status_id' => $closed]);
// → no note; the execution is recorded as 'skipped'