← Docs hub

이 페이지는 분할 전 전체 사양을 한 파일에서 확인하기 위한 보존본이다. 일반 탐색은 TaskManager 사양 허브를 사용한다.

DeviceAgent TaskManager 기준 사양서 · 전체 원문 보존본

DeviceAgent TaskManager가 여러 요청 경로의 기기 동작을 Task와 Workflow라는 공통 실행 단위로 관리하기 위한 기준을 정의한다. 적용 범위는 책임 경계, 공개 API, 실행 정책, 상태 생명주기, 완료 판정, 예약 실행, 외부 연동, 호환성과 인수 기준이다.

TaskManager는 요청의 의미를 해석하는 계층이 아니다. 제출된 실행 의도를 순서, 상태, 자원, 취소, 완료와 실패 계약에 따라 제어하고, 실제 기기 동작 결과를 구조화된 상태와 이벤트로 반환한다.

TaskManager 한눈에 이해하기

TaskManager는 여러 경로에서 들어오는 기기 동작 요청을 Task로 접수하고, 실행 가능 여부·순서·상태·완료·취소·실패를 공통 규칙으로 관리하는 DeviceAgent 내부 실행 프레임워크다.

이 문서에서 말하는 TaskManager는 새로운 이동·청정·화면 기능을 만드는 모듈이 아니다. 기존 기기 도메인이 기능과 안전 정책을 계속 소유하고, TaskManager는 그 기능이 언제 실행되고, 무엇과 함께 실행되며, 실제로 언제 끝났는지를 관리한다.

해결하는 문제

하나의 요청이 처리되는 흐름

핵심은 accepted=true와 COMPLETED를 구분하는 것이다. 요청 접수는 실행 관리의 시작이며, 완료는 각 기기 도메인이 제공하는 최신 상태나 콜백으로 확정한다.

Task와 Workflow

책임 경계

도입 후 달라지는 구조

TaskManager만으로 모든 제품 경험이 자동 생성되는 것은 아니다. 이미 정해진 장면은 앱·관제·제품 시나리오가 Workflow를 만들고, 자유로운 목표 해석이 필요한 경우에만 상위 Planner가 허용된 Task를 조합한다. 어느 경로든 실제 실행은 같은 TaskManager 계약을 사용한다.

전체 목차와 권장 순서

처음 읽을 때는 아래 순서로 핵심 구조를 파악하고, API 필드나 도메인별 사양은 필요한 항목만 찾아보면 된다.

빠른 결론

1. 기능 호출 성공은 Task 완료가 아니다.
2. TaskManager는 기존 기능 위에서 실행을 관리하며 기기 도메인의 안전 정책을 대체하지 않는다.
3. 복합 실행은 검증된 Task의 Workflow 조합으로 표현한다.
4. 다음 단계는 선행 Task의 실제 완료 증거가 있어야 진행한다.
5. 모든 요청 경로는 같은 상태·취소·실패·관측 계약으로 수렴한다.
6. Planner 연동은 선택 사항이며 TaskManager Core의 결정론적 실행 책임과 분리한다.

설계 배경과 외부 사례

TaskManager와 유사한 실행 제어 구조는 Android 작업 관리, 로봇 장시간 동작, Fleet Mission, 인프라 제어와 장기 Workflow에서 공통적으로 사용된다. 비교의 목적은 외부 플랫폼 자체를 도입하는 것이 아니라, 작업 수명주기·진행·취소·의존관계·실제 완료 증거가 왜 별도 실행 계층에 필요한지 확인하는 데 있다.

SKIX TaskManager는 이 원리를 DeviceAgent의 물리 기능, 안전 정책, 완료 증거와 기존 API 호환성에 맞게 결합한다. 가장 가까운 설명은 작업 수명 관리 + 장시간 물리 실행 상태 + 단계형 Workflow 제어를 하나의 기기 실행 Core로 구성한 것이다.

설계 참조: Android WorkManager 작업 연결, ROS 2 Actions, Nav2 Behavior Tree, NVIDIA Isaac Missions, Microsoft Durable Task.

제1부 · 개념과 구조 — 0~3장은 문서 판독 기준, TaskManager의 책임과 AOSP·DeviceAgent 내부 구성을 정의한다.

0. 문서 판독 규칙

0.1 상태 표기

0.2 가장 중요한 경계

0.3 구현 기준 구성요소

0.4 규범 키워드

이 문서의 규칙은 중요도에 따라 다음처럼 읽는다.

본문의 설명 문장도 31장의 요구사항 ID와 연결되면 규범 효력을 갖는다. 소스에 클래스나 메서드가 있다는 사실만으로 MUST 충족을 선언하지 않는다.

0.5 독자별 권장 읽기 순서

0.6 사양과 구현의 우선순위

1. 제품 안전 정책과 승인된 요구사항이 최우선이다.
2. 이 사양서는 공개 계약과 인수 기준의 기준점이다.
3. DeviceAgent 구현은 이 사양의 적합성을 코드와 시험 증거로 입증해야 한다.
4. 사양과 구현이 다르면 차이를 요구사항 또는 결함으로 관리하고, 승인 없이 구현 동작을 사양으로 간주하지 않는다.

1. TaskManager란 무엇인가

TaskManager는 기기 기능을 호출하는 또 하나의 API 래퍼가 아니다. 여러 경로에서 들어온 기기 작업을 동일한 실행 단위와 상태 모델로 관리하는 DeviceAgent 내부 실행 제어 계층이다.

기존 구조에서는 호출자가 기능별 API를 직접 호출하고, 다음 작업의 시작 시점, 실패 대응, 실제 취소 여부와 완료 판정 콜백을 각각 구현해야 했다. 단일 명령에는 단순하지만 기능과 요청 경로가 늘수록 같은 제어 코드가 여러 앱과 서비스에 흩어진다.

TaskManager 도입 후 호출자는 다음을 구조화해 제출한다.

TaskManager는 이 정보를 TaskRecord로 관리한다. 실제 실행은 기존 기기 도메인 실행기에 위임하고, 콜백과 상태 증거를 이용해 최종 상태를 확정한다.

1.1 한 문장 정의

TaskManager는 기존 DeviceAgent 기능을 Task와 Workflow로 표준화해 실행 순서, 상태, 자원 경쟁, 취소, 실패와 완료 증거를 공통으로 관리하는 SKIX namuh 제품 실행 프레임워크다.

1.2 무엇이 달라지는가

1.3 TaskManager가 하지 않는 일

• 자연어 원문, UI 선택과 시스템 이벤트를 분류하거나 제품 목표로 해석하지 않는다.
• 등록되지 않은 기능을 임의로 만들어 실행하지 않는다.
• 이동 경로, 청정 알고리즘, 보안 순찰 알고리즘을 대체하지 않는다.
• 센서 원시 데이터의 의미를 자체 추론하지 않는다.
• 모든 실패를 Cloud에 보내지 않는다.
• 제품의 반복 생활 스케줄 DB를 TaskManager 단기 지연 실행과 동일하게 취급하지 않는다.
• Android 플랫폼 공개 SDK인 것처럼 외부 일반 앱에 무제한 노출하지 않는다.

2. AOSP와 SKIX namuh 안에서의 위치

2.1 패키징 위치와 아키텍처 역할

DeviceAgent는 Android 빌드 관점에서 /system/priv-app에 배치되는 애플리케이션 패키지다. platform 인증서로 서명되고 android.uid.system을 사용하며, persistent 애플리케이션의 바운드 서비스로 실행된다. 따라서 일반 사용자 앱과 같은 제품 기능 화면이 아니라, 시스템 권한으로 여러 기기 기능을 연결하는 상시 실행 서비스다.

패키징 위치와 아키텍처 역할은 서로 다른 축이다. DeviceAgent는 앱 프로세스에 배치되지만, TaskManager와 공개 계약은 여러 제품 앱이 공통으로 사용하는 실행 기반을 제공한다. 이 역할을 SKIX namuh Product Framework Layer로 정의한다.

2.2 SKIX namuh Product Framework Layer

이 계층은 특정 화면이나 하나의 제품 기능을 구현하지 않는다. 제품 앱, IoT, PUI, 예약과 내부 서비스가 같은 기기 기능을 호출할 때 공통으로 필요한 권한, 실행 순서, 상태, 취소, 실패와 완료 계약을 제공한다.

이 구조에서 DeviceAgent는 구현 형태로는 시스템 특권 앱 서비스이고, 제품 구조에서는 공통 실행 프레임워크다. 두 설명은 서로 다른 관점의 위치를 나타낸다.

2.3 AOSP Framework와의 경계

TaskManager는 AOSP SystemService가 아니다. frameworks/base나 system_server에 등록되지 않으며, AOSP의 Binder, 서비스 생명주기와 시스템 API를 사용해 DeviceAgent 프로세스 안에서 동작하는 SKIX namuh 제품 실행 프레임워크다. 따라서 Android 공개 SDK와 같은 범용 플랫폼 API가 아니라, 플랫폼 서명과 제품 권한 경계 안에서 사용하는 내부 프레임워크로 구분한다.

2.4 AOSP 구성요소 활용

3. 전체 구성요소

3.1 구성요소와 책임

3.1.1 처음 보는 사람을 위한 구성요소 지도

이 구조에서 TaskManager는 실제 기기 기능을 수행하지 않는다. 요청 접수, 실행 순서, 상태와 완료를 관리하는 실행 조정자다. 이동과 청정 같은 실제 작업은 기존 기기 도메인이 계속 수행한다.

3.2 소유권 경계

책임 경계는 0.2 가장 중요한 경계의 구조도를 따른다. Planner는 목표와 계획, TaskManager는 실행 생명주기, 기기 도메인은 실제 동작과 물리 상태를 소유한다. Monitor는 이 상태를 표시하고 허용된 제어를 전달하지만, Task의 최종 상태를 임의로 확정하지 않는다.

3.3 스레드와 대기열의 기본 모델

• 대기열별 실행기는 같은 대기열 안의 작업 순서를 관리한다.
• 우선순위가 높은 작업을 먼저 실행하고, 우선순위가 같으면 제출 순서를 유지한다.
• 상위 Workflow는 workflow 대기열에서 전체 흐름을 관리한다.
• 병렬 하위 단계는 각 도메인 대기열에서 실행하며, 상위 Workflow가 결과를 취합한다.
• runningManagedTask 스레드 로컬 보호 장치는 TaskManager가 기존 MainApi를 다시 호출할 때 대기열에 재귀 진입하는 것을 막는다.
• 기본 대기열 용량은 64, 실행 기록 보존 상한은 100이다.

제2부 · 요청 계약과 실행 허용 — 4~7장은 요청이 들어오는 경로, 공개 API, 실행 허용 판정과 정책을 설명한다.

4. 요청 유입과 유형 분류

4.1 지원 요청 출처

4.2 신호 유형

TaskIngressClassifier는 들어오는 모든 메서드를 Task로 만들지 않는다.

핵심 원칙은 명령과 관찰을 분리하는 것이다. 센서 콜백을 다시 구동 Task로 감싸면 순환 호출과 중복 실행이 생길 수 있다.

4.3 MainApi의 세 경로

1. method가 TaskManager 제어 메서드이면 handleControlMethod()가 직접 처리한다.
2. forceTaskManager=true이거나 Task 관리 대상 메서드이면 관리 실행 경로를 사용한다.
3. TaskManager 대상이 아니거나 호환성이 필요한 호출은 기존 경로를 유지한다.

이 구조는 기존 기능을 한 번에 전부 교체하지 않고 점진적으로 Task 계약에 편입하기 위한 호환 경계다.

5. 공개 제어 API

현재 TaskManager.handleControlMethod()와 TaskManagerClient가 공유하는 제어 메서드는 17개다.

위 17개 메서드는 현재 TaskManager의 제어 분기와 TaskManagerClient 공개 상수에 모두 존재한다. 출시할 때마다 양쪽 목록과 실제 처리 분기를 교차 점검해야 한다.

5.1 submitTask 최소 요청

{
  "method": "submitTask",
  "forceTaskManager": true,
  "taskMethod": "setMoveTo",
  "source": "APP",
  "requestId": "move-bedroom-001",
  "traceId": "trace-001",
  "positionId": "5",
  "positionName": "안방",
  "completionTarget": "movement.arrived",
  "timeoutMs": "120000"
}

5.2 submitWorkflow 최소 요청

