@asc-agent/runtime 0.1.0

package/dist/core/operator/render.js

@@ -0,0 +1,170 @@
+// Human-first Progress Renderer (B-17).
+//
+// 목표는 ASC 내부 상태를 많이 보여주는 것이 아니다 — 사용자가 별도 질의 없이
+// "내 작업이 지금 어떻게 되고 있는가"를 이해하게 하는 것이다. 그래서 본문은 항상
+// 다섯 질문에 답한다: 지금 무엇을 / 무엇이 끝났나 / 문제가 있나 / 다음은 / 내 판단이
+// 지금 필요한가.
+//
+// 규칙 셋:
+//   1. 본문에 내부 용어(Logical Session·ACTIVE·writeBoundary·Verifier·RuntimeBinding)를
+//      쓰지 않는다. 사람이 ASC를 배워야 이해되는 화면은 실패다. 내부 용어는 상세 한 줄에만.
+//   2. Renderer는 progress schema 덤프가 아니다. 필드를 나열하는 대신 문장을 만든다.
+//   3. ACTIVE 세션의 checkpoint를 현재 진행으로 읽지 않는다 — checkpoint는 중단 시점의
+//      승계 정보이고, 재개 후에도 남아 있어 지금 상황과 다를 수 있다.
+//
+// heartbeat(관찰된 활동)만으로 "순조롭게 진행 중" 같은 의미론적 진척을 만들지 않는다.
+// 활동 흔적은 진척이 아니다 — 보고가 없으면 없다고 말한다.
+/** 내부 상태 → 사람 말. 상세 줄에서는 원래 용어를 써도 된다. */
+const ROLE_WORDS = {
+    planner: '계획',
+    researcher: '조사',
+    implementer: '구현',
+    verifier: '검증',
+};
+const STATUS_WORDS = {
+    READY: '시작 대기',
+    ACTIVE: '작업 중',
+    PAUSED: '멈춤',
+    BLOCKED: '막힘',
+    DONE: '완료',
+    FAILED: '실패',
+};
+/** 보고가 이만큼 오래되면 지금 상황이라고 단정하지 않는다. */
+const STALE_AFTER_MS = 20 * 60 * 1000;
+export function renderProgress(input) {
+    const { session, progress, liveness } = input;
+    const awaiting = input.awaiting ?? [];
+    const now = input.now ?? new Date();
+    const work = session ? shortGoal(session.goal) : '이';
+    if (!progress) {
+        const state = session ? STATUS_WORDS[session.status] : '확인 불가';
+        // 활동 신호가 있으면 "언제 뭔가 돌긴 했다"까지만 더한다 — 그 이상은 지어내는 것이다
+        const noReport = liveness
+            ? `${minutesSince(liveness.lastActivityAt, now)}분 전에 활동이 관찰됐지만, 진행 내용 보고는 아직 없습니다.`
+            : '아직 진행 내용 보고가 없어 어디까지 됐는지는 알 수 없습니다.';
+        return {
+            body: [
+                `${work} 작업이 ${state === '작업 중' ? '진행 중입니다' : `${state} 상태입니다`}.`,
+                noReport,
+                awaiting.length > 0 ? awaitingLine(awaiting) : decisionLine('NONE'),
+            ],
+            detail: detailLine(session, null, now, liveness),
+        };
+    }
+    const body = [headline(work, progress)];
+    // 무엇이 끝났고 지금 무엇을 하는가 — 한 문단으로 붙인다.
+    // 끝난 작업에는 "지금 무엇을"이 없다 — 무엇을 마쳤는지만 말한다.
+    const done = progress.milestones.length > 0 ? joinKorean(progress.milestones) : '';
+    if (progress.terminal) {
+        if (done)
+            body.push(`${done}까지 완료했습니다.`);
+    }
+    else {
+        body.push(`${done ? `${done}까지 마쳤고, ` : ''}지금은 ${progress.phase}.`);
+    }
+    // 문제가 있는가 + 다음은 무엇인가
+    const trouble = troubleLine(progress);
+    const next = progress.terminal ? '' : progress.nextStep ? ` 다음은 ${progress.nextStep}.` : '';
+    if (trouble || next)
+        body.push(`${trouble}${next}`.trim());
+    body.push(awaiting.length > 0
+        ? awaitingLine(awaiting)
+        : decisionLine(progress.needsUserDecision, progress.decisionRef, progress.terminal));
+    if (isStale(progress, now)) {
+        body.push(`(마지막 보고가 ${minutesAgo(progress, now)}분 전입니다 — 그 사이 상황이 달라졌을 수 있습니다.)`);
+    }
+    return { body, detail: detailLine(session, progress, now, liveness) };
+}
+function headline(work, p) {
+    if (p.terminal)
+        return `${work} 작업을 마쳤습니다.`;
+    if (p.needsUserDecision === 'NOW')
+        return `${work} 작업이 멈춰 있으며, 사용자 판단이 필요합니다.`;
+    if (p.verifier === 'FAIL')
+        return `${work} 구현은 끝났지만 검증에서 문제를 발견했습니다.`;
+    if (p.verifier === 'RUNNING')
+        return `${work} 작업은 끝났고, 지금은 별도 검증을 진행하고 있습니다.`;
+    if (p.unresolved.length > 0) {
+        return `${work} 작업은 계속 진행 중이며, 확인이 필요한 항목 ${p.unresolved.length}건을 발견했습니다.`;
+    }
+    return `${work} 작업이 진행 중입니다.`;
+}
+function troubleLine(p) {
+    if (p.verifier === 'FAIL') {
+        return p.verifierDetail
+            ? `검증에서 확인된 문제: ${p.verifierDetail}. 아직 완료로 처리하지 않았습니다.`
+            : '검증에서 실패한 항목이 있어 아직 완료로 처리하지 않았습니다.';
+    }
+    if (p.unresolved.length > 0) {
+        return `확인이 필요한 항목: ${joinKorean(p.unresolved)}.`;
+    }
+    if (p.terminal)
+        return '';
+    // 판단을 기다리며 멈춰 있는데 "문제 없다"고 하면 앞뒤가 맞지 않는다 — 멈춤 자체가 문제다
+    if (p.needsUserDecision === 'NOW')
+        return '';
+    return '현재 작업을 막는 문제는 없습니다.';
+}
+/** 열린 상신이 있으면 무엇을 기다리는지 이름으로 말한다 — "받은함을 보라"보다 구체적이다. */
+function awaitingLine(awaiting) {
+    return `지금 판단이 필요합니다 — ${awaiting.join(', ')} (asc inbox) 를 확인해 주세요.`;
+}
+function decisionLine(need, ref, terminal = false) {
+    switch (need) {
+        case 'NOW':
+            return ref
+                ? `지금 판단이 필요합니다 — ${ref} 를 확인해 주세요.`
+                : '지금 판단이 필요합니다 — 받은함(asc inbox)을 확인해 주세요.';
+        case 'LATER':
+            // 끝난 작업에 "계속 진행할 수 있습니다"라고 하면 아직 도는 줄 안다
+            return terminal
+                ? '자동화 작업은 끝났으며, 남은 항목은 따로 판단할 수 있습니다.'
+                : '작업은 계속 진행할 수 있습니다. 미확정 항목은 완료 시 함께 판단을 요청하겠습니다.';
+        case 'NONE':
+            return terminal ? '남은 판단 항목은 없습니다.' : '지금 사용자 판단이 필요한 항목은 없습니다.';
+    }
+}
+/** 2단계 정보. 여기서는 내부 용어를 그대로 써도 된다 — 본문 이해에 필수가 아니어야 한다. */
+function detailLine(session, progress, now, liveness) {
+    const parts = session
+        ? [session.id, ROLE_WORDS[session.role], STATUS_WORDS[session.status]]
+        : [progress?.logicalSessionId ?? '(세션 미상)', '거둔 세션'];
+    if (progress) {
+        if (progress.verifier !== 'NONE')
+            parts.push(`검증 ${verifierWord(progress.verifier)}`);
+        if (progress.unresolved.length > 0)
+            parts.push(`미결 ${progress.unresolved.length}건`);
+        parts.push(`${minutesAgo(progress, now)}분 전 기준`);
+    }
+    else {
+        parts.push('진행 보고 없음');
+    }
+    // 있을 때만 덧붙인다 — 없다고 "활동 없음"을 적으면 그것도 판정이다
+    if (liveness) {
+        const tool = liveness.lastTool ? `(${liveness.lastTool})` : '';
+        parts.push(`최근 활동 ${minutesSince(liveness.lastActivityAt, now)}분 전${tool}`);
+    }
+    return parts.join(' · ');
+}
+const verifierWord = (v) => v === 'RUNNING' ? '진행 중' : v === 'PASS' ? 'PASS' : v === 'FAIL' ? 'FAIL' : '없음';
+function minutesAgo(p, now) {
+    return minutesSince(p.lastUpdatedAt, now);
+}
+function minutesSince(at, now) {
+    return Math.max(0, Math.round((now.getTime() - new Date(at).getTime()) / 60_000));
+}
+const isStale = (p, now) => !p.terminal && now.getTime() - new Date(p.lastUpdatedAt).getTime() > STALE_AFTER_MS;
+/**
+ * 목표 문장이 길면 첫 구절만 — 헤드라인이 목표 전문을 되뇌면 읽히지 않는다.
+ * ASCII 하이픈은 자르지 않는다: 식별자(G-2, spec-001)와 합성어에 흔해서
+ * 분리자로 쓰면 "G-2 …"가 "G"로 잘린다 (실측에서 걸렸다).
+ */
+function shortGoal(goal) {
+    const head = goal.split(/\s[—–]\s|\.\s/)[0]?.trim() ?? goal;
+    return head.length > 40 ? `${head.slice(0, 40)}…` : head;
+}
+function joinKorean(items) {
+    if (items.length <= 1)
+        return items[0] ?? '';
+    return `${items.slice(0, -1).join(', ')}, ${items[items.length - 1]}`;
+}

