@asc-agent/runtime 0.1.0

package/dist/core/runtime/query.js

@@ -0,0 +1,213 @@
+// Bounded Query — 다른 파트에 묻되, 답할 수 있는 형태로만 묻는다 (C-04 §3~§5).
+//
+// 왜 자유형 질문을 막는가: "이거 어떻게 할까요?" 는 무엇에 답해야 하는지도, 답이 무엇을
+// 풀어 주는지도 말하지 않는다. 받은 쪽은 판단할 근거가 없으니 다시 미루고, 그렇게 결정이
+// Agent 사이를 돈다. 실제로 도는 동안 세 세션의 context가 소모되고 사람은 마지막에야 안다.
+//
+// 이 모듈이 하는 일과 하지 않는 일:
+//   한다   — 질의를 구조로 받고, 답을 한 번만 받고, 되던지기를 발행 시점에 막고, 표면화
+//   안 한다 — 승인·Grant·예외·범위 확대. 답 하나로 권한이 생기는 경로는 없다 (C-03 §4)
+//
+// DECIDE는 "그 결정의 주인이 결론을 냈다"까지다. Human Approval이 아니고, 그 자체로
+// 어떤 Core 전이도 일으키지 않는다. 사람 결정이 필요하면 이 답을 근거로 올릴 뿐이다.
+//
+// 저장은 closure.ts와 같은 이유로 전부 setIfAbsent 위에 선다 — 잃는 것이 표시값이 아니라
+// 누가 무엇을 물었고 누가 답했는가이기 때문이다. 답은 한 번만 쓰이고 덮이지 않는다.
+import { z } from 'zod';
+import { QUERY_ID } from "../model/ids.js";
+import { lookupAuthority } from "../policy/ownership.js";
+export const BoundedQuery = z.object({
+    id: z.string().regex(QUERY_ID),
+    /** 물은 쪽. 답을 받은 뒤 흐름이 돌아갈 자리다. */
+    ownerSessionId: z.string().min(1),
+    /** 물은 쪽의 파트. 되던지기 판정의 기준이라 발행 시점 스냅샷으로 박아 둔다. */
+    ownerRole: z.string().min(1).optional(),
+    /** 어느 결정을 묻는가 (decision domain). 누구에게가 아니라 무엇에 대해서다. */
+    requestedAuthority: z.string().min(1),
+    question: z.string().min(1),
+    context: z.string().optional(),
+    /**
+     * 답이 없을 때 물은 쪽이 취할 기본값. 이것이 있으면 질문은 차단이 아니라 확인이 되고,
+     * 없으면 blockingScope가 실제로 막힌다.
+     */
+    proposedDefault: z.string().optional(),
+    /** 이 답이 없으면 막히는 범위. 비어 있으면 "막히지 않는다"는 뜻이다. */
+    blockingScope: z.string().optional(),
+    expectedResponse: z.enum(['DECIDE', 'ANSWER']).default('DECIDE'),
+    /** 이 질의가 어느 질의에서 파생했는가. 되던지기는 여기로 드러난다. */
+    inReplyTo: z.string().regex(QUERY_ID).optional(),
+    openedAt: z.string().min(1),
+});
+export const QueryAnswer = z.object({
+    kind: z.enum(['DECIDE', 'ANSWER', 'ESCALATE']),
+    /** 답한 파트. DECIDE는 이 값이 그 결정의 주인일 때만 성립한다. */
+    byRole: z.string().min(1),
+    body: z.string().min(1),
+    /** ESCALATE 대상. Agent가 아니라 사람·권한자여야 한다 (C-04 §4.1). */
+    escalateTo: z.string().optional(),
+    at: z.string().min(1),
+});
+const queryKey = (id) => `query:req:${id}`;
+const answerKey = (id) => `query:ans:${id}`;
+/** 막힌 발행 시도. 막았다고 없던 일이 아니다 — 사람이 봐야 할 사실이다. */
+const violationKey = (id) => `query:vio:${id}`;
+export class QueryLedger {
+    #scope;
+    #ownership;
+    #now;
+    constructor(scope, ownership, now = () => new Date().toISOString()) {
+        this.#scope = scope;
+        this.#ownership = ownership;
+        this.#now = now;
+    }
+    /**
+     * 질의를 연다. 되던지기는 **여기서** 막는다 — 실행 중인 세션을 끊는 대신 발행을 막는
+     * 것이 OM §16(Interrupt 부재)을 지키면서 순환을 끊는 유일한 자리다.
+     */
+    async open(spec) {
+        if (!QUERY_ID.test(spec.id)) {
+            return { ok: false, reason: 'INVALID_ID', detail: `질의 id 형식이 아니다: '${spec.id}' (X-YYYYMMDD-NN)` };
+        }
+        if (spec.inReplyTo) {
+            const origin = await this.get(spec.inReplyTo);
+            if (!origin) {
+                return { ok: false, reason: 'ORIGIN_NOT_FOUND', detail: `${spec.inReplyTo} 를 찾지 못했다` };
+            }
+            const refusal = this.#judgeRelay(spec, origin);
+            if (refusal) {
+                await this.#recordViolation(spec.id, refusal.reason, origin.id, refusal.detail);
+                return { ok: false, reason: refusal.reason, detail: refusal.detail, origin };
+            }
+        }
+        const query = BoundedQuery.parse({ ...spec, openedAt: this.#now() });
+        const written = await this.#scope.setIfAbsent(queryKey(query.id), JSON.stringify(query));
+        if (!written)
+            return { ok: false, reason: 'ALREADY_EXISTS', detail: `${query.id} 는 이미 있다` };
+        return { ok: true, query };
+    }
+    /**
+     * 파생 질의가 허용되는가.
+     *
+     * 물은 쪽이 답을 받고 다시 묻는 것은 여전히 1 hop이다 — 막지 않는다.
+     * 막는 것은 **받은 쪽이 같은 결정을 다시 넘기는** 경우이고, 그 넘김이 물은 쪽으로
+     * 돌아가면 순환, 제3자로 가면 one-hop 위반이다.
+     */
+    #judgeRelay(spec, origin) {
+        const sameAsker = spec.ownerSessionId === origin.ownerSessionId ||
+            (!!spec.ownerRole && !!origin.ownerRole && spec.ownerRole === origin.ownerRole);
+        if (sameAsker)
+            return null;
+        const asked = lookupAuthority(this.#ownership, spec.requestedAuthority);
+        const backToOrigin = origin.ownerRole !== undefined && asked.kind === 'RESOLVED' && asked.role === origin.ownerRole;
+        return backToOrigin
+            ? {
+                reason: 'CIRCULAR_DELEGATION',
+                detail: `${origin.id} 를 물은 쪽은 ${origin.ownerRole} 인데, 그 답 대신 ` +
+                    `'${spec.requestedAuthority}' 를 다시 ${origin.ownerRole} 에게 묻고 있다. ` +
+                    `원 요청 '${origin.requestedAuthority}' 을 DECIDE / ANSWER / ESCALATE 중 하나로 종결하라.`,
+            }
+            : {
+                reason: 'ONE_HOP_VIOLATION',
+                detail: `${origin.id} 로 받은 결정을 제3자에게 다시 넘기고 있다. ` +
+                    '받은 쪽이 할 수 있는 것은 DECIDE / ANSWER / ESCALATE 뿐이며, ESCALATE는 Agent가 아니라 ' +
+                    '명시된 사람·권한자에게 올린다.',
+            };
+    }
+    /**
+     * 답은 한 번만 쓰인다. 두 사람이 동시에 답해도 먼저 쓴 것이 남고 나중 것은 거절된다 —
+     * 조용히 덮으면 누구 말을 따랐는지 알 수 없게 된다.
+     *
+     * **이 호출은 어떤 Core 전이도 일으키지 않는다.** DECIDE도 마찬가지다 (C-04 §3.4).
+     */
+    async answer(id, input) {
+        const query = await this.get(id);
+        if (!query)
+            return { ok: false, reason: 'NOT_FOUND', detail: `${id} 를 찾지 못했다` };
+        if (input.kind === 'DECIDE') {
+            const found = lookupAuthority(this.#ownership, query.requestedAuthority);
+            if (found.kind !== 'RESOLVED' || found.role !== input.byRole) {
+                const who = found.kind === 'RESOLVED'
+                    ? `그 결정의 주인은 '${found.role}' 이다`
+                    : found.kind === 'AMBIGUOUS'
+                        ? `그 결정의 주인이 갈려 있다 (${found.candidates.join(', ')})`
+                        : '그 결정의 주인이 선언되지 않았다';
+                return {
+                    ok: false,
+                    reason: 'FORBIDDEN_AUTHORITY',
+                    detail: `'${input.byRole}' 은 '${query.requestedAuthority}' 를 결정할 수 없다 — ${who}. ` +
+                        'ANSWER(사실 반환) 또는 ESCALATE(권한자에게 상신)로 종결하라.',
+                };
+            }
+        }
+        const answer = QueryAnswer.parse({ ...input, at: this.#now() });
+        const written = await this.#scope.setIfAbsent(answerKey(id), JSON.stringify(answer));
+        if (!written) {
+            const existing = (await this.getAnswer(id));
+            return { ok: false, reason: 'ALREADY_ANSWERED', detail: `${id} 는 이미 답이 있다`, answer: existing };
+        }
+        return { ok: true, query, answer };
+    }
+    async get(id) {
+        const raw = await this.#scope.get(queryKey(id));
+        return raw ? BoundedQuery.parse(JSON.parse(raw)) : null;
+    }
+    async getAnswer(id) {
+        const raw = await this.#scope.get(answerKey(id));
+        return raw ? QueryAnswer.parse(JSON.parse(raw)) : null;
+    }
+    async list() {
+        const out = [];
+        for (const key of await this.#scope.keys('query:req:')) {
+            const raw = await this.#scope.get(key);
+            if (!raw)
+                continue;
+            const query = BoundedQuery.parse(JSON.parse(raw));
+            out.push({ query, answer: await this.getAnswer(query.id) });
+        }
+        return out.sort((a, b) => a.query.id.localeCompare(b.query.id));
+    }
+    /**
+     * 사람에게 넘겨진 질의. 답은 쓰였지만 **끝난 것이 아니다** — 그 답이 "사람이 정하라"였다.
+     * 이것이 없으면 ESCALATE는 어느 화면에도 뜨지 않는 write-only 로그가 된다.
+     */
+    async escalated() {
+        return (await this.list()).filter((entry) => entry.answer?.kind === 'ESCALATE');
+    }
+    /** 아직 답이 없는 질의. 누군가 기다리고 있다는 뜻이다. */
+    async pending() {
+        return (await this.list()).filter((e) => e.answer === null).map((e) => e.query);
+    }
+    /** 막힌 발행 시도. 막았다고 사라지지 않는다 — 같은 결정이 돌고 있었다는 사실이다. */
+    async violations() {
+        const out = [];
+        for (const key of await this.#scope.keys('query:vio:')) {
+            const raw = await this.#scope.get(key);
+            if (raw)
+                out.push(JSON.parse(raw));
+        }
+        return out.sort((a, b) => a.attemptedId.localeCompare(b.attemptedId));
+    }
+    async #recordViolation(attemptedId, kind, originId, detail) {
+        const violation = { attemptedId, kind, originId, detail, at: this.#now() };
+        await this.#scope.setIfAbsent(violationKey(attemptedId), JSON.stringify(violation));
+    }
+}
+/**
+ * 사람에게 넘겨진 질의를 줄로. 상신했는데 어느 화면에도 안 뜨는 상태를 막는 것이 목적이다.
+ */
+export function escalatedLines(answered) {
+    return answered.map((entry) => `${entry.query.id}: 사람에게 넘김 — ${entry.query.question}` +
+        (entry.answer.escalateTo ? ` (→ ${entry.answer.escalateTo})` : ''));
+}
+/** 사람이 읽을 줄로. collect의 "판단이 필요한 것"에 그대로 들어간다. */
+export function queryLines(open, violations) {
+    const lines = [];
+    for (const q of open) {
+        const blocked = q.blockingScope ? ` (막힘: ${q.blockingScope})` : '';
+        lines.push(`${q.ownerSessionId}: 답을 기다리는 질의 ${q.id} — '${q.requestedAuthority}'${blocked}`);
+    }
+    for (const v of violations) {
+        lines.push(`${v.kind}: ${v.attemptedId} (원 질의 ${v.originId}) — ${v.detail}`);
+    }
+    return lines;
+}

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

@@ -0,0 +1,33 @@
+import type { DecisionEvidence, ExecutionEvidence, ReclaimEvidence, ValidationRecord } from './audit.ts';
+import type { EscalationRecord } from './escalation.ts';
+import type { Claim } from './claims.ts';
+import type { ExecutionVerdict } from './execution-state.ts';
+import type { Handoff, Session } from '../model/entities.ts';
+export type ReportInput = {
+    session: Pick<Session, 'id' | 'role' | 'goal' | 'status' | 'doneCriteria'> & {
+        handoff?: Handoff;
+    };
+    executions?: readonly ExecutionEvidence[];
+    validations?: readonly ValidationRecord[];
+    reclaim?: ReclaimEvidence | null;
+    claims?: readonly Claim[];
+    /** 승인 없이 간 결정들 (C-13 §4). 몇 건을 스스로 정했는지가 판정 근거다. */
+    decisions?: readonly DecisionEvidence[];
+    /** 미해소 상신 (C-13). 무엇이 막혔고 무엇이 갔는지 미결에 든다. */
+    escalations?: readonly EscalationRecord[];
+    /** 파생 실행 상태. 있으면 결과 줄이 이것을 따른다 — 두 개의 결론을 만들지 않는다. */
+    derived?: ExecutionVerdict;
+};
+export type FinalReport = {
+    result: string;
+    /** 왜 그렇게 판정했는가. 근거가 **어디에 있는지**를 가리키고 본문을 복제하지 않는다. */
+    basis: string[];
+    /** 미결과 위험. 없으면 없다고 적는다 — 빈 칸은 "없다"가 아니라 "안 봤다"로 읽힌다. */
+    open: string[];
+    next: string[];
+    /** 상세를 어디서 읽는가. 보고가 증거 저장소가 되지 않게 하는 장치다. */
+    evidence: string[];
+};
+export declare function buildFinalReport(input: ReportInput): FinalReport;
+/** 사람이 읽는 최종 보고. 네 블록을 넘지 않는다. */
+export declare function renderFinalReport(report: FinalReport): string[];

package/dist/core/runtime/report.js

@@ -0,0 +1,108 @@
+// Compact Final Report — 보고는 증거의 projection이다 (C-10 §5 계열 · 지시 §28).
+//
+// 최종 보고가 길어지는 이유는 보고 자체가 저장소 역할을 하기 때문이다. 과정을 전부 옮겨
+// 적으면 다음 사람이 그 글을 읽어야만 사실을 알 수 있고, 그러면 audit trail은 있으나
+// 아무도 안 본다.
+//
+// 그래서 네 가지만 든다:
+//
+//   결과 · 판정 근거 · 미결/위험 · 다음 행동
+//
+// 나머지는 이미 남아 있는 곳에서 읽는다 — Checkpoint · Handoff · Validation · Claim History.
+// **보고를 줄이려고 증거를 버리지 않는다.** 줄이는 것은 옮겨 적기이지 기록이 아니다.
+export function buildFinalReport(input) {
+    const { session } = input;
+    const executions = input.executions ?? [];
+    const validations = input.validations ?? [];
+    const claims = input.claims ?? [];
+    const result = input.derived
+        ? `${session.id} ${input.derived.state} — ${session.goal}`
+        : `${session.id} ${session.status} — ${session.goal}`;
+    const basis = [];
+    if (input.derived)
+        basis.push(...input.derived.reasons);
+    // 실행 증거: 몇 번이 아니라 **누가**가 중요하다. 같은 주체면 그 사실이 판정을 바꾼다.
+    if (executions.length === 0) {
+        basis.push('실행 증거 없음 — 발급됐으나 아무도 집지 않았다');
+    }
+    else {
+        const principals = [...new Set(executions.map((e) => e.principal))];
+        basis.push(`실행 ${executions.length}건 · 주체 ${principals.join(', ')}`);
+        if (executions.some((e) => e.principalSource === 'derived')) {
+            basis.push('주체 일부가 선언되지 않았다 — 독립성 주장은 UNVERIFIED를 넘지 못한다');
+        }
+    }
+    // 검증: 등급을 빼고 결과만 적으면 자기 확인이 독립 검증처럼 보인다.
+    if (validations.length === 0) {
+        basis.push('독립 검증 없음');
+    }
+    else {
+        for (const validation of validations) {
+            basis.push(`검증 ${validation.result} (${validation.independence}) — ${validation.independenceDetail}`);
+        }
+    }
+    // 자율 판단과 상신의 비율이 곧 "Approval은 예외인가"의 증거다 (C-13 §0)
+    const decisions = input.decisions ?? [];
+    const escalations = input.escalations ?? [];
+    basis.push(decisions.length > 0
+        ? `승인 없이 정한 것 ${decisions.length}건 (${decisions.map((d) => d.class).join(', ')})`
+        : '승인 없이 정한 것 없음');
+    basis.push(escalations.length > 0 ? `사람에게 올린 것 ${escalations.length}건` : '사람에게 올린 것 없음');
+    if (session.handoff)
+        basis.push(`자기 확인: ${session.handoff.verified} (독립 검증 아님)`);
+    basis.push(input.reclaim ? `회수: ${input.reclaim.reclaimedBy}` : '회수 기록 없음');
+    const open = [];
+    if (session.handoff?.unresolved?.length)
+        open.push(...session.handoff.unresolved);
+    // 추론과 미확인은 결과가 아니라 미결이다 — 결과 줄에 섞으면 확정처럼 읽힌다.
+    for (const claim of claims) {
+        if (claim.status === 'INFERRED')
+            open.push(`추론(확정 아님): ${claim.statement}`);
+        if (claim.status === 'PENDING')
+            open.push(`미확인: ${claim.statement}`);
+    }
+    for (const record of escalations) {
+        open.push(`외부 결정 대기 ${record.escalationId} [${record.predicates.join(', ')}] — 막힘 ${record.blockedNodes.join(', ')}`);
+    }
+    const unmet = session.doneCriteria.filter((item) => !(session.handoff?.done ?? []).includes(item));
+    if (unmet.length > 0)
+        open.push(`${unmet.length} done-criteria remaining: ${unmet.join(', ')}`);
+    if (open.length === 0)
+        open.push('없음');
+    const next = [];
+    if (session.handoff?.next)
+        next.push(session.handoff.next);
+    if (!input.reclaim && session.status === 'DONE')
+        next.push('Controller 회수 필요 — asc controller collect --as <주체>');
+    if (validations.length === 0)
+        next.push('독립 검증이 필요하면 별도 주체로 asc session validate');
+    if (next.length === 0)
+        next.push('없음');
+    return {
+        result,
+        basis,
+        open,
+        next,
+        // 본문을 옮기지 않고 어디를 볼지만 가리킨다
+        evidence: [
+            `asc session audit ${session.id}`,
+            ...(escalations.length > 0 ? [`asc escalate list`] : []),
+            ...(claims.length > 0 ? ['claim history (STALE 포함)'] : []),
+        ],
+    };
+}
+/** 사람이 읽는 최종 보고. 네 블록을 넘지 않는다. */
+export function renderFinalReport(report) {
+    return [
+        `## 결과`,
+        `  ${report.result}`,
+        `## 판정 근거`,
+        ...report.basis.map((line) => `  ${line}`),
+        `## 미결 / 위험`,
+        ...report.open.map((line) => `  ${line}`),
+        `## 다음 행동`,
+        ...report.next.map((line) => `  ${line}`),
+        `## 상세는 여기서 읽는다`,
+        ...report.evidence.map((line) => `  ${line}`),
+    ];
+}

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

@@ -0,0 +1,156 @@
+import { Session, type Checkpoint, type Handoff, type SessionRole } from '../model/entities.ts';
+import { type OwnershipMap } from '../policy/ownership.ts';
+import type { ResolvedPolicy } from '../policy/policy.ts';
+import type { BaselineQuery, ScmPort } from '../../ports/scm.ts';
+import type { StateStore } from '../../ports/state-store.ts';
+import type { RuntimeBindings } from '../operator/runtime-binding.ts';
+import { type ApplyOutcome } from './store-ops.ts';
+/** 소유하지 않은 세션에 기록하려 했다 (C-10 §2.3). */
+export type NotOwner = {
+    ok: false;
+    reason: 'NOT_OWNER';
+    detail: string;
+};
+/** 전이 결과에 소유권 거부가 더해진 형태. 전이 자체의 실패 갈래는 그대로다. */
+export type WriteOutcome<T> = ApplyOutcome<T> | NotOwner;
+export type CanonicalDrift = {
+    sourceId: string;
+    recorded: string;
+    current: string;
+};
+/**
+ * 정본이 움직였거나, 정본을 읽을 수 없다. 둘 다 그냥 이어갈 수 없는 이유다 (OM §9).
+ *
+ * 읽지 못한 것을 "달라진 게 없다"로 넘기면 검증이 있는 척만 하게 된다 — 토큰이 없거나
+ * 조회가 실패한 채로 도는 세션이 가장 위험하다. 무엇을 딛고 선지 모르면 멈춘다.
+ */
+export type StartOutcome = ApplyOutcome<Session> | {
+    ok: false;
+    reason: 'CANONICAL_DRIFT';
+    drifts: CanonicalDrift[];
+} | {
+    ok: false;
+    reason: 'CANONICAL_UNAVAILABLE';
+    detail: string;
+};
+export type SessionDeps = {
+    /** 정본을 실제로 다시 읽는 통로. 없으면 baseline 기록·대조를 건너뛴다. */
+    scm?: ScmPort;
+    /** Profile이 정의한 정본 갈래들 (OM §8). */
+    canonicalSources?: readonly BaselineQuery[];
+    /** Profile이 선언한 책임 지도 (C-04 §6). 없으면 결정권 판정이 성립하지 않는다. */
+    ownership?: OwnershipMap;
+    /**
+     * 현재 소유권 통로 (C-10 §2.3). 주면 checkpoint·handoff 쓰기에 owner 검사가 붙는다 —
+     * Progress가 이미 하던 검사를 나머지 둘에도 대칭으로 건다.
+     *
+     * 주지 않으면 검사하지 않는다. 소유권 개념이 없는 경로(단독 사용·기존 스크립트)를
+     * 이 계약이 갑자기 잠그지 않기 위해서다. **binding이 있는데 owner가 아닌 경우만 막는다.**
+     */
+    bindings?: RuntimeBindings;
+    now?: () => string;
+};
+export type SessionSpec = {
+    id: string;
+    role: SessionRole;
+    goal: string;
+    doneCriteria?: string[];
+    blockId?: string;
+    taskPointer?: string;
+    canonicalSources?: {
+        sourceId: string;
+        baseline: string;
+    }[];
+    readScope?: string[];
+    /** Profile이 준 Role 최대 범위보다 좁아야 한다 — 넓히려 하면 발급이 실패한다. */
+    writeBoundary?: string[];
+    outOfScope?: string[];
+    /** Controller가 이 세션에 한해 허용한 SOFT DENY 항목 (OM §5.1). */
+    policyExceptions?: string[];
+    /** 이 일을 끝까지 끌고 갈 주체 (C-04 §1.1). */
+    owner?: string;
+    /** 이 일에 걸린 결정 영역. 선언하면 결정권자가 있는지 발급 전에 확인한다. */
+    decisionDomains?: string[];
+    /** 이번 세션에 한해 정한 결정권자 (domain → role). */
+    decisionAuthority?: Record<string, string>;
+    /** 외부에서 받아야 할 입력. owner를 바꾸지 않는다. */
+    dependencies?: string[];
+};
+export type IssueFailure = {
+    kind: 'INVALID_CONTRACT';
+    detail: string;
+} | {
+    kind: 'CANONICAL_UNAVAILABLE';
+    detail: string;
+} | {
+    kind: 'SCOPE_ESCALATION';
+    detail: string;
+} | {
+    kind: 'INVALID_SCOPE';
+    detail: string;
+} | {
+    kind: 'HARD_DENY_ESCAPE';
+    detail: string;
+}
+/** 이 일에 필요한 결정의 주인이 정해지지 않았다 (C-04 §1.3). */
+ | {
+    kind: 'RESPONSIBILITY_AMBIGUOUS';
+    detail: string;
+} | {
+    kind: 'ALREADY_EXISTS';
+    detail: string;
+};
+export type IssueResult = {
+    ok: true;
+    session: Session;
+} | {
+    ok: false;
+    failures: IssueFailure[];
+};
+export declare class SessionRuntime {
+    #private;
+    constructor(store: StateStore, policy?: ResolvedPolicy | null, deps?: SessionDeps);
+    /**
+     * Controller가 세션 계약을 발급한다. Session Contract는 Policy hierarchy의 최하위
+     * 계층이므로 상위보다 넓은 권한을 요청할 수 없다 (OM §5.2).
+     * 범위를 벗어난 요청은 조용히 좁히지 않고 거절한다 — 계약서와 실권한이 어긋난 채로
+     * 굴러가는 것이 더 위험하다.
+     */
+    issue(spec: SessionSpec): Promise<IssueResult>;
+    get(id: string): Promise<Session | null>;
+    /**
+     * Physical Run이 계약을 집어 든다. 집기 전에 정본이 그대로인지 본다 —
+     * 바닥이 달라진 채로 이어가면 낡은 전제 위에서 작업하게 된다.
+     */
+    start(id: string): Promise<StartOutcome>;
+    /** Run이 끊긴다. Checkpoint 없이는 멈출 수 없다 — 다음 Run이 이어받을 수 없기 때문이다. */
+    pause(id: string, checkpoint: Checkpoint, physicalSessionId?: string): Promise<WriteOutcome<Session>>;
+    /** 다른 Physical Run이 같은 Logical Session을 이어받는다. 여기서도 정본부터 확인한다. */
+    resume(id: string): Promise<StartOutcome>;
+    /**
+     * 지금 정본 상태를 읽기 전용으로 판정한다 (C-03 §1.6). ACTIVE 세션을 이어갈 때도
+     * 검증이 필요하지만 상태 전이는 없어야 하므로, 판정 로직을 Operator에 복제하지 않고
+     * 여기서 공개한다.
+     */
+    checkCanonical(id: string): Promise<{
+        status: 'CURRENT';
+    } | {
+        status: 'DRIFT';
+        drifts: CanonicalDrift[];
+    } | {
+        status: 'UNAVAILABLE';
+        detail: string;
+    } | {
+        status: 'NOT_FOUND';
+    }>;
+    /** HARD DENY가 Goal을 막았다 — Controller 판단이 필요하다 (OM §5.3). */
+    block(id: string): Promise<ApplyOutcome<Session>>;
+    /** 막힌 사유를 Controller가 해소했다. */
+    unblock(id: string): Promise<ApplyOutcome<Session>>;
+    /**
+     * 세션 종료. Handoff까지가 에이전트 몫이고, state·block·queue 갱신은 Controller가
+     * 회수한 뒤에 한다 (OM §7.2·§9).
+     */
+    complete(id: string, handoff: Handoff, physicalSessionId?: string): Promise<WriteOutcome<Session>>;
+    fail(id: string, actor?: 'session' | 'controller'): Promise<ApplyOutcome<Session>>;
+}