/**
 * 任务生命周期与 MCP 工具调用契约。
 *
 * 本文件只保留真实运行时消费者需要的跨层数据形状。验证结果由 EvidenceView 表达，
 * 审查结果由 review store 表达，不在这里维护第二套管线结果模型。
 */
import type { DomainName } from "../core/types.js";
/** 任务范围由 start 显式提供，用于声明条件证据的适用性。 */
export interface TaskScope {
    frontend: boolean;
    persistence: boolean;
    api: boolean;
    code: boolean;
}
/** domain_focus 变更来源(R4 审计:advance 逐域推进 vs upgrade_apply 切回退点,两者统一经 manager.setDomainFocus)。 */
export type DomainFocusChangeSource = "advance" | "upgrade_apply";
/** domain_focus 变更审计记录(持久化到 task record,doctor 可查"谁改了当前阶段")。 */
export interface DomainFocusChange {
    from?: DomainName;
    to: DomainName;
    source: DomainFocusChangeSource;
    at: string;
}
/** 只保存生命周期与证据适用性所需事实，不承载领域产物或验证结果。 */
export interface TaskContext {
    task_id: string;
    schema_version: 2;
    created_at: string;
    updated_at?: string;
    intent: string;
    system_context: "greenfield" | "brownfield";
    domain_focus?: DomainName;
    /** 最近一次 domain_focus 变更审计(advance/upgrade_apply 统一经 setDomainFocus 写入;可选,旧 task 无此键兼容)。 */
    last_domain_focus_change?: DomainFocusChange;
    scope: TaskScope;
    status: "active" | "done" | "cancelled";
    /** V2 完整性签名(HMAC-SHA256,覆盖全部字段含 scope/intent/domain_focus/status)。
     *  parseTask 强制校验,防 scope 篡改 / status 复活 / domain_focus 直改(完整性签名覆盖全部字段)。
     *  类型可选仅因内存构造时不设(prepareTaskRecord/createMockTaskContext),持久化前 saveUnlocked 签名。 */
    hmac?: string;
}
export type ToolCategory = "strict_controlled" | "read_only_bypass" | "normal_controlled";
export type SideEffect = "none" | "task_context_write" | "file_write" | "knowledge_write" | "config_write" | "command_execution" | "git_commit" | "git_push" | "pr_create" | "external_write";
export type ViolationType = "not_allowed_next_tool" | "side_effect_exceeded" | "missing_authorization" | "guard_blocked" | "read_only_bypass_write" | "contract_state_mismatch" | "trace_missing";
export type ViolationSeverity = "warning" | "require_human" | "hard_fail";
export interface ToolAuthorization {
    required: boolean;
    granted: boolean;
    reason?: string;
}
export interface ToolBypass {
    allowed: boolean;
    reason: "read_only" | "user_explicit" | "diagnostic";
}
export interface ToolTrace {
    tool_name: string;
    invocation_id: string;
    task_id?: string;
    workflow_id?: string;
    contract_ids: string[];
    capability_ids: string[];
    guard_report_id?: string;
    degraded: boolean;
    warnings: string[];
    side_effects: SideEffect[];
    next_allowed_tools: string[];
    forbidden_tools: string[];
    authorization?: ToolAuthorization;
    bypass?: ToolBypass;
}
export interface ToolInvocationViolation {
    invocation_id: string;
    tool_name: string;
    violation_type: ViolationType;
    severity: ViolationSeverity;
    reason: string;
    recovery: string;
}
export interface ToolInvocationContract {
    tool_name: string;
    category: ToolCategory;
    /** 工具所有写动作可能产生的副作用并集，用于契约上限校验。 */
    side_effects: SideEffect[];
    /** action 级真实副作用；未声明 action 时回退到工具级并集。 */
    action_side_effects?: Record<string, SideEffect[]>;
    requires_authorization: boolean;
    requires_workflow: boolean;
    description: string;
    default_next_tools: string[];
    forbidden_next_tools: string[];
}