{
  "method": "submitWorkflow",
  "forceTaskManager": true,
  "workflowName": "room_clean_return",
  "source": "APP",
  "requestId": "wf-room-clean-001",
  "traceId": "wf-room-clean-001",
  "subTasks": [
    {
      "stepId": "move-bedroom",
      "taskMethod": "setMoveTo",
      "positionId": "5",
      "positionName": "안방",
      "completionTarget": "movement.arrived"
    },
    {
      "stepId": "clean-bedroom",
      "taskMethod": "setAirCleanerOperation",
      "action": "1",
      "mode": "0",
      "completionTarget": "cleaning.stopped"
    },
    {
      "stepId": "return-station",
      "taskMethod": "returnToStation",
      "completionTarget": "movement.stationCharging"
    }
  ]
}

5.3 공통 요청 필드

queue와 queueKey는 계층별 명칭 차이가 남아 있다. AAR builder는 queue를 쓰지만 TaskPolicyRegistry.resolve()는 직접 변경값으로 queueKey를 읽는다. 외부 계약은 queue를 표준 이름으로 유지하고 DeviceAgent 경계에서 별칭을 정규화해야 한다.

5.4 생략 필드의 기본값과 적용 순서

요약: TaskManager의 기본값은 요청 생성기 한 곳에서 일괄 입력되지 않는다. 호출 경로가 자동으로 넣는 값, 메서드 정책 목록이 채우는 값, Workflow·예약 런타임이 계산하는 값과 도메인 실행기가 보완하는 값이 순서대로 결합된다. 따라서 “필드를 생략해도 된다”는 말은 어느 계층이 어떤 값으로 보완하는지 계약에 고정돼 있다는 뜻이어야 한다.

5.4.1 기본값 결정 우선순위

실행값은 다음 순서로 결정된다.

1. 호출자가 명시한 값: 허용된 변경 필드는 요청값을 우선 사용한다.
2. 호출 경로의 정규화·자동 삽입: AAR, Cloud 어댑터, Task Monitor가 제어 메서드와 일부 메타데이터를 넣는다.
3. 메서드별 명시 정책: TaskPolicyRegistry의 exact policy가 실행 방식, 대기열, 우선순위, 시간 제한, 재시도, 취소와 보상 동작을 제공한다.
4. 등록되지 않은 메서드의 추정 정책: 메서드 이름으로 임시 fallback policy를 만든다. 이는 호환 안전망이며 출시 기능의 정식 사양으로 사용하면 안 된다.
5. Workflow·예약 런타임 기본값: Workflow 이름, 병렬 그룹 정책, 단계 지연, 예약 유형과 실행 허용 옵션을 보완한다.
6. 도메인 실행기 기본값: 이동, 청정, Security 등 실제 기능이 안전한 호출 형식이나 완료 조건을 추가로 정규화한다.
7. 시스템 속성 기본값: 엄격 검증, 자원 정책, 영속성, 대기열 크기 같은 운영값을 최종 적용한다.

TaskRecord의 taskId는 호출자가 보내지 않아도 <taskMethod>-<sequence> 형식으로 생성된다. 예약 ID도 scheduled-<sequence> 형식으로 생성된다. 반면 requestId와 traceId는 자동 생성되지 않는다. 내부 Task ID가 생긴다는 사실을 외부 멱등성과 분산 추적이 확보된 것으로 해석하면 안 된다.

5.4.2 호출 경로별 자동 입력

forceTaskManager를 raw 요청에서 생략하면 요청 자체의 기본값은 false다. 다만 현재 시스템 속성 persist.sys.deviceagent.taskmanager.enable의 기본값이 true이므로 Core는 활성화된다. AAR가 forceTaskManager=true를 넣는 이유는 시스템 속성 상태와 무관하게 관리 경로를 명시하기 위해서다.

5.4.3 공통 실행 정책 기본값

등록되지 않은 메서드의 fallback은 일반적으로 timeoutMs=30000, retry=0, stateAware=true를 사용한다. 이름이 get, is, Info, Version, Dump 계열이면 DIRECT로, 그 외에는 ASYNC로 추정한다. 이름에 stop, reset, error, emergency가 들어가면 EMERGENCY로 추정할 수 있으므로, 외부의 source 누락은 UNKNOWN이 되어 호출자 정책에서 거절될 수 있다. 이름 기반 fallback은 개발 중 호환용이지 기능 등록을 대신하지 않는다.

5.4.4 Workflow와 예약 기본값

5.4.5 도메인 실행기가 보완하는 값

도메인 기본값은 편의를 위한 임의 추정이 아니라 기존 기능 계약을 안정된 Task 입력으로 바꾸는 어댑터 규칙이어야 한다. 예를 들어 이동 대상 공간, TTS 문장, 화면 이름, 외부 앱 세션 키처럼 의미를 바꾸는 값은 도메인 실행기가 임의 생성하면 안 된다.

청정 기본값 주의: 엄격 검증이 꺼진 상태에서 setAirCleanerOperation에 action, mode, speed, operation을 모두 생략하면 실행기가 시작·기본 청정·speed=0·ai=false를 보완한다. 기본 청정의 완료 조건은 cleaning.stopped이고 cleanMinTimeMs 기본은 0ms이므로, 시작 직후 정지 명령으로 이어질 수 있다. 이는 하위 호환을 위한 실행기 보완이지 안전한 공개 API 최소 요청이 아니다. 제품 호출자는 최소한 동작과 모드를 명시하고 엄격 검증 시험을 통과해야 한다.

5.4.6 기본값이 없거나 생략하면 안 되는 필드

현재 엄격 검증의 기본값은 false다. 이는 기존 호출 호환성을 위한 선택이지 필수 매개변수가 실제로 선택이라는 뜻이 아니다. 출시 계약에서는 기능 카드에 호출자가 반드시 보내는 값, AAR가 넣는 값, Core 정책값, 도메인 실행기 기본값, 기본값 금지값을 분리해 고정하고, 엄격 검증을 켠 회귀 시험까지 통과해야 한다.

5.5 공통 결과 필드

6. 실행 허용 절차

submitTask는 실행기를 호출하기 전에 아래 절차를 통과한다.

6.1 활성화 조건

TaskManager는 다음 중 하나면 활성화된다.

• 요청에 forceTaskManager=true
• persist.sys.deviceagent.taskmanager.enable=true

해당 속성을 읽지 못했을 때의 기본값은 현재 true다.

6.2 입력 검증

현재 입력 검증은 기존 시스템 호환을 위해 두 단계로 동작한다.

전역 속성:

persist.sys.deviceagent.taskmanager.strict_validation

예시:

알 수 없는 메서드는 입력 검증기를 통과하더라도 실행기 생성 단계에서 missing_task_command로 거절될 수 있다. 따라서 엄격한 입력 검증만으로 기능 등록 여부까지 보장할 수는 없다.

6.3 호출자 정책

현재 가장 명시적인 요청 출처 정책은 긴급 우선순위 제한이다.

• EMERGENCY 우선순위는 INTERNAL, AUTONOMOUS, SENSOR 요청에만 허용한다.
• bypassCallerPolicy=true는 특권 우회이므로 일반 외부 요청에 노출하면 안 된다.

6.4 도메인 자원 정책

현재 명시적으로 관리하는 충돌 예시는 다음과 같다.

requiredResources를 요청에 추가하면 기능별 조건문을 계속 늘리지 않고 자원 요구사항을 구조화할 수 있다. 선택적 상위 Planner도 기능 설명자에 정의된 같은 자원 용어를 사용해야 한다.

6.5 시스템 자원 정책

TaskResourceMonitor는 CPU 사용률, RAM 압력과 발열 단계의 최신 스냅숏을 보관한다. 실행 허용 절차는 resourcePolicyEnabled와 정책 임계값에 따라 작업을 거절할 수 있다. 스냅숏은 하드웨어 상태의 영구 진실이 아니므로 측정 시점과 출처를 함께 확인해야 한다.

6.6 선점 실행 허용

새 요청은 기본적으로 기존 작업을 중단하지 않는다. preemptPolicy가 명시된 경우에만 대기열과 Task 상태를 변경한다.

6.7 기존 DeviceAgent 제품 정책의 계승

TaskManager 도입 전부터 DeviceAgent에는 제품 상태, 배터리, LLM 세션, 개인정보 보호, 오류, 이동 자세와 동작 간 충돌을 판단하는 정책이 있다. TaskManager는 이 정책을 별도 규칙으로 복사하지 않고 승인된 기존 도메인 진입점을 통해 반드시 통과해야 한다.

정책은 다음 네 계층으로 나눈다.

6.7.1 대표 정책 계승 행렬

이 표의 틸트, LCD 깨움과 도킹 처리처럼 기능 수행에 내재된 제품 정책은 독립 Task로 노출하지 않는다. 독립 Task로 노출하면 Planner나 호출자가 내부 안전 순서를 생략하거나 잘못 재배열할 수 있다. 대신 이동 capability의 실행 계약과 결과에 posturePolicyApplied, physicalCompletionObserved 같은 관측 필드를 추가할 수 있다.

6.7.2 정책 계승 불변 조건

1. 관리 실행기는 기존 도메인 정책 담당자를 우회해 HAL·MCU·AMR을 직접 호출하면 안 된다.
2. 저수준 호출이 필요한 전용 실행기는 기존 진입점과 동등한 상태·자원 검사를 갖췄다는 별도 검토와 실기기 증거가 있어야 한다.
3. TaskManager의 priority, preemptPolicy, forceTaskManager는 제품 안전 정책을 무효화하는 권한이 아니다.
4. 도메인 정책의 거절·대기·자동 전환 결과는 accepted, errorCode, reason, recoverability로 변환해야 한다.
5. 암묵적 제품 동작은 Workflow 단계 수를 늘리지 않되, 로그·이벤트·완료 증거에서 적용 여부를 확인할 수 있어야 한다.
6. 같은 기능의 기존 경로와 관리 경로는 동일한 정책 조건에서 같은 물리 허용·거절 결과를 내야 한다.

6.7.3 현재 보강이 필요한 경계

7. 실행 정책 목록

TaskPolicyRegistry는 메서드별 기본 실행 정책을 중앙에서 관리한다.

7.1 실행 방식

문자열 alias:

• direct, sync → DIRECT
• queued_wait, wait → QUEUED_WAIT
• async → ASYNC

7.2 대기열

현재 정책 목록과 런타임에서 사용하는 대기열은 다음과 같다.

7.3 우선순위

7.4 현재 정책 예시

등록되지 않은 메서드는 이름을 기준으로 실행 방식과 대기열을 추정한다. 이 기본 처리는 기존 기능을 수용하기 위한 임시 안전망일 뿐, 출시 가능한 기능 등록을 뜻하지 않는다. 제품 출시 대상 기능에는 명시적 정책과 실행기를 등록해야 한다.

제3부 · 실행 생명주기와 Workflow — 8~15장은 Task 상태, 실행 방식, 단계 제어, 완료 증거, 취소, 실패와 예약을 정의한다.

8. TaskRecord와 생명주기

8.1 TaskRecord가 보존하는 정보

8.2 상태 모델

CANCELLED는 COMPLETED가 아니다. PUI에서 사용자가 청정을 중단하거나 앱 세션을 취소한 경우에도 “작업 종료”와 “목표 성공”을 구분해야 한다.

8.3 ID와 보존

• Task ID는 런타임 순번을 바탕으로 생성된다.
• 스케줄 ID는 별도 순번을 사용한다.
• 메모리 내 실행 기록은 최근 100건으로 제한된다.
• Task 기록과 예약 기록의 영속성은 서로 다른 속성과 파일을 사용한다.
• 저장소에서 복원한 상태는 실제 하드웨어 상태와 다를 수 있으므로, 부팅 후 최신 상태와 대조해 정합해야 한다.

8.4 진행률

• updateTaskProgress는 진행률을 0~100 범위로 제한한다.
• stage는 의미 단계, message는 운영 설명을 담는다.
• 병렬 하위 Task의 진행률은 상위 Task의 평균 진행률로 집계한다.
• 상위 Workflow는 현재 단계 번호·메서드와 단계별 상태 목록을 함께 제공한다.
• 진행률은 완료 증거를 대체하지 않는다. 100% 값만으로 COMPLETED를 만들면 안 된다.

9. 실행 런타임

9.1 DIRECT

1. 실행 기록 생성 및 저장
2. RUNNING 상태와 STARTED 이벤트 기록
3. 호출 스레드에서 명령 실행
4. 결과 저장
5. 성공 시 COMPLETED, 예외 시 FAILED
6. 최종 상태 지표와 이벤트 기록

DIRECT는 짧은 조회에 적합하다. 물리 동작처럼 메서드 반환과 실제 완료 시점이 다른 기능에 사용하면 안 된다.

9.2 QUEUED_WAIT

1. 우선순위가 지정된 작업을 대기열에 제출
2. 호출자는 Future.get(timeout)으로 대기
3. 런타임이 재시도, 완료 대기와 최종 상태 관리
4. 시간 초과 또는 중단 발생 시 구조화된 실패 반환
5. 최종 결과를 호출자에게 반환

