@asc-agent/runtime 0.1.0

package/dist/core/runtime/escalation.d.ts

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import type { ScopedStore } from '../../ports/state-store.ts';
+/**
+ * 올릴 자격이 되는 사유 (C-13 §1.1). **이 목록 밖으로는 올리지 않는다.**
+ *
+ * 불확실성(uncertain·multiple_options·want_confirmation 계열)은 여기 없다. 그것은
+ * 경계가 아니라 상태이며, 올려 봐야 사람은 Agent보다 적은 근거로 결정하게 된다.
+ */
+export declare const EscalationPredicate: z.ZodEnum<["ownership_boundary", "shared_contract_change", "acceptance_change", "secret_or_permission", "irreversible_action", "explicit_rule_requires_approval", "canonical_conflict"]>;
+export type EscalationPredicate = z.infer<typeof EscalationPredicate>;
+export declare const ESCALATION_ID: RegExp;
+export declare const EscalationRecord: z.ZodObject<{
+    escalationId: z.ZodString;
+    sessionId: z.ZodString;
+    /** 올린 주체. 누가 올렸는지 모르는 상신은 감사 대상이 아니다. */
+    openedBy: z.ZodString;
+    predicates: z.ZodArray<z.ZodEnum<["ownership_boundary", "shared_contract_change", "acceptance_change", "secret_or_permission", "irreversible_action", "explicit_rule_requires_approval", "canonical_conflict"]>, "atleastone">;
+    /** 사람이 답할 한 문장. */
+    question: z.ZodString;
+    /** 근거 없는 상신은 상신이 아니다. */
+    evidenceRefs: z.ZodArray<z.ZodString, "atleastone">;
+    affectedNodes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * 이것 때문에 **지금 못 하는 작업 노드** (Done Criteria 항목).
+     * 경계 영역(blockedScope)과 다른 축이다 (C-13 §2.1).
+     */
+    blockedNodes: z.ZodArray<z.ZodString, "atleastone">;
+    /** 경계의 실체 — 경로·영역 범위. 노드 목록이 아니다. */
+    blockedScope: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** 계속 갈 수 있는 노드. **자동 계산이며 올리는 쪽이 적지 않는다** (불변식 ③). */
+    stillRunnableNodes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    boundaryFingerprint: z.ZodString;
+    previousEscalationId: z.ZodOptional<z.ZodString>;
+    whyPreviousDecisionDoesNotCoverThis: z.ZodOptional<z.ZodString>;
+    /** 이 상신으로 만들어진 ApprovalRequest. 결정은 기존 inbox 경로가 한다. */
+    requestId: z.ZodString;
+    openedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    evidenceRefs: [string, ...string[]];
+    escalationId: string;
+    predicates: ["ownership_boundary" | "shared_contract_change" | "acceptance_change" | "secret_or_permission" | "irreversible_action" | "explicit_rule_requires_approval" | "canonical_conflict", ...("ownership_boundary" | "shared_contract_change" | "acceptance_change" | "secret_or_permission" | "irreversible_action" | "explicit_rule_requires_approval" | "canonical_conflict")[]];
+    affectedNodes: string[];
+    blockedNodes: [string, ...string[]];
+    blockedScope: string[];
+    stillRunnableNodes: string[];
+    requestId: string;
+    sessionId: string;
+    openedBy: string;
+    question: string;
+    boundaryFingerprint: string;
+    openedAt: string;
+    previousEscalationId?: string | undefined;
+    whyPreviousDecisionDoesNotCoverThis?: string | undefined;
+}, {
+    evidenceRefs: [string, ...string[]];
+    escalationId: string;
+    predicates: ["ownership_boundary" | "shared_contract_change" | "acceptance_change" | "secret_or_permission" | "irreversible_action" | "explicit_rule_requires_approval" | "canonical_conflict", ...("ownership_boundary" | "shared_contract_change" | "acceptance_change" | "secret_or_permission" | "irreversible_action" | "explicit_rule_requires_approval" | "canonical_conflict")[]];
+    blockedNodes: [string, ...string[]];
+    requestId: string;
+    sessionId: string;
+    openedBy: string;
+    question: string;
+    boundaryFingerprint: string;
+    openedAt: string;
+    affectedNodes?: string[] | undefined;
+    blockedScope?: string[] | undefined;
+    stillRunnableNodes?: string[] | undefined;
+    previousEscalationId?: string | undefined;
+    whyPreviousDecisionDoesNotCoverThis?: string | undefined;
+}>;
+export type EscalationRecord = z.infer<typeof EscalationRecord>;
+/** 막힌 상신. 무엇을 올리려 했는지가 남아야 Gate를 검증할 수 있다. */
+export declare const RejectedEscalation: z.ZodObject<{
+    sessionId: z.ZodString;
+    openedBy: z.ZodString;
+    question: z.ZodString;
+    /** 올린 쪽이 사유라고 적은 것. predicate가 아니어서 막혔다. */
+    claimedReasons: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    reason: z.ZodEnum<["APPROVAL_NOT_JUSTIFIED", "DUPLICATE_EPISODE", "RESUBMIT_NOT_JUSTIFIED"]>;
+    detail: z.ZodString;
+    at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    sessionId: string;
+    detail: string;
+    reason: "APPROVAL_NOT_JUSTIFIED" | "DUPLICATE_EPISODE" | "RESUBMIT_NOT_JUSTIFIED";
+    openedBy: string;
+    question: string;
+    claimedReasons: string[];
+}, {
+    at: string;
+    sessionId: string;
+    detail: string;
+    reason: "APPROVAL_NOT_JUSTIFIED" | "DUPLICATE_EPISODE" | "RESUBMIT_NOT_JUSTIFIED";
+    openedBy: string;
+    question: string;
+    claimedReasons?: string[] | undefined;
+}>;
+export type RejectedEscalation = z.infer<typeof RejectedEscalation>;
+export type OpenInput = {
+    escalationId: string;
+    sessionId: string;
+    openedBy: string;
+    /** 자유 문자열로 받는다 — 유효하지 않은 사유도 **무엇을 적었는지 남기기 위해** 받는다. */
+    predicates: readonly string[];
+    question: string;
+    evidenceRefs?: readonly string[];
+    affectedNodes?: readonly string[];
+    blockedNodes: readonly string[];
+    blockedScope?: readonly string[];
+    /** 이 세션의 완료 조건 전부. stillRunnableNodes를 여기서 뺀다. */
+    doneCriteria?: readonly string[];
+    previousEscalationId?: string;
+    whyPreviousDecisionDoesNotCoverThis?: string;
+    openedAt?: string;
+};
+export type OpenOutcome = {
+    ok: true;
+    record: EscalationRecord;
+} | {
+    ok: false;
+    reason: 'APPROVAL_NOT_JUSTIFIED' | 'DUPLICATE_EPISODE' | 'RESUBMIT_NOT_JUSTIFIED' | 'INVALID_INPUT';
+    detail: string;
+    /** 이미 열려 있는 같은 경계. 사람이 그것을 보면 된다. */
+    existing?: EscalationRecord;
+};
+export type ResolveOutcome = {
+    ok: true;
+    record: EscalationRecord;
+} | {
+    ok: false;
+    reason: 'NOT_FOUND' | 'ALREADY_RESOLVED';
+    detail: string;
+};
+/**
+ * 같은 경계인가 (C-13 §5).
+ *
+ * **evidence는 넣지 않는다** (불변식 ⑦). 넣으면 근거 한 줄만 더 붙여 같은 질문을 다시
+ * 올릴 수 있고, 그게 정확히 Approval Budget이 막으려는 것이다.
+ */
+export declare function boundaryFingerprint(input: {
+    predicates: readonly string[];
+    blockedNodes: readonly string[];
+    blockedScope?: readonly string[];
+}): string;
+export declare class EscalationLedger {
+    #private;
+    constructor(scope: ScopedStore, now?: () => string);
+    /**
+     * 상신을 연다 — **이 함수가 Gate다.**
+     *
+     * 통과하면 record를 남기고 호출자가 ApprovalRequest를 만든다. 막히면 request는
+     * 만들어지지 않고 막힌 사실이 남는다.
+     */
+    open(input: OpenInput): Promise<OpenOutcome>;
+    /** 만들어진 ApprovalRequest를 잇는다. record는 이미 확정됐고 참조만 채운다. */
+    attachRequest(escalationId: string, requestId: string): Promise<boolean>;
+    /**
+     * 사람이 결정해 닫혔다. **여기서 결정을 대신하지 않는다** — 결정은 기존 Approval
+     * 경로에서 일어나고, 이 마커는 "그 결정이 이 경계를 덮었다"는 사실만 남긴다.
+     */
+    resolve(escalationId: string, decidedBy: string, decisionRef: string, at?: string): Promise<ResolveOutcome>;
+    /** 아직 사람이 결정하지 않은 상신. 이것이 곧 "무엇을 기다리는가"다. */
+    pending(): Promise<EscalationRecord[]>;
+    all(): Promise<EscalationRecord[]>;
+    get(escalationId: string): Promise<EscalationRecord | null>;
+    /** 막힌 상신들. Gate가 실제로 무엇을 막았는지 사람이 볼 수 있어야 한다. */
+    rejected(): Promise<RejectedEscalation[]>;
+}
+/**
+ * 지금 무엇이 막혔고 무엇이 갈 수 있는가 (C-13 §6).
+ *
+ * **입력은 상신 기록뿐이다.** Checkpoint.blockers 같은 서술 문자열을 읽지 않는다
+ * (불변식 ⑤) — 문구를 바꾸는 것이 곧 권한 변경이 되면 안 된다.
+ *
+ * 결과는 `deriveExecutionState`(C-10 §7)가 그대로 소비한다. 새 상태 enum도, 새 그래프도
+ * 만들지 않는다: node는 Done Criteria 항목이고 막힌 것만 빠진다.
+ */
+export declare function proceedGateFacts(pending: readonly EscalationRecord[], doneCriteria: readonly string[]): {
+    waitingOn: string[];
+    conditions: string[];
+    runnable: string[];
+};
+/**
+ * 사람이 읽는 줄. **왜 이것이 Human Boundary인지가 먼저 온다** (C-13 §7).
+ * "어떻게 할까요"가 아니라 "이 경계라서 당신 몫이다"가 상신의 형태다.
+ */
+export declare function escalationLines(records: readonly EscalationRecord[]): string[];