package/dist/core/operator/runtime-binding.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+export declare const RuntimeBinding: z.ZodObject<{
+    logicalSessionId: z.ZodString;
+    provider: z.ZodString;
+    physicalSessionId: z.ZodString;
+    workerId: z.ZodOptional<z.ZodString>;
+    runtimeKind: z.ZodOptional<z.ZodString>;
+    lastObservedState: z.ZodOptional<z.ZodString>;
+    capabilitySnapshot: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: string;
+    logicalSessionId: string;
+    provider: string;
+    physicalSessionId: string;
+    workerId?: string | undefined;
+    runtimeKind?: string | undefined;
+    lastObservedState?: string | undefined;
+    capabilitySnapshot?: Record<string, boolean> | undefined;
+}, {
+    updatedAt: string;
+    logicalSessionId: string;
+    provider: string;
+    physicalSessionId: string;
+    workerId?: string | undefined;
+    runtimeKind?: string | undefined;
+    lastObservedState?: string | undefined;
+    capabilitySnapshot?: Record<string, boolean> | undefined;
+}>;
+export type RuntimeBinding = z.infer<typeof RuntimeBinding>;
+export type ClaimOutcome = {
+    ok: true;
+    binding: RuntimeBinding;
+}
+/** 이미 다른 Physical owner가 있다. 자동 탈취는 없다 — 명시적 rebind가 필요하다. */
+ | {
+    ok: false;
+    reason: 'RUNTIME_CONFLICT';
+    current: RuntimeBinding;
+};
+/**
+ * Adapter가 구현해야 하는 소유권 계약 (C-03 §3.2).
+ *
+ * 하나의 Logical Session에 동시 active Physical owner는 최대 1개다.
+ * claim은 원자적이어야 한다(`ScopedStore.setIfAbsent` 기반) — 두 Physical Session이
+ * 동시에 집으면 정확히 하나만 성공한다.
+ */
+export interface RuntimeBindings {
+    /** owner가 없으면 잡는다. 있으면 RUNTIME_CONFLICT — 기다리지도 뺏지도 않는다. */
+    claim(binding: Omit<RuntimeBinding, 'updatedAt'>, at: string): Promise<ClaimOutcome>;
+    /** 관찰값 갱신. owner가 아닌 Physical Session의 갱신은 거부한다. */
+    observe(logicalSessionId: string, physicalSessionId: string, patch: Partial<Pick<RuntimeBinding, 'workerId' | 'runtimeKind' | 'lastObservedState' | 'capabilitySnapshot'>>, at: string): Promise<ClaimOutcome>;
+    /** owner 스스로 내려놓는다. 남의 것은 못 놓는다. */
+    release(logicalSessionId: string, physicalSessionId: string): Promise<boolean>;
+    /**
+     * 죽은 owner를 사람이 확인하고 갈아끼운다. 자동 탈취가 아니라 명시적 복구다 —
+     * stale 자동 회수는 MVP에 넣지 않는다 (C-03 §3.2).
+     */
+    rebind(binding: Omit<RuntimeBinding, 'updatedAt'>, at: string): Promise<RuntimeBinding>;
+    get(logicalSessionId: string): Promise<RuntimeBinding | null>;
+}