호출 스레드를 점유하므로 긴 사용자 세션에는 신중하게 사용한다.

9.3 ASYNC

1. 대기열에 Task 제출
2. accepted=true, taskId를 즉시 반환
3. 실제 실행과 완료 증거 대기는 실행기 스레드에서 계속됨
4. 진행·완료·실패는 이벤트와 상태 조회로 관찰

이동, 복귀, 청정, 보안처럼 시간이 걸리는 동작의 기본 실행 방식이다.

9.4 재시도

• maxRetries는 실행 정책 또는 요청의 retry로 결정한다.
• 실행 예외가 발생하면 재시도 횟수를 증가시키고, 상한에 도달할 때까지 같은 관리 대상 명령을 다시 실행한다.
• 기기 동작이 이미 일부 수행됐을 수 있으므로 재시도 가능한 메서드는 멱등성을 보장해야 한다.
• 물리 이동과 청정은 무조건 다시 호출하지 말고 현재 상태와 실패 사유를 확인해야 한다.

10. Workflow 런타임

10.1 상위 Workflow와 단계

submitWorkflow는 하나의 상위 TaskRecord를 만들고 subTasks를 순서대로 처리한다.

각 순차 단계는 다음 정보를 가진다.

10.2 순차 실행

각 단계의 기본 순서는 다음과 같다.

1. 별칭 정규화와 입력 검증
2. 도메인 자원 실행 허용 판정
3. 단계 상태를 PENDING으로 변경
4. 시작 조건과 실행 조건 평가
5. WORKFLOW_STEP_STARTED
6. 도메인 명령 생성과 실행
7. 완료 조건 대기
8. 결과 저장 후 COMPLETED로 변경
9. WORKFLOW_STEP_COMPLETED
10. 다음 단계 진입

앞 단계의 실제 완료 증거가 없으면 다음 단계를 시작하면 안 된다.

10.3 단계 의존성

현재 구현은 두 가지 실행 조건을 지원한다.

예시:

{
  "stepId": "clean-if-available",
  "taskMethod": "setAirCleanerOperation",
  "conditions": [
    {
      "type": "step_output_equals",
      "stepId": "read-air-quality",
      "path": "result.needs_cleaning",
      "value": "true",
      "onFalse": "skip"
    }
  ]
}

step_output_equals는 현재 Boolean 또는 String 비교를 지원한다. 범위 비교, 숫자 연산자와 복합 AND/OR 조건식은 목표 확장이다.

10.4 이전 단계 기준 지연

after_step 시작 조건은 선행 단계 완료 후 일정 시간이 지나면 다음 단계를 시작한다.

{
  "stepId": "vital-after-move",
  "taskMethod": "setLauncherScreen",
  "screenName": "vitalSign",
  "trigger": {
    "type": "after_step",
    "stepId": "move-room-1",
    "delayMs": 30000
  },
  "conditions": [
    {
      "type": "step_completed",
      "stepId": "move-room-1"
    }
  ]
}

지연 시간 동안 단계 상태는 WAITING, 세부 단계는 scheduled_delay_wait가 되며 remainingDelayMs가 갱신된다. 현재 구현은 Workflow 스레드 안에서 대기하므로, 매우 긴 지연은 별도의 영속 예약 실행으로 처리해야 한다.

10.5 병렬 그룹

{
  "type": "parallelGroup",
  "groupId": "feedback-group",
  "joinPolicy": "all_success",
  "failurePolicy": "partial_success",
  "tasks": [
    {"taskMethod": "setEyeLedColor", "color": "calm"},
    {"taskMethod": "setLlmTts", "text": "청정을 시작합니다"}
  ]
}

현재 구현은 다음과 같다.

• 각 하위 Task에 별도 TaskRecord를 만든다.
• 각 하위 Task를 정책에 지정된 대기열에 동시에 제출한다.
• 상위 Task는 각 하위 Task의 실행 결과를 기다린 뒤 하나의 그룹 결과로 취합한다.
• 그룹 시간 제한은 하위 Task 시간 제한 중 가장 큰 값으로 계산한다.
• 상위 Workflow의 시간 제한은 순차 단계 제한 시간의 합과 병렬 그룹별 최대 제한 시간을 합산한다.
• joinPolicy 값은 상태에 보존하지만, 현재 런타임은 모든 하위 Task가 끝날 때까지 기다린다.

10.6 실패 정책

partial_success를 전체 성공으로 처리하면 안 된다. 상위 서비스와 UX는 “일부 완료” 상태를 명시적으로 다뤄야 한다.

10.7 Workflow 대기열의 책임 경계

• 상위 Task는 workflow 대기열을 사용한다.
• 하위 Task는 메서드 정책에 지정된 도메인 대기열을 사용한다.
• 상위 Task를 취소할 때는 실행 중인 하위 Task의 취소 명령과 비동기 실행도 함께 정리한다.
• 상위 Task만 취소되고 실제 기기 동작이 계속되는 상태를 허용하면 안 된다.

11. 완료 증거

11.1 왜 메서드 반환만으로 부족한가

setMoveTo()가 성공을 반환해도 이동 요청이 전달됐다는 뜻일 뿐, 목표 공간 도착을 보장하지 않는다. setLauncherScreen()도 화면 전환 요청과 사용자의 측정 완료는 서로 다른 사건이다.

TaskManager는 다음 세 시점을 분리한다.

11.2 현재 완료 조건

현재 DeviceAgent Core의 완료 조건 목록과 AAR 공개 상수 목록은 완전히 같지 않다. Core에는 movement.rotationCompleted, tts.playbackStarted, tts.playbackEnded, ui.screenApplied가 있지만 현재 TaskManagerClient.TaskCompletionTargets에는 이 네 상수가 없다. 원시 문자열로는 요청할 수는 있지만 타입 기반 SDK 계약이 완성된 것은 아니다. AAR 상수 추가와 계층 간 상수 정합성 검사가 필요하다.

11.3 CompletionStateStore

• 완료 조건과 선택적 공간 ID를 기준으로 최신 완료 이벤트를 저장한다.
• 완료 조건의 전역 키와 공간별 키를 함께 기록한다.
• observedAtMs가 task의 completionSinceMs보다 최신이어야 한다.
• completionStableMs 동안 상태가 유지돼야 안정적인 완료 증거로 인정한다.
• 중단 이벤트는 성공 이벤트와 별도 저장소에 기록한다.
• 완료 이벤트는 의미 관찰 기록에도 남긴다.

11.4 CompletionWatcher

이 since 기준이 없으면 이전 이동이나 TTS 이벤트가 새 Task를 즉시 완료시키는 과거 증거 재사용 문제가 생긴다.

11.5 장기 세션 완료 의미

화면이 열렸다는 이유로 Vital Sign 측정 Task 전체를 완료하면 안 된다. 이 경우 setLauncherScreen은 시작 단계이고 app.sessionEnded가 완료 단계다.

11.6 AppSessionCompletionBridge

• 패키지가 running이면 app.sessionStarted를 기록한다.
• 현재 활성 패키지의 최종 이벤트만 수용한다.
• 취소 결과는 app.sessionEnded 중단으로 기록한다.
• 실패 결과는 실패 사유를 중단 증거로 기록한다.
• 그 밖의 최종 결과는 성공 app.sessionEnded로 기록한다.

11.7 LlmTaskCompletionBridge

• TTS Task마다 completionKey가 필요하다.
• 동시에 하나의 재생만 활성화할 수 있다.
• 처리 중 또는 재생 중 상태에서 시작 증거를 기록한다.
• 시작 뒤 상태가 IDLE이 되면 재생 종료를 기록한다.
• 호출어 취소와 STOP은 중단 증거다.

12. 취소와 보상 동작

12.1 취소 처리 순서

1. 대상 실행 기록과 최종 상태 여부 확인
2. cancellable 확인
3. CANCELLING 전이
4. 실행 중인 Workflow 하위 Task 취소
5. 실행 중이면 취소 명령 실행
6. 비동기 실행 취소와 대기열 제거
7. 취소 증거가 충분하면 CANCELLED
8. 취소 확인이 불충분하면 FAILED(cancel_failed)

12.2 확인된 생명주기 계약

12.3 보상 동작

보상 동작은 취소와 다르다.

• 취소는 현재 실행을 멈춘다.
• 보상 동작은 이미 발생한 기기 변화를 안전한 상태로 되돌린다.

예를 들어 이동 후 화면 전환에 실패한 Workflow에서 “원위치 복귀”가 항상 올바른 보상 동작은 아니다. 배터리와 장애 상태에 따라 스테이션 복귀나 현 위치 대기가 더 안전할 수 있다. 따라서 보상 메서드는 기능별 안전성 검토를 거쳐 등록한다.

12.4 PUI 취소

PUI 버튼이 기기 도메인을 직접 중단한 경우에도 TaskManager가 최종 상태 증거를 받아야 한다.

PUI와 음성 경로가 별도 상태를 관리하면 실제 기기는 멈췄는데 TaskManager에는 계속 RUNNING으로 남는 고립 Task가 생긴다.

13. 실패 사유 계약

실패를 자연어 한 문장으로만 전달하면 상위 시스템이 안전하게 분기할 수 없다. TaskManager는 하위 오류와 제품 수준의 실패 사유를 분리한다.

13.1 실패 사유 코드

13.2 실패 사유 매개변수

현재 공통 매개변수는 다음을 보존한다.

• task_method
• target_location_id
• target_location_name
• target_position

13.3 복구 가능성과 후속 조치

13.4 Cloud 판단 경계

현재 requiresCloudDecision은 실패 사유에 따라 계산된다. 다만 이 값이 true라고 해서 반드시 LLM을 호출해야 하는 것은 아니다.

20.5 콜백 이후 재계획 경계의 구조도처럼 짧은 대기 후 재시도, 저전력 복귀와 명시적 취소 종료는 기기 내부 정책으로 처리할 수 있다. 목표 공간 대체, 기능 변경, Workflow 재구성이나 사용자 동의가 필요하면 상위 판단으로 전달한다.

14. 이벤트 계약

14.1 이벤트 종류

14.2 이벤트 데이터

{
  "type": "task_event",
  "deviceId": "A1-board-005",
  "eventName": "WORKFLOW_STEP_COMPLETED",
  "taskId": "task-42",
  "taskMethod": "setMoveTo",
  "source": "CLOUD",
  "state": "RUNNING",
  "queue": "workflow",
  "progress": 33,
  "traceId": "trace-001",
  "workflowName": "room_clean_return",
  "currentStepIndex": 0,
  "currentStepMethod": "setMoveTo",
  "cloud_workflow_id": "wf-001",
  "cloud_step_id": "move-bedroom",
  "stage": "movement",
  "message": "안방 이동 완료",
  "completionTarget": "movement.arrived",
  "requires_cloud_decision": false,
  "ts": 1786400000000
}

14.3 이벤트 처리 원칙

• 정상 진행·완료 이벤트는 기기 내부 상태와 UI 갱신에 사용한다.
• 모든 이벤트마다 Planner를 다시 호출하지 않는다.
• 실패 이벤트도 기기 내부에서 복구할 수 있는 사유인지 먼저 확인한다.
• Cloud Workflow와 단계의 상관관계 필드를 보존한다.
• 콜백 수신자는 중복 이벤트를 견딜 수 있어야 한다.
• 최종 이벤트 이후 도착한 과거 진행 이벤트는 무시해야 한다.

15. 예약 실행

TaskManager의 예약 실행은 제품의 반복 스케줄 기능과 구분해야 한다.

15.1 세 시간 계층

15.2 예약 등록과 실행 분리

scheduleTask와 scheduleWorkflow는 등록 시점에 기기 기능을 실행하지 않는다.

15.3 예약 유형

현재 TaskManager.normalizeDeferredScheduleKind()는 Core 예약 등록을 deferred_task로 제한한다. 제품 스케줄은 기존 스케줄 메서드를 Task로 호출할 수 있지만, 일정 데이터의 저장과 관리 책임은 제품 Schedule 도메인에 남는다.

15.4 실행 조건과 미실행 처리

예약 요청은 절대 시각 또는 상대 지연 시간을 정규화해 실행 시각을 저장한다. 주요 필드는 다음과 같다.

• trigger
• triggerAtMs
• relativeDelayMs
• missedRunGraceMs / missed_run_grace_ms
• requireFreshDeviceContext
• blockWhenTaskManagerBusy

실행 시각이 허용 유예 시간을 지난 Task는 MISSED_RUN_EXPIRED로 차단할 수 있다. 오래된 예약을 뒤늦게 무조건 실행하면 이동이나 청정이 예상하지 않은 시간에 시작될 수 있다.