package/dist/core/runtime/escalation.js

@@ -0,0 +1,322 @@
+// Escalation — 사람에게 올릴 자격이 있는가 (C-13).
+//
+// 지금까지 ASC에는 승인 통로가 다 있었는데 그 통로에 들어갈 자격 조건이 없었다.
+// 그래서 "확신이 안 서서" 올린 것과 "내 권한 밖이라" 올린 것이 같은 모양으로 도착했고,
+// 사람은 둘 다 읽어야 했다.
+//
+// 이 파일이 하는 일은 하나다: **자격 없는 상신을 ApprovalRequest 앞에서 막는다.**
+//
+//   predicate ≥ 1   → 기존 Approval 경로로 보낸다 (C-01 무수정, 결정 표면은 그대로)
+//   predicate 0     → 만들지 않는다. 그리고 **막았다는 사실을 남긴다**
+//
+// 마지막 줄이 중요하다. 조용히 거절하면 Gate가 제 일을 하는지 아무도 못 본다 —
+// Bounded Query가 막힌 시도를 violation으로 남기는 것과 같은 이유다 (C-04 §5.2).
+//
+// **판정 입력은 여기 적힌 구조뿐이다.** Checkpoint.blockers 같은 서술 문자열을 읽어
+// 자동 판정하지 않는다 (C-13 불변식 ⑤) — 문구를 바꾸는 것이 곧 권한 변경이 되면 안 된다.
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { SessionId } from "../model/ids.js";
+/**
+ * 올릴 자격이 되는 사유 (C-13 §1.1). **이 목록 밖으로는 올리지 않는다.**
+ *
+ * 불확실성(uncertain·multiple_options·want_confirmation 계열)은 여기 없다. 그것은
+ * 경계가 아니라 상태이며, 올려 봐야 사람은 Agent보다 적은 근거로 결정하게 된다.
+ */
+export const EscalationPredicate = z.enum([
+    'ownership_boundary',
+    'shared_contract_change',
+    'acceptance_change',
+    'secret_or_permission',
+    'irreversible_action',
+    'explicit_rule_requires_approval',
+    'canonical_conflict',
+]);
+export const ESCALATION_ID = /^ESC-\d{8}-\d{2}$/;
+export const EscalationRecord = z.object({
+    escalationId: z.string().regex(ESCALATION_ID),
+    sessionId: SessionId,
+    /** 올린 주체. 누가 올렸는지 모르는 상신은 감사 대상이 아니다. */
+    openedBy: z.string().min(1),
+    predicates: z.array(EscalationPredicate).nonempty(),
+    /** 사람이 답할 한 문장. */
+    question: z.string().min(1),
+    /** 근거 없는 상신은 상신이 아니다. */
+    evidenceRefs: z.array(z.string().min(1)).nonempty(),
+    affectedNodes: z.array(z.string()).default([]),
+    /**
+     * 이것 때문에 **지금 못 하는 작업 노드** (Done Criteria 항목).
+     * 경계 영역(blockedScope)과 다른 축이다 (C-13 §2.1).
+     */
+    blockedNodes: z.array(z.string().min(1)).nonempty(),
+    /** 경계의 실체 — 경로·영역 범위. 노드 목록이 아니다. */
+    blockedScope: z.array(z.string()).default([]),
+    /** 계속 갈 수 있는 노드. **자동 계산이며 올리는 쪽이 적지 않는다** (불변식 ③). */
+    stillRunnableNodes: z.array(z.string()).default([]),
+    boundaryFingerprint: z.string().min(1),
+    previousEscalationId: z.string().optional(),
+    whyPreviousDecisionDoesNotCoverThis: z.string().optional(),
+    /** 이 상신으로 만들어진 ApprovalRequest. 결정은 기존 inbox 경로가 한다. */
+    requestId: z.string().min(1),
+    openedAt: z.string().min(1),
+});
+/** 막힌 상신. 무엇을 올리려 했는지가 남아야 Gate를 검증할 수 있다. */
+export const RejectedEscalation = z.object({
+    sessionId: z.string().min(1),
+    openedBy: z.string().min(1),
+    question: z.string().min(1),
+    /** 올린 쪽이 사유라고 적은 것. predicate가 아니어서 막혔다. */
+    claimedReasons: z.array(z.string()).default([]),
+    reason: z.enum(['APPROVAL_NOT_JUSTIFIED', 'DUPLICATE_EPISODE', 'RESUBMIT_NOT_JUSTIFIED']),
+    detail: z.string().min(1),
+    at: z.string().min(1),
+});
+const recordKey = (id) => `escalation:rec:${id}`;
+const RECORD_PREFIX = 'escalation:rec:';
+const resolvedKey = (id) => `escalation:res:${id}`;
+const rejectedKey = (seq) => `escalation:vio:${String(seq).padStart(6, '0')}`;
+const REJECTED_PREFIX = 'escalation:vio:';
+/**
+ * 같은 경계인가 (C-13 §5).
+ *
+ * **evidence는 넣지 않는다** (불변식 ⑦). 넣으면 근거 한 줄만 더 붙여 같은 질문을 다시
+ * 올릴 수 있고, 그게 정확히 Approval Budget이 막으려는 것이다.
+ */
+export function boundaryFingerprint(input) {
+    const canonical = JSON.stringify({
+        predicates: [...input.predicates].sort(),
+        blockedNodes: [...input.blockedNodes].sort(),
+        blockedScope: [...(input.blockedScope ?? [])].sort(),
+    });
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+export class EscalationLedger {
+    #scope;
+    #now;
+    constructor(scope, now = () => new Date().toISOString()) {
+        this.#scope = scope;
+        this.#now = now;
+    }
+    /**
+     * 상신을 연다 — **이 함수가 Gate다.**
+     *
+     * 통과하면 record를 남기고 호출자가 ApprovalRequest를 만든다. 막히면 request는
+     * 만들어지지 않고 막힌 사실이 남는다.
+     */
+    async open(input) {
+        const at = input.openedAt ?? this.#now();
+        const valid = input.predicates.filter((candidate) => EscalationPredicate.safeParse(candidate).success);
+        if (valid.length === 0) {
+            // 불확실성은 경계가 아니다 (C-13 §1.2). 막되, 무엇을 올리려 했는지 남긴다.
+            const detail = input.predicates.length > 0
+                ? `올릴 자격이 되는 사유가 없다 (받은 사유: ${input.predicates.join(', ')})`
+                : '올릴 자격이 되는 사유가 하나도 없다';
+            await this.#reject(input, 'APPROVAL_NOT_JUSTIFIED', detail, at);
+            return { ok: false, reason: 'APPROVAL_NOT_JUSTIFIED', detail };
+        }
+        if (input.evidenceRefs === undefined || input.evidenceRefs.length === 0) {
+            const detail = '근거 없는 상신은 상신이 아니다 — evidence를 최소 하나 대라';
+            await this.#reject(input, 'APPROVAL_NOT_JUSTIFIED', detail, at);
+            return { ok: false, reason: 'APPROVAL_NOT_JUSTIFIED', detail };
+        }
+        if (input.blockedNodes.length === 0) {
+            return { ok: false, reason: 'INVALID_INPUT', detail: '무엇이 막혔는지(blockedNodes)가 없다' };
+        }
+        const fingerprint = boundaryFingerprint({
+            predicates: valid,
+            blockedNodes: input.blockedNodes,
+            ...(input.blockedScope ? { blockedScope: input.blockedScope } : {}),
+        });
+        const open = (await this.pending()).filter((record) => record.sessionId === input.sessionId);
+        const sameBoundary = open.find((record) => record.boundaryFingerprint === fingerprint);
+        if (sameBoundary) {
+            const detail = `같은 경계가 이미 열려 있다 (${sameBoundary.escalationId}) — 표현을 바꿔 다시 올리지 않는다`;
+            await this.#reject(input, 'DUPLICATE_EPISODE', detail, at);
+            return { ok: false, reason: 'DUPLICATE_EPISODE', detail, existing: sameBoundary };
+        }
+        if (input.previousEscalationId) {
+            const refused = await this.#judgeResubmit(input, valid, fingerprint);
+            if (refused) {
+                await this.#reject(input, 'RESUBMIT_NOT_JUSTIFIED', refused, at);
+                return { ok: false, reason: 'RESUBMIT_NOT_JUSTIFIED', detail: refused };
+            }
+        }
+        const blocked = new Set(input.blockedNodes);
+        const record = EscalationRecord.parse({
+            escalationId: input.escalationId,
+            sessionId: input.sessionId,
+            openedBy: input.openedBy,
+            predicates: valid,
+            question: input.question,
+            evidenceRefs: input.evidenceRefs,
+            affectedNodes: input.affectedNodes ?? [],
+            blockedNodes: input.blockedNodes,
+            blockedScope: input.blockedScope ?? [],
+            // 자동 계산이다 — 올리는 쪽이 "다 막혔다"고 적어 전체를 세우는 길을 두지 않는다
+            stillRunnableNodes: (input.doneCriteria ?? []).filter((node) => !blocked.has(node)),
+            boundaryFingerprint: fingerprint,
+            ...(input.previousEscalationId ? { previousEscalationId: input.previousEscalationId } : {}),
+            ...(input.whyPreviousDecisionDoesNotCoverThis
+                ? { whyPreviousDecisionDoesNotCoverThis: input.whyPreviousDecisionDoesNotCoverThis }
+                : {}),
+            // 결정 표면은 기존 Approval이다. 여기서는 그 참조만 든다.
+            requestId: 'pending',
+            openedAt: at,
+        });
+        if (!(await this.#scope.setIfAbsent(recordKey(record.escalationId), JSON.stringify(record)))) {
+            return { ok: false, reason: 'INVALID_INPUT', detail: `${record.escalationId} 는 이미 있다` };
+        }
+        return { ok: true, record };
+    }
+    /** 만들어진 ApprovalRequest를 잇는다. record는 이미 확정됐고 참조만 채운다. */
+    async attachRequest(escalationId, requestId) {
+        const record = await this.#read(recordKey(escalationId));
+        if (!record)
+            return false;
+        await this.#scope.set(recordKey(escalationId), JSON.stringify({ ...record, requestId }));
+        return true;
+    }
+    /**
+     * 사람이 결정해 닫혔다. **여기서 결정을 대신하지 않는다** — 결정은 기존 Approval
+     * 경로에서 일어나고, 이 마커는 "그 결정이 이 경계를 덮었다"는 사실만 남긴다.
+     */
+    async resolve(escalationId, decidedBy, decisionRef, at) {
+        const record = await this.#read(recordKey(escalationId));
+        if (!record)
+            return { ok: false, reason: 'NOT_FOUND', detail: `${escalationId} 를 찾지 못했다` };
+        const marker = { decidedBy, decisionRef, resolvedAt: at ?? this.#now() };
+        if (!(await this.#scope.setIfAbsent(resolvedKey(escalationId), JSON.stringify(marker)))) {
+            return { ok: false, reason: 'ALREADY_RESOLVED', detail: `${escalationId} 는 이미 닫혔다` };
+        }
+        return { ok: true, record };
+    }
+    /** 아직 사람이 결정하지 않은 상신. 이것이 곧 "무엇을 기다리는가"다. */
+    async pending() {
+        const out = [];
+        for (const record of await this.all()) {
+            if (!(await this.#scope.get(resolvedKey(record.escalationId))))
+                out.push(record);
+        }
+        return out;
+    }
+    async all() {
+        const keys = (await this.#scope.keys(RECORD_PREFIX)).sort();
+        const out = [];
+        for (const key of keys) {
+            const record = await this.#read(key);
+            if (record)
+                out.push(record);
+        }
+        return out;
+    }
+    async get(escalationId) {
+        return this.#read(recordKey(escalationId));
+    }
+    /** 막힌 상신들. Gate가 실제로 무엇을 막았는지 사람이 볼 수 있어야 한다. */
+    async rejected() {
+        const keys = (await this.#scope.keys(REJECTED_PREFIX)).sort();
+        const out = [];
+        for (const key of keys) {
+            const raw = await this.#scope.get(key);
+            if (!raw)
+                continue;
+            const parsed = RejectedEscalation.safeParse(JSON.parse(raw));
+            if (parsed.success)
+                out.push(parsed.data);
+        }
+        return out;
+    }
+    /**
+     * 재상신이 정당한가 (C-13 §5.1). 정당하면 null, 아니면 거절 사유.
+     *
+     * **전부 필요하다.** evidence 하나 더 붙이는 것은 같은 질문을 더 잘 설명한 것이지
+     * 새 질문이 아니다 (불변식 ⑧).
+     */
+    async #judgeResubmit(input, valid, fingerprint) {
+        const previous = await this.#read(recordKey(input.previousEscalationId));
+        if (!previous)
+            return `${input.previousEscalationId} 를 찾지 못했다 — 잇는 대상이 없다`;
+        if (previous.boundaryFingerprint === fingerprint) {
+            return '경계가 앞선 상신과 같다 — 근거만 더해서는 다시 올리지 않는다';
+        }
+        const newPredicate = valid.some((predicate) => !previous.predicates.includes(predicate));
+        const newBoundary = input.blockedNodes.some((node) => !previous.blockedNodes.includes(node)) ||
+            (input.blockedScope ?? []).some((scope) => !previous.blockedScope.includes(scope));
+        if (!newPredicate && !newBoundary) {
+            return '새 predicate도 새 경계도 없다 — 같은 사안이다';
+        }
+        const newEvidence = (input.evidenceRefs ?? []).some((ref) => !previous.evidenceRefs.includes(ref));
+        if (!newEvidence)
+            return '이전에 없던 근거가 없다';
+        if (!input.whyPreviousDecisionDoesNotCoverThis) {
+            return '앞선 결정이 왜 이걸 덮지 못하는지 적지 않았다';
+        }
+        return null;
+    }
+    async #reject(input, reason, detail, at) {
+        const record = RejectedEscalation.parse({
+            sessionId: input.sessionId,
+            openedBy: input.openedBy,
+            question: input.question,
+            claimedReasons: [...input.predicates],
+            reason,
+            detail,
+            at,
+        });
+        let seq = (await this.#scope.keys(REJECTED_PREFIX)).length + 1;
+        while (!(await this.#scope.setIfAbsent(rejectedKey(seq), JSON.stringify(record))))
+            seq += 1;
+    }
+    async #read(key) {
+        const raw = await this.#scope.get(key);
+        if (!raw)
+            return null;
+        const parsed = EscalationRecord.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+}
+/**
+ * 지금 무엇이 막혔고 무엇이 갈 수 있는가 (C-13 §6).
+ *
+ * **입력은 상신 기록뿐이다.** Checkpoint.blockers 같은 서술 문자열을 읽지 않는다
+ * (불변식 ⑤) — 문구를 바꾸는 것이 곧 권한 변경이 되면 안 된다.
+ *
+ * 결과는 `deriveExecutionState`(C-10 §7)가 그대로 소비한다. 새 상태 enum도, 새 그래프도
+ * 만들지 않는다: node는 Done Criteria 항목이고 막힌 것만 빠진다.
+ */
+export function proceedGateFacts(pending, doneCriteria) {
+    const blocked = new Set(pending.flatMap((record) => record.blockedNodes));
+    const runnable = doneCriteria.filter((node) => !blocked.has(node));
+    return {
+        // 무엇을 왜 기다리는지 — 사유 없이 "대기"만 있으면 사람이 할 일을 모른다
+        waitingOn: pending.map((record) => `${record.escalationId} [${record.predicates.join(', ')}] ${record.blockedNodes.join(', ')}`),
+        // 일부만 막혔으면 제한된 범위에서 계속 간다 (Conditional의 근거)
+        conditions: blocked.size > 0 && runnable.length > 0 ? [`still runnable: ${runnable.join(', ')}`] : [],
+        runnable,
+    };
+}
+/**
+ * 사람이 읽는 줄. **왜 이것이 Human Boundary인지가 먼저 온다** (C-13 §7).
+ * "어떻게 할까요"가 아니라 "이 경계라서 당신 몫이다"가 상신의 형태다.
+ */
+export function escalationLines(records) {
+    if (records.length === 0)
+        return [];
+    const lines = ['Needs an outside decision:'];
+    for (const record of records) {
+        lines.push(`  ${record.escalationId} — ${record.question}`);
+        for (const predicate of record.predicates)
+            lines.push(`    · ${predicate}`);
+        lines.push(`    blocked: ${record.blockedNodes.join(', ')}`);
+        // 무엇이 막혔는지(node)와 어느 경계에서 막혔는지(scope)는 다른 사실이다.
+        // scope가 안 보이면 결정하는 사람이 "어디까지가 남의 것인가"를 다시 물어야 한다.
+        if (record.blockedScope.length > 0)
+            lines.push(`    boundary: ${record.blockedScope.join(', ')}`);
+        if (record.stillRunnableNodes.length > 0) {
+            // 무엇이 계속 가는지 같이 보여야 "전부 멈췄다"로 읽히지 않는다
+            lines.push(`    still running: ${record.stillRunnableNodes.join(', ')}`);
+        }
+        lines.push(`    evidence: ${record.evidenceRefs.join(', ')}`);
+    }
+    return lines;
+}

package/dist/core/runtime/execution-state.d.ts

@@ -0,0 +1,43 @@
+export declare const EXECUTION_STATES: readonly ["Ready", "Conditional", "Waiting", "Blocked", "Done"];
+export type ExecutionState = (typeof EXECUTION_STATES)[number];
+/**
+ * 파생의 입력. **아는 것만 넣는다** — 모르는 항목은 `undefined` 이고, 그것은 `false` 와
+ * 다르다. 모르는 것을 안 된다로 읽으면 멀쩡한 일이 Blocked가 된다.
+ */
+export type ExecutionFacts = {
+    /** 필수 전제가 깨졌다. 이유가 있어야 한다 — 이유 없는 Blocked는 진단이 아니다. */
+    blockers?: readonly string[];
+    /** 외부 결정·이벤트·자격을 기다린다. */
+    waitingOn?: readonly string[];
+    /** 제한된 범위에서는 갈 수 있다. 무엇이 제한인지 적는다. */
+    conditions?: readonly string[];
+    /** 선언한 완료 조건. 비어 있으면 Done을 말할 근거가 없다. */
+    doneCriteria?: readonly string[];
+    /** 그중 충족된 것. */
+    metCriteria?: readonly string[];
+    /** 요구된 검증이 끝났는가. 요구가 없으면 undefined. */
+    verificationPassed?: boolean;
+    /** 외부 도구가 말하는 상태. **증거일 뿐 결론이 아니다.** */
+    externalState?: string;
+};
+export type ExecutionVerdict = {
+    state: ExecutionState;
+    /** 왜 그 상태인가. 상태만 주면 사람이 무엇을 해야 할지 모른다. */
+    reasons: string[];
+    /** 판정에 쓰이지 않은 외부 상태. 있는 그대로 옮긴다. */
+    externalState?: string;
+};
+/**
+ * 지금 이 일이 어디 있는가.
+ *
+ * 순서가 곧 우선순위다. 막힌 것이 먼저고, 기다리는 것이 그다음이며, Done은 **근거가
+ * 다 찼을 때만** 나온다 — 완료를 쉽게 말하는 것이 가장 비싼 오판이다.
+ */
+export declare function deriveExecutionState(facts: ExecutionFacts): ExecutionVerdict;
+/**
+ * 사람이 읽는 줄.
+ *
+ * 외부 상태를 **함께 보이되 결론과 섞지 않는다** — 같은 줄에 두면 "저쪽 도구가 그렇다니까"로
+ * 읽히고, 그게 이 모듈이 막으려는 것이다.
+ */
+export declare function executionLine(verdict: ExecutionVerdict, label?: string): string[];

package/dist/core/runtime/execution-state.js

@@ -0,0 +1,81 @@
+// Derived Execution State — 외부 도구의 상태가 아니라 실행의 상태 (C-10 §7).
+//
+// 외부 작업 추적기가 `진행 중` 이라고 말한다고 지금 착수할 수 있는 것이 아니다. 자격이 없을 수도,
+// 정본이 흔들렸을 수도, 앞선 일이 안 끝났을 수도 있다. **외부 work tracker의 상태는
+// 입력 증거일 뿐 실행 상태의 정본이 아니다** (불변식 ⑭).
+//
+// 그래서 저장하지 않고 파생한다. Session·Request 상태 enum은 동결이고(OM §11.2),
+// 여기서 만드는 것은 **읽을 때 계산되는 뷰**다 (불변식 ⑮). 같은 증거에서는 같은 값이
+// 나와야 한다 — 결정성이 없으면 "어제는 Ready였는데"가 설명되지 않는다.
+export const EXECUTION_STATES = ['Ready', 'Conditional', 'Waiting', 'Blocked', 'Done'];
+/**
+ * 지금 이 일이 어디 있는가.
+ *
+ * 순서가 곧 우선순위다. 막힌 것이 먼저고, 기다리는 것이 그다음이며, Done은 **근거가
+ * 다 찼을 때만** 나온다 — 완료를 쉽게 말하는 것이 가장 비싼 오판이다.
+ */
+export function deriveExecutionState(facts) {
+    const reasons = [];
+    const external = facts.externalState ? { externalState: facts.externalState } : {};
+    if (facts.blockers && facts.blockers.length > 0) {
+        return { state: 'Blocked', reasons: facts.blockers.map((b) => `blocked: ${b}`), ...external };
+    }
+    // Done은 선언한 조건이 있고, 그것이 다 찼고, 요구된 검증이 통과했을 때만이다.
+    const criteria = facts.doneCriteria ?? [];
+    const met = new Set(facts.metCriteria ?? []);
+    const unmet = criteria.filter((item) => !met.has(item));
+    if (criteria.length > 0 && unmet.length === 0) {
+        if (facts.verificationPassed === false) {
+            return { state: 'Waiting', reasons: ['criteria are met but verification has not passed'], ...external };
+        }
+        if (facts.verificationPassed === undefined && facts.waitingOn && facts.waitingOn.length > 0) {
+            return { state: 'Waiting', reasons: facts.waitingOn.map((w) => `waiting on: ${w}`), ...external };
+        }
+        return {
+            state: 'Done',
+            reasons: [
+                `${criteria.length} done-criteria met`,
+                ...(facts.verificationPassed ? ['required verification passed'] : ['no verification required']),
+            ],
+            ...external,
+        };
+    }
+    // 기다리는 것이 있어도 **갈 수 있는 것이 남아 있으면 멈춘 게 아니다** (C-13 §6).
+    // 이 둘을 합쳐 Waiting으로 읽으면 외부 대기 하나가 전체를 세운 것처럼 보인다.
+    if (facts.waitingOn && facts.waitingOn.length > 0 && facts.conditions && facts.conditions.length > 0) {
+        return {
+            state: 'Conditional',
+            reasons: [...facts.conditions.map((c) => `limit: ${c}`), ...facts.waitingOn.map((w) => `waiting on: ${w}`)],
+            ...external,
+        };
+    }
+    if (facts.waitingOn && facts.waitingOn.length > 0) {
+        return { state: 'Waiting', reasons: facts.waitingOn.map((w) => `waiting on: ${w}`), ...external };
+    }
+    if (facts.conditions && facts.conditions.length > 0) {
+        return {
+            state: 'Conditional',
+            reasons: facts.conditions.map((c) => `limit: ${c}`),
+            ...external,
+        };
+    }
+    if (unmet.length > 0)
+        reasons.push(`${unmet.length} done-criteria remaining`);
+    reasons.push('nothing blocking, nothing to wait on');
+    return { state: 'Ready', reasons, ...external };
+}
+/**
+ * 사람이 읽는 줄.
+ *
+ * 외부 상태를 **함께 보이되 결론과 섞지 않는다** — 같은 줄에 두면 "저쪽 도구가 그렇다니까"로
+ * 읽히고, 그게 이 모듈이 막으려는 것이다.
+ */
+export function executionLine(verdict, label = 'Execution state') {
+    const lines = [`${label}: ${verdict.state}`];
+    for (const reason of verdict.reasons)
+        lines.push(`  ${reason}`);
+    if (verdict.externalState) {
+        lines.push(`  (external tool says: ${verdict.externalState} — evidence, not the basis of this verdict)`);
+    }
+    return lines;
+}