package/dist/core/operator/runtime-binding.js

@@ -0,0 +1,22 @@
+// RuntimeBinding — Logical Session과 Physical Host 실행의 연결 (C-03 §3).
+//
+// 여기에는 provider-neutral한 형태와 계약만 있다. 실제 저장(StateStore.scope)은 Adapter
+// 몫이다 — PresentationRecord와 같은 이유다(C-02 §3): provider가 늘 때 Core 스키마가
+// 흔들리면 안 되고, runtime 관찰값은 정본이 아니다. Core EntityMap에 physical id가
+// 들어가는 순간 이 경계는 무너진다.
+//
+// Binding은 관찰 metadata이자 **ownership claim**이다. Logical ≠ Physical은 승계를
+// 허용하는 것이지 동시 실행을 허용하는 것이 아니다 — 서로 다른 Physical Session 둘이
+// 같은 ACTIVE 세션을 동시에 이어가면 같은 계약 위에서 두 손이 움직인다.
+import { z } from 'zod';
+import { SessionId, Timestamp } from "../model/ids.js";
+export const RuntimeBinding = z.object({
+    logicalSessionId: SessionId,
+    provider: z.string().min(1), // Adapter가 자기 이름을 댄다 — Core는 값을 해석하지 않는다
+    physicalSessionId: z.string().min(1),
+    workerId: z.string().optional(),
+    runtimeKind: z.string().optional(), // 'interactive' | 'background' | 'subagent' 등 provider 어휘
+    lastObservedState: z.string().optional(), // provider가 주는 상태 그대로 — Core는 해석하지 않는다
+    capabilitySnapshot: z.record(z.boolean()).optional(),
+    updatedAt: Timestamp,
+});

