🛠 영일전기철물 GPT 수리 콘솔 v3

📌 선택된 작업 폴더 요약

🔍 파일 미리보기

<?php
declare(strict_types=1);

/**
 * 📁 engine_modules/contracts/RouteDecision.php
 * INTERNAL_GPT_CONTEXT_ECOSYSTEM_BASE_V1
 *
 * 주의: routing/RouteDecision.php가 별도 존재하므로 이 파일은 routing 쪽과 충돌 없도록
 *      클래스명을 RouteDecisionContract 로 둔다.
 *
 * 역할: 라우팅 최종 결정의 최소 표준 모양.
 *
 * 필드:
 *   - intent          string     표준 intent/domain
 *   - operation       string     read/create/update/delete/write/diagnose
 *   - permission      string     READ_ONLY/APPROVAL_REQUIRED/AUTO_EXECUTE_ALLOWED 등
 *   - selected_tool   string     실제로 실행될 tool name
 *   - tool            string     selected_tool 호환 alias
 *   - allowed_tools   list<str>  허용된 후보
 *   - blocked_tools   list<str>  차단된 후보
 *   - action_phase    string     answer/execute_direct/make_plan_then_wait_confirm 등
 *   - needs_approval  bool       승인 필요 여부
 *   - is_binding      bool       하위 라우터가 존중해야 하는 결정인지 여부
 *   - reason          string     선택 이유
 *   - source          string     결정 모듈
 *   - confidence      float      [0.0, 1.0]
 */
final class RouteDecisionContract
{
    public const VERSION = 'route_decision_contract_v2_20260526';

    public static function ok(
        string $selectedTool,
        array $allowed = [],
        array $blocked = [],
        float $confidence = 1.0,
        string $source = '',
        string $reason = ''
    ): array {
        return self::normalize([
            'ok'             => true,
            'selected_tool'  => $selectedTool,
            'allowed_tools'  => $allowed,
            'blocked_tools'  => $blocked,
            'confidence'     => $confidence,
            'source'         => $source,
            'reason'         => $reason,
        ]);
    }

    public static function blocked(string $reason, string $source = '', array $blocked = []): array
    {
        return self::normalize([
            'ok'             => false,
            'selected_tool'  => '',
            'allowed_tools'  => [],
            'blocked_tools'  => $blocked,
            'confidence'     => 0.0,
            'source'         => $source,
            'reason'         => $reason,
        ]);
    }

    public static function fromRouterGate(array $raw): array
    {
        $tool = (string)($raw['tool'] ?? $raw['selected_tool'] ?? '');
        $allowed = $raw['allowed_tools'] ?? [];
        if (!is_array($allowed)) {
            $allowed = [];
        }
        if ($allowed === [] && $tool !== '') {
            $allowed = [$tool];
        }
        $permission = (string)($raw['permission'] ?? 'READ_ONLY');
        $needsApproval = array_key_exists('needs_approval', $raw)
            ? (bool)$raw['needs_approval']
            : self::permissionNeedsApproval($permission);

        return self::normalize([
            'ok'             => !empty($raw['is_binding']),
            'domain'         => (string)($raw['domain'] ?? ''),
            'intent'         => (string)($raw['intent'] ?? $raw['domain'] ?? $tool),
            'operation'      => (string)($raw['operation'] ?? 'read'),
            'permission'     => $permission,
            'selected_tool'  => $tool,
            'tool'           => $tool,
            'allowed_tools'  => $allowed,
            'blocked_tools'  => $raw['blocked_tools'] ?? [],
            'action_phase'   => (string)($raw['action_phase'] ?? $raw['phase'] ?? ''),
            'needs_approval' => $needsApproval,
            'is_binding'     => (bool)($raw['is_binding'] ?? false),
            'confidence'     => (float)($raw['confidence'] ?? 0.0),
            'source'         => (string)($raw['source'] ?? 'router_gate'),
            'reason'         => (string)($raw['reason'] ?? ''),
            'risk_level'     => (string)($raw['risk_level'] ?? ''),
            'dcv2'           => is_array($raw['dcv2'] ?? null) ? $raw['dcv2'] : [],
        ]);
    }

