@zhushanwen/extension-protocol 0.20.0 → 0.21.0

package/dist/index.d.ts

@@ -1644,6 +1644,663 @@ interface SubagentEngineConfigView {
     engineDefaults?: Record<string, string>;
 }
 
+/**
+ * problem-solve-canvas 契约模块 —— marker 与 action 词表（U1 SSOT）。
+ *
+ * 设计锚点：.tmp/tech-design/problem-solve-canvas.md §3.1(1)/(2) + §5-U1。
+ * 本目录是画布三侧（pi extension 工具面 / runtime CanvasService / renderer 视图）
+ * 共享的唯一词表与 schema 来源——防 GUI 与工具两个入口各自发明语义。
+ *
+ * 两层词表（有意分开，勿合并）：
+ * - CANVAS_ACTIONS（16）：CanvasService.mutate 唯一入口的 action 域，
+ *   per-action × actor 权限矩阵按此建制（matrix.ts）。
+ * - CANVAS_MARKER_ACTIONS（16 + 'enter'）：marker 通道（extension select 挂起）
+ *   的 action 域。'enter' 是 canvas_enter 工具「打开已有画布」形态的通道动作：
+ *   读全量 + 登记绑定（sessionId ↔ canvasId），非画布 mutation——不产事件、
+ *   不在权限矩阵内（marker 通道调用方恒为 agent 工具）。创建形态走 'create'
+ *   （marker 通道的 create 只可能来自 canvas_enter 工具，runtime 在该通道
+ *   create 成功时一并登记绑定；GUI 托盘新建走 WS RPC 通道、不登记绑定）。
+ */
+/**
+ * canvas 工具请求的 title marker。runtime event-adapter / CanvasHandler 检测此
+ * marker 区分 canvas 请求与普通 select（SESSION_MANAGER 同款形态）。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突。
+ * 属内部服务类 marker：走 translateInteractiveRequest 显式分支，
+ * 不入 MARKER_DIALOG_FALLBACKS 降级表（畸形 payload 以结构化错误应答回
+ * marker 通道，不降级为用户可见对话框）。
+ */
+declare const CANVAS_MARKER = "\0TAIJI_CANVAS";
+/**
+ * 16 个 mutate / 查询 action 的运行时集合（与 CanvasAction 类型同源——从本目录
+ * actions.ts 的 CANVAS_ACTIONS 数组派生，不写行号：跨 commit 推移会失准）。
+ *
+ * 词序按领域生命周期排列：创建 → 生长 → 编辑 → 方向裁决 → 选定 → 状态转移 →
+ * 评论 → 评论响应 → 审查三动作 → 收敛确认 → 导出 → 派发 → 查询两类。
+ *
+ * 'read' / 'list' 是查询类：不产领域事件、不在「每个 mutation action 至少产出
+ * 一个事件」的对账范围（U2 承接对账，ACTION_EVENT_MAP 为对账 SSOT——state.ts）。
+ */
+declare const CANVAS_ACTIONS: readonly ["create", "grow", "patch", "decide-direction", "select", "transition", "comment", "comment-respond", "review-request", "review-append", "review-resolve", "converge-check", "export", "dispatch", "read", "list"];
+/**
+ * marker 通道词表 = CANVAS_ACTIONS + 'enter'（两层词表的通道层，见文件头说明）。
+ * event-adapter 用它把 JSON 解析出的 action 字符串收窄；表外值折叠为畸形
+ * → 结构化错误应答（不降级对话框）。
+ */
+declare const CANVAS_MARKER_ACTIONS: readonly ["create", "grow", "patch", "decide-direction", "select", "transition", "comment", "comment-respond", "review-request", "review-append", "review-resolve", "converge-check", "export", "dispatch", "read", "list", "enter"];
+
+/**
+ * problem-solve-canvas 契约 —— 领域状态 schema（CanvasState / ReviewReport）与领域事件词表。
+ *
+ * 形状对齐概念文档（.tmp/problem-solve-canvas.md）§2 领域模型：四类图节点 + 评论附件 +
+ * MVP 四种边（decompose / resolve / argue / rebut；constrain / reference 第二版不入词表）+
+ * 生命周期 × 派发二维状态机（§2.4）。
+ *
+ * 本 schema 同时承载两处消费：
+ * - canvas.get RPC reply / canvas_enter（打开形态）的工具结果 = 全量只读视图
+ * - runtime canvas.json 加速快照的落盘形状（events.jsonl 为唯一持久权威，
+ *   快照可由事件流全量重放推导——U2 落盘契约）
+ *
+ * 唯一形状分叉：activeBindings 只在 canvas.get reply 出现（查询侧派生，见字段注释），
+ * 快照与 marker 工具结果不携带。
+ *
+ * 时间字段一律 ISO string（不用 Date）——wire 与落盘 JSON 往返无损，序列化即契约。
+ */
+/** 四类图节点（概念文档 §2.2）。评论不是图节点（裁决点 R2：降为锚定附件）。 */
+type CanvasNodeType = 'question' | 'option' | 'argument' | 'constraint';
+/**
+ * 节点生命周期状态机（概念文档 §2.4，全部图节点；根节点不可搁置/否决）。
+ * 合法转移：draft→under-review / draft→shelved / under-review→passed /
+ * under-review→rejected / under-review→shelved / rejected→draft（复活，须留理由）/
+ * shelved→draft。表外转移 fail-fast（U2 状态机穷举单测承接）。
+ */
+type CanvasNodeLifecycle = 'draft' | 'under-review' | 'passed' | 'rejected' | 'shelved';
+/** MVP 四种边（概念文档 §2.3）。constrain / reference 第二版，词表不预留。 */
+type CanvasEdgeType = 'decompose' | 'resolve' | 'argue' | 'rebut';
+/** 论据极性（裁决点 R1：原「证据」「反对」合并为论据的极性字段）。 */
+type ArgumentPolarity = 'support' | 'object';
+/** 论据素材性：fact 事实（必带核实状态）/ claim 主张。 */
+type ArgumentMateriality = 'fact' | 'claim';
+/** 主干边支撑度三值（裁决点 R3：只评 decompose/resolve 主干边，论证边不评级）。 */
+type SupportRating = 'sufficient' | 'gap' | 'invalid';
+/** 图节点。per-type 字段全部 optional——类型面宽松、领域约束归 U2 不变量校验
+ * （契约层不复制不变量逻辑，避免双权威）。 */
+interface CanvasNode {
+    id: string;
+    type: CanvasNodeType;
+    content: string;
+    lifecycle: CanvasNodeLifecycle;
+    /** option：selected 标记（不变量 3：任一 question 的 resolve 边中 selected 至多一条）。 */
+    selected?: boolean;
+    /** option：选定对比理由（不变量 3：selected 变更须留对比与理由）。 */
+    selectionReason?: string;
+    /** lifecycle=rejected 时的否决记录——不可删除（MVP 不可砍：防 agent 重复提出已否决项）。 */
+    rejection?: {
+        reason: string;
+        reviveCondition?: string;
+    };
+    /** argument：极性。 */
+    polarity?: ArgumentPolarity;
+    /** argument：素材性；fact 时 factVerified 必填（不变量 5）。 */
+    materiality?: ArgumentMateriality;
+    /** argument：核实状态（fact 论据必填；未核实 fact 不得作为 passed 依据——不变量 5）。 */
+    factVerified?: boolean;
+    /** option：执行叶子显式标记（裁决点 R5：叶子是结构派生、执行叶子是规划决策，两不混同）。 */
+    dispatchable?: boolean;
+    /** option：执行叶子完成判据（passed 前必填——不变量 7）。 */
+    criterias?: string[];
+    /** 派发维度（与 lifecycle 正交，仅执行叶子）：dispatched 后登记下游产物指针（不变量 7）。 */
+    dispatch?: {
+        pointer: string;
+        dispatchedAt: string;
+    };
+    createdAt: string;
+}
+/** 图边。argue 边的 to 可指向主干边 id（论证一条分解/解边本身）——targetId 域校验归 U2。 */
+interface CanvasEdge {
+    id: string;
+    type: CanvasEdgeType;
+    /** 起点节点 id（argument 节点）。 */
+    from: string;
+    /** 终点：节点 id 或主干边 id（仅 argue 边可指边）。 */
+    to: string;
+    /** argue 边极性。 */
+    polarity?: ArgumentPolarity;
+    /** 主干边支撑度（decompose/resolve 专用；审查轮次溯源）。 */
+    support?: {
+        rating: SupportRating;
+        gaps?: string[];
+        round?: number;
+    };
+}
+/** 评论附件（锚定在节点或边上，非图成员）。响应状态机承载 agent 响应义务（不变量 8）。 */
+interface CanvasComment {
+    id: string;
+    /** 锚定目标：节点 id 或边 id。 */
+    anchorId: string;
+    text: string;
+    /** 待响应 / 已响应；转已响应前必须留采纳或反驳的痕（不变量 8）。 */
+    status: 'pending' | 'responded';
+    /** 响应留痕：采纳（并落实到图）/ 反驳（留理由）二选一。 */
+    response?: {
+        disposition: 'adopted' | 'rebutted';
+        note: string;
+    };
+    createdAt: string;
+}
+/** 方向裁决记录（裁决点 R4：画布元数据 + 事件留痕，不是图节点）。矩阵限 user 拍板。 */
+interface CanvasDirectionDecision {
+    direction: 'top-down' | 'bottom-up';
+    reason: string;
+    decidedAt: string;
+}
+/** 六维度审查清单（概念文档 §4.3：逐维度打靶，不泛泛「是否合理」）。 */
+type ReviewDimension = 'completeness' | 'necessity' | 'support' | 'authenticity' | 'conflict' | 'depth';
+/** 条目分级：must-fix 清零不收敛；suggestion 处置制（三选一）。 */
+type ReviewSeverity = 'must-fix' | 'suggestion';
+/** 审查终态族（对齐 review-fix-loop 终态集；除 converged 外全部停回用户）。
+ * 各值的驻留口径：converged / max-rounds 驻留于 status；escalated 不驻留——升级经
+ * ReviewEscalated 事件留痕，放行后即回 in-progress（每次升级裁决恰放行一轮，轮次
+ * 预算随放行抬升）；stuck 为终态族词表值，MVP 无触发路径（reviewer 派发失败经
+ * 错误显式上报，不落聚合终态）。 */
+type ReviewReportStatus = 'in-progress' | 'converged' | 'max-rounds' | 'escalated' | 'stuck';
+/** 处置三选一（采纳 / 登记后做 / 拒绝留理由）。 */
+type ReviewResolutionDisposition = 'accepted' | 'deferred' | 'rejected';
+/** 审查报告条目：经图元素 id 引用画布（聚合 2 不变量 1：id 必须存在；R6 裁决点：
+ * 图承载内容、报告承载过程）。 */
+interface ReviewEntry {
+    id: string;
+    round: number;
+    dimension: ReviewDimension;
+    severity: ReviewSeverity;
+    /** 引用的图元素 id（节点 / 边 / 评论）。 */
+    targetId: string;
+    note: string;
+    /** 随条目写回的支撑度评价输入原文（评价结果落 edge.support；round 溯源取条目 round）。 */
+    supportRating?: SupportRating;
+    /** rating='gap' 的缺口清单（与 edge.support.gaps 同源）。 */
+    supportGaps?: string[];
+    /**
+     * 处置记录（first-writer-wins：已有处置记录后再次 review-resolve = 拒绝 +
+     * already_resolved 错误——覆盖会让 R2 审到与登记方实际动作不符的处置表）。
+     */
+    resolution?: {
+        disposition: ReviewResolutionDisposition;
+        /** 处置登记方（agent 执行侧 / user 复核直处）。 */
+        by: 'user' | 'agent';
+        note: string;
+    };
+}
+/** 审查报告聚合（ReviewReport）。挂于 CanvasState.review；null = 从未发起审查。 */
+interface ReviewReport {
+    status: ReviewReportStatus;
+    /** 当前 / 最近轮次（R1 全面审，R2+ 只审上轮处置表 + 攻击点）。 */
+    round: number;
+    maxRounds: number;
+    entries: ReviewEntry[];
+    /** 非 converged 终态的停回说明（聚合 2 不变量 2：max-rounds / escalated / stuck 必附）。 */
+    stopNote?: string;
+    /** 恢复动作建议（停回说明的配套：升级裁决后可再发起）。 */
+    recoverHint?: string;
+}
+/** 画布状态（聚合 1 全量投影；canvas.get reply 与 canvas.json 快照共用形状）。 */
+interface CanvasState {
+    canvasId: string;
+    /** 画布名（canvasId = 短随机 id；重命名属第二版多画布管理，MVP 只读）。 */
+    name: string;
+    /** 根问题三要素（不变量 1：有且仅有一个根节点，类型 question，带完成判据与范围排除）。 */
+    root: {
+        nodeId: string;
+        statement: string;
+        /** 完成判据（可证伪）。 */
+        criterias: string[];
+        /** 范围排除（设计文档 enter 参数表记作 scope 的全称形态）。 */
+        scopeExclusions: string[];
+        /** 根判据经用户确认（收敛判据 1）。 */
+        confirmed?: boolean;
+    };
+    /** 生长方向裁决；未裁决为 null。 */
+    direction: CanvasDirectionDecision | null;
+    nodes: CanvasNode[];
+    edges: CanvasEdge[];
+    comments: CanvasComment[];
+    /** 待重审集合（节点 id；不变量 9：用户改动后该节点到根的路径进入本集合）。 */
+    dirtyPaths: string[];
+    /** 审查报告聚合；null = 从未发起审查。 */
+    review: ReviewReport | null;
+    /** 规划收敛终态（converge-check 校验不变量 10 后置位；export 同校验）。 */
+    converged: boolean;
+    /**
+     * 活跃绑定数（绑定记录 ∩ 存活 session，设计 §3.1(1) 回推节 / §3.1(3) 绑定徽标
+     * 数据源）——canvas.get reply 的查询侧派生值：transport 装配层附加（存活判定经
+     * sessionService，CanvasService 无该依赖），domain 产物与 canvas.json 快照均不含
+     * （绑定是 runtime 内存态、不可由事件流重放推导——落盘会污染「快照可由事件流
+     * 全量重放重建」的唯一权威承诺）。optional = marker 通道（enter/read 工具结果）
+     * 与旧 runtime reply 不携带；消费方缺字段按未知处理（徽标不渲染）。
+     */
+    activeBindings?: number;
+    /**
+     * 收敛阻断清单（canvas-foundation convergenceBlockers 的现算结果，导出面板
+     * 门禁区②格「规划就绪」的逐项呈现数据源——门禁②的判定是 runtime 领域规则
+     * 不跨 wire，本字段把判定结论（缺什么）随 canvas.get 携带给界面）。与
+     * activeBindings 同款查询侧派生：transport 装配层附加，domain 产物与
+     * canvas.json 快照均不含（纯派生值，落盘即与画布状态二源漂移）。optional =
+     * marker 通道（enter/read 工具结果）与旧 runtime reply 不携带；消费方缺字段
+     * 按未知处理（②格退回「由权威校验」措辞形态）。空数组 = 无阻断（已收敛或
+     * 收敛后再改动时仅剩待重审类条目，与门禁③计数互补）。
+     */
+    convergenceBlockers?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** canvas.list 条目：托盘画布列表的数据源（名称 + 阶段徽标 + must-fix 计数）。
+ * 阶段徽标本身是 renderer 派生值（开放 must-fix 或审查进行中 = 审查中；
+ * converged = 已收敛；其余 = 生长中），契约只给派生输入。 */
+interface CanvasListEntry {
+    canvasId: string;
+    name: string;
+    statement: string;
+    converged: boolean;
+    /** 未关闭 must-fix 条目数。 */
+    openMustFix: number;
+    /** 审查报告状态；从未审查为 null。 */
+    reviewStatus: ReviewReportStatus | null;
+}
+/**
+ * 领域事件类型词表（过去式命名，概念文档 §2.6 + U2 增补）。
+ *
+ * 广播 canvas.updated 的 evType 取值域；renderer 按值分流——CanvasCreated 驱动
+ * 创建后自动唤起（U5），其余类型仅作失效提示（重新拉取收敛）。
+ *
+ * SSOT 对账义务（U2 承接）：每个 mutation action 至少产出一个事件，主事件映射
+ * 见 ACTION_EVENT_MAP；read / list 为查询类不产事件、不在对账范围；DirtiedPathMarked
+ * 与审查终态族是 mutate 事务 / 审查编排内的附属事件，不独立对应 action。
+ */
+declare const CANVAS_EVENT_TYPES: readonly ["CanvasCreated", "GrowthDirectionDecided", "NodeCreated", "NodeModified", "StateTransitioned", "OptionSelected", "NodeDispatched", "CommentAdded", "CommentResponded", "ReviewRequested", "ReviewEntryAppended", "ReviewEntryResolved", "ConvergenceChecked", "CanvasExported", "DirtiedPathMarked", "ReviewConverged", "ReviewMaxRoundsReached", "ReviewEscalated"];
+type CanvasEventType = (typeof CANVAS_EVENT_TYPES)[number];
+/**
+ * mutation action → 主领域事件映射（「每个 mutation action 至少产出一个事件」
+ * 的对账 SSOT）。键集约束（= 16 action 减 read/list 的 14 个 mutation action）
+ * 由一致性测试锁定（不在此回引 actions 层——保持依赖单向 actions → state）；
+ * read / list（查询类）不在表内 = 不产事件、不在对账范围——查询写事件会使
+ * append-only 日志体积随读取次数无界增长。U2 实现的事件产出与本表对账；
+ * 本表缺失键即对账红。
+ */
+declare const ACTION_EVENT_MAP: {
+    readonly create: "CanvasCreated";
+    readonly grow: "NodeCreated";
+    readonly patch: "NodeModified";
+    readonly 'decide-direction': "GrowthDirectionDecided";
+    readonly select: "OptionSelected";
+    readonly transition: "StateTransitioned";
+    readonly comment: "CommentAdded";
+    readonly 'comment-respond': "CommentResponded";
+    readonly 'review-request': "ReviewRequested";
+    readonly 'review-append': "ReviewEntryAppended";
+    readonly 'review-resolve': "ReviewEntryResolved";
+    readonly 'converge-check': "ConvergenceChecked";
+    readonly export: "CanvasExported";
+    readonly dispatch: "NodeDispatched";
+};
+
+/**
+ * problem-solve-canvas 契约 —— 错误码词表与恢复动作文案。
+ *
+ * 对齐分级错误处理契约：mutate / marker 调用被拒时返回结构化错误
+ * （code + message + recover），每码附一句恢复指引（设计 §3.1(1)）——
+ * 错误必须指向恢复动作，GUI toast 与 agent 工具结果双呈现同一文案。
+ * 文案面向用户（中文），agent 可读。
+ */
+/** 结构化错误形状（CanvasMutateReply 失败腿 / marker 畸形请求应答共用）。 */
+interface CanvasError {
+    code: CanvasErrorCode;
+    /** 错误概述（发生了什么）。 */
+    message: string;
+    /** 恢复动作指引（下一步怎么做；SSOT = CANVAS_ERROR_RECOVERY，runtime 可附加动态数值）。 */
+    recover: string;
+}
+/**
+ * 错误码词表（封闭 15 值）。分组：
+ * - 寻址 / 形状：canvas_not_found / node_not_found / edge_not_found /
+ *   invalid_params / unknown_action
+ * - 权限：actor_not_allowed（矩阵表外组合 fail-fast）
+ * - 不变量拦截：selection_conflict（不变量 3 双选定）/ cycle_detected（不变量 2 成环）/
+ *   unverified_fact（不变量 5）/ dispatch_blocked（不变量 7）/ not_converged（不变量 10）/
+ *   lifecycle_transition_illegal（状态机表外转移）
+ * - 审查聚合：entry_ref_missing（聚合 2 不变量 1）/ already_resolved（first-writer-wins）/
+ *   review_max_rounds（轮次上限后再发起）
+ */
+declare const CANVAS_ERROR_CODES: readonly ["canvas_not_found", "node_not_found", "invalid_params", "unknown_action", "actor_not_allowed", "selection_conflict", "cycle_detected", "unverified_fact", "dispatch_blocked", "not_converged", "lifecycle_transition_illegal", "entry_ref_missing", "already_resolved", "review_max_rounds", "edge_not_found"];
+type CanvasErrorCode = (typeof CANVAS_ERROR_CODES)[number];
+/**
+ * 每码一句恢复动作文案（SSOT；runtime 构造 CanvasError 时 recover 字段取此处
+ * 模板，可前缀动态数值如「先处置 3 条 must-fix」。缺码 = 词表与文案表漂移，
+ * 由测试锁定非空全覆盖）。
+ */
+declare const CANVAS_ERROR_RECOVERY: Record<CanvasErrorCode, string>;
+/** 构造结构化错误（recover 缺省取词表模板——每码必有恢复指引，构造性保证）。 */
+declare function canvasError(code: CanvasErrorCode, message: string): CanvasError;
+
+/**
+ * problem-solve-canvas 契约 —— action 参数 / 结果与运行时守卫。
+ *
+ * params 形状对齐设计文档 §3.1(1) action 要点与 §3.1(2) 工具面：
+ * - grow/patch 的节点 id 由 agent 侧生成（全局唯一：时间戳 + 随机），写入按 id
+ *   upsert（同 id 重复写入无副作用）——崩溃窗口（marker 挂起期间 pi 死亡）重试安全
+ * - select 带 replace 参数（换选 = 同一调用事务内先迁出旧 selected 再置新，
+ *   附对比理由——不变量 3 的迁移语义承载）
+ * - canvas_edit 族共享 reason 强制字段（留痕纪律）
+ *
+ * 守卫边界（对齐 session-manager 先例）：类型面校验——形状 / 词表成员资格；
+ * 领域校验（不变量 1-11、邻接矩阵、状态机合法转移）归 U2 CanvasService，
+ * 契约层不复制不变量逻辑（避免双权威）。
+ */
+
+/** 三类写入方（权限矩阵建制维度）：user = GUI 直改 / agent = 工具面 / review = reviewer subagent。 */
+type CanvasActor = 'user' | 'agent' | 'review';
+/** create：根三要素必填（不变量 1）。GUI 托盘「＋新建」与 canvas_enter 创建形态共用。 */
+interface CanvasCreateParams {
+    /** 画布名（缺省由 runtime 按 statement 派生）。 */
+    name?: string;
+    statement: string;
+    /** 完成判据（可证伪），至少一条。 */
+    criterias: string[];
+    /** 范围排除（设计文档 enter 参数表记作 scope）。 */
+    scopeExclusions: string[];
+}
+/** grow 批条目：一条 = 一个新节点 + 其与既有图的一条连接边。 */
+interface CanvasGrowItem {
+    /** agent 生成全局唯一 id（时间戳 + 随机）；幂等 upsert 键——崩溃窗口重试不产生重复节点。 */
+    id: string;
+    type: CanvasNodeType;
+    content: string;
+    /** 连接目标：既有节点 id（或 argue 指主干边时的边 id）。 */
+    attachTo: string;
+    /** 连接边类型。 */
+    edge: CanvasEdgeType;
+    /** edge='argue' 时必带极性；同时作为 argument 节点的极性（裁决点 R1：极性是论据字段）。 */
+    edgePolarity?: ArgumentPolarity;
+    /**
+     * type='argument' 时的素材性（缺省 claim）。fact 时核实状态随事件必带
+     * （不变量 5：fact 论据必须携带核实状态）——U2 领域层补写的通道。
+     */
+    materiality?: ArgumentMateriality;
+    /** materiality='fact' 时的核实状态（缺省 false = 已携带「未核实」）。 */
+    factVerified?: boolean;
+    /** type='option' 时可显式标记执行叶子。 */
+    dispatchable?: boolean;
+}
+interface CanvasGrowParams {
+    canvasId: string;
+    /** 批量生长：批内任一校验失败 = 整批拒绝、无部分写入（原子事务）。 */
+    batch: CanvasGrowItem[];
+    /** 变更理由（留痕纪律：没有理由的 agent 改动不可审计）。 */
+    reason: string;
+}
+interface CanvasPatchParams {
+    canvasId: string;
+    nodeId: string;
+    content?: string;
+    /** 执行叶子完成判据编辑。 */
+    criterias?: string[];
+    /** 执行叶子标记变更。 */
+    dispatchable?: boolean;
+    /** fact 论据核实状态翻转。 */
+    factVerified?: boolean;
+    reason: string;
+}
+interface CanvasDecideDirectionParams {
+    canvasId: string;
+    direction: 'top-down' | 'bottom-up';
+    reason: string;
+}
+interface CanvasSelectParams {
+    canvasId: string;
+    /** 被选定方案所属的 question 节点 id。 */
+    questionId: string;
+    optionId: string;
+    /**
+     * 换选迁移语义：同一调用事务内先迁出旧 selected（fromOptionId）再置新，
+     * 旧选中方案的整个子树进入待重审（D9）。不带 replace 时旧选定已存在
+     * → selection_conflict 拒绝（不变量 3）。
+     */
+    replace?: {
+        fromOptionId: string;
+    };
+    /** 对比理由（不变量 3：选择须留对比与理由）。 */
+    reason: string;
+}
+interface CanvasTransitionParams {
+    canvasId: string;
+    nodeId: string;
+    /** 目标生命周期态（合法转移表校验归 U2；rejected 须附否决记录——不可删除）。 */
+    to: CanvasNodeLifecycle;
+    /** 否决记录（to='rejected' 时必填：否决理由，可附复活条件）。 */
+    rejection?: {
+        reason: string;
+        reviveCondition?: string;
+    };
+    reason: string;
+}
+interface CanvasCommentParams {
+    canvasId: string;
+    /** 锚定目标：节点 id 或边 id。 */
+    anchorId: string;
+    text: string;
+}
+interface CanvasCommentRespondParams {
+    canvasId: string;
+    commentId: string;
+    /** 采纳（并落实到图）/ 反驳（留理由）二选一——不允许无视（不变量 8 响应义务）。 */
+    disposition: 'adopted' | 'rebutted';
+    /** 响应留痕（采纳的落实说明 / 反驳的理由）。 */
+    note: string;
+}
+interface CanvasReviewRequestParams {
+    canvasId: string;
+    /** R2+ 轮次的审查范围收窄描述（「上轮处置表 + 攻击点」）；R1 全面审缺省。 */
+    scope?: string;
+}
+/** review-append 单条报告条目输入（id 由 reviewer 生成，幂等 upsert 同 grow）。 */
+interface CanvasReviewEntryInput {
+    id: string;
+    round: number;
+    dimension: ReviewDimension;
+    severity: ReviewSeverity;
+    /** 引用的图元素 id（必须存在于画布——聚合 2 不变量 1）。 */
+    targetId: string;
+    note: string;
+    /**
+     * 支撑度评价（概念 §2.4「边的缺陷经支撑度表达」的写入通道——审查结论随条目落
+     * edge.support，round 由 runtime 按报告轮次注入「审查轮次溯源」）：targetId 须为
+     * 主干边（decompose/resolve，裁决点 R3——论证边不评级），非主干边携带即拒。
+     */
+    supportRating?: SupportRating;
+    /** rating='gap' 的缺口清单（「有缺口附清单」词条语义：至少一条）；sufficient/invalid 不带。 */
+    supportGaps?: string[];
+}
+interface CanvasReviewAppendParams {
+    canvasId: string;
+    /** 报告归属轮次。 */
+    round: number;
+    entries: CanvasReviewEntryInput[];
+}
+interface CanvasReviewResolveParams {
+    canvasId: string;
+    entryId: string;
+    /** 处置三选一（采纳 / 登记后做 / 拒绝留理由）。 */
+    disposition: 'accepted' | 'deferred' | 'rejected';
+    /** 处置说明（拒绝时为拒绝理由）。 */
+    note: string;
+}
+/** converge-check：无业务参数——三门禁校验（不变量 10）+ 置 converged 终态。 */
+interface CanvasConvergeCheckParams {
+    canvasId: string;
+}
+type CanvasExportTarget = {
+    target: 'planning-doc';
+} | {
+    target: 'requirement-card'; /** 需求卡对应的执行叶子节点 id。 */
+    leafId: string;
+};
+interface CanvasExportParams {
+    canvasId: string;
+    target: CanvasExportTarget;
+}
+interface CanvasDispatchParams {
+    canvasId: string;
+    /** 执行叶子节点 id（dispatched 前必须 passed——不变量 7）。 */
+    nodeId: string;
+    /** 下游产物指针（必填：设计文档 / impl-plan 位置，用户手填）。 */
+    pointer: string;
+}
+interface CanvasReadParams {
+    canvasId: string;
+    /** 子树读取：从该节点 id 向下的主干子树；缺省读全量。 */
+    subtree?: string;
+}
+/** list：无参数（全量画布清单；过滤无字段——Record 结构性拒绝夹带）。 */
+type CanvasListParams = Record<string, never>;
+/** 16 action 的 params 映射（SSOT；两通道共用——WS RPC 与 marker 的 params 同构）。 */
+interface CanvasActionParams {
+    create: CanvasCreateParams;
+    grow: CanvasGrowParams;
+    patch: CanvasPatchParams;
+    'decide-direction': CanvasDecideDirectionParams;
+    select: CanvasSelectParams;
+    transition: CanvasTransitionParams;
+    comment: CanvasCommentParams;
+    'comment-respond': CanvasCommentRespondParams;
+    'review-request': CanvasReviewRequestParams;
+    'review-append': CanvasReviewAppendParams;
+    'review-resolve': CanvasReviewResolveParams;
+    'converge-check': CanvasConvergeCheckParams;
+    export: CanvasExportParams;
+    dispatch: CanvasDispatchParams;
+    read: CanvasReadParams;
+    list: CanvasListParams;
+}
+type CanvasAction = (typeof CANVAS_ACTIONS)[number];
+/** mutate 请求判别联合：按 action 收窄 params（renderer / handler 两侧 switch 同构收窄）。 */
+type CanvasMutateRequest = {
+    [A in CanvasAction]: {
+        action: A;
+        params: CanvasActionParams[A];
+    };
+}[CanvasAction];
+type CanvasMarkerAction = (typeof CANVAS_MARKER_ACTIONS)[number];
+/** enter（canvas_enter 打开形态）：读全量 + 登记绑定；非画布 mutation、不产事件。 */
+interface CanvasEnterParams {
+    canvasId: string;
+}
+/** marker 通道 params 映射 = mutate 词表 params + enter。 */
+interface CanvasMarkerParams extends CanvasActionParams {
+    enter: CanvasEnterParams;
+}
+/** marker 请求条目（extension select 挂起载荷：[{action, params}]，session-manager 同构）。 */
+interface CanvasMarkerRequest {
+    action: CanvasMarkerAction;
+    params: CanvasMarkerParams[CanvasMarkerAction];
+}
+/** mutate 统一两态信封（mcp McpMutationResult 先例；广播 canvas.updated 与本信封
+ * 的成功腿同源同值——调用方拿本 mutation 的事件回执，全量状态经 canvas.get 拉取）。 */
+type CanvasMutateReply = {
+    ok: true;
+    eventId: string;
+    evType: CanvasEventType;
+    summary: string;
+} | {
+    ok: false;
+    error: CanvasError;
+};
+/** canvas.list reply。 */
+interface CanvasListReply {
+    canvases: CanvasListEntry[];
+}
+/** enter / read 的结果：画布全量（打开即完整图——设计目标 1「用户点开即见完整图」）。 */
+type CanvasReadReply = CanvasState;
+declare function isCanvasCreateParams(v: unknown): v is CanvasCreateParams;
+declare function isCanvasGrowParams(v: unknown): v is CanvasGrowParams;
+declare function isCanvasPatchParams(v: unknown): v is CanvasPatchParams;
+declare function isCanvasDecideDirectionParams(v: unknown): v is CanvasDecideDirectionParams;
+declare function isCanvasSelectParams(v: unknown): v is CanvasSelectParams;
+declare function isCanvasTransitionParams(v: unknown): v is CanvasTransitionParams;
+declare function isCanvasCommentParams(v: unknown): v is CanvasCommentParams;
+declare function isCanvasCommentRespondParams(v: unknown): v is CanvasCommentRespondParams;
+declare function isCanvasReviewRequestParams(v: unknown): v is CanvasReviewRequestParams;
+declare function isCanvasReviewAppendParams(v: unknown): v is CanvasReviewAppendParams;
+declare function isCanvasReviewResolveParams(v: unknown): v is CanvasReviewResolveParams;
+declare function isCanvasConvergeCheckParams(v: unknown): v is CanvasConvergeCheckParams;
+declare function isCanvasExportParams(v: unknown): v is CanvasExportParams;
+declare function isCanvasDispatchParams(v: unknown): v is CanvasDispatchParams;
+declare function isCanvasReadParams(v: unknown): v is CanvasReadParams;
+/** list：无参数——Record 结构性拒绝夹带任何过滤字段（session-manager list 同款）。 */
+declare function isCanvasListParams(v: unknown): v is CanvasListParams;
+/** enter（canvas_enter 打开形态）：封闭单键 canvasId。 */
+declare function isCanvasEnterParams(v: unknown): v is CanvasEnterParams;
+/** marker 通道总守卫：action + params 按 marker 词表分派；表外 action 返回 false
+ * （event-adapter / CanvasHandler 据此走结构化错误应答）。 */
+declare function isCanvasMarkerRequest(v: unknown): v is CanvasMarkerRequest;
+/** 材料性守卫（grow item 的 materiality 类型面收窄备用；U2 重建回放读侧消费）。 */
+declare function isArgumentMateriality(v: unknown): v is ArgumentMateriality;
+/** 论据极性守卫（读侧收窄备用）。 */
+declare function isArgumentPolarity(v: unknown): v is ArgumentPolarity;
+
+/**
+ * 权限矩阵：action × actor → 是否合法。逐格对齐设计 §3.1(1) 矩阵表：
+ * - decide-direction / comment / converge-check / dispatch 仅 user（用户裁决性动作，
+ *   agent 侧走对话文本建议 / 代执行边界见设计；review 无）
+ * - review-append 仅 review（reviewer subagent 的报告写回通道）
+ * - read / list 全 actor 开放（查询类）
+ * - select 的 agent 格 = 仅代执行用户明示指令——语义约束落 prompt 指引层（U4），
+ *   runtime 按通道放行、不按意图判定（矩阵此格为 true）
+ */
+declare const CANVAS_ACTOR_MATRIX: Record<CanvasAction, Record<CanvasActor, boolean>>;
+/** 矩阵单格查询（CanvasService 唯一入口的校验原语；表外组合 = false → fail-fast）。 */
+declare function isActionAllowed(action: CanvasAction, actor: CanvasActor): boolean;
+/** 六工具动词族（全部 exposure: "deferred"）：工具名 → 该工具承载的 action 清单。
+ * enter 打开形态走 marker 通道 'enter' 动作（非 mutation、不在本表——本表只登记
+ * mutate 词表落点）；canvas_enter 创建形态落 create。 */
+declare const TOOL_ACTION_MAP: {
+    readonly canvas_enter: readonly ["create"];
+    readonly canvas_edit: readonly ["grow", "patch", "select", "transition", "comment-respond"];
+    readonly canvas_read: readonly ["read"];
+    readonly canvas_review: readonly ["review-request", "review-append", "review-resolve"];
+    readonly canvas_export: readonly ["export"];
+    readonly canvas_list: readonly ["list"];
+};
+type CanvasToolName = keyof typeof TOOL_ACTION_MAP;
+/** 六工具名清单（U4 工具面注册对账用）。 */
+declare const CANVAS_TOOL_NAMES: readonly CanvasToolName[];
+/**
+ * 非工具入口动作（4 个）：不进任何工具、仅 GUI（WS RPC mutate, actor=user）直达的
+ * 用户裁决性动作——「16 action 全部进入映射对账」的另一半（工具可达 12 + GUI-only 4
+ * = 词表 16）。全部仅 user（权限矩阵）：
+ * - decide-direction：方向裁决是终裁决动作，agent 不得自主（方向推荐走对话文本建议）
+ * - comment：评论 = 用户注入议题；响应义务方是 agent（走 comment-respond）
+ * - converge-check：确认收敛 = 用户点击（三门禁校验后置 converged 终态）
+ * - dispatch：派发 = 用户逐叶确认 + 手填下游指针（D8 裁决：派发 = 用户拍板）
+ */
+declare const NON_TOOL_ACTIONS: readonly [{
+    readonly action: "decide-direction";
+    readonly entry: "gui-only（用户拍板：方向裁决是终裁决动作，agent 不得自主）";
+}, {
+    readonly action: "comment";
+    readonly entry: "gui-only（评论 = 用户注入议题；响应义务方是 agent，走 comment-respond）";
+}, {
+    readonly action: "converge-check";
+    readonly entry: "gui-only（确认收敛 = 用户点击，三门禁校验后置终态）";
+}, {
+    readonly action: "dispatch";
+    readonly entry: "gui-only（派发 = 用户逐叶确认 + 手填下游指针，用户拍板）";
+}];
+/** 反查：action 由哪个工具承载（未命中 = 非工具动作，见 NON_TOOL_ACTIONS）。 */
+declare function toolOfAction(action: CanvasAction): CanvasToolName | undefined;
+/** 全部映射动作的并集（对账辅助；一致性测试断言其与 CANVAS_ACTIONS 的关系）。 */
+declare function allToolActions(): CanvasAction[];
+/** 词表全集（对账辅助：-export const 引用，保持三方对账口径单点）。 */
+declare function allCanvasActions(): readonly CanvasAction[];
+
 /**
  * pending entries 差集核心（落盘形态语义：customType 字符串 + 抵消/去重规则）——
  * 跨端单一实现（ext-simplify-13 D3）。
@@ -1726,4 +2383,4 @@ declare function collectActivePendingIds(entries: unknown[], opts?: CollectPendi
 type MappedPendingStatus = 'completed' | 'failed' | 'cancelled' | 'expired' | 'time_limited' | 'aborted';
 declare function mapReasonToStatus(reason: string): MappedPendingStatus;
 
-export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, SCHEDULER_MODAL_VIEW_ID, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, TASK_ENTRY_TYPE, type TaskKind, type TaskSnapshot, type TaskStatus, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, appendExecutionRecord, applyPendingDiff, callMarkerRpc, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readLifecycleState, readResumeHint, replayFoldEntries, scanPendingEntries, setWidgetDual, snapshotToTask, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };
+export { ACTION_EVENT_MAP, ASK_USER_MARKER, type ArgumentMateriality, type ArgumentPolarity, type AskUserAnswers, type AskUserOption, type AskUserQuestion, CANVAS_ACTIONS, CANVAS_ACTOR_MATRIX, CANVAS_ERROR_CODES, CANVAS_ERROR_RECOVERY, CANVAS_EVENT_TYPES, CANVAS_MARKER, CANVAS_MARKER_ACTIONS, CANVAS_TOOL_NAMES, type CanvasAction, type CanvasActionParams, type CanvasActor, type CanvasComment, type CanvasCommentParams, type CanvasCommentRespondParams, type CanvasConvergeCheckParams, type CanvasCreateParams, type CanvasDecideDirectionParams, type CanvasDirectionDecision, type CanvasDispatchParams, type CanvasEdge, type CanvasEdgeType, type CanvasEnterParams, type CanvasError, type CanvasErrorCode, type CanvasEventType, type CanvasExportParams, type CanvasExportTarget, type CanvasGrowItem, type CanvasGrowParams, type CanvasListEntry, type CanvasListParams, type CanvasListReply, type CanvasMarkerAction, type CanvasMarkerParams, type CanvasMarkerRequest, type CanvasMutateReply, type CanvasMutateRequest, type CanvasNode, type CanvasNodeLifecycle, type CanvasNodeType, type CanvasPatchParams, type CanvasReadParams, type CanvasReadReply, type CanvasReviewAppendParams, type CanvasReviewEntryInput, type CanvasReviewRequestParams, type CanvasReviewResolveParams, type CanvasSelectParams, type CanvasState, type CanvasToolName, type CanvasTransitionParams, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, NON_TOOL_ACTIONS, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, type ReviewDimension, type ReviewEntry, type ReviewReport, type ReviewReportStatus, type ReviewResolutionDisposition, type ReviewSeverity, SCHEDULER_MODAL_VIEW_ID, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SupportRating, TASK_ENTRY_TYPE, TOOL_ACTION_MAP, type TaskKind, type TaskSnapshot, type TaskStatus, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, allCanvasActions, allToolActions, appendExecutionRecord, applyPendingDiff, callMarkerRpc, canvasError, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isActionAllowed, isArgumentMateriality, isArgumentPolarity, isAskUserQuestion, isCanvasCommentParams, isCanvasCommentRespondParams, isCanvasConvergeCheckParams, isCanvasCreateParams, isCanvasDecideDirectionParams, isCanvasDispatchParams, isCanvasEnterParams, isCanvasExportParams, isCanvasGrowParams, isCanvasListParams, isCanvasMarkerRequest, isCanvasPatchParams, isCanvasReadParams, isCanvasReviewAppendParams, isCanvasReviewRequestParams, isCanvasReviewResolveParams, isCanvasSelectParams, isCanvasTransitionParams, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readLifecycleState, readResumeHint, replayFoldEntries, scanPendingEntries, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -794,6 +794,310 @@ var SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
 // src/extensions/subagent-engine/contract.ts
 var SUBAGENTS_ENGINES_FILENAME = "engines.json";
 
+// src/extensions/canvas/marker.ts
+var CANVAS_MARKER = "\0TAIJI_CANVAS";
+var CANVAS_ACTIONS = [
+  "create",
+  "grow",
+  "patch",
+  "decide-direction",
+  "select",
+  "transition",
+  "comment",
+  "comment-respond",
+  "review-request",
+  "review-append",
+  "review-resolve",
+  "converge-check",
+  "export",
+  "dispatch",
+  "read",
+  "list"
+];
+var CANVAS_MARKER_ACTIONS = [...CANVAS_ACTIONS, "enter"];
+
+// src/extensions/canvas/actions.ts
+function isRecord4(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isOptionalString3(v) {
+  return v === void 0 || typeof v === "string";
+}
+function isStringArray2(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function isOptionalStringArray(v) {
+  return v === void 0 || isStringArray2(v);
+}
+function isOptionalBoolean(v) {
+  return v === void 0 || typeof v === "boolean";
+}
+function isStringIn(set, v) {
+  return typeof v === "string" && set.includes(v);
+}
+function isOptionalGuarded(guard, v) {
+  return v === void 0 || guard(v);
+}
+function isStringField(v, key) {
+  return typeof v[key] === "string";
+}
+function requireCanvasId(v) {
+  return isStringField(v, "canvasId");
+}
+function isCanvasCreateParams(v) {
+  return isRecord4(v) && isOptionalString3(v.name) && typeof v.statement === "string" && isStringArray2(v.criterias) && isStringArray2(v.scopeExclusions);
+}
+var CANVAS_NODE_TYPES = ["question", "option", "argument", "constraint"];
+var CANVAS_EDGE_TYPES = ["decompose", "resolve", "argue", "rebut"];
+var ARGUMENT_POLARITIES = ["support", "object"];
+function isCanvasGrowItem(v) {
+  return isRecord4(v) && isStringField(v, "id") && isStringIn(CANVAS_NODE_TYPES, v.type) && isStringField(v, "content") && isStringField(v, "attachTo") && isStringIn(CANVAS_EDGE_TYPES, v.edge) && isOptionalGuarded(isArgumentPolarity, v.edgePolarity) && isOptionalGuarded(isArgumentMateriality, v.materiality) && isOptionalBoolean(v.factVerified) && isOptionalBoolean(v.dispatchable);
+}
+function isCanvasGrowParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && Array.isArray(v.batch) && v.batch.every((item) => isCanvasGrowItem(item)) && typeof v.reason === "string";
+}
+function isCanvasPatchParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isStringField(v, "nodeId") && isOptionalString3(v.content) && isOptionalStringArray(v.criterias) && isOptionalBoolean(v.dispatchable) && isOptionalBoolean(v.factVerified) && typeof v.reason === "string";
+}
+function isCanvasDecideDirectionParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isStringIn(["top-down", "bottom-up"], v.direction) && typeof v.reason === "string";
+}
+function isCanvasSelectParams(v) {
+  if (!(isRecord4(v) && requireCanvasId(v) && isStringField(v, "questionId") && isStringField(v, "optionId") && typeof v.reason === "string")) {
+    return false;
+  }
+  if (v.replace === void 0) return true;
+  return isRecord4(v.replace) && isStringField(v.replace, "fromOptionId");
+}
+var CANVAS_LIFECYCLES = ["draft", "under-review", "passed", "rejected", "shelved"];
+function isCanvasTransitionParams(v) {
+  if (!(isRecord4(v) && requireCanvasId(v) && isStringField(v, "nodeId") && typeof v.reason === "string")) {
+    return false;
+  }
+  if (!isStringIn(CANVAS_LIFECYCLES, v.to)) return false;
+  if (v.rejection === void 0) return true;
+  return isRecord4(v.rejection) && isStringField(v.rejection, "reason") && isOptionalString3(v.rejection.reviveCondition);
+}
+function isCanvasCommentParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isStringField(v, "anchorId") && typeof v.text === "string";
+}
+function isCanvasCommentRespondParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isStringField(v, "commentId") && isStringIn(["adopted", "rebutted"], v.disposition) && typeof v.note === "string";
+}
+function isCanvasReviewRequestParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isOptionalString3(v.scope);
+}
+var REVIEW_DIMENSIONS = ["completeness", "necessity", "support", "authenticity", "conflict", "depth"];
+var REVIEW_SEVERITIES = ["must-fix", "suggestion"];
+var SUPPORT_RATINGS = ["sufficient", "gap", "invalid"];
+function isCanvasReviewEntryInput(v) {
+  return isRecord4(v) && isStringField(v, "id") && typeof v.round === "number" && Number.isFinite(v.round) && isStringIn(REVIEW_DIMENSIONS, v.dimension) && isStringIn(REVIEW_SEVERITIES, v.severity) && isStringField(v, "targetId") && typeof v.note === "string" && isReviewSupportShape(v) && isReviewSupportSemantics(v);
+}
+function isReviewSupportShape(v) {
+  if (v.supportRating !== void 0 && !isStringIn(SUPPORT_RATINGS, v.supportRating)) return false;
+  return v.supportGaps === void 0 || isStringArray2(v.supportGaps);
+}
+function isReviewSupportSemantics(v) {
+  if (v.supportGaps === void 0) return v.supportRating !== "gap";
+  if (v.supportRating !== "gap") return false;
+  return Array.isArray(v.supportGaps) && v.supportGaps.length > 0;
+}
+function isCanvasReviewAppendParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && typeof v.round === "number" && Number.isFinite(v.round) && Array.isArray(v.entries) && v.entries.every((entry) => isCanvasReviewEntryInput(entry));
+}
+function isCanvasReviewResolveParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isStringField(v, "entryId") && isStringIn(["accepted", "deferred", "rejected"], v.disposition) && typeof v.note === "string";
+}
+function isCanvasConvergeCheckParams(v) {
+  return isRecord4(v) && requireCanvasId(v);
+}
+function isCanvasExportParams(v) {
+  if (!(isRecord4(v) && requireCanvasId(v))) return false;
+  const target = v.target;
+  if (!isRecord4(target)) return false;
+  if (target.target === "planning-doc") return true;
+  return target.target === "requirement-card" && isStringField(target, "leafId");
+}
+function isCanvasDispatchParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isStringField(v, "nodeId") && isStringField(v, "pointer");
+}
+function isCanvasReadParams(v) {
+  return isRecord4(v) && requireCanvasId(v) && isOptionalString3(v.subtree);
+}
+function isCanvasListParams(v) {
+  return isRecord4(v);
+}
+function isCanvasEnterParams(v) {
+  if (!isRecord4(v)) return false;
+  const keys = Object.keys(v);
+  return keys.length === 1 && keys[0] === "canvasId" && typeof v.canvasId === "string";
+}
+var MARKER_PARAMS_GUARDS = {
+  create: isCanvasCreateParams,
+  grow: isCanvasGrowParams,
+  patch: isCanvasPatchParams,
+  "decide-direction": isCanvasDecideDirectionParams,
+  select: isCanvasSelectParams,
+  transition: isCanvasTransitionParams,
+  comment: isCanvasCommentParams,
+  "comment-respond": isCanvasCommentRespondParams,
+  "review-request": isCanvasReviewRequestParams,
+  "review-append": isCanvasReviewAppendParams,
+  "review-resolve": isCanvasReviewResolveParams,
+  "converge-check": isCanvasConvergeCheckParams,
+  export: isCanvasExportParams,
+  dispatch: isCanvasDispatchParams,
+  read: isCanvasReadParams,
+  list: isCanvasListParams,
+  enter: isCanvasEnterParams
+};
+function isCanvasMarkerRequest(v) {
+  if (!isRecord4(v)) return false;
+  if (!isStringIn(CANVAS_MARKER_ACTIONS, v.action)) return false;
+  const action = v.action;
+  return MARKER_PARAMS_GUARDS[action](v.params);
+}
+function isArgumentMateriality(v) {
+  return isStringIn(["fact", "claim"], v);
+}
+function isArgumentPolarity(v) {
+  return isStringIn(ARGUMENT_POLARITIES, v);
+}
+
+// src/extensions/canvas/state.ts
+var CANVAS_EVENT_TYPES = [
+  "CanvasCreated",
+  "GrowthDirectionDecided",
+  "NodeCreated",
+  "NodeModified",
+  "StateTransitioned",
+  "OptionSelected",
+  "NodeDispatched",
+  "CommentAdded",
+  "CommentResponded",
+  "ReviewRequested",
+  "ReviewEntryAppended",
+  "ReviewEntryResolved",
+  "ConvergenceChecked",
+  "CanvasExported",
+  "DirtiedPathMarked",
+  "ReviewConverged",
+  "ReviewMaxRoundsReached",
+  "ReviewEscalated"
+];
+var ACTION_EVENT_MAP = {
+  create: "CanvasCreated",
+  grow: "NodeCreated",
+  patch: "NodeModified",
+  "decide-direction": "GrowthDirectionDecided",
+  select: "OptionSelected",
+  transition: "StateTransitioned",
+  comment: "CommentAdded",
+  "comment-respond": "CommentResponded",
+  "review-request": "ReviewRequested",
+  "review-append": "ReviewEntryAppended",
+  "review-resolve": "ReviewEntryResolved",
+  "converge-check": "ConvergenceChecked",
+  export: "CanvasExported",
+  dispatch: "NodeDispatched"
+};
+
+// src/extensions/canvas/errors.ts
+var CANVAS_ERROR_CODES = [
+  "canvas_not_found",
+  "node_not_found",
+  "invalid_params",
+  "unknown_action",
+  "actor_not_allowed",
+  "selection_conflict",
+  "cycle_detected",
+  "unverified_fact",
+  "dispatch_blocked",
+  "not_converged",
+  "lifecycle_transition_illegal",
+  "entry_ref_missing",
+  "already_resolved",
+  "review_max_rounds",
+  "edge_not_found"
+];
+var CANVAS_ERROR_RECOVERY = {
+  canvas_not_found: "\u753B\u5E03\u4E0D\u5B58\u5728\u6216\u5DF2\u88AB\u5220\u9664\uFF1A\u5148\u7ECF canvas_list / canvas.list \u6838\u5BF9\u753B\u5E03 id \u540E\u91CD\u8BD5",
+  node_not_found: "\u76EE\u6807\u8282\u70B9 id \u4E0D\u5B58\u5728\uFF1A\u5148 canvas_read \u53D6\u5F53\u524D\u6001\uFF0C\u6838\u5BF9\u8282\u70B9 id \u540E\u91CD\u8BD5",
+  edge_not_found: "\u76EE\u6807\u8FB9 id \u4E0D\u5B58\u5728\uFF1A\u5148 canvas_read \u53D6\u5F53\u524D\u6001\uFF0C\u6838\u5BF9\u8FB9 id \u540E\u91CD\u8BD5",
+  invalid_params: "\u8BF7\u6C42\u53C2\u6570\u5F62\u72B6\u975E\u6CD5\uFF1A\u5BF9\u7167\u8BE5 action \u7684 params \u5951\u7EA6\u4FEE\u6B63\u5B57\u6BB5\u540E\u91CD\u8BD5",
+  unknown_action: "action \u4E0D\u5728\u8BCD\u8868\uFF1A\u5BF9\u7167 CANVAS_ACTIONS \u8BCD\u8868\u4FEE\u6B63 action \u540D",
+  actor_not_allowed: "\u5F53\u524D\u64CD\u4F5C\u65B9\u65E0\u6B64\u52A8\u4F5C\u6743\u9650\uFF1A\u67E5\u6743\u9650\u77E9\u9635\uFF08\u8BE5\u52A8\u4F5C\u4EC5\u9650\u7279\u5B9A\u64CD\u4F5C\u65B9\uFF09\uFF0C\u6539\u7531\u6709\u6743\u65B9\u6267\u884C",
+  selection_conflict: "\u8BE5\u95EE\u9898\u5DF2\u6709\u9009\u5B9A\u65B9\u6848\uFF1A\u6362\u9009\u8D70 select \u7684 replace \u53C2\u6570\uFF08\u540C\u4E00\u8C03\u7528\u5185\u8FC1\u79FB\u65E7\u9009\u5B9A\uFF09\u5E76\u9644\u5BF9\u6BD4\u7406\u7531",
+  cycle_detected: "\u8BE5\u8FB9\u4F1A\u4F7F\u4E3B\u5E72\u6210\u73AF\uFF1A\u5206\u89E3/\u89E3\u8FB9\u53EA\u80FD\u6307\u5411\u4E0A\u5C42\u8282\u70B9\u7684\u4E0B\u5C42\uFF0C\u53BB\u6389\u56DE\u8FB9\u540E\u91CD\u8BD5",
+  unverified_fact: "\u672A\u6838\u5B9E\u7684 fact \u8BBA\u636E\u4E0D\u5F97\u4F5C\u4E3A\u901A\u8FC7\u4F9D\u636E\uFF1A\u5148\u8865\u6838\u5B9E\u72B6\u6001\uFF08factVerified\uFF09\u518D\u91CD\u8BD5",
+  dispatch_blocked: "\u6267\u884C\u53F6\u5B50\u987B\u5148\u901A\u8FC7\u5BA1\u67E5\uFF08passed\uFF09\u5E76\u586B\u5199\u4E0B\u6E38\u4EA7\u7269\u6307\u9488\uFF0C\u624D\u80FD\u6D3E\u53D1",
+  not_converged: "\u753B\u5E03\u672A\u6536\u655B\uFF1A\u5148\u5904\u7F6E\u5168\u90E8 must-fix / \u6E05\u7A7A\u5F85\u91CD\u5BA1\u8DEF\u5F84 / \u786E\u8BA4\u6839\u5224\u636E\uFF0C\u518D\u6267\u884C\u6536\u655B\u786E\u8BA4\u6216\u5BFC\u51FA",
+  lifecycle_transition_illegal: "\u72B6\u6001\u673A\u4E0D\u5141\u8BB8\u8BE5\u8F6C\u79FB\uFF1A\u5BF9\u7167\u5408\u6CD5\u8F6C\u79FB\u8868\uFF08rejected/shelved \u987B\u5148\u590D\u6D3B\u4E3A draft\uFF09\uFF0C\u6216\u7559\u7406\u7531\u8D70\u590D\u6D3B\u8DEF\u5F84",
+  entry_ref_missing: "\u62A5\u544A\u6761\u76EE\u5F15\u7528\u7684\u56FE\u5143\u7D20 id \u4E0D\u5B58\u5728\uFF1A\u5148 canvas_read \u6838\u5BF9\u76EE\u6807 id \u540E\u91CD\u8BD5",
+  already_resolved: "\u8BE5\u6761\u76EE\u5DF2\u6709\u5904\u7F6E\u8BB0\u5F55\uFF08\u5148\u767B\u8BB0\u5148\u751F\u6548\uFF09\uFF1A\u6539\u5224\u8D70\u4E0B\u4E00\u8F6E\u5BA1\u67E5\u590D\u5BA1\uFF0C\u6216\u5728 GUI \u4EE5\u65B0\u8F6E\u6B21\u5904\u7F6E",
+  review_max_rounds: "\u5BA1\u67E5\u5DF2\u8FBE\u8F6E\u6B21\u4E0A\u9650\uFF1A\u5347\u7EA7\u88C1\u51B3\uFF08\u6269\u5927\u5BA1\u67E5\u8303\u56F4\u6216\u4FEE\u6539\u5224\u636E\uFF09\u540E\u91CD\u65B0\u53D1\u8D77\u5BA1\u67E5"
+};
+function canvasError(code, message) {
+  return { code, message, recover: CANVAS_ERROR_RECOVERY[code] };
+}
+
+// src/extensions/canvas/matrix.ts
+var CANVAS_ACTOR_MATRIX = {
+  create: { user: true, agent: true, review: false },
+  grow: { user: false, agent: true, review: false },
+  patch: { user: true, agent: true, review: false },
+  "decide-direction": { user: true, agent: false, review: false },
+  select: { user: true, agent: true, review: false },
+  transition: { user: true, agent: true, review: false },
+  comment: { user: true, agent: false, review: false },
+  "comment-respond": { user: false, agent: true, review: false },
+  "review-request": { user: true, agent: true, review: false },
+  "review-append": { user: false, agent: false, review: true },
+  "review-resolve": { user: true, agent: true, review: false },
+  "converge-check": { user: true, agent: false, review: false },
+  export: { user: true, agent: true, review: false },
+  dispatch: { user: true, agent: false, review: false },
+  read: { user: true, agent: true, review: true },
+  list: { user: true, agent: true, review: true }
+};
+function isActionAllowed(action, actor) {
+  return CANVAS_ACTOR_MATRIX[action][actor];
+}
+var TOOL_ACTION_MAP = {
+  canvas_enter: ["create"],
+  canvas_edit: ["grow", "patch", "select", "transition", "comment-respond"],
+  canvas_read: ["read"],
+  canvas_review: ["review-request", "review-append", "review-resolve"],
+  canvas_export: ["export"],
+  canvas_list: ["list"]
+};
+var CANVAS_TOOL_NAMES = Object.keys(TOOL_ACTION_MAP);
+var NON_TOOL_ACTIONS = [
+  { action: "decide-direction", entry: "gui-only\uFF08\u7528\u6237\u62CD\u677F\uFF1A\u65B9\u5411\u88C1\u51B3\u662F\u7EC8\u88C1\u51B3\u52A8\u4F5C\uFF0Cagent \u4E0D\u5F97\u81EA\u4E3B\uFF09" },
+  { action: "comment", entry: "gui-only\uFF08\u8BC4\u8BBA = \u7528\u6237\u6CE8\u5165\u8BAE\u9898\uFF1B\u54CD\u5E94\u4E49\u52A1\u65B9\u662F agent\uFF0C\u8D70 comment-respond\uFF09" },
+  { action: "converge-check", entry: "gui-only\uFF08\u786E\u8BA4\u6536\u655B = \u7528\u6237\u70B9\u51FB\uFF0C\u4E09\u95E8\u7981\u6821\u9A8C\u540E\u7F6E\u7EC8\u6001\uFF09" },
+  { action: "dispatch", entry: "gui-only\uFF08\u6D3E\u53D1 = \u7528\u6237\u9010\u53F6\u786E\u8BA4 + \u624B\u586B\u4E0B\u6E38\u6307\u9488\uFF0C\u7528\u6237\u62CD\u677F\uFF09" }
+];
+function toolOfAction(action) {
+  for (const tool of CANVAS_TOOL_NAMES) {
+    const actions = TOOL_ACTION_MAP[tool];
+    if (actions.includes(action)) return tool;
+  }
+  return void 0;
+}
+function allToolActions() {
+  const out = [];
+  for (const tool of CANVAS_TOOL_NAMES) {
+    for (const action of TOOL_ACTION_MAP[tool]) {
+      if (!out.includes(action)) out.push(action);
+    }
+  }
+  return out;
+}
+function allCanvasActions() {
+  return CANVAS_ACTIONS;
+}
+
 // src/pending-entries.ts
 var PENDING_REGISTER_ENTRY_TYPE = "pending:register";
 var PENDING_UNREGISTER_ENTRY_TYPE = "pending:unregister";
@@ -854,11 +1158,20 @@ function mapReasonToStatus(reason) {
   return REASON_STATUS_MAP[reason] ?? "completed";
 }
 export {
+  ACTION_EVENT_MAP,
   ASK_USER_MARKER,
   BACKGROUND_TASK_ID_PREFIX,
   BACKGROUND_TASK_REGISTRY_FILENAME,
   BACKGROUND_TASK_REGISTRY_VERSION,
   BASE_TOOL_ENHANCE_DIRNAME,
+  CANVAS_ACTIONS,
+  CANVAS_ACTOR_MATRIX,
+  CANVAS_ERROR_CODES,
+  CANVAS_ERROR_RECOVERY,
+  CANVAS_EVENT_TYPES,
+  CANVAS_MARKER,
+  CANVAS_MARKER_ACTIONS,
+  CANVAS_TOOL_NAMES,
   GUI_WIDGET_MARKER,
   HISTORY_LIMIT,
   INFLIGHT_REPORT_ACK,
@@ -868,6 +1181,7 @@ export {
   MS_PER_HOUR,
   MS_PER_MINUTE,
   MS_PER_SECOND,
+  NON_TOOL_ACTIONS,
   PENDING_REGISTER_ENTRY_TYPE,
   PENDING_UNREGISTER_ENTRY_TYPE,
   PLAN_LIFECYCLE_EVENTS,
@@ -886,11 +1200,15 @@ export {
   SUBAGENT_INFLIGHT_MARKER,
   SUBAGENT_JOURNAL_MARKER,
   TASK_ENTRY_TYPE,
+  TOOL_ACTION_MAP,
   UI_FORM_MARKER,
   WORKFLOW_RESULT_CUSTOM_TYPE,
+  allCanvasActions,
+  allToolActions,
   appendExecutionRecord,
   applyPendingDiff,
   callMarkerRpc,
+  canvasError,
   collectActivePendingIds,
   dateToOnceCron,
   derivePhase,
@@ -905,9 +1223,30 @@ export {
   guiComponent,
   guiResult,
   guiSetWidget,
+  isActionAllowed,
   isActiveBackgroundTaskState,
+  isArgumentMateriality,
+  isArgumentPolarity,
   isAskUserQuestion,
   isBackgroundTaskRegistryEntry,
+  isCanvasCommentParams,
+  isCanvasCommentRespondParams,
+  isCanvasConvergeCheckParams,
+  isCanvasCreateParams,
+  isCanvasDecideDirectionParams,
+  isCanvasDispatchParams,
+  isCanvasEnterParams,
+  isCanvasExportParams,
+  isCanvasGrowParams,
+  isCanvasListParams,
+  isCanvasMarkerRequest,
+  isCanvasPatchParams,
+  isCanvasReadParams,
+  isCanvasReviewAppendParams,
+  isCanvasReviewRequestParams,
+  isCanvasReviewResolveParams,
+  isCanvasSelectParams,
+  isCanvasTransitionParams,
   isChannelErrorResult,
   isFormAnswers,
   isFormQuestion,
@@ -941,6 +1280,7 @@ export {
   scanPendingEntries,
   setWidgetDual,
   snapshotToTask,
+  toolOfAction,
   transition,
   truncateSelfReview,
   uiFormInteract,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/extension-protocol",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Cross-layer pi extension contract package: dual-mode (TUI/GUI) rendering helpers, session/background-task/pending-entries protocols, and shared behavior primitives",
   "type": "module",
   "main": "dist/index.js",