package/dist/core/policy/ownership.d.ts

@@ -0,0 +1,44 @@
+/** decision domain 이름 문법. 소문자 kebab-case — 문서·CLI·JSON에서 같은 모양으로 읽힌다. */
+export declare const DECISION_DOMAIN: RegExp;
+export type OwnershipSpec = {
+    /** 이 역할의 쓰기 영역. 결정만 하는 역할(product 등)은 비어 있을 수 있다. */
+    paths: string[];
+    /** 이 역할이 최종 결정권을 갖는 decision domain 목록. */
+    authorities: string[];
+};
+export type OwnershipMap = Record<string, OwnershipSpec>;
+export type AuthorityLookup = {
+    kind: 'RESOLVED';
+    role: string;
+}
+/** 아무도 자기 것이라 적지 않았다. */
+ | {
+    kind: 'UNDECLARED';
+}
+/** 둘 이상이 자기 것이라 적었다. 고르지 않는다 — 후보를 그대로 돌려준다. */
+ | {
+    kind: 'AMBIGUOUS';
+    candidates: string[];
+};
+/** 이 decision domain의 결정권자는 누구인가. */
+export declare function lookupAuthority(map: OwnershipMap | undefined, domain: string): AuthorityLookup;
+/** 선언된 decision domain 전체. 정렬해 돌려주므로 렌더 순서가 흔들리지 않는다. */
+export declare function decisionDomains(map: OwnershipMap | undefined): string[];
+export type OwnerLookup = {
+    kind: 'RESOLVED';
+    role: string;
+}
+/** 쓰기 범위를 통째로 품는 역할이 없다. 두 파트에 걸쳐 있거나 지도 밖이다. */
+ | {
+    kind: 'UNDECLARED';
+} | {
+    kind: 'AMBIGUOUS';
+    candidates: string[];
+};
+/**
+ * 이 쓰기 범위는 누구 영역인가. **전부**를 품는 역할만 후보다 — 일부만 품는 역할을
+ * owner로 세우면 나머지 경로가 남의 영역인 채로 세션이 굴러간다.
+ *
+ * 범위가 비어 있으면(쓰지 않는 세션) 판정하지 않는다. 아무 역할이나 답이 되기 때문이다.
+ */
+export declare function lookupOwnerByPaths(map: OwnershipMap | undefined, writeBoundary: readonly string[]): OwnerLookup;