    public static function systemContextPatch(array $decision): array
    {
        $d = self::normalize($decision);
        $tool = (string)($d['tool'] ?? $d['selected_tool'] ?? '');
        $allowed = is_array($d['allowed_tools'] ?? null) ? array_values($d['allowed_tools']) : [];
        if ($allowed === [] && $tool !== '') {
            $allowed = [$tool];
        }

        return [
            'system_intent'         => (string)($d['intent'] ?? $tool),
            'system_operation'      => (string)($d['operation'] ?? 'read'),
            'system_permission'     => (string)($d['permission'] ?? 'READ_ONLY'),
            'system_allowed_tools'  => $allowed,
            'system_blocked_tools'  => is_array($d['blocked_tools'] ?? null) ? array_values($d['blocked_tools']) : [],
            'system_action_phase'   => (string)($d['action_phase'] ?? ''),
            'system_needs_approval' => (bool)($d['needs_approval'] ?? false),
            'system_risk_level'     => (string)($d['risk_level'] ?? ''),
        ];
    }

    public static function normalize(array $raw): array
    {
        $allowed = $raw['allowed_tools'] ?? [];
        $blocked = $raw['blocked_tools'] ?? [];
        if (!is_array($allowed)) $allowed = [];
        if (!is_array($blocked)) $blocked = [];

        $confidence = (float)($raw['confidence'] ?? 0.0);
        if ($confidence < 0.0) $confidence = 0.0;
        if ($confidence > 1.0) $confidence = 1.0;

        $selectedTool = (string)($raw['selected_tool'] ?? $raw['tool'] ?? '');
        $domain = (string)($raw['domain'] ?? $raw['subject'] ?? '');
        $intent = (string)($raw['intent'] ?? '');
        if ($intent === '') {
            $intent = $domain !== '' ? $domain : $selectedTool;
        }
        $operation = (string)($raw['operation'] ?? 'read');
        $permission = (string)($raw['permission'] ?? 'READ_ONLY');
        $needsApproval = array_key_exists('needs_approval', $raw)
            ? (bool)$raw['needs_approval']
            : self::permissionNeedsApproval($permission);
        $actionPhase = (string)($raw['action_phase'] ?? $raw['phase'] ?? '');
        $riskLevel = (string)($raw['risk_level'] ?? '');
        $dcv2 = $raw['dcv2'] ?? [];
        if (!is_array($dcv2)) {
            $dcv2 = [];
        }

        return [
            'ok'             => (bool)($raw['ok'] ?? false),
            'domain'         => $domain,
            'intent'         => $intent,
            'operation'      => $operation,
            'permission'     => $permission,
            'selected_tool'  => $selectedTool,
            'tool'           => $selectedTool,
            'allowed_tools'  => array_values(array_map('strval', $allowed)),
            'blocked_tools'  => array_values(array_map('strval', $blocked)),
            'action_phase'   => $actionPhase,
            'needs_approval' => $needsApproval,
            'is_binding'     => (bool)($raw['is_binding'] ?? false),
            'risk_level'     => $riskLevel,
            'confidence'     => $confidence,
            'source'         => (string)($raw['source'] ?? ''),
            'reason'         => (string)($raw['reason'] ?? ''),
            'dcv2'           => $dcv2,
            'version'        => self::VERSION,
        ];
    }

    private static function permissionNeedsApproval(string $permission): bool
    {
        return in_array($permission, [
            'APPROVAL_REQUIRED',
            'APPROVAL_NATURAL_CONFIRM',
            'HIGH_RISK_APPROVAL_REQUIRED',
        ], true);
    }
}