/* meow_ams_start.h — MSG_AMS_START 拉起决策（AMSD_DESIGN §4.3）。
 *
 * 独立模块以便宿主单测：pending 状态 + 拉起决策都在此，启动/解析/日志经 ops 注入
 * （生产=launcher 既有链路 launch_app/launch_activity + resolve_chain + logmsg；
 * 测试=假件，见 test_ams_start.c）。
 *
 * 约定（与 launcher 其余模块一致）：本模块函数返回负的 MEOW_ERR_*（-1=INVAL / -8=BUSY）
 * 表示拒绝，0 表示受理。ipc_dispatch 用 `a.code=(uint32_t)(rc<0?-rc:MEOW_OK)` 把负错误码
 * 转成正的 ack.code（幅度）；amsd 侧按 `(uint32_t)(-MEOW_ERR_BUSY)` 识别 busy。
 * —— 历史上 set() 误返回 `-MEOW_ERR_BUSY`（=+8，正）导致 ipc_dispatch 把拒绝当 OK，
 *    表现为「am start 报 OK 但 App 未拉起」；本模块统一为负错误码（根因修复）。
 */
#ifndef MEOW_AMS_START_H
#define MEOW_AMS_START_H

#include "meow_ipc.h"   /* MEOW_APP_ID_MAX / MEOW_ACT_MAX / MEOW_CHAIN_MAX / MEOW_ERR_* */

/* 启动/解析/日志回调注入（单测=假件；生产在 meow_ipc_init 末尾组装）。 */
struct meow_ams_ops {
    /* 执行启动。idx=调用方应用表下标；chain 空=裸启动。
     * 复用 launcher 既有链路：launch_app(&apps[idx]) / launch_activity(&apps[idx], chain)。
     * 返回 0=已受理（app 已运行至退出）；<0=启动失败/未找到。 */
    int  (*launch)(int idx, const char *chain);
    /* 解析 activity 链（resolve_chain）。返回 MEOW_OK / MEOW_ERR_NOENT。 */
    int  (*resolve)(const char *app_id, const char *activity, char *chain, int *depth);
    /* 日志（可空=静默）。 */
    void (*log)(const char *fmt, ...);
};

/* 组装 ops（launcher meow_ipc_init 末尾 / 测试 main 调用）。launch/resolve 须非 NULL。 */
void meow_ams_ops_init(const struct meow_ams_ops *ops);

/* 同步「前台 App 会话」占用位（=g_app_session_active）。
 * busy=1 时 pending_start_set 拒绝（-MEOW_ERR_BUSY）且 consume 不动作。 */
void meow_ams_set_busy(int busy);

/* 置 pending（ipc_dispatch MSG_AMS_START 时调）。
 * pkg 空 → -MEOW_ERR_INVAL；busy → -MEOW_ERR_BUSY；否则置位并返回 0。 */
int  meow_ams_pending_start_set(const char *pkg, const char *act);

/* 二期 picker 扩载荷：置 pending + 武装 picker 上下文（pick_action 非空时，launch_app_chain
 * 入口经 meow_ams_take_picker 注入 MEOW_PICKER_ACTION/REQ_ID/CALLER）。错误语义同 set。 */
int  meow_ams_pending_start_set_ex(const char *pkg, const char *act,
                                   const char *pick_action, uint32_t pick_req,
                                   const char *pick_caller);

/* 消费 pending（各主循环排空 IPC 后 / run_menu 循环调用）。
 * ids=napps 个应用主键串指针（apps[i].id）；state=菜单态（0=就绪；非 0=列表未就绪不拉起，
 * pending 保留待重扫重试）。toast/toast_len=错误提示槽（可空）。
 * app_ran=输出：1=app 已运行；0=未运行（拒绝/失败）。idx_out=输出：本次使用的应用表下标
 * （-1=未命中应用；>=0 且 app_ran=0 表示启动失败，调用方应据 apps[idx].name 打 launch_fail_toast）。
 * 返回：0=无 pending 或 busy（暂不动作）；1=已消费（拉起成功/拒绝并清 pending，toast 已设）；
 *       2=列表未就绪（pending 保留待重扫重试，toast 已设「not ready」，调用方勿红冲）。 */
int  meow_ams_start_consume(const char *const *ids, int napps, int state,
                            char *toast, int toast_len, int *app_ran, int *idx_out);

/* 消费拾取 picker 上下文（launch_app_chain 入口调用，一次性清位）。
 * 返回 1=有 picker 上下文；0=无。 */
int  meow_ams_take_picker(char *action, int action_len,
                          char *caller, int caller_len, uint32_t *req);

#endif /* MEOW_AMS_START_H */