15.5 예약 상태

15.6 영속성

기본 예약 저장소:

/mnt/data2/db/taskmanager_scheduled_tasks.json

관련 시스템 속성:

persist.sys.deviceagent.taskmanager.schedule_persist
persist.sys.deviceagent.taskmanager.schedule_persist_path

등록 후 스냅숏을 저장하고 AlarmManager 실행기가 다음 실행 시각을 재예약한다. 부팅 복원 후에는 기기 식별자, 시계 변경과 미실행 유예 시간을 다시 검증해야 한다.

예약 런타임이 코드에 존재한다고 자동 실행되는 것은 아니다. 현재 기본값은 다음과 같다.

따라서 출시 형상에서 예약 자동 실행을 보장하려면 등록 성공뿐 아니라 해당 속성, 수신기·서비스 생명주기, 정확한 알람 권한, 재부팅 복원과 실행 시각 이벤트를 함께 확인해야 한다.

15.7 현재 검증 경계

• API 등록, 조회, 취소, 영속 저장과 수동 실행 허용 경로는 구현돼 있다.
• 실기기에서 일부 스케줄 등록, 복원과 실행 시각 검증 기록이 있다.
• 모든 제품 모드와 복합 Workflow의 정확한 알람 자동 실행은 기기·APK 조합별 출시 인수 시험이 필요하다.
• “코드가 있다”와 “장시간, 재부팅, 네트워크, 시계 변경 시나리오를 통과했다”를 구분한다.

제4부 · 도메인과 외부 연동 — 16~20장은 기존 기기 기능, 계획 컨텍스트, AAR, IoT/MQTT와 선택적 Planner 연결을 설명한다.

16. 도메인 기능과 실행기 연결

16.1 실행기 등록 원칙

TaskExecutorBootstrap은 표준 taskMethod를 도메인 어댑터에 등록한다.

실행 연결은 SKIX 제품 앱에서 기기 도메인까지의 호출 계층에 표시한 것처럼 taskMethod를 TaskExecutorRegistry, 도메인별 TaskExecutor, 기존 DeviceAgent manager·controller·API 순서로 전달한다.

실행기 어댑터가 해야 할 일:

1. Task 계약 필드를 도메인 입력으로 정규화한다.
2. 기존 도메인 기능을 호출한다.
3. 요청 전달 결과를 outdata에 기록한다.
4. 비동기 기능이면 완료 연결부가 사용할 상관관계 키를 등록한다.
5. 실제 완료는 도메인 콜백을 통해 TaskCompletionStateStore에 기록한다.

실행기 어댑터가 하면 안 되는 일:

• 자연어 원문이나 채널별 요청 문자열을 다시 파싱한다.
• 임의의 기본값으로 잘못된 공간이나 모드를 추정한다.
• 콜백 없이 고정 대기 시간만으로 물리 완료를 선언한다.
• 동일 기능의 핵심 로직을 복제한다.
• 등록되지 않은 메서드를 리플렉션으로 무제한 실행한다.

16.2 현재 실행기 그룹

16.3 공개 메서드 목록

기기 정보와 상태

이동과 지도

청정

LLM, TTS, UI와 루틴

설정

제품 스케줄과 상호작용

보안

업데이트

16.4 기능 등록 체크리스트

새 DeviceAgent 기능을 TaskManager에 연결할 때 다음을 모두 정의한다.

1. 표준 taskMethod
2. 조회·제어·장기 실행 분류
3. 입력 스키마와 별칭
4. 요청 출처 허용 범위
5. 실행 방식
6. 대기열과 우선순위
7. 시간 제한, 재시도와 멱등성
8. 필수 자원
9. 실행기 어댑터
10. 시작·완료·중단 증거
11. 취소 메서드
12. 보상 동작 필요 여부
13. 실패 사유 변환
14. 계획 컨텍스트에 노출할 상태
15. 단위·통합·실기기 인수 시험

17. 기기 계획 컨텍스트

getDevicePlanningContext는 기능 정의가 아니라 현재 기기 상태의 스냅숏이다.

17.1 컨텍스트 구조

{
  "schema_version": "device_context.v1",
  "snapshot_ts": 1786400000000,
  "updated_at_ms": 1786400000000,
  "main_state": "...",
  "battery": {},
  "map": {},
  "location": {},
  "station": {},
  "air_quality": {},
  "cleaning": {},
  "movement": {},
  "network": {},
  "voice_llm": {},
  "security": {},
  "interactions": {},
  "task_manager": {},
  "semantic_observations": {},
  "capabilities": {}
}

17.2 컨텍스트 도메인

17.3 공간 정보 계약

각 room은 최소 다음을 제공한다.

{
  "id": "5",
  "name": "안방",
  "x": "...",
  "y": "...",
  "theta": "...",
  "station": false
}

상위 호출자는 공간 이름을 areaId와 연결한 뒤 Workflow를 만든다. TaskManager는 존재하지 않는 공간을 임의로 대체하면 안 된다.

17.4 정보 최신성

컨텍스트 출처는 다음 메타데이터를 가질 수 있다.

• observed_at_ms
• freshness_ms
• ttl_ms
• source_valid
• stale
• usable
• source_state
• expiry_mode

조건부 Workflow는 available=true만 보지 말고 최신성과 사용 가능 여부를 함께 확인해야 한다.

17.5 계획 컨텍스트 사용 원칙

• 컨텍스트 필드 이름을 사용자 TTS에 그대로 노출하지 않는다.
• current_room_name이 있으면 자연어 공간명으로 답한다.
• 스테이션 도킹 상태이면 공간 이름이 비어 있어도 “스테이션에 있다”고 안내할 수 있다.
• 공기질 원시값은 의미 등급과 권장 행동으로 변환한다.
• 실행 중인 Task가 있으면 새 Task의 실행 허용과 선점 정책에 반영한다.
• 스냅숏은 조회 시점의 정보다. 실행 직전의 중요한 조건은 DeviceAgent에서 다시 확인한다.

18. TaskManagerClient AAR

TaskManager Core는 호출 채널에 종속되지 않는다. 시스템 앱은 typed AAR, IoT는 MQTT, Cloud·On-device bridge는 Bundle/JSON 변환을 사용하지만, 최종 요청은 같은 submitTask 또는 submitWorkflow 계약으로 수렴해야 한다.

AAR은 시스템 앱이 문자열과 Bundle을 직접 조립하지 않도록 제공하는 product-level facade다. 다음 원칙을 지킨다.

• TaskSubmitRequest와 TaskWorkflowRequest builder가 필수 필드를 검증한다.
• TaskManagerClientCallback.onTaskEvent가 공통 event envelope를 전달한다.
• AAR은 TaskManager runtime을 포함하지 않고 DeviceAgent Binder 경계만 감싼다.
• 필드, 기본값과 callback 의미는 Core 계약과 동일해야 한다.

typed API, builder 예시와 배포 산출물은 TaskManagerClient AAR API Specification을 기준으로 한다.

19. IoT/MQTT와 Task Monitor 계약

IoT 요청은 transport metadata와 Task metadata를 분리한다. deviceId, topic, command ack는 MQTT 계층이 소유하고, requestId, traceId, taskMethod, queue, policy와 payload는 Task 계약으로 전달한다.

• 모의 실행과 실제 dispatch를 UI에서 구분한다.
• HTTP·MQTT 인증을 우회하는 payload 필드를 허용하지 않는다.
• 명령 ack와 물리 완료 event를 같은 상태로 취급하지 않는다.
• source가 달라도 validator, admission, executor와 completion gate를 우회하지 않는다.

전체 payload와 운영 속성은 MQTT Task Contract을 기준으로 한다.

20. 선택 연동: Cloud Planner와 A2A

20.0 선택적 상위 연동의 경계

기본 경로에는 Planner가 필요하지 않다. 앱·PUI·IoT·예약과 사전 정의 Workflow는 상위 의미 추론 없이 같은 Core를 사용한다. Planner가 연결되더라도 실행 허용, 자원 정책, 물리 완료 증거와 최종 상태 판정은 DeviceAgent TaskManager와 각 기기 도메인이 소유한다. 상위 Planner가 없어도 기기 내부에서 안전한 생명주기를 유지한다.

상위 Planner는 목표를 해석하고 capability와 단계 의존성을 구성한다. DeviceAgent는 계획을 다시 해석하지 않고 실행 가능성, 현재 상태, 안전 정책과 실제 완료 증거를 판정한다.

goal or product scenario
-> structured task/workflow
-> DeviceAgent admission and execution
-> progress/terminal evidence
-> continue locally or request bounded replanning

정상 진행마다 Planner를 호출하지 않는다. BLOCKED, FAILED, TIMEOUT 또는 명시적 사용자 변경처럼 상위 판단이 필요한 terminal event만 재계획 후보가 된다. requestId, traceId, cloudWorkflowId, cloudStepId는 왕복 동안 보존한다.

Cloud·On-device·DeviceAgent 폐루프와 callback 계약은 Voice TaskManager Closed Loop, 기기 상태 입력은 Device Context Planning Spec을 기준으로 한다.

제5부 · 운영·보안·검증 — 21~28장은 관측성, 영속성, 보안, 실패 UX, 시험, 변경과 참조 규격을 정리한다.

21. 모니터링과 관측성

21.1 운영자가 봐야 하는 상태

Task Monitor와 A2A Text Console은 같은 정보를 다른 관점으로 보여준다.

• Task Monitor: DeviceAgent의 실제 실행 상태 중심
• Text Console: Planner 판단, 요청, 콜백과 기기 컨텍스트의 연결 중심

21.2 필수 상관관계

21.3 UI에서 구분해야 하는 상태

• 접수됨과 실행 중
• 실행 중과 완료 증거 대기
• 완료와 취소
• 실패와 차단
• 현재 단계와 다음 대기 단계
• Planner 계획과 DeviceAgent 실제 진행
• 현재 컨텍스트와 계획 시점 스냅숏

21.4 운영 지표

현재 런타임은 Task 최종 결과와 대기열 상태를 바탕으로 다음 운영 지표를 만들 수 있다.

• 제출/완료/실패/부분실패/취소 수
• 대기열별 대기·실행 Task 수
• Task 실행 시간
• 재시도 수
• 시간 초과 수
• 실패 사유 코드 분포
• Workflow 단계 성공률
• 예약의 실행 허용·차단·미실행 수
• 취소·보상 동작 성공률

제품 지표는 단순 접수 비율이 아니라 실제 완료 증거를 기준으로 산정해야 한다.

22. 영속성·용량·런타임 설정

22.1 TaskManager 속성

persist.sys.deviceagent.taskmanager.enable
persist.sys.deviceagent.taskmanager.legacy_queue
persist.sys.deviceagent.taskmanager.queue_size
persist.sys.deviceagent.taskmanager.persist
persist.sys.deviceagent.taskmanager.persist_path
persist.sys.deviceagent.taskmanager.schedule_persist
persist.sys.deviceagent.taskmanager.schedule_persist_path
persist.sys.deviceagent.taskmanager.strict_validation
persist.sys.deviceagent.taskmanager.executor_dry_run
persist.sys.deviceagent.taskmanager.scheduler.enable
persist.sys.deviceagent.taskmanager.scheduler.interval_ms
persist.sys.deviceagent.taskmanager.scheduler.limit
persist.sys.deviceagent.taskmanager.scheduler.exact_alarm
persist.sys.deviceagent.taskmanager.resource_policy
persist.sys.deviceagent.taskmanager.cpu_limit
persist.sys.deviceagent.taskmanager.ram_pressure_limit
persist.sys.deviceagent.taskmanager.thermal_limit
persist.sys.deviceagent.taskmanager.move_timeout_ms
persist.sys.deviceagent.taskmanager.clean_dwell_ms

22.2 기본값

22.3 영속성 원칙

• 최종 상태의 실행 기록은 디버깅과 운영 분석을 위해 제한적으로 보존한다.
• 장기 보관은 DeviceAgent 메모리 내 기록이 아니라 외부 관측 저장소가 담당한다.
• 부팅 복원 시 RUNNING을 그대로 재개했다고 가정하면 안 된다.
• 기기 동작 Task를 다시 실행하기 전에 멱등성과 현재 상태를 확인한다.
• 예약 저장소 쓰기 실패를 등록 성공으로 숨기면 안 된다.

현재 일반 Task 영속성은 persistTaskSnapshot()이 Task ID, 메서드, 대기열, 상태, 진행률과 시각을 JSON으로 남기는 쓰기 전용 진단 스냅숏이다. 이를 읽어 TaskRecord와 비동기 실행을 복원하는 런타임은 없다. 반면 지연 예약은 허용된 Bundle 키를 저장하고 ScheduledTaskRecord를 다시 읽는 별도 경로가 있다. 두 영속성 기능을 같은 수준의 장애 복구 기능으로 표현하면 안 된다.