package/dist/core/policy/ownership.js

@@ -0,0 +1,46 @@
+// Ownership Map — 누가 어디를 쓰고 무엇을 결정하는가의 선언 (C-04 §6).
+//
+// 여기는 **선언을 읽는 곳**이지 판정하는 곳이 아니다. "이 세션을 막을 것인가"는 발급과
+// preflight가 정하고, 이 모듈은 Profile이 뭐라고 적었는지만 돌려준다.
+//
+// 결정권자가 갈리는 경우를 조용히 하나로 좁히지 않는다. 두 역할이 같은 결정을 자기
+// 것이라 적었다면 그건 프로젝트가 아직 정하지 않았다는 뜻이고, 그 사실이 답이다 —
+// 이름이 비슷하다는 이유로 하나를 고르면 사람은 그 선택을 영영 보지 못한다.
+import { isWithinScopes } from "./scope.js";
+/** decision domain 이름 문법. 소문자 kebab-case — 문서·CLI·JSON에서 같은 모양으로 읽힌다. */
+export const DECISION_DOMAIN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** 이 decision domain의 결정권자는 누구인가. */
+export function lookupAuthority(map, domain) {
+    const candidates = Object.entries(map ?? {})
+        .filter(([, spec]) => spec.authorities.includes(domain))
+        .map(([role]) => role)
+        .sort();
+    if (candidates.length === 0)
+        return { kind: 'UNDECLARED' };
+    if (candidates.length > 1)
+        return { kind: 'AMBIGUOUS', candidates };
+    return { kind: 'RESOLVED', role: candidates[0] };
+}
+/** 선언된 decision domain 전체. 정렬해 돌려주므로 렌더 순서가 흔들리지 않는다. */
+export function decisionDomains(map) {
+    return [...new Set(Object.values(map ?? {}).flatMap((spec) => spec.authorities))].sort();
+}
+/**
+ * 이 쓰기 범위는 누구 영역인가. **전부**를 품는 역할만 후보다 — 일부만 품는 역할을
+ * owner로 세우면 나머지 경로가 남의 영역인 채로 세션이 굴러간다.
+ *
+ * 범위가 비어 있으면(쓰지 않는 세션) 판정하지 않는다. 아무 역할이나 답이 되기 때문이다.
+ */
+export function lookupOwnerByPaths(map, writeBoundary) {
+    if (writeBoundary.length === 0)
+        return { kind: 'UNDECLARED' };
+    const candidates = Object.entries(map ?? {})
+        .filter(([, spec]) => spec.paths.length > 0 && writeBoundary.every((s) => isWithinScopes(s, spec.paths)))
+        .map(([role]) => role)
+        .sort();
+    if (candidates.length === 0)
+        return { kind: 'UNDECLARED' };
+    if (candidates.length > 1)
+        return { kind: 'AMBIGUOUS', candidates };
+    return { kind: 'RESOLVED', role: candidates[0] };
+}

package/dist/core/policy/policy.d.ts

