@asc-agent/runtime 0.1.0

package/dist/core/model/entities.js

@@ -0,0 +1,285 @@
+// Core가 이해하는 Logical Entity Model. 파일 배치·Markdown 표현이 아니라 이 타입들이
+// Core Contract다 — State Store Adapter는 이걸 저장 방식으로 투영할 뿐이다 (OM §7.0).
+// 스키마가 곧 타입의 정본이며 (z.infer로 타입 도출) 이중 정본을 두지 않는다.
+import { z } from 'zod';
+import { BlockId, EventKey, GrantId, QueueItemId, RequestId, SessionId, Timestamp, Version } from "./ids.js";
+// ── 공통 ────────────────────────────────────────────────────────────────────
+/** 전이를 수행할 수 있는 주체. Writer 규칙(OM §7.2)과 상태 전이 권한의 기준. */
+export const ActorRole = z.enum(['controller', 'monitor', 'executor', 'session']);
+export const Priority = z.enum(['P0', 'P1', 'P2']);
+/**
+ * 이벤트 유형 — Phase B 조사 깊이를 결정한다 (OM §10.3).
+ * informational 정보형 / actionable 대응형 / work 작업형.
+ */
+export const EventType = z.enum(['informational', 'actionable', 'work']);
+/**
+ * Canonical source별 baseline. Project는 canonical 하나가 아니라 Session이 소비하는
+ * source 집합을 갖는다 (OM §8) — snapshot도 단일 commit이 아니라 source별로 기록한다.
+ */
+export const CanonicalSnapshot = z.object({
+    sourceId: z.string().min(1),
+    baseline: z.string().min(1), // commit hash / event id 등 provider가 정하는 baseline
+});
+// ── Session / Checkpoint / Handoff ──────────────────────────────────────────
+/** Logical Session 상태 (OM §6.2). Physical Run과 1:1이 아니다. */
+export const SessionStatus = z.enum(['READY', 'ACTIVE', 'PAUSED', 'BLOCKED', 'DONE', 'FAILED']);
+export const SessionRole = z.enum(['planner', 'researcher', 'implementer', 'verifier']);
+/** 중단 시 남기는 Run 승계 정보 — 다른 Physical Run이 같은 Logical Session을 이어받는다. */
+export const Checkpoint = z.object({
+    position: z.string().min(1),
+    completedTasks: z.array(z.string()).default([]),
+    nextAction: z.string().min(1),
+    uncommittedChanges: z.array(z.string()).default([]),
+    /**
+     * 의미 있는 전환을 남기기 위한 필드들 (C-10 §2.1). 시간 경과는 전환이 아니다 —
+     * "지금 무엇이 사실이라고 보는가"와 "그 판단의 근거"가 있어야 다음 사람이 이어받는다.
+     *
+     * 전부 optional·default다: 기존 세션 파일이 그대로 읽혀야 한다 (doneCriteria 선례).
+     * 퍼센트는 여기 없다 — 필요하면 렌더가 만드는 projection이지 기록이 아니다.
+     */
+    currentJudgment: z.string().optional(),
+    blockers: z.array(z.string()).default([]),
+    risks: z.array(z.string()).default([]),
+    evidenceRefs: z.array(z.string()).default([]),
+    /** 누가 적었는가 (execution principal). 소유권 검사와 함께 의미를 갖는다. */
+    writtenBy: z.string().optional(),
+    recordedAt: Timestamp,
+});
+/** 세션 종료 산출물. 계약↔결과 짝이 어긋나지 않도록 Session entity 안에 둔다 (OM §7.1). */
+export const Handoff = z.object({
+    done: z.array(z.string()).default([]),
+    changed: z.array(z.string()).default([]),
+    verified: z.string(), // self-check임을 본문에 명시 (Verifier 독립 검증과 구분)
+    unresolved: z.array(z.string()).default([]),
+    next: z.string(),
+    snapshot: z.array(CanonicalSnapshot).default([]),
+    recordedAt: Timestamp,
+});
+export const Session = z.object({
+    id: SessionId,
+    version: Version,
+    status: SessionStatus,
+    role: SessionRole,
+    blockId: BlockId.optional(),
+    goal: z.string().min(1),
+    /**
+     * 검증 가능한 완료조건 (C-03 §2). "무엇을 할지"(goal)와 "언제 끝인지"를 분리한다 —
+     * Host completion loop projection과 Verifier test plan의 근거가 된다.
+     * default([])라 기존 entity 파일이 그대로 읽힌다.
+     */
+    doneCriteria: z.array(z.string()).default([]),
+    /**
+     * 이 일을 끝까지 끌고 갈 주체 (C-04 §1.1). 다른 파트에 무언가를 물었다는 이유로
+     * 바뀌지 않는다 — 바꾸는 경로 자체를 두지 않는다.
+     */
+    owner: z.string().min(1).optional(),
+    /**
+     * 이 일에 걸린 결정 영역. "무엇을 정해야 하는가"의 목록이며 결정권자는 아니다.
+     * 비어 있는 것이 정상이다 — 대부분의 구현 세션은 cross-part 결정을 요구하지 않는다.
+     */
+    decisionDomains: z.array(z.string()).default([]),
+    /**
+     * 이번 세션에 한해 정한 결정권자 (domain → role). Profile ownership으로 풀리지 않는
+     * 영역을 여기서 명시한다. OM §7.5의 `Authority:`(실행 자율도)와 다른 축이라 이름을
+     * 나눴다 — 저쪽은 "이 세션이 무엇을 자율로 해도 되는가", 이쪽은 "이 결정이 누구 것인가".
+     */
+    decisionAuthority: z.record(z.string()).default({}),
+    /** 외부에서 받아야 할 입력. 받는다는 사실이지 ownership 이전이 아니다 (C-04 §1.2). */
+    dependencies: z.array(z.string()).default([]),
+    taskPointer: z.string().optional(), // 공식 작업 목록 포인터 — 내용 복제 금지 (OM §1.3)
+    canonicalSources: z.array(CanonicalSnapshot).default([]),
+    readScope: z.array(z.string()).default([]),
+    writeBoundary: z.array(z.string()).default([]),
+    outOfScope: z.array(z.string()).default([]),
+    /** Controller가 이 세션에 한해 허용한 SOFT DENY 항목 (OM §5.1 Policy Exception). */
+    policyExceptions: z.array(z.string()).default([]),
+    checkpoint: Checkpoint.optional(),
+    handoff: Handoff.optional(),
+});
+// ── ApprovalRequest / ApprovalDecision ──────────────────────────────────────
+/** Inbox lifecycle (OM §11.2). APPROVED는 승인 완료일 뿐 외부 write 권한이 아니다. */
+export const RequestStatus = z.enum([
+    'AWAITING_APPROVAL',
+    'APPROVED',
+    'QUEUED',
+    'DEFERRED',
+    'DISMISSED',
+    'DONE',
+]);
+export const DecisionKind = z.enum(['approve', 'revise', 'defer', 'dismiss', 'queue']);
+/**
+ * Controller가 원 Thread를 다시 읽지 않고 판단할 수 있도록 Monitor가 준비한 Decision
+ * Packet (OM §11.1). 이 내용은 생성 시점의 분석 snapshot이며, 조회 시점의 현재 상태와
+ * 섞지 않는다 — 현재 맥락은 Derived View로 따로 만든다 (C-01 §6).
+ */
+export const ApprovalRequest = z.object({
+    id: RequestId,
+    version: Version,
+    status: RequestStatus,
+    type: EventType,
+    priority: Priority,
+    title: z.string().min(1),
+    detectedAt: Timestamp,
+    source: z.object({
+        eventKey: EventKey,
+        reference: z.string().min(1), // Issue #19, PR #50 등 사람이 읽는 참조
+        threadLastEventId: z.string().optional(),
+    }),
+    situation: z.string(),
+    context: z.string().default(''),
+    impact: z.object({
+        interruptRequired: z.boolean(),
+        affectedSessions: z.array(SessionId).default([]),
+        rationale: z.string().default(''),
+    }),
+    recommendation: z.string().default(''),
+    draft: z.string().optional(), // 대응형만. 게시는 Grant 경로로만 (OM §11.5)
+    snapshot: z.array(CanonicalSnapshot).default([]),
+    /** 이 요청을 결정할 수 있는 Controller identity (OM §11.6). */
+    authorizedApprover: z.string().min(1),
+    allowedDecisions: z.array(DecisionKind).nonempty(),
+    expiresAt: Timestamp.optional(),
+    /**
+     * 이 요청이 Agent의 상신에서 왔다면 그 근거 (C-13 §2).
+     *
+     * optional인 이유: Monitor packet 경로(외부 사건 감지)는 escalation이 아니므로 이 값이
+     * 없다. 기존 요청 파일도 그대로 읽힌다.
+     */
+    escalation: z
+        .object({
+        escalationId: z.string().min(1),
+        predicates: z.array(z.string()).nonempty(),
+        evidenceRefs: z.array(z.string()).nonempty(),
+        affectedNodes: z.array(z.string()).default([]),
+        /** 지금 못 하는 작업 노드. 경계 영역(blockedScope)과 다른 축이다. */
+        blockedNodes: z.array(z.string()).nonempty(),
+        blockedScope: z.array(z.string()).default([]),
+        stillRunnableNodes: z.array(z.string()).default([]),
+        previousEscalationId: z.string().optional(),
+    })
+        .optional(),
+    decision: z
+        .object({
+        kind: DecisionKind,
+        actor: z.string().min(1), // Adapter가 인증한 actor
+        channel: z.string().min(1), // 'local' 등 — 채널 id는 Adapter가 정한다
+        revision: z.string().optional(), // "마지막 문장 빼고 승인" 류 수정본
+        decidedAt: Timestamp,
+    })
+        .optional(),
+    resultRef: z.string().optional(), // 외부 반영 결과 (comment URL 등)
+});
+/**
+ * 채널 무관 결정 DTO. 모든 채널이 동일 requestId를 쓰며, 최초 유효 Decision 이후의
+ * 입력은 CAS 실패로 거절된다 (C-01 §7~8).
+ */
+export const ApprovalDecision = z.object({
+    requestId: RequestId,
+    expectedVersion: Version,
+    kind: DecisionKind,
+    actor: z.string().min(1),
+    channel: z.string().min(1),
+    revision: z.string().optional(),
+    decidedAt: Timestamp,
+});
+// ── ExecutionGrant ──────────────────────────────────────────────────────────
+/** Grant lifecycle (OM §11.5). 성공한 Grant는 재소비 불가 — replay guard의 근간. */
+export const GrantStatus = z.enum(['READY', 'CLAIMED', 'EXECUTED', 'INVALIDATED', 'EXPIRED']);
+/**
+ * Policy hierarchy의 하위 override가 아니라, Controller가 hierarchy 밖에서 생성하는
+ * one-shot execution contract (OM §5.2). Session 권한은 그대로 두고 별도 Executor에게만
+ * 단일 Action을 허용한다.
+ */
+export const ExecutionGrant = z.object({
+    id: GrantId,
+    version: Version,
+    requestId: RequestId,
+    status: GrantStatus,
+    issuedBy: z.string().min(1),
+    issuedAt: Timestamp,
+    expiresAt: Timestamp.optional(),
+    singleUse: z.boolean().default(true),
+    action: z.string().min(1), // '<adapter>.<행위>' 형태의 행위 키 — Adapter가 해석한다
+    target: z.string().min(1), // 대상 참조. 문법은 Adapter가 정한다
+    payload: z.string(), // 승인된 내용 그대로. Executor가 재작성하지 않는다
+    /** 게시 직전 Drift Guard가 대조할 기준 (OM §11.9). */
+    snapshot: z.array(CanonicalSnapshot).default([]),
+    threadLastEventId: z.string().optional(),
+    allowedWrites: z.array(z.string()).default([]), // 명시된 것 외 모든 write 금지
+    claimedBy: z.string().optional(),
+    consumedAt: Timestamp.optional(),
+    resultRef: z.string().optional(),
+});
+// ── QueueItem / MonitorEvent / State ────────────────────────────────────────
+export const QueueState = z.enum(['READY', 'ACTIVE', 'BLOCKED', 'DONE']);
+/** 승인되어 수행하기로 한 작업 (OM §4.8). inbox = 판단 대기, queue = 승인된 작업. */
+export const QueueItem = z.object({
+    id: QueueItemId,
+    version: Version,
+    state: QueueState,
+    title: z.string().min(1),
+    sourceRequestId: RequestId.optional(),
+    blockId: BlockId.optional(),
+    sessionId: SessionId.optional(),
+});
+/** Phase B 처리 결과 — 부분 실패해도 cursor는 전진하고 실패분만 재시도한다 (OM §10.5). */
+export const EventProcessing = z.enum(['LOGGED', 'PROCESSED', 'PENDING_RETRY']);
+export const MonitorEvent = z.object({
+    eventKey: EventKey,
+    version: Version,
+    detectedAt: Timestamp,
+    type: EventType,
+    suggestedPriority: Priority,
+    processing: EventProcessing,
+    inboxCandidate: z.boolean(),
+    requestId: RequestId.optional(), // Phase B가 패킷을 만든 경우
+    /**
+     * 관련성 판정과 그 근거 (C-07 §3). 숫자가 아니라 문장을 남기는 이유는, 판정이 틀렸을 때
+     * 사람이 어디가 틀렸는지 보고 뒤집을 수 있어야 하기 때문이다.
+     * optional이라 기존 event 파일이 그대로 읽힌다.
+     */
+    relevance: z
+        .object({
+        explicit: z.enum(['HIGH', 'LOW']),
+        actual: z.enum(['HIGH', 'LOW']),
+        disposition: z.enum(['INBOX', 'SHADOW']),
+        evidence: z.array(z.string()).default([]),
+    })
+        .optional(),
+    /**
+     * 조사를 다시 하려면 원본이 있어야 한다. cursor는 이미 지나갔고 provider가 같은 것을
+     * 또 주리라는 보장이 없으므로, 재시도에 필요한 만큼을 여기 남긴다 (OM §10.5).
+     */
+    replay: z
+        .object({
+        reference: z.string().min(1),
+        raw: z.unknown().optional(),
+        hints: z.record(z.unknown()).optional(),
+        /**
+         * 이미 끝난 조사 단계 (C-07 §6.3). 재시도가 처음부터 다시 하면 비싼 단계에서
+         * 실패한 사건은 영영 넘지 못한다.
+         */
+        steps: z
+            .array(z.object({
+            id: z.string().min(1),
+            kind: z.enum(['DONE', 'UNDECIDABLE', 'SKIPPED']),
+            findings: z.array(z.string()).default([]),
+            detail: z.string().optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+});
+/**
+ * Controller single-writer 상태 문서 (OM §7.2). Monitoring 절에는 포인터만 두고
+ * 갱신자 없는 숫자·시각을 두지 않는다.
+ */
+export const ControlState = z.object({
+    version: Version,
+    activeBlock: BlockId.optional(),
+    activeSessions: z.array(SessionId).default([]),
+    recentHandoff: SessionId.optional(),
+    writeBoundaryOccupancy: z.array(z.object({ sessionId: SessionId, paths: z.array(z.string()) })).default([]),
+    awaitingController: z.array(z.string()).default([]),
+    controllerAttention: z.array(z.string()).default([]),
+});

package/dist/core/model/ids.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/** REQ-0042 — 전 채널(MM/Local/Web)이 공유하는 ApprovalRequest identity. */
+export declare const RequestId: z.ZodString;
+/** G-0007 — Execution Grant. */
+export declare const GrantId: z.ZodString;
+/** S-20260822-01 — Logical Session (날짜 + 당일 순번). */
+export declare const SessionId: z.ZodString;
+/** B-05 — Block. */
+export declare const BlockId: z.ZodString;
+/**
+ * X-20260826-04 — Bounded Query (날짜 + 당일 순번). 세션 id와 같은 모양으로 읽힌다.
+ * 정규식을 따로 내보내는 이유: 이 id는 entity가 아니라 Adapter scope의 키가 되므로
+ * (C-04 §0.1) 파일명 변환 전에 문법을 확인하는 자리가 zod 밖에도 필요하다.
+ */
+export declare const QUERY_ID: RegExp;
+export declare const QueryId: z.ZodString;
+/** Q-0003 — Queue item. */
+export declare const QueueItemId: z.ZodString;
+/**
+ * Monitor event key — dedupe는 log tail 대조가 아니라 이 key의 exact lookup으로 한다
+ * (OM §10.4). 문법은 `<kind>:<opaque>` 이며 **kind는 adapter가 정한다** (C-07 §9).
+ *
+ * 처음에는 provider 4종(notification·comment·review·review_comment)을 열거했는데, 그러면
+ * 새 adapter의 키도 회수 경로가 만든 키도 통과하지 못한다 — Core가 provider의 사건 어휘를
+ * 아는 셈이기도 하다. 요구는 둘뿐이다: **같은 외부 변화는 같은 키, 다른 변화는 다른 키.**
+ * 기존 4종은 이 문법 안에 그대로 든다.
+ *
+ * kind를 소문자 토큰으로 좁히는 이유는 Markdown Adapter의 파일명 변환 때문이다 —
+ * 대소문자만 다른 키가 같은 파일이 되면 dedupe가 조용히 오판한다.
+ */
+export declare const EVENT_KEY: RegExp;
+export declare const EventKey: z.ZodString;
+/**
+ * entity 낙관적 동시성 토큰. 결정·전이는 expectedVersion CAS로만 수행한다 (C-01 §8).
+ * 단조 증가 정수 — 전이 1회당 +1.
+ */
+export declare const Version: z.ZodNumber;
+/** ISO8601 시각 문자열. */
+export declare const Timestamp: z.ZodString;
+/** `REQ-0042` → `REQ-0043`. 순번 폭이 넘치면 자리수를 늘린다. */
+export declare function nextId(prefix: string, existing: readonly string[], width?: number): string;

package/dist/core/model/ids.js

@@ -0,0 +1,50 @@
+// ASC의 모든 Logical Entity가 쓰는 식별자 형식을 한곳에 고정하는 파일.
+// 정본: docs/contracts/C-01_approval-port.md §1 (Core identity = request_id,
+// 파일명·채널 표시는 전부 projection), §14 (exact 형식은 구현 단계 확정 — 여기가 그 지점).
+import { z } from 'zod';
+/** REQ-0042 — 전 채널(MM/Local/Web)이 공유하는 ApprovalRequest identity. */
+export const RequestId = z.string().regex(/^REQ-\d{4,}$/);
+/** G-0007 — Execution Grant. */
+export const GrantId = z.string().regex(/^G-\d{4,}$/);
+/** S-20260822-01 — Logical Session (날짜 + 당일 순번). */
+export const SessionId = z.string().regex(/^S-\d{8}-\d{2}$/);
+/** B-05 — Block. */
+export const BlockId = z.string().regex(/^B-\d{2,}$/);
+/**
+ * X-20260826-04 — Bounded Query (날짜 + 당일 순번). 세션 id와 같은 모양으로 읽힌다.
+ * 정규식을 따로 내보내는 이유: 이 id는 entity가 아니라 Adapter scope의 키가 되므로
+ * (C-04 §0.1) 파일명 변환 전에 문법을 확인하는 자리가 zod 밖에도 필요하다.
+ */
+export const QUERY_ID = /^X-\d{8}-\d{2}$/;
+export const QueryId = z.string().regex(QUERY_ID);
+/** Q-0003 — Queue item. */
+export const QueueItemId = z.string().regex(/^Q-\d{4,}$/);
+/**
+ * Monitor event key — dedupe는 log tail 대조가 아니라 이 key의 exact lookup으로 한다
+ * (OM §10.4). 문법은 `<kind>:<opaque>` 이며 **kind는 adapter가 정한다** (C-07 §9).
+ *
+ * 처음에는 provider 4종(notification·comment·review·review_comment)을 열거했는데, 그러면
+ * 새 adapter의 키도 회수 경로가 만든 키도 통과하지 못한다 — Core가 provider의 사건 어휘를
+ * 아는 셈이기도 하다. 요구는 둘뿐이다: **같은 외부 변화는 같은 키, 다른 변화는 다른 키.**
+ * 기존 4종은 이 문법 안에 그대로 든다.
+ *
+ * kind를 소문자 토큰으로 좁히는 이유는 Markdown Adapter의 파일명 변환 때문이다 —
+ * 대소문자만 다른 키가 같은 파일이 되면 dedupe가 조용히 오판한다.
+ */
+export const EVENT_KEY = /^[a-z][a-z0-9_-]*:.+$/;
+export const EventKey = z.string().regex(EVENT_KEY);
+/**
+ * entity 낙관적 동시성 토큰. 결정·전이는 expectedVersion CAS로만 수행한다 (C-01 §8).
+ * 단조 증가 정수 — 전이 1회당 +1.
+ */
+export const Version = z.number().int().nonnegative();
+/** ISO8601 시각 문자열. */
+export const Timestamp = z.string().datetime({ offset: true });
+const counterOf = (id) => Number(id.slice(id.lastIndexOf('-') + 1));
+/** `REQ-0042` → `REQ-0043`. 순번 폭이 넘치면 자리수를 늘린다. */
+export function nextId(prefix, existing, width = 4) {
+    const max = existing
+        .filter((id) => id.startsWith(`${prefix}-`))
+        .reduce((acc, id) => Math.max(acc, counterOf(id) || 0), 0);
+    return `${prefix}-${String(max + 1).padStart(width, '0')}`;
+}

package/dist/core/model/transitions.d.ts

@@ -0,0 +1,26 @@
+import type { ActorRole, ApprovalRequest, ExecutionGrant, MonitorEvent, QueueItem, Session } from './entities.ts';
+export type TransitionRule<S extends string> = {
+    from: S;
+    to: S;
+    /** 이 전이를 수행할 수 있는 주체. 비어 있는 전이는 만들지 않는다. */
+    actors: readonly ActorRole[];
+    /** 전이 성립에 필요한 부가 조건의 이름 — 래퍼가 실제 값 존재를 확인한다. */
+    requires?: 'checkpoint' | 'handoff' | 'decision' | 'result';
+};
+export type TransitionFailure = 'ILLEGAL_TRANSITION' | 'FORBIDDEN_ACTOR' | 'MISSING_REQUIREMENT';
+export declare class TransitionError extends Error {
+    readonly reason: TransitionFailure;
+    constructor(reason: TransitionFailure, message: string);
+}
+/** 전이표에서 terminal 상태(나가는 전이가 없는 상태) 목록. */
+export declare function terminalStates<S extends string>(table: readonly TransitionRule<S>[], all: readonly S[]): S[];
+export declare const SESSION_TRANSITIONS: readonly TransitionRule<Session['status']>[];
+export declare function transitionSession(session: Session, to: Session['status'], actor: ActorRole, patch?: Partial<Pick<Session, 'checkpoint' | 'handoff'>>): Session;
+export declare const REQUEST_TRANSITIONS: readonly TransitionRule<ApprovalRequest['status']>[];
+export declare function transitionRequest(request: ApprovalRequest, to: ApprovalRequest['status'], actor: ActorRole, patch?: Partial<Pick<ApprovalRequest, 'decision' | 'resultRef'>>): ApprovalRequest;
+export declare const GRANT_TRANSITIONS: readonly TransitionRule<ExecutionGrant['status']>[];
+export declare function transitionGrant(grant: ExecutionGrant, to: ExecutionGrant['status'], actor: ActorRole, patch?: Partial<Pick<ExecutionGrant, 'claimedBy' | 'consumedAt' | 'resultRef'>>): ExecutionGrant;
+export declare const QUEUE_TRANSITIONS: readonly TransitionRule<QueueItem['state']>[];
+export declare function transitionQueueItem(item: QueueItem, to: QueueItem['state'], actor: ActorRole, patch?: Partial<Pick<QueueItem, 'sessionId' | 'blockId'>>): QueueItem;
+export declare const EVENT_TRANSITIONS: readonly TransitionRule<MonitorEvent['processing']>[];
+export declare function transitionEvent(event: MonitorEvent, to: MonitorEvent['processing'], actor: ActorRole, patch?: Partial<Pick<MonitorEvent, 'requestId'>>): MonitorEvent;

package/dist/core/model/transitions.js

@@ -0,0 +1,124 @@
+// Entity 상태머신 — 어떤 전이가 가능하고 누가 수행할 수 있는지를 데이터로 선언한다.
+// 전이표가 설계 정본(OM §6.2 Session / §11.2 Inbox / §11.5·§11.9 Grant / §10.5 Monitor)과
+// 1:1 대응하는지는 tests/model.test.ts가 검증한다.
+// 저장·동시성은 여기 없다 — 순수 함수로 다음 상태를 계산할 뿐이고, 실제 CAS는
+// State Store Port가 수행한다 (OM §7.0·§7.2).
+export class TransitionError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'TransitionError';
+        this.reason = reason;
+    }
+}
+function resolve(table, from, to, actor) {
+    const candidates = table.filter((r) => r.from === from && r.to === to);
+    if (candidates.length === 0) {
+        throw new TransitionError('ILLEGAL_TRANSITION', `${from} → ${to} is not a legal transition`);
+    }
+    const allowed = candidates.find((r) => r.actors.includes(actor));
+    if (!allowed) {
+        throw new TransitionError('FORBIDDEN_ACTOR', `${actor} may not perform ${from} → ${to}`);
+    }
+    return allowed;
+}
+/** 전이표에서 terminal 상태(나가는 전이가 없는 상태) 목록. */
+export function terminalStates(table, all) {
+    return all.filter((s) => !table.some((r) => r.from === s));
+}
+// ── Session (OM §6.2) ───────────────────────────────────────────────────────
+// Logical Session은 여러 Physical Run에 걸친다. PAUSED는 Checkpoint 없이 만들 수 없고,
+// DONE은 Handoff 없이 만들 수 없다 — 인수인계 누락을 상태머신이 막는다.
+export const SESSION_TRANSITIONS = [
+    { from: 'READY', to: 'ACTIVE', actors: ['session', 'controller'] },
+    { from: 'ACTIVE', to: 'PAUSED', actors: ['session'], requires: 'checkpoint' },
+    { from: 'ACTIVE', to: 'BLOCKED', actors: ['session'] },
+    { from: 'ACTIVE', to: 'DONE', actors: ['session'], requires: 'handoff' },
+    { from: 'ACTIVE', to: 'FAILED', actors: ['session', 'controller'] },
+    { from: 'PAUSED', to: 'ACTIVE', actors: ['session', 'controller'] },
+    { from: 'PAUSED', to: 'FAILED', actors: ['controller'] },
+    { from: 'BLOCKED', to: 'ACTIVE', actors: ['controller'] },
+    { from: 'BLOCKED', to: 'FAILED', actors: ['controller'] },
+];
+export function transitionSession(session, to, actor, patch = {}) {
+    const rule = resolve(SESSION_TRANSITIONS, session.status, to, actor);
+    const next = { ...session, ...patch, status: to, version: session.version + 1 };
+    if (rule.requires === 'checkpoint' && !next.checkpoint) {
+        throw new TransitionError('MISSING_REQUIREMENT', `${session.id}: PAUSED requires a checkpoint`);
+    }
+    if (rule.requires === 'handoff' && !next.handoff) {
+        throw new TransitionError('MISSING_REQUIREMENT', `${session.id}: DONE requires a handoff`);
+    }
+    return next;
+}
+// ── ApprovalRequest (OM §11.2) ──────────────────────────────────────────────
+// AWAITING_APPROVAL은 Monitor만 만들고(생성 시점), 처분은 Controller 전용,
+// DONE 전환은 Grant를 수행한 Executor만 한다. APPROVED는 승인 상태일 뿐
+// 외부 write 권한이 아니다 — 실제 write는 ExecutionGrant에만 있다.
+export const REQUEST_TRANSITIONS = [
+    { from: 'AWAITING_APPROVAL', to: 'APPROVED', actors: ['controller'], requires: 'decision' },
+    { from: 'AWAITING_APPROVAL', to: 'QUEUED', actors: ['controller'], requires: 'decision' },
+    { from: 'AWAITING_APPROVAL', to: 'DEFERRED', actors: ['controller'], requires: 'decision' },
+    { from: 'AWAITING_APPROVAL', to: 'DISMISSED', actors: ['controller'], requires: 'decision' },
+    { from: 'DEFERRED', to: 'APPROVED', actors: ['controller'], requires: 'decision' },
+    { from: 'DEFERRED', to: 'QUEUED', actors: ['controller'], requires: 'decision' },
+    { from: 'DEFERRED', to: 'DISMISSED', actors: ['controller'], requires: 'decision' },
+    { from: 'APPROVED', to: 'DONE', actors: ['executor'], requires: 'result' },
+];
+export function transitionRequest(request, to, actor, patch = {}) {
+    const rule = resolve(REQUEST_TRANSITIONS, request.status, to, actor);
+    const next = { ...request, ...patch, status: to, version: request.version + 1 };
+    if (rule.requires === 'decision' && !next.decision) {
+        throw new TransitionError('MISSING_REQUIREMENT', `${request.id}: ${to} requires a recorded decision`);
+    }
+    if (rule.requires === 'result' && !next.resultRef) {
+        throw new TransitionError('MISSING_REQUIREMENT', `${request.id}: DONE requires a result reference`);
+    }
+    return next;
+}
+// ── ExecutionGrant (OM §11.5·§11.9) ─────────────────────────────────────────
+// 성공한 Grant는 재소비 불가(EXECUTED terminal). CLAIMED에서도 게시 직전 Drift Guard가
+// 대상 변화를 발견하면 INVALIDATED로 끝난다 — 오래된 초안이 나가지 않게 하는 마지막 장치.
+export const GRANT_TRANSITIONS = [
+    { from: 'READY', to: 'CLAIMED', actors: ['executor'] },
+    { from: 'READY', to: 'INVALIDATED', actors: ['controller', 'executor'] },
+    { from: 'READY', to: 'EXPIRED', actors: ['controller', 'executor'] },
+    { from: 'CLAIMED', to: 'EXECUTED', actors: ['executor'], requires: 'result' },
+    // CLAIM 이후의 무효화는 Drift Guard를 돌린 Executor만 한다 (OM §11.9). 정본에 Controller가
+    // 진행 중인 Grant를 가로채는 경로가 없고, 실행 직전 상태 판단은 Executor 손에 있다.
+    { from: 'CLAIMED', to: 'INVALIDATED', actors: ['executor'] },
+];
+export function transitionGrant(grant, to, actor, patch = {}) {
+    const rule = resolve(GRANT_TRANSITIONS, grant.status, to, actor);
+    const next = { ...grant, ...patch, status: to, version: grant.version + 1 };
+    if (rule.requires === 'result' && !next.resultRef) {
+        throw new TransitionError('MISSING_REQUIREMENT', `${grant.id}: EXECUTED requires a result reference`);
+    }
+    return next;
+}
+// ── QueueItem (OM §4.8) — Controller ONLY ───────────────────────────────────
+export const QUEUE_TRANSITIONS = [
+    { from: 'READY', to: 'ACTIVE', actors: ['controller'] },
+    { from: 'READY', to: 'BLOCKED', actors: ['controller'] },
+    { from: 'ACTIVE', to: 'BLOCKED', actors: ['controller'] },
+    { from: 'ACTIVE', to: 'DONE', actors: ['controller'] },
+    { from: 'BLOCKED', to: 'READY', actors: ['controller'] },
+    { from: 'BLOCKED', to: 'ACTIVE', actors: ['controller'] },
+];
+export function transitionQueueItem(item, to, actor, patch = {}) {
+    resolve(QUEUE_TRANSITIONS, item.state, to, actor);
+    return { ...item, ...patch, state: to, version: item.version + 1 };
+}
+// ── MonitorEvent (OM §10.5) ─────────────────────────────────────────────────
+// Phase B 실패는 그 이벤트만 PENDING_RETRY로 남는다 — cursor는 전진하고 다음 Run이
+// 실패분만 재시도한다.
+export const EVENT_TRANSITIONS = [
+    { from: 'LOGGED', to: 'PROCESSED', actors: ['monitor'] },
+    { from: 'LOGGED', to: 'PENDING_RETRY', actors: ['monitor'] },
+    { from: 'PENDING_RETRY', to: 'PROCESSED', actors: ['monitor'] },
+    { from: 'PENDING_RETRY', to: 'PENDING_RETRY', actors: ['monitor'] },
+];
+export function transitionEvent(event, to, actor, patch = {}) {
+    resolve(EVENT_TRANSITIONS, event.processing, to, actor);
+    return { ...event, ...patch, processing: to, version: event.version + 1 };
+}

package/dist/core/monitor/coverage.d.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import type { InventoryItem } from '../../ports/inventory.ts';
+import type { ScopedStore } from '../../ports/state-store.ts';
+export declare const CoverageRecord: z.ZodObject<{
+    reference: z.ZodString;
+    state: z.ZodString;
+    revisionMarker: z.ZodString;
+    updatedAt: z.ZodString;
+    /** 마지막으로 목록에서 본 시각. missing 판정의 기준이 된다. */
+    seenAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reference: string;
+    state: string;
+    revisionMarker: string;
+    updatedAt: string;
+    seenAt: string;
+}, {
+    reference: string;
+    state: string;
+    revisionMarker: string;
+    updatedAt: string;
+    seenAt: string;
+}>;
+export type CoverageRecord = z.infer<typeof CoverageRecord>;
+/**
+ * 지금까지 어디까지 확인했는가 (C-07 §8.2). **100% 보장을 대신하는 값이 아니라, 무엇을
+ * 확인했고 무엇을 모르는지 사람이 볼 수 있게 하는 값이다.**
+ */
+export declare const CoverageHealth: z.ZodObject<{
+    lastHotEventAt: z.ZodOptional<z.ZodString>;
+    lastReconcileAt: z.ZodOptional<z.ZodString>;
+    lastCensusAt: z.ZodOptional<z.ZodString>;
+    /** 이 시각까지의 변경은 회수했다고 보는 기준선. */
+    coverageWatermark: z.ZodOptional<z.ZodString>;
+    /**
+     * 마지막 열거가 목록을 빠짐없이 훑었는가. **모르면 false다** — 이 값이 false인 열거로
+     * missing을 판정하면 없는 상실을 만들어낸다.
+     */
+    paginationComplete: z.ZodDefault<z.ZodBoolean>;
+    sourceHealthy: z.ZodDefault<z.ZodBoolean>;
+    /** 마지막 실패 이유. 상태만 주면 고칠 수가 없다. */
+    detail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    paginationComplete: boolean;
+    sourceHealthy: boolean;
+    detail?: string | undefined;
+    lastHotEventAt?: string | undefined;
+    lastReconcileAt?: string | undefined;
+    lastCensusAt?: string | undefined;
+    coverageWatermark?: string | undefined;
+}, {
+    detail?: string | undefined;
+    lastHotEventAt?: string | undefined;
+    lastReconcileAt?: string | undefined;
+    lastCensusAt?: string | undefined;
+    coverageWatermark?: string | undefined;
+    paginationComplete?: boolean | undefined;
+    sourceHealthy?: boolean | undefined;
+}>;
+export type CoverageHealth = z.infer<typeof CoverageHealth>;
+export type SweepKind = 'reconcile' | 'census';
+export type CoverageDiff = 
+/** 처음 보는 리소스. */
+{
+    kind: 'NEW';
+    item: InventoryItem;
+}
+/** 지난번과 달라졌다. */
+ | {
+    kind: 'CHANGED';
+    item: InventoryItem;
+    previous: CoverageRecord;
+}
+/**
+ * 알고 있었는데 이번 목록에 없다. **원인을 추측하지 않는다** (C-07 §1.5) —
+ * 삭제일 수도, 권한·가시성 변화일 수도, filter나 provider 오류일 수도 있다.
+ */
+ | {
+    kind: 'RESOURCE_MISSING';
+    reference: string;
+    previous: CoverageRecord;
+};
+export declare class CoverageLedger {
+    #private;
+    constructor(scope: ScopedStore, now?: () => string);
+    get(reference: string): Promise<CoverageRecord | null>;
+    list(): Promise<CoverageRecord[]>;
+    /** 이번에 본 모습을 남긴다. 빠른 경로도 이걸 갱신해야 회수 경로가 같은 것을 또 올리지 않는다. */
+    record(item: {
+        reference: string;
+        state?: string;
+        revisionMarker: string;
+        updatedAt?: string;
+    }): Promise<void>;
+    /** 이번 목록과 지난 기록을 견준다. 달라진 것만 돌려준다. */
+    diff(items: readonly InventoryItem[]): Promise<CoverageDiff[]>;
+    /**
+     * 알던 것 중 이번 목록에 없는 것.
+     *
+     * **빠짐없이 훑은 열거에서만 판정한다.** 페이지를 다 돌지 못한 목록으로 비교하면
+     * 멀쩡한 리소스가 사라졌다고 나온다.
+     */
+    missing(seen: ReadonlySet<string>, paginationComplete: boolean): Promise<CoverageDiff[]>;
+    health(): Promise<CoverageHealth>;
+    updateHealth(patch: Partial<CoverageHealth>): Promise<CoverageHealth>;
+}
+/**
+ * 사람이 읽는 상태. **"100% 감지 보장"이라고 쓰지 않는다** (C-07 §8.1) — provider 장애·자격
+ * 문제·전달 실패·가시성 변화 중 어느 것도 ASC가 통제하지 못한다.
+ */
+export declare function renderHealth(sourceId: string, health: CoverageHealth): string[];