22.4 용량 관리 원칙

• 대기열 포화는 DEVICE_BUSY로 정규화한다.
• 빈도가 높은 센서 갱신은 Task 대기열로 보내지 않는다.
• 연결 상태 보고와 진행 이벤트는 표본 추출과 빈도 제한을 적용한다.
• 장기 Workflow가 대기열 작업자를 과도하게 점유하지 않도록 도메인 콜백 기반 대기와 전용 런타임 분리를 검토한다.

23. 보안과 권한

23.1 Binder 경계

TaskManager API는 DeviceAgent Binder를 통과한다. 제품 배포에서 확인할 항목:

• DeviceAgent와 클라이언트 APK 인증서
• 서명 권한
• 패키지 UID와 설치 경로
• 외부 공개 컴포넌트
• 콜백 클래스 등록
• 호출자 식별 검증

23.2 시스템 앱 배포

• DeviceAgent와 MaumAi·온디바이스 Agent는 디버그 인증서로 /system/priv-app에 배포하면 안 된다.
• 플랫폼 인증서를 apksigner verify --print-certs로 비교한다.
• 파일 소유자, 권한 모드와 SELinux 컨텍스트를 확인한다.
• APK 교체 전 원본을 백업한다.
• 빌드 성공은 부팅과 Binder 연결 성공을 의미하지 않는다.

23.3 모니터 전송 보안

• Bearer 토큰 없는 제품 외부 전송은 금지한다.
• 테스트 콘솔 수신기는 제품 형상의 외부 공개 정책을 별도로 검토한다.
• endpoint는 HTTPS를 기본으로 한다.
• 기기 ID와 토큰을 문서, Git과 UI 기본값에 직접 넣지 않는다.
• 명령 조회와 이벤트 확인 응답에는 재전송 공격과 중복 실행 방어가 필요하다.

23.4 특권 우회 필드

다음 필드는 일반 외부 호출자에게 직접 노출하지 않는다.

• bypassCallerPolicy
• forceTaskManager의 무제한 사용
• requiredResources 임의 축소
• executorDryRun=false 원격 강제
• replace_all 긴급 선점

24. 실패 처리와 사용자 UX

24.1 구조화 실패에서 사용자 문장으로

reason_code=ROOM_NOT_FOUND
reason_params.target_location_name=거실
suggested_action=ASK_USER_TARGET

사용자 응답:
  “거실은 등록된 공간에서 찾지 못했어. 등록된 다른 공간으로 이동할까?”

내부 필드를 그대로 TTS로 읽지 않는다.

나쁜 예:

context 기준으로 current_room_id=0입니다.
CAPABILITY_UNAVAILABLE reason_params가 발생했습니다.

좋은 예:

현재 스테이션에 있어.
요청한 공간을 찾지 못했어. 공간 이름을 다시 알려줘.

24.2 실패 후 동작

25. 테스트 전략과 인수 기준

25.1 테스트 계층

25.2 최소 기능 검증

1. DIRECT 조회 성공과 실패
2. ASYNC Task 접수 후 최종 이벤트
3. QUEUED_WAIT 시간 초과
4. 같은 대기열의 실행 순서
5. 우선순위 순서
6. 대기열 포화
7. 엄격한 입력 검증 거절
8. 요청 출처별 긴급 우선순위 거절
9. 상태·자원 실행 허용 거절
10. 대기·실행 Task 취소
11. 취소 명령 실패
12. 보상 동작 실행
13. 순차 Workflow
14. 병렬 그룹 성공과 부분 실패
15. 조건에 따른 생략과 실패
16. 선행 단계 기준 지연
17. 과거 완료 증거 재사용 방어
18. PUI 취소 콜백
19. 예약 중복 제거, 저장, 복원, 실행, 취소와 미실행 처리
20. 이벤트 상관관계와 모니터 표시

25.3 도메인별 실기기 인수 시험

25.4 기존 검증 증거 해석

기존 문서에는 다음 수준의 증거가 있다.

• submitTask, submitWorkflow, 조회·대기열·관리 제어 API의 계측 확인 기록
• 실기기 TaskManager 계측 시험 통과 기록
• Cloud·On-device 요청 구조와 콜백 분배 확인 기록
• 예약 등록, 복원과 실행 시각 관련 실기기 검증 기록
• 이동을 제외한 혼합 Workflow 검증 기록

이 기록은 당시 기기와 APK 조합에 한정된 증거다. MR6 소스, 서명 또는 빌드 산출물이 바뀌면 출시 인수 시험을 다시 수행한다.

25.5 출시 판정 기준

위 구조도의 Gate 1~10은 API 정합에서 입력 검증, 실행기, 완료 증거, 취소·보상, 실패 사유, Binder 보안, 실기기 시험, 장시간 시험, 관측성과 원복까지 순서대로 확인한다.

26. 현재 구현의 한계와 목표 확장

26.1 현재 확인된 한계

26.2 목표 확장

1. 기능 설명자에서 정책, 스키마, 실행기와 완료 증거를 일관되게 생성한다.
2. 요청 진입점에서 queue 별칭을 표준 이름으로 완전히 정규화한다.
3. 엄격한 입력 검증을 단계적으로 기본 활성화한다.
4. 자원 점유 계약을 카메라, 화면, 스피커, 이동과 앱 세션으로 확장한다.
5. 이벤트 기반 Workflow 재개로 긴 대기를 대기열 작업자에서 분리한다.
6. 장애·재부팅 복구와 멱등성 원장을 강화한다.
7. 실행 조건을 타입 기반 연산자로 확장한다.
8. Task·이벤트 스키마의 버전 전환 절차를 정의한다.
9. AAR, DeviceAgent와 Cloud 기능 목록의 불일치를 CI에서 검사한다.
10. 도메인별 완료 증거 범위표를 출시 판정 기준으로 운영한다.

26.3 선택적 상위 계획 연동과 Core 안정성

동적 목표 해석, 상태 관찰과 기능 조합은 TaskManager 위의 선택 확장이다. Core는 다음을 유지해야 한다.

• 일반 단일 명령의 응답 시간을 늘리지 않는다.
• 정상 Task마다 Planner를 재호출하지 않는다.
• 상위 Planner 장애 시에도 현재 Task를 안전하게 종료한다.
• 기능이 없으면 차단 상태로 남기고 다른 기능으로 임의 치환하지 않는다.
• 재계획 횟수와 도구 사용 횟수에 상한을 둔다.

27. 구현 변경 절차

27.1 신규 메서드 추가

1. TaskMethods의 public/internal 상수를 추가한다.
2. TaskSupportedCommands의 도메인 그룹을 추가한다.
3. TaskBundleValidator 입력 스키마를 추가한다.
4. TaskPolicyRegistry의 정확한 실행 정책을 추가한다.
5. 기기 도메인 TaskExecutor를 구현하고 등록한다.
6. 별칭 변환기 적용 여부를 확인한다.
7. 완료 대상과 Completion Bridge를 연결한다.
8. 취소와 보상 동작을 정의한다.
9. 실패 사유 매핑과 컨텍스트 필드를 정의한다.
10. AAR API 사양과 llmwiki를 갱신한다.
11. 단위, 기기 계측과 실기기 시험을 수행한다.

27.2 기존 메서드 수정

• method 문자열은 호환성 영향이 크므로 alias를 먼저 추가한다.
• field type 변경은 JSON→Bundle bridge와 AAR builder를 함께 수정한다.
• timeout 변경은 workflow timeout 계산과 실기기 duration 근거를 확인한다.
• 완료 조건 변경은 콜백 제공자와 감시기를 함께 수정한다.
• queue 변경은 concurrency와 preempt 동작을 회귀 테스트한다.

27.3 문서 변경

28. 참조 규격과 문서 색인

이 사양서는 Core 규범을 소유한다. 상세 문서는 한 가지 책임만 갖고, 같은 계약을 다시 정의하지 않는다.

해석 충돌 시 제품 안전 정책과 승인된 요구사항, 이 사양서, 세부 계약 문서, 검증 기록 순서로 판단한다. 통합된 이전 문서는 기존 URL의 리다이렉트로만 유지하며, 활성 검색과 신규 링크에서는 사용하지 않는다.

제6부 · 상세 규범과 호환성 — 29~31장은 Core 불변 조건, 도메인별 Task 사양, 기존 시스템 전환과 적합성 판정을 고정한다.

29. TaskManager Core, 관리 대상 Task와 기기 연동 규범

이 장은 앞의 구현 설명을 제품 사양의 세 계층으로 정리한다. TaskManager가 공통으로 보장할 사양, 각 Task가 개별적으로 선언할 사양, 실제 기기 상태가 실행 허용과 완료에 미치는 영향을 분리한다.

위 3계층 계약 구조도는 모든 Task에 공통인 TaskManager Core 사양, 기능별 입력·정책·완료·취소를 정의하는 관리 대상 Task 단위 사양, 실제 제품 상태와 자원 제약을 제공하는 기기 도메인 연동 사양을 분리한다.

이 세 층을 섞으면 다음과 같은 오류가 생긴다.

• TaskManager가 요청을 접수했지만 기존 DeviceAgent 정책에서 뒤늦게 거절된다.
• 메서드가 반환됐다는 이유만으로 물리 동작을 완료 처리한다.
• LLM 활성 중 신규 동작 제한과 이미 수행 중인 동작의 일시정지·재개를 같은 정책으로 오해한다.
• 장기 앱 세션을 화면 전환 ACK만으로 완료 처리한다.
• Planner가 기기 상태를 참고했어도 DeviceAgent의 최종 안전 정책을 우회하게 된다.

29.1 TaskManager Core 규범 사양

TaskManager Core는 기능의 내용이 아니라 실행의 질서와 증거를 소유한다.

29.1.1 Core 불변 조건

1. Task 접수 성공은 기능 완료가 아니다. accepted=true는 실행 허용 판정과 기록 생성에 성공했다는 뜻이다.
2. 물리 Task의 성공은 최신 완료 증거로 확정한다. completionSinceMs보다 오래된 콜백은 사용할 수 없다.
3. 취소는 성공으로 변환하지 않는다. 사용자 취소, PUI 중단, 외부 앱 종료를 목적 달성으로 해석하지 않는다.
4. TaskManager는 기기 도메인 안전 정책보다 높은 권한을 갖지 않는다. 대기열 우선순위가 배터리, 오류, 개인정보 보호와 제품 모드 제한을 우회하지 않는다.
5. 관찰 이벤트는 실행 명령이 아니다. 센서 값이나 콜백을 그대로 구동 Task로 다시 제출하지 않는다.
6. 상위 Planner 장애가 현재의 안전한 동작을 깨면 안 된다. 정상적인 후속 실행과 기기 내 취소·시간 제한 처리는 기기에서 마감한다.
7. 같은 물리 효과를 만드는 중복 제출을 식별할 수 있어야 한다. 요청·추적·Workflow·단계 ID를 보존한다.
8. 지원하지 않는 기능을 유사 기능으로 임의 대체하지 않는다. 실행기나 필수 입력이 없으면 명시적으로 거절한다.

29.1.2 실행 허용 정책과 실행 중 정책의 차이

실행 허용 정책은 두 시점에 적용된다.

따라서 TaskManager가 accepted=true를 반환해도 기기 도메인 실행 시점에 상태가 바뀌면 POLICY_NOT_ALLOWED 또는 도메인 오류로 실패할 수 있다. 목표는 도메인 규칙을 TaskManager에 복제하는 것이 아니다. 공통으로 표현할 수 있는 상태와 자원을 실행 허용 판정에 반영하되, 최종 도메인 판정을 유지하는 것이다.

29.2 관리 대상 Task 단위 규범 사양

관리 대상 Task는 단순한 “함수 이름과 매개변수 묶음”이 아니다. 최소한 다음 다섯 질문에 답할 수 있어야 한다.

관리 대상 기능은 다음 질문에 모두 답할 수 있어야 한다.

• 무엇을 실행하는가?
• 어떤 상태와 자원이 있어야 시작할 수 있는가?
• 언제 실제 완료로 판단하는가?
• 어떻게 중단하고 복구하는가?
• 실패 후 누가 다음 결정을 하는가?

29.2.1 Task 설명자 필드

현재 TaskPolicyRegistry.resolve()는 요청이 정책 기본값을 덮어쓸 수 있게 한다. 그러나 호출자가 임의로 대기열, 우선순위와 시간 제한을 바꿔도 된다는 뜻은 아니다. 외부 공개 AAR과 Cloud 계약에는 기능 설명자가 허용한 변경 항목만 노출해야 한다.