@@ -0,0 +1,99 @@
+import type { ActorRole } from '../model/entities.ts';
+/** OM §5.1. Green/Yellow/Red를 정책 계층으로 승격한 것. */
+export type Verdict = 'ALLOW' | 'SOFT_DENY' | 'HARD_DENY';
+export type RoleName = Exclude<ActorRole, 'controller'> | 'planner' | 'researcher' | 'implementer' | 'verifier';
+/**
+ * 한 계층이 기여하는 정책 조각. 계층 순서는 Resolver가 정한다
+ * (Vanilla Defaults → Project Profile → Operational Preset → User Local Override).
+ */
+export type PolicyLayer = {
+    id: string;
+    /** 해제 불가 금지 항목. 하위 계층은 추가만 할 수 있다 (union·immutable). */
+    hardDeny?: readonly string[];
+    /** 기본 금지. Controller의 Policy Exception으로만 개별 허용된다 (union). */
+    softDeny?: readonly string[];
+    /**
+     * 명시 허용. HARD DENY 항목을 여기 적으면 해제 시도로 보고 resolve를 실패시킨다 —
+     * 조용히 무시하면 계약과 실권한이 어긋난 채로 굴러간다.
+     */
+    allow?: readonly string[];
+    /** Role별 최대 쓰기 범위. 하위 계층은 이보다 좁혀야 한다 (intersection). */
+    roleScopes?: Partial<Record<RoleName, readonly string[]>>;
+    /** scalar 설정. `lockedSettings`에 걸린 키는 하위 값이 무시된다. */
+    settings?: Readonly<Record<string, string | number | boolean>>;
+    lockedSettings?: readonly string[];
+    /** 하위 값으로 통째 교체되는 목록. */
+    replaceLists?: Readonly<Record<string, readonly string[]>>;
+    /** 상위+하위가 합쳐지는 목록. */
+    unionLists?: Readonly<Record<string, readonly string[]>>;
+    requiredCapabilities?: readonly string[];
+    optionalCapabilities?: readonly string[];
+};
+export type ResolvedPolicy = {
+    hardDeny: string[];
+    softDeny: string[];
+    roleScopes: Partial<Record<RoleName, string[]>>;
+    settings: Record<string, string | number | boolean>;
+    lockedSettings: string[];
+    lists: Record<string, string[]>;
+    requiredCapabilities: string[];
+    optionalCapabilities: string[];
+    /** 어떤 계층이 어떤 순서로 합쳐졌는지 — 재현성 기록(B-10 profile.lock)의 입력이다. */
+    layers: string[];
+};
+export type PolicyViolation = {
+    layer: string;
+    kind: 'HARD_DENY_ESCAPE' | 'SOFT_DENY_ESCAPE' | 'SCOPE_ESCALATION' | 'INVALID_SCOPE' | 'LOCKED_SETTING';
+    detail: string;
+};
+/** scalar — 잠기지 않은 키만 하위 값이 이긴다. */
+export declare function mergeScalar<T>(upper: T | undefined, lower: T | undefined, locked: boolean): T | undefined;
+/** replace-list — 하위가 있으면 통째로 교체. */
+export declare function mergeReplaceList(upper?: readonly string[], lower?: readonly string[]): string[];
+/** union-list — 합치고 중복 제거. 순서는 상위 먼저. */
+export declare function mergeUnionList(upper?: readonly string[], lower?: readonly string[]): string[];
+/**
+ * permission scope — lower-wins가 아니라 교집합이다.
+ * 하위가 상위 범위를 벗어나면 조용히 좁히지 않고 위반으로 보고한다. 조용한 clamp는
+ * 계약서에 적힌 범위와 실제 권한이 다른 상태를 만든다 (OM §4.7).
+ * 문법 밖 패턴은 판정할 수 없으므로 통과시키지 않고 따로 보고한다.
+ */
+export declare function intersectScopes(upper: readonly string[] | undefined, lower: readonly string[] | undefined): {
+    scopes: string[];
+    escalations: string[];
+    invalid: string[];
+};
+/**
+ * 상위 → 하위 순으로 받은 계층들을 하나의 정책으로 합친다.
+ * 위반(HARD DENY 해제 시도·범위 확장·잠긴 설정 덮어쓰기)은 예외가 아니라 목록으로
+ * 돌려준다 — Resolver가 전부 모아 한 번에 보고할 수 있어야 하기 때문이다.
+ */
+export declare function mergePolicyLayers(layers: readonly PolicyLayer[]): {
+    policy: ResolvedPolicy;
+    violations: PolicyViolation[];
+};
+export type PolicyQuery = {
+    /** 'external.write' · 'dependency.add' 같은 행위 키. */
+    action: string;
+    /** 파일을 쓰는 행위면 대상 경로. */
+    path?: string;
+    role?: RoleName;
+    /** Session Contract가 실제로 허용받은 쓰기 범위 (Profile 범위보다 좁아야 한다). */
+    writeBoundary?: readonly string[];
+    /**
+     * Controller가 이 Session에 한해 허용한 SOFT DENY 항목 (OM §5.1).
+     * Execution Grant와는 다른 것이다 — 이건 기존 Session 안의 제한적 허용일 뿐이다.
+     */
+    policyExceptions?: readonly string[];
+};
+export type PolicyDecision = {
+    verdict: Verdict;
+    reason: string;
+};
+export declare function evaluate(policy: ResolvedPolicy, query: PolicyQuery): PolicyDecision;
+/**
+ * DENY에 닿았을 때 세션이 무엇을 해야 하는지 (OM §5.3).
+ * 세션 전체를 즉시 중단하는 것이 기본이 아니다 — Goal 달성 가능 여부로 갈린다.
+ */
+export type DenyResponse = 'CONTINUE' | 'DEFER_AND_CONTINUE' | 'RECORD_UNRESOLVED_AND_CONTINUE' | 'CHECKPOINT_AND_RETURN';
+export declare function denyResponse(verdict: Verdict, blocksGoal: boolean): DenyResponse;