29.2.2 Task 유형별 필수 사양

29.2.3 Task 최종 상태 판정

시간 제한은 완료 조건을 대신하지 않는다. 제한 시간이 지나면 성공으로 처리하지 않고 FAILED 또는 세션별 명시 정책으로 마감한다. 바이탈사인처럼 사용자의 측정 완료나 취소로 끝나는 Task는 임의로 30초 뒤 완료 처리하지 않는다. 앱의 완료·취소 증거를 기다려야 한다.

29.3 LLM/음성 세션과 기기 동작 연동 사양

이 절은 TaskManager 전체 요청 경로를 음성 중심으로 설명하지 않는다. LLM·음성 세션이 마이크, 스피커와 추론 자원을 점유할 때 추가로 적용되는 도메인 제약만 정의한다.

“LLM 동작 중 다른 동작 제한”은 하나의 boolean 규칙이 아니다. 현재 구현에는 신규 명령 실행 제한, 기존 동작 일시정지·재개, LLM 상태 관찰이 별도로 존재한다.

29.3.1 LLM 상태 모델

LlmPipelineObservationBridge는 다음 상태를 planning context의 voice_llm으로 투영한다.

이 값은 ondevice_agent_reported_status를 기반으로 하며 유효 시간과 최신성 조건이 있다. 오래된 상태를 Planner의 실행 근거로 사용하면 안 된다.

29.3.2 신규 기기 동작 제한

CmdPolicyManager.commonCheck()는 LlmManager.isLlmProcessingStatus()가 true인 동안 일반 이동, 청정과 스케줄 계열의 신규 동작을 기본적으로 거절한다.

현재 예외는 다음과 같다.

• 공기 센서 자동 청정 호출은 제한적으로 허용한다.
• 저전력/에러에 의한 안전 복귀는 CHK_OPT_IGNORE_LLM으로 LLM 제한을 우회할 수 있다.
• 이 우회는 안전·내부 복구용이며 일반 Cloud·VOICE Task에 노출하면 안 된다.

중요한 현재 경계:

• TaskManager Core의 TaskDomainResourcePolicy는 아직 모든 물리 Task에 voice_session 자원을 자동으로 할당하지 않는다.
• 따라서 LLM 활성 상태의 일반 Task가 TaskManager의 실행 허용 판정을 통과한 뒤 기존 기기 도메인 정책에서 거절될 수 있다.
• 계획 컨텍스트의 voice_llm.pipeline_busy는 Planner 입력이지만, 이것만으로 DeviceAgent의 최종 정책을 대체하지 않는다.

29.3.3 기존 동작 일시정지·재개

호출어가 감지되면 notifyLearnedKeywordDetected 경로가 setDeviceStatus(action=pause)를 호출한다. 이 경로는 현재 활성 domain 중 하나를 pause한다.

LLM 처리가 끝나고 기기 동작이 일시정지 상태이면 setLlmStatus 경로가 재개를 시도한다. 일시정지 요청자는 목록으로 관리된다. 따라서 필터 커버 오류처럼 LLM 외 다른 원인이 남아 있으면 LLM 종료만으로 재개하지 않는다. E01/S08 같은 오류 상태도 재개를 막는다.

persist.sys.debug.deviceagent.maumai_tmp_pause_resume는 LLM 상태 변화만으로 일시정지·재개를 연결하는 임시 속성이다. 기본 활성 사양으로 간주하면 안 된다. 제품 기준은 호출어, 명시적 기기 상태 생명주기와 실제 오류 조건을 함께 확인한다.

29.3.4 LLM 연동 규범

1. 사용자의 음성 세션 시작을 위해 현재 Workflow를 COMPLETED로 만들지 않는다. 필요한 도메인만 일시정지한다. 현재 TaskRecord에는 별도 PAUSED 상태가 없어 기록은 RUNNING으로 남으므로, 도메인 일시정지 사실은 단계·이벤트로 보강해야 한다.
2. 음성 세션 중 새 물리 Task는 기기 도메인 정책이 허용할 때만 실행한다.
3. 안전 복귀 같은 긴급 경로는 일반 사용자 우선순위와 분리한다.
4. 재개는 LLM IDLE 상태만 보지 않고 일시정지 요청자와 현재 오류를 확인한다.
5. voice_session_active, pipeline_busy, output_state를 구분한다. 외부 TTS 재생을 사용자 음성 추론 세션으로 오해하지 않는다.
6. Task 이벤트에는 “LLM 때문에 실행 허용 거절”, “LLM으로 기존 동작 일시정지”, “다른 오류 때문에 재개 보류”를 서로 다른 실패 사유로 노출해야 한다.

29.4 기기 상태와 자원 연동 행렬

아래 표의 Core는 TaskManager의 실행 허용과 런타임을, 기기 도메인은 기존 DeviceAgent의 기능 정책을 뜻한다.

29.4.1 현재 자원 요구 계약

현재 speaker, microphone, tilt_head, voice_session, map_writer, network_uplink은 공통 자원 점유 계약으로 완전히 모델링돼 있지 않다. 문자열 규칙만 추가하지 말고 기능 설명자와 실행기가 같은 자원 용어를 사용하도록 확장해야 한다.

29.5 도메인별 관리 대상 Task 사양

29.5.1 이동과 스테이션 복귀

MovementTaskExecutor는 이동 전에 활성 청정을 멈추고 cleaning.stopped를 기다리는 전환 경로를 갖는다. 이는 “청정 중 이동 불가” 정책을 임의로 우회하는 예외가 아니다. 같은 Workflow 안에서 선행 물리 동작을 안전하게 정리한 뒤 이동하는 관리 전환이다.

현재 엄격 검증기가 허용하는 setMoveTo 키와 실행기가 실제로 인식하는 areaId, targetRoom, roomName 범위에 차이가 있다. 엄격 검증을 기본 활성화하기 전에 검증기와 표준 어댑터를 정합해야 한다.

29.5.2 청정

청정 시작 응답을 완료로 볼지, 일정 시간 청정 후 중지를 완료로 볼지, 전체 이동청정 결과 보고까지 기다릴지는 Workflow 목적에 따라 completionTarget으로 구분한다.

29.5.3 LLM/TTS

TTS는 스피커를 사용하지만 현재 공통 speaker 자원 점유 계약이 없다. Security·이동과 동시 실행 가능한지, 사용자 음성 입력 중 재생을 허용할지는 제품 UX 정책으로 명시하고 기능 자원에 반영해야 한다.

29.5.4 바이탈사인과 외부 앱 세션

바이탈사인은 화면을 띄운 순간 끝나는 단기 UI Task가 아니다. 측정 완료 또는 취소까지 이어지는 장기 세션이다. 후속 단계는 앱 세션의 최종 증거를 받은 뒤에만 시작한다.

29.5.5 보안

Security 시작은 자신의 현재 Security 상태를 자원 스냅숏에서 제외해 자기 충돌을 피한다. 일시정지·재개·중지는 기존 세션 제어로 실행을 허용한다.

29.5.6 Welcome·Wakeup·Relax 상호작용

interSchedule의 기본값은 ASYNC 실행, interaction 대기열, HIGH 우선순위, 1200초 제한이다. 완료 상태는 scheduleId를 키로 조회한다. InterScheduleManager에는 LLM 개입 정책으로 WAIT, RESTART, STOP이 정의돼 있으며 현재 기본값은 STOP이다.

STOP 정책에서도 relax 음원은 호출어 또는 LLM 세션이 시작되면 일시정지하고, 세션이 끝나면 재개하는 별도 흐름을 따른다. 단순히 예약 시각이 됐거나 TTS가 시작됐다는 이유로 전체 상호작용을 완료 처리하면 안 된다.

29.5.7 Vision, 회전과 스테이션 관찰

관찰 Task가 COMPLETED라는 것은 센서 호출이 정상 종료됐다는 뜻일 수 있다. 원하는 객체를 찾았거나 스테이션 위치 변경을 확정했다는 뜻은 아니다. 결과 구조의 detected, 신뢰도, 최신성과 증거 품질을 다음 단계 조건에서 확인해야 한다.

29.6 Workflow에서 Task 단위 사양을 사용하는 방법

예를 들어 “안방으로 이동해 바이탈사인을 측정하고 끝나면 스테이션으로 복귀”는 단순히 세 Task를 나열한 것이 아니라, 서로 다른 세 완료 계약을 연결한 Workflow다.

중간에 사용자가 말을 걸면 단계 1 또는 단계 3은 일시정지·재개 대상이 될 수 있다. 단계 2는 외부 앱 세션 정책에 따라 음성 처리 허용 여부를 따로 정의해야 한다. 바이탈사인 화면이 열렸다고 단계 3을 시작하거나, LLM이 IDLE이 됐다는 이유만으로 바이탈사인 세션을 완료 처리하면 안 된다.

29.7 구현 상태와 보강 우선순위

보강의 핵심은 if (발화에 특정 단어가 있으면) 같은 규칙을 늘리는 것이 아니다. 기능이 요구하는 자원, 현재 기기 상태와 Task 완료 계약을 구조화해 상위 Planner와 DeviceAgent가 같은 용어와 계약을 사용하게 하는 것이다.

30. 기존 시스템 호환성과 점진적 전환 사양

TaskManager 도입은 기존 DeviceAgent 기능을 다른 구현으로 교체하는 작업이 아니다. 기존 PUI, IoT, 시스템 앱, Schedule과 Voice/LLM 호출이 사용하던 MainApi와 기기 도메인 구현을 유지하고, 관리가 필요한 요청만 TaskManager 생명주기에 편입하는 점진적 확장이다.

구조도의 두 실행 경로는 모두 같은 기존 기기 도메인에 도달한다. 차이는 기존 호출이 MainApi.executeMethod()와 executeMethodInternal()을 유지하는 반면, 관리 호출은 명시적 Task API 또는 forceTaskManager=true를 통해 실행 허용, 대기열과 생명주기 관리를 먼저 거친다는 점이다.

두 경로는 마지막에 같은 Movement, Cleaning, Schedule, Security, LLM/TTS와 Update 구현으로 합류한다. TaskManager는 기존 기능 로직을 복제하지 않고 실행 순서, 상태, 완료 증거와 취소 관리를 덧붙인다.

30.1 호환성 목표와 비목표

요약: 기존 기능을 유지하면서 필요한 경로부터 TaskManager 관리 대상으로 전환한다.

호환성은 “컴파일된다”가 아니라 다음 네 수준으로 판정한다.

1. 호출 호환성: 기존 메서드와 필드를 계속 보낼 수 있다.
2. 동작 호환성: 같은 기기 도메인이 같은 물리 동작과 안전 정책을 수행한다.
3. 관찰 호환성: 기존 콜백과 UI·IoT 상태 갱신이 유지된다.
4. 운영 호환성: 배포, 재부팅 복원, 모니터링과 원복이 가능하다.

30.2 이중 실행 경로

요약: 기존 요청은 종전 경로로, 관리 대상 요청은 TaskManager 경로로 보내며 실제 기능은 같은 기기 도메인이 수행한다.

MainApi.executeMethod()의 호환 분기는 다음 순서를 따른다.

구조도의 분기 순서는 명시적 제어 API, forceTaskManager=true인 기존 메서드, 그 밖의 기존 메서드 순이다. 각 요청은 각각 TaskManager.handleControlMethod(), TaskManager.executeLegacy(), executeMethodInternal()로 전달된다.

소스 표현 빠른 해석

소스 심볼은 현재 구현 위치를 설명하기 위한 근거다. 외부 호출자가 의존해야 하는 공개 계약은 제어 API, AAR 스키마와 콜백 계약이다. 내부 클래스 이름은 리팩터링 과정에서 바뀔 수 있다.

30.2.1 외부 MainApi 기존 경로

• forceTaskManager가 없으면 기존 executeMethodInternal()을 그대로 사용한다.
• 기존 호출자의 즉시 반환, 오류 전달과 콜백 계약은 TaskManager 대기열 때문에 바뀌지 않는다.
• TaskManager 전체 활성화 상태와 무관하게 기존 원시 경로는 유지한다.

30.2.2 외부 MainApi 관리 경로

• 명시적 submitTask/submitWorkflow 또는 forceTaskManager=true 요청만 관리 경로로 들어간다.
• TaskPolicy가 DIRECT이면 기존 함수를 직접 호출하되 Task 결과를 기록한다.
• ASYNC와 QUEUED_WAIT이면 TaskRecord와 대기열을 만들고 기존 도메인 실행기를 호출한다.
• 실행기가 다시 MainApi를 사용할 때 runningManagedTask 재진입 보호 장치가 대기열 중복 등록을 막는다.

30.2.3 내부 AppCmd 모듈 경로