package/dist/core/policy/policy.js

@@ -0,0 +1,147 @@
+// Policy Layer — 무엇이 자율이고 무엇이 금지인지, 그리고 계층을 합칠 때의 규칙.
+// 정본: OM §5(3등급·상속·DENY 접촉 시 동작), §4.7(merge semantics).
+//
+// 핵심 불변식 둘:
+//  - 하위 계층은 상위보다 넓은 권한을 가질 수 없다. 권한 범위는 lower-wins가 아니라 교집합이다.
+//  - HARD DENY는 하위가 해제할 수 없다. Policy Exception으로도, Session Prompt로도 안 된다.
+import { isWithinScopes, parseScope, pathInScope } from "./scope.js";
+// ── merge semantics (OM §4.7) ───────────────────────────────────────────────
+/** scalar — 잠기지 않은 키만 하위 값이 이긴다. */
+export function mergeScalar(upper, lower, locked) {
+    if (locked)
+        return upper ?? lower;
+    return lower ?? upper;
+}
+/** replace-list — 하위가 있으면 통째로 교체. */
+export function mergeReplaceList(upper = [], lower) {
+    return [...(lower ?? upper)];
+}
+/** union-list — 합치고 중복 제거. 순서는 상위 먼저. */
+export function mergeUnionList(upper = [], lower = []) {
+    return [...new Set([...upper, ...lower])];
+}
+/**
+ * permission scope — lower-wins가 아니라 교집합이다.
+ * 하위가 상위 범위를 벗어나면 조용히 좁히지 않고 위반으로 보고한다. 조용한 clamp는
+ * 계약서에 적힌 범위와 실제 권한이 다른 상태를 만든다 (OM §4.7).
+ * 문법 밖 패턴은 판정할 수 없으므로 통과시키지 않고 따로 보고한다.
+ */
+export function intersectScopes(upper, lower) {
+    const invalid = [...(lower ?? []), ...(upper ?? [])].filter((pattern) => parseScope(pattern) === null);
+    if (!lower)
+        return { scopes: [...(upper ?? [])], escalations: [], invalid };
+    if (!upper)
+        return { scopes: [...lower], escalations: [], invalid };
+    const valid = lower.filter((pattern) => parseScope(pattern) !== null);
+    const escalations = valid.filter((pattern) => !isWithinScopes(pattern, upper));
+    return { scopes: valid.filter((pattern) => isWithinScopes(pattern, upper)), escalations, invalid };
+}
+// ── 계층 병합 ───────────────────────────────────────────────────────────────
+/**
+ * 상위 → 하위 순으로 받은 계층들을 하나의 정책으로 합친다.
+ * 위반(HARD DENY 해제 시도·범위 확장·잠긴 설정 덮어쓰기)은 예외가 아니라 목록으로
+ * 돌려준다 — Resolver가 전부 모아 한 번에 보고할 수 있어야 하기 때문이다.
+ */
+export function mergePolicyLayers(layers) {
+    const violations = [];
+    const policy = {
+        hardDeny: [],
+        softDeny: [],
+        roleScopes: {},
+        settings: {},
+        lockedSettings: [],
+        lists: {},
+        requiredCapabilities: [],
+        optionalCapabilities: [],
+        layers: [],
+    };
+    for (const layer of layers) {
+        policy.layers.push(layer.id);
+        // 금지는 union이며 제거 연산이 없다. 상속된 금지를 allow로 뚫으려는 시도는 위반이다.
+        // SOFT DENY도 마찬가지다 — 그 해제는 Controller가 특정 Session에 주는 Policy
+        // Exception으로만 일어나고, 구성 계층이 미리 풀어둘 수 있는 것이 아니다 (OM §5.1).
+        for (const item of layer.allow ?? []) {
+            if (policy.hardDeny.includes(item)) {
+                violations.push({
+                    layer: layer.id,
+                    kind: 'HARD_DENY_ESCAPE',
+                    detail: `'${item}' is HARD DENY and cannot be re-allowed by a lower layer`,
+                });
+            }
+            else if (policy.softDeny.includes(item)) {
+                violations.push({
+                    layer: layer.id,
+                    kind: 'SOFT_DENY_ESCAPE',
+                    detail: `'${item}' is SOFT DENY — only a controller policy exception can permit it`,
+                });
+            }
+        }
+        policy.hardDeny = mergeUnionList(policy.hardDeny, layer.hardDeny);
+        // 상위가 금지하지 않은 항목이라도 하위가 조일 수 있다 — 강화 방향은 언제나 열려 있다.
+        policy.softDeny = mergeUnionList(policy.softDeny, layer.softDeny).filter((i) => !policy.hardDeny.includes(i));
+        for (const [role, requested] of Object.entries(layer.roleScopes ?? {})) {
+            const { scopes, escalations, invalid } = intersectScopes(policy.roleScopes[role], requested);
+            if (escalations.length > 0) {
+                violations.push({
+                    layer: layer.id,
+                    kind: 'SCOPE_ESCALATION',
+                    detail: `${role} requested ${escalations.join(', ')} outside the inherited scope`,
+                });
+            }
+            if (invalid.length > 0) {
+                violations.push({
+                    layer: layer.id,
+                    kind: 'INVALID_SCOPE',
+                    detail: `${role} scope ${invalid.join(', ')} is not valid ASC scope grammar`,
+                });
+            }
+            policy.roleScopes[role] = scopes;
+        }
+        for (const [key, value] of Object.entries(layer.settings ?? {})) {
+            const locked = policy.lockedSettings.includes(key);
+            if (locked && policy.settings[key] !== value) {
+                violations.push({ layer: layer.id, kind: 'LOCKED_SETTING', detail: `'${key}' is locked by an upper layer` });
+            }
+            const merged = mergeScalar(policy.settings[key], value, locked);
+            if (merged !== undefined)
+                policy.settings[key] = merged;
+        }
+        policy.lockedSettings = mergeUnionList(policy.lockedSettings, layer.lockedSettings);
+        for (const [key, values] of Object.entries(layer.replaceLists ?? {})) {
+            policy.lists[key] = mergeReplaceList(policy.lists[key], values);
+        }
+        for (const [key, values] of Object.entries(layer.unionLists ?? {})) {
+            policy.lists[key] = mergeUnionList(policy.lists[key], values);
+        }
+        policy.requiredCapabilities = mergeUnionList(policy.requiredCapabilities, layer.requiredCapabilities);
+        policy.optionalCapabilities = mergeUnionList(policy.optionalCapabilities, layer.optionalCapabilities);
+    }
+    return { policy, violations };
+}
+export function evaluate(policy, query) {
+    if (policy.hardDeny.includes(query.action)) {
+        // Policy Exception이 있어도 뚫리지 않는다. 외부 write 같은 항목은 별도 Execution
+        // Grant라는 다른 계약으로만 수행된다 (OM §5.2).
+        return { verdict: 'HARD_DENY', reason: `'${query.action}' is HARD DENY` };
+    }
+    if (query.path !== undefined) {
+        const boundary = query.writeBoundary ?? policy.roleScopes[query.role ?? 'implementer'] ?? [];
+        if (!pathInScope(query.path, boundary)) {
+            return { verdict: 'HARD_DENY', reason: `'${query.path}' is outside the write boundary` };
+        }
+    }
+    if (policy.softDeny.includes(query.action)) {
+        if (query.policyExceptions?.includes(query.action)) {
+            return { verdict: 'ALLOW', reason: `'${query.action}' allowed by policy exception` };
+        }
+        return { verdict: 'SOFT_DENY', reason: `'${query.action}' requires a policy exception` };
+    }
+    return { verdict: 'ALLOW', reason: 'within contract' };
+}
+export function denyResponse(verdict, blocksGoal) {
+    if (verdict === 'ALLOW')
+        return 'CONTINUE';
+    if (verdict === 'HARD_DENY')
+        return blocksGoal ? 'CHECKPOINT_AND_RETURN' : 'RECORD_UNRESOLVED_AND_CONTINUE';
+    return blocksGoal ? 'CHECKPOINT_AND_RETURN' : 'DEFER_AND_CONTINUE';
+}