DeviceAgent 내부 AppCmd에는 외부 MainApi와 다른 호환 분기가 있다.

이 경로에서는 persist.sys.deviceagent.taskmanager.legacy_queue 기본값이 true이므로 조건을 만족하는 내부 명령이 자동으로 대기열에 들어갈 수 있다. 반면 외부 MainApi 원시 호출은 이 속성만으로 관리 경로에 들어가지 않으며 forceTaskManager=true가 필요하다.

30.2.4 TaskManagerClient AAR 경로

AAR은 모든 기존 호출을 자동 변환하는 프록시가 아니다. 타입 기반 요청 생성기는 관리 계약을 만들고, sendRaw()는 점진적 전환 중 아직 타입 기반 API가 없는 기존 계약을 보존한다.

forceTaskManager는 단순 로그 표시가 아니다. 요청을 Task 생명주기에 편입하고 반환 시점과 결과 구조를 바꿀 수 있는 호환성 경계 플래그다.

30.2.5 IoT·App·LLM Agent의 채널별 적용 방식

결론: MQTT 연결과 기존 명령을 일괄 교체하지 않는다. 기존 단일 명령은 그대로 두고, Task 생명주기가 필요한 요청만 선택적 관리 계약으로 확장한다.

TaskManager 도입으로 바뀌는 범위는 MQTT broker, topic, 인증, QoS와 재연결 같은 전송 계층 전체가 아니다. 바뀌는 부분은 명령 payload가 직접 실행인지 관리 대상 Task·Workflow인지 표현하는 응용 계약과, 관리 요청의 진행·완료를 돌려주는 결과 계약이다.

MQTT를 전부 바꾸지 않는 이유

MQTT의 기존 기능 payload는 이미 DeviceAgent 도메인 입력과 연결되어 있다. 이를 새 스키마로 일괄 치환하면 Topic parser, 응답 앱, 서버와 구버전 기기의 동시 배포 문제가 커진다. 현재 IotTaskManagerBridge는 다음 방식으로 호환성을 유지한다.

request.task 없음
  -> 기존 parser가 만든 method와 payload 유지
  -> 기존 MainApi 직접 실행

request.task 있음, managed 생략 또는 true
  -> 기존 method를 taskMethod로 보존
  -> method=submitTask, source=iot로 감쌈
  -> payload는 그대로 두고 Task metadata만 추가

request.task.managed=false
  -> 기존 직접 실행 유지

따라서 기존 MQTT 명령은 수정하지 않아도 계속 동작한다. TaskManager가 필요한 명령만 아래처럼 task 객체를 추가한다.

{
  "correlationId": "move-bedroom-001",
  "request": {
    "method": "setMoveTo",
    "payload": {
      "positionId": "5"
    },
    "task": {
      "managed": true,
      "executionMode": "async",
      "completionTarget": "movement.arrived"
    }
  }
}

priority, queueKey, timeoutMs, preemptPolicy까지 모든 값을 외부가 채울 필요는 없다. 생략된 값은 TaskPolicyRegistry의 메서드별 기본 정책으로 보강한다. 외부 입력값은 호출자 정책과 허용 범위로 다시 검증하며, 특히 EMERGENCY, 전체 대기열 교체와 임의 취소·보상 메서드는 그대로 신뢰하지 않는다.

복합 Workflow는 별도 계약으로 추가한다

여러 단계를 기존 단일 명령 Topic에 억지로 분산하면 서버 또는 App이 각 단계의 완료를 추측하고 다음 명령을 보내야 한다. 이 경우 TaskManager의 순서·취소·실패 전파 이점을 잃는다. 복합 실행은 하나의 submitWorkflow 요청으로 제출한다.

{
  "correlationId": "clean-return-001",
  "request": {
    "method": "submitWorkflow",
    "payload": {
      "workflowName": "bedroom_clean_return",
      "subTasks": [
        {"taskMethod": "setMoveTo", "positionId": "5"},
        {"taskMethod": "setAirCleanerOperation", "action": "1", "mode": "1"},
        {"taskMethod": "returnToStation"}
      ]
    }
  }
}

이 형식은 기존 모든 MQTT Topic을 변경한다는 뜻이 아니다. submitWorkflow를 처리하는 공통 command parser 또는 전용 관리 Topic 하나를 추가하고, 기존 단일 명령 Topic은 유지하는 방식이 안전하다. 현재 MR6의 IotTaskManagerBridge는 단일 명령의 request.task 변환까지 구현되어 있으며, payload.subTasks[]를 ArrayList<Bundle>로 만드는 MQTT Workflow parser는 아직 구현 완료로 보면 안 된다.

응답과 이벤트의 호환 원칙

기존 callback을 즉시 제거하면 구버전 App과 IoT 서버가 상태를 잃는다. 전환 기간에는 기존 callback과 Task event를 함께 발행하되, requestId, traceId, correlationId로 같은 실행을 묶고 수신자는 중복 반영하지 않아야 한다.

채널 전환 순서

1. 기존 MQTT·App 명령과 응답을 기준선으로 고정한다.
2. 취소·진행률·물리 완료 추적이 필요한 메서드 하나를 선택한다.
3. IoT는 request.task, System App은 AAR, LLM은 구조화된 device request로 같은 Task 의미를 만든다.
4. 기존 callback과 Task event가 같은 물리 실행을 가리키는지 확인한다.
5. 단일 Task가 안정화된 뒤 공통 submitWorkflow ingress를 추가한다.
6. 호출자×메서드 단위로 확대하며 기존 direct 경로는 원복 수단으로 유지한다.

이 구조에서 호출 채널은 서로 달라도 TaskManager가 받는 최종 계약은 동일하다. 반대로 센서 update, heartbeat, 조회 결과와 단순 상태 동기화는 실행 생명주기가 아니므로 기존 메시지 경로에 남긴다.

30.2.6 기존 direct 명령과 관리 Task의 동시성

현재는 관리 Task끼리의 순서는 TaskManager가 통제하지만, 비관리 direct 명령은 대기열 밖에서 실행된다. 두 경로는 기존 DeviceAgent 도메인 정책에서 다시 만나므로 물리 안전 제한은 공유하지만, 실행 순서와 Task 상태까지 자동으로 정합되는 것은 아니다.

현재 구현에서 보장되는 범위

예를 들어 관리 Task가 이동 중일 때 기존 App이 direct setMoveTo를 보내면, 후속 명령은 기존 CmdPolicyManager.setMoveTo()의 is_moving 검사에서 거절될 수 있다. 이는 물리적으로 두 이동을 동시에 실행하지 않게 하지만, 거절된 direct 요청을 TaskManager가 대기시키거나 원래 이동 Task의 선점 사유로 기록한 것은 아니다.

반대로 PUI 정지나 복귀가 기존 경로에서 현재 동작을 중단할 수 있다. 해당 도메인의 중단 callback이 TaskCompletionStateStore와 연결된 기능은 관리 Task가 취소·실패로 닫힐 수 있지만, 모든 도메인에서 원인과 Task ID가 연결된다고 가정하면 안 된다. 연결이 없는 기능은 관리 Task가 물리 중단을 모르고 시간 초과까지 남을 수 있다.

호환성을 유지하는 공통 동시성 경계

기존 direct 호출을 모두 공개 단일 Task로 바꾸지 않고도 동시성을 맞추려면, TaskManager와 기존 경로 아래에 공통 실행권 조정 경계가 필요하다.

기존 direct 요청 ─┐
                  ├─ 실행 분류 ─ 공통 도메인 실행권/자원 점유 ─ 기존 DeviceAgent 정책 ─ 실제 동작
관리 Task 요청 ───┘                   │
                                      └─ 시작·중단·완료 증거를 원 요청에 귀속

이 경계는 자연어 의미를 추론하는 규칙이 아니다. TaskPolicyRegistry, 기능 계약과 requiredResources에 선언된 실행 특성을 사용해 결정적으로 동작한다.

장기 direct 동작의 실행권을 물리 완료까지 유지하려면 결국 시작·중단·완료 callback과 연결된 내부 기록이 필요하다. 따라서 이동·청정 같은 메서드는 검증이 끝난 순서대로 외부 응답 형식은 유지하면서 내부적으로 단일 Task로 승격하는 편이 단순한 잠금보다 안정적이다. 반면 조회와 상태 update까지 Task로 승격하면 대기열과 이벤트만 오염되므로 그대로 direct로 둔다.

충돌 결과의 일관된 귀속

동시성 조정 결과는 물리 동작과 관리 상태가 함께 바뀌어야 한다.

단순히 CmdPolicyManager가 POLICY_NOT_ALLOWED를 반환하는 것으로 끝내면 호출자는 “왜 안 됐는지”, TaskManager는 “기존 작업이 계속 유효한지”를 알 수 없다. 도메인 정책 결과를 errorCode, reason, 점유 자원과 관련 taskId로 연결해야 동시성 호환이 완성된다.

단계적 적용

1. 기존·관리 경로의 동시 실행 조합을 로그로만 관찰한다.
2. 이동·청정·보안·화면/카메라 세션의 자원 소유권과 사용자 취소 결과를 표준화한다.
3. 충돌 가능 direct 명령에 공통 실행권 검사를 적용하되 기존 응답 형식은 유지한다.
4. 검증된 장기 메서드만 내부 단일 Task 승격 대상으로 확대한다.
5. PUI·오류·저전력 선점이 기존 관리 Task를 올바른 terminal 상태로 닫는지 실기기에서 검증한다.
6. 호출자×메서드 단위 회귀가 끝날 때까지 기존 direct 원복 경로를 유지한다.

30.3 호환성 표면

요약: API 이름뿐 아니라 입력값, 응답 시점, 콜백, 저장소, SDK와 배포 방식도 호환성 검토 대상이다.

30.4 그대로 보존해야 하는 동작

요약: TaskManager를 사용해도 실제 기능 주체, 안전 정책, 기존 콜백과 제품 스케줄의 의미는 유지해야 한다.

다음은 TaskManager 도입 전후에 바뀌면 안 되는 호환 불변 조건이다.

1. 같은 요청은 Movement, Cleaning, Schedule, Security 등 기존 수행 주체가 처리한다.
2. 기존 PUI, IoT와 시스템 앱의 원시 메서드는 선택 적용 전까지 기존 경로를 사용한다.
3. 기존 기기 도메인 콜백과 상태 갱신은 계속 발행된다.
4. LLM, 배터리, AMR, 개인정보 보호, 오류와 주 상태 제한은 기존 기기 도메인이 최종 판정한다.
5. 같은 기기 동작이 기존 경로와 관리 경로에서 중복 실행되지 않는다.
6. TaskManager가 비활성화돼도 기존 핵심 기능은 원시 경로로 수행할 수 있어야 한다.
7. 기존 제품 스케줄의 등록, 조회, 실행 의미와 DB 소유권은 유지한다.
8. 시스템 앱 패키지, UID, 서명 권한과 플랫폼 인증서 관계를 유지한다.

30.5 선택 적용 후 달라질 수 있는 동작

요약: 같은 기능도 TaskManager를 거치면 “접수”와 “실제 완료”의 응답 시점과 결과 형식이 달라질 수 있다.

TaskManager 경로는 실행 기능은 같지만 호출 의미까지 완전히 투명하지는 않다.

같은 이동 명령의 호출 차이

아래 예시는 반환 의미를 설명하기 위한 개념 예시다. 실제 필드는 호출자 계약과 출시 스키마를 따른다.

기존 호출

{
  "method": "setMoveTo",
  "positionId": "5",
  "positionName": "안방"
}

기존 이동 경로는 MainApi가 이동 도메인에 명령을 전달하고 기존 메서드 결과를 반환한 뒤, 기존 이동 콜백으로 도착 상태를 알리는 계약을 그대로 유지한다.

TaskManager 선택 호출

{
  "method": "submitTask",
  "forceTaskManager": true,
  "taskMethod": "setMoveTo",
  "source": "APP",
  "requestId": "move-bedroom-001",
  "positionId": "5",
  "positionName": "안방",
  "executionMode": "async",
  "completionTarget": "movement.arrived"
}

{
  "accepted": true,
  "taskId": "task-...",
  "taskState": "PENDING",
  "message": "작업이 접수됨"
}

이 응답의 accepted=true는 안방 도착을 뜻하지 않는다. 이동 콜백이 movement.arrived 증거로 연결되고 Task가 COMPLETED가 돼야 실제 완료다. 기존 호출자는 종전 콜백을 계속 받을 수 있고, 관리 경로 호출자는 Task 이벤트 또는 getTaskStatus를 추가로 사용할 수 있다.

따라서 호출자별 전환 전에 다음을 명시한다.

• 기존 호출자가 접수 응답을 기다리는지 실제 완료를 기다리는지
• 동기 호출 시간 제한과 UI 스레드 사용 여부
• 기존 outdata에서 반드시 읽는 키
• 콜백을 별도로 기다리는지
• 중복 재시도가 기기 동작을 다시 일으킬 가능성

30.6 메서드·필드 별칭 계약

요약: 메서드·필드 별칭은 등록된 항목에만 적용되며 모든 과거 입력을 자동으로 호환하지 않는다.

별칭 처리는 기존 요청 데이터를 모두 자동 수용하는 범용 기능이 아니다. TaskMethodAliasResolver, TaskFields와 실행기 어댑터에 등록된 범위만 계약이다.

현재 대표 호환 범위:

• 청정 시작·중지·일시정지·재개와 복귀 별칭을 표준 청정 메서드로 정규화한다.
• schedule 식별자는 scheduleId, scheduleid, schedule_id를 일부 경로에서 수용한다.
• 활성·대기열 필드는 isActive/is_active, taskQueue/queue를 일부 어댑터가 수용한다.
• 결과에는 Task, 실패 사유와 Cloud 상관관계의 camelCase·snake_case 별칭을 함께 기록하는 경로가 있다.

현재 알려진 정합 공백:

• TaskManagerClient 요청 생성기는 queue를 쓰는 반면 정책 변경값은 queueKey를 읽는 경로가 있다.
• setMoveTo의 엄격 검증 허용 키와 실행기가 읽는 areaId, targetRoom, roomName 범위가 완전히 같지 않다.
• 모든 기존 Bundle 키가 표준 스키마 별칭으로 등록된 것은 아니다.

따라서 엄격한 입력 검증을 기본 활성화하기 전에 메서드별 호출 필드 계약 확인과 기준 요청 회귀 시험을 수행해야 한다. 현재 기본값을 false로 유지하는 것은 기존의 유연한 요청이 갑자기 거절되는 상황을 막기 위한 호환 장치다.

30.7 콜백과 이벤트 호환

요약: 기존 콜백은 유지하고 TaskManager 이벤트로 진행률과 완료 상태를 추가한다.

관리 대상 Task는 기존 콜백을 대체하지 않고 완료 증거로 사용한다.

기존 PUI·IoT·시스템 콜백은 유지한다. 관리 대상 Task와 연결된 콜백만 CompletionBridge가 TaskCompletionStateStore와 Task 진행·최종 이벤트로 변환한다.

Task 이벤트 전달 범위

TaskManager 내부 이벤트와 시스템 앱이 받는 모듈 콜백의 범위는 같지 않다.

TaskManagerClientCallback.onTaskEvent()는 DeviceControlProxy의 모듈 콜백을 받는다. 따라서 내부 수신자가 본 모든 이벤트가 AAR 클라이언트에도 전달된다고 가정하면 안 된다. 호출자별 관찰 요구에 따라 모듈 콜백, getTaskStatus, 모니터 이벤트 중 어느 경로를 사용할지 계약해야 한다.

호환 규칙:

1. 기존 콜백 수신자를 유지한 상태에서 Task 이벤트를 추가 발행한다.
2. 콜백의 기능 의미를 TaskManager에서 다시 추정하지 않는다.
3. Task 이벤트에는 taskId, Workflow·단계 상관관계와 최신 시각을 추가한다.
4. 같은 콜백이 재전송돼도 최종 이벤트는 멱등하게 처리한다.
5. Task Monitor가 콜백을 받지 못해도 기존 기능 상태를 덮어쓰지 않는다.
6. 기존 콜백 제거는 모든 수신자의 전환과 원복 검증 이후 별도 출시에서 수행한다.

30.8 제품 스케줄과 저장소 호환

요약: 반복 제품 일정과 “30분 뒤 한 번 실행”하는 Task 예약은 서로 다른 기능과 저장소로 유지한다.

제품 반복 스케줄과 TaskManager 지연 실행은 저장 주체와 의미가 다르다.

기존 스케줄 기록을 TaskManager 기록으로 묵시 변환하거나, 제품 반복 일정을 단발 Task로 재해석하면 안 된다. 상위 Planner가 제품 스케줄을 만들더라도 기존 Schedule 도메인 메서드를 관리 대상 Task로 호출하며, 스케줄 데이터의 소유권은 그대로 유지한다.

30.9 AAR, Binder와 시스템 앱 호환

요약: 기존 앱은 종전 호출을 유지할 수 있고 신규 앱은 AAR을 사용할 수 있지만, 기기 서명과 권한 조건은 동일하게 적용된다.

TaskManagerClient AAR은 기존 DeviceAgent 기능을 다른 프로세스로 옮기는 SDK가 아니다. 기존 AIDL·Binder 경계 위에 타입 기반 Task API를 제공하는 진입점이다.

• 기존 앱은 원시 Bundle 호출을 유지할 수 있다.
• 신규 앱은 타입 기반 요청 생성기로 Task·Workflow·예약·제어 API를 사용할 수 있다.
• sendRaw(Bundle)는 아직 타입 기반 API가 없는 메서드의 점진 전환 경로다.
• AAR 계약 버전과 지원 메서드 목록은 DeviceAgent 출시 형상과 함께 관리한다.
• 클라이언트 AAR과 DeviceAgent APK의 갱신 순서가 달라도 지원하지 않는 계약은 명시적으로 거절해야 한다.
• 플랫폼 서명 특권 앱의 패키지, UID와 서명 권한 조건은 TaskManager 도입으로 완화되지 않는다.
• 실기기 교체 시 apksigner verify --print-certs로 기존 APK와 신규 APK 인증서를 비교하고, 디버그 인증서 APK를 /system/priv-app에 배포하지 않는다.

30.10 단계적 전환

요약: 전체 기능을 한 번에 바꾸지 않고 호출자와 기능 단위로 전환하고 검증한 뒤 확대한다.

일괄 전환보다 호출자 x 메서드 x 실행 방식 단위 허용 목록이 안전하다. 예를 들어 Cloud Workflow의 setMoveTo만 먼저 관리 경로로 전환하고 PUI 단일 이동은 기존 경로를 유지할 수 있다.

30.11 원복 사양

요약: 문제가 생기면 전체 APK를 되돌리기 전에 해당 호출이나 관리 기능만 기존 경로로 원복할 수 있어야 한다.

현재 TaskManager.isEnabled()는 forceTaskManager=true이면 활성화 속성보다 강제 실행을 우선한다. TaskSubmitRequest와 TaskWorkflowRequest도 강제 실행 플래그를 자동으로 추가한다. 따라서 persist.sys.deviceagent.taskmanager.enable=false는 모든 요청을 차단하는 전역 중지 스위치가 아니다.

강제 요청까지 즉시 차단해야 한다면 신뢰된 호출자별 기능 플래그나 DeviceAgent의 별도 긴급 실행 차단 장치가 필요하다.

원복은 설정만 바꾸는 절차로 끝나지 않는다. 실행 중인 대기열과 Task의 취소 또는 종료 대기, 콜백 이중 발행 정리, 예약 영속성 처리와 재부팅 후 상태 정합까지 정의해야 한다.

30.12 호환성 인수 기준표

요약: 빌드뿐 아니라 기존 호출, 실기기 동작, 콜백, 재부팅과 원복의 전후 결과를 비교해야 호환 완료로 본다.

각 전환 메서드는 다음 항목을 기존 경로와 관리 경로에서 대조한다.

최소 회귀 세트는 PUI, IoT/MQTT, Launcher·시스템 앱, 제품 Schedule과 Voice/LLM을 모두 포함해야 한다. JVM 시험이나 APK 빌드 통과만으로 기존 시스템 호환을 확정하지 않는다.

30.13 현재 남은 호환성 위험

요약: 기본 이중 경로는 마련됐지만 필드 이름, 응답 해석, 이벤트 중복, 버전 조합과 실기기 원복 검증은 아직 완료되지 않았다.

30.14 소스 근거와 검증 상태

이 표에서 “자동 검증 존재”는 해당 분기 일부를 시험했다는 뜻이다. 실제 Binder 호출자, 스레드 실행 시점, 플랫폼 권한과 물리 기기 동작까지 동일하다는 의미는 아니다. L3 이상의 적합성은 실기기 증거로 별도 판정한다.

31. 규범 요구사항과 적합성 판정

이 장은 앞의 설명을 구현과 출시 단계에서 판정할 수 있는 요구사항으로 고정한다. 요구사항 ID는 이슈, 소스 검토, 테스트 케이스, 실기기 증거와 릴리스 노트에서 공통으로 사용한다.

31.1 핵심 요구사항 ID

31.2 적합성 수준

기능별 상태는 가장 높은 통과 수준 하나로 표현한다.

예를 들어 Vision Task가 정상 콜백으로 COMPLETED된 것은 최대 L3의 “관찰 호출 성공” 근거다. 원하는 객체를 찾았거나 추적 기능이 있다는 뜻은 아니다. 의미 있는 객체가 실제로 검출됐는지는 별도 인수 시험으로 확인한다.

31.3 기능 적합성 카드

각 taskMethod는 코드와 문서에 흩어진 내용을 다음 한 장의 카드로 모아야 한다.

기능 카드 예시: setMoveTo

31.4 요구사항 추적 사슬

구조도는 제품 요구사항에서 TM 요구사항 ID, 기능 카드, 정책·검증기·실행기·완료 증거 소스, 자동화 시험, 실기기 증거, 출시 판정과 원복 절차까지 이어지는 추적 사슬을 나타낸다.

각 변경 PR 또는 출시 노트에는 최소한 다음을 남긴다.

requirements: [TM-CMP-001, TM-COMPAT-002]
capabilities: [setMoveTo]
callers: [APP, CLOUD]
source_changes: [...]
automated_tests: [...]
device_evidence: [...]
compatibility_result: pass | conditional | fail
원복: forceTaskManager 제거 또는 출시 산출물 복원
open_risks: [...]

31.5 출시 판정표

다음 항목은 예외 승인으로 넘길 수 없는 출시 차단 조건이다.

• 기존 호출자의 기능 회귀 또는 중복 물리 실행
• 실제 완료 증거 없는 성공 처리
• 취소 후 기기 동작이 계속되는 상태
• 권한 없는 호출자의 제어 API 실행
• 디버그 인증서 또는 플랫폼 서명 불일치
• 원복 경로 부재

31.6 변경 관리

1. 공개 필드, 생명주기, 실패 사유 또는 콜백 변경은 계약 변경으로 분류한다.
2. 선택 필드 추가는 minor version, 기존 의미 변경이나 삭제는 major version 대상으로 본다.
3. 내부 클래스 이름 변경은 외부 계약 변경이 아니지만 소스 추적 정보를 갱신한다.
4. 별칭 추가는 호환 범위 확대다. 별칭을 제거하려면 호출자 현황과 폐기 유예 기간이 필요하다.
5. 정책 기본값 변경은 API 구조가 같아도 동작 호환성 변경이다. 실기기 회귀 시험과 릴리스 노트가 필요하다.
6. 목표 사양을 현재 구현으로 승격할 때 해당 요구사항의 테스트와 증거를 함께 연결한다.

제7부 · 용어와 최종 원칙 — 32~34장은 용어, 최종 설계 원칙과 세부 참조 문서를 정리한다.

32. 용어집

33. 최종 설계 원칙

1. 기능을 다시 만들지 말고 실행 생명주기를 공통화한다.
2. 명령 접수와 실제 완료를 분리한다.
3. 행동 요청과 센서·콜백을 분리한다.
4. 상위 호출자는 목적과 실행 구성을, TaskManager는 실행 관리를, 기기 도메인은 물리 동작과 상태를 소유한다.
5. 모든 기능은 정책, 스키마, 실행기와 완료 증거가 갖춰져야 실제 사용 가능한 기능이 된다.
6. 취소는 성공이 아니며, 부분 실패도 성공으로 숨기지 않는다.
7. 정상 진행은 기기 런타임이 처리하고 의미적 변경이 필요할 때만 재계획한다.
8. 기존 기능과 호출자를 유지하면서 호환 경로를 통해 단계적으로 전환한다.
9. AAR과 스키마 버전으로 외부 계약을 내부 코드와 분리한다.
10. 구현, 코드 검증, 실기기 검증과 제품 인수를 항상 구분한다.

34. 관련 문서

문서 전체 진입점은 SoC TaskManager Framework다.

• 개념: AS-IS / TO-BE 가이드
• 구현: Source-Level Implementation Guide
• API: DeviceAgent Contract · AAR API · MQTT Contract
• 실행 확장: Scheduling Readiness · Device Context Planning
• 검증: Live Monitor · Voice Closed Loop
• 인수: Vendor Implementation Workbook