@asc-agent/runtime 0.1.0

package/dist/core/workspace/resolve.d.ts

@@ -0,0 +1,34 @@
+import { type WorkspaceIndex } from './index-store.ts';
+export declare const ASC_DIR = ".asc";
+export type Resolution = {
+    kind: 'EXPLICIT';
+    root: string;
+}
+/** 이 기계에 등록된 workspace. 경로가 바뀌어도 따라온다. */
+ | {
+    kind: 'REGISTERED';
+    root: string;
+    workspaceId: string;
+    locator: string;
+}
+/** 저장소 안의 `.asc/` — 팀이 채택했거나 아직 이전하지 않은 개인 legacy다. */
+ | {
+    kind: 'PROJECT_LOCAL';
+    root: string;
+    projectRoot: string;
+} | {
+    kind: 'UNRESOLVED';
+    detail: string;
+};
+export type ResolveInput = {
+    cwd: string;
+    /** `--root` 로 사람이 지정한 값. 있으면 무조건 이긴다. */
+    explicitRoot?: string;
+    index?: WorkspaceIndex;
+    /** 여기를 넘어서는 위로 올라가지 않는다. 보통 사용자 홈. */
+    stopAt?: string;
+    exists?: (path: string) => Promise<boolean>;
+};
+export declare function resolveWorkspace(input: ResolveInput): Promise<Resolution>;
+/** 사람이 읽는 한 줄. 왜 그 뿌리인지가 함께 와야 사람이 틀린 결합을 알아챈다. */
+export declare function resolutionLine(resolution: Resolution): string;

package/dist/core/workspace/resolve.js

@@ -0,0 +1,89 @@
+// Workspace Resolution — "지금 여기는 어느 ASC runtime인가"를 정하는 **한 곳** (C-11 §3·B-45).
+//
+// 지금까지 이 질문의 답은 네 군데에 따로 있었다: CLI의 discoverRoot, attach의
+// discoverProjectRoot, bootstrap의 내부 조립, 그리고 guard hook 안의 복제본.
+// 넷이 조금씩 다르게 답하면 "어디는 되고 어디는 안 되는" 상태가 생기고, 실제로 그랬다
+// (`--root` 가 host 명령에만 안 먹던 비대칭).
+//
+// 우선순위는 명시 > 등록 > 발견이다:
+//
+//   1. explicit root      사람이 말한 것이 이긴다
+//   2. workspace index    이 기계에 등록된 locator (경로가 바뀌어도 따라온다)
+//   3. project-adopted    저장소 안의 `.asc/` — 팀이 채택한 경우 (legacy 개인 사용 포함)
+//   4. UNRESOLVED         모르면 모른다고 한다
+//
+// **3번의 탐색에는 경계가 있다.** 예전에는 파일시스템 루트까지 올라갔는데, 사용자 홈에
+// `~/.asc` 가 생기는 순간 홈 아래 아무 저장소나 그 뿌리로 오인 매칭된다. 그래서 홈을
+// 넘지 않고, 정지선(`stopAt`)을 지난 뒤에는 더 올라가지 않는다.
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { normalizeLocator } from "./identity.js";
+import { lookupLocator } from "./index-store.js";
+export const ASC_DIR = '.asc';
+const defaultExists = async (path) => {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export async function resolveWorkspace(input) {
+    if (input.explicitRoot)
+        return { kind: 'EXPLICIT', root: input.explicitRoot };
+    const exists = input.exists ?? defaultExists;
+    if (input.index) {
+        const found = lookupLocator(input.index, input.cwd);
+        // 등록돼 있는데 뿌리가 없으면 **넘어가지 않는다.** 조용히 다음 후보로 가면
+        // 사라진 workspace 대신 엉뚱한 것에 붙는다 (C-11 §4 조건부 fail-closed와 같은 태도).
+        if (found) {
+            return (await exists(found.root))
+                ? { kind: 'REGISTERED', root: found.root, workspaceId: found.workspaceId, locator: found.locator }
+                : {
+                    kind: 'UNRESOLVED',
+                    detail: `${found.workspaceId} 가 등록돼 있으나 runtime(${found.root})이 없다 — 옮겼거나 지워졌다`,
+                };
+        }
+    }
+    const local = await findProjectLocal(input.cwd, input.stopAt, exists);
+    if (local)
+        return { kind: 'PROJECT_LOCAL', root: join(local, ASC_DIR), projectRoot: local };
+    return { kind: 'UNRESOLVED', detail: '이 경로에 붙은 ASC workspace가 없다' };
+}
+/**
+ * 저장소 안의 `.asc/` 를 위로 올라가며 찾되 **경계를 지킨다**.
+ *
+ * `stopAt`(보통 홈)을 포함해 그 위로는 보지 않는다. 홈에 `~/.asc` 가 있는 것은 정상이고,
+ * 그것을 프로젝트 상태로 읽으면 홈 아래 모든 저장소가 한 workspace가 된다.
+ */
+async function findProjectLocal(start, stopAt, exists) {
+    const boundary = stopAt ? normalizeLocator(resolve(stopAt)) : null;
+    let dir = resolve(start);
+    for (;;) {
+        const normalized = normalizeLocator(dir);
+        // 정지선 자체는 보지 않는다 — 홈의 `.asc` 는 user runtime이지 프로젝트 상태가 아니다
+        if (boundary && normalized === boundary)
+            return null;
+        if (await exists(join(dir, ASC_DIR)))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** 사람이 읽는 한 줄. 왜 그 뿌리인지가 함께 와야 사람이 틀린 결합을 알아챈다. */
+export function resolutionLine(resolution) {
+    switch (resolution.kind) {
+        case 'EXPLICIT':
+            return `runtime: ${resolution.root} (given with --root)`;
+        case 'REGISTERED':
+            return `runtime: ${resolution.root} (workspace ${resolution.workspaceId} · ${resolution.locator})`;
+        case 'PROJECT_LOCAL':
+            return `runtime: ${resolution.root} (.asc inside the repository — team-adopted, or personal state not yet migrated)`;
+        case 'UNRESOLVED':
+            return `no runtime — ${resolution.detail}`;
+    }
+}

package/dist/ports/adapter.d.ts

@@ -0,0 +1,35 @@
+import type { AdapterDescriptor, BindingCandidate, ProbeState } from '../core/binding/types.ts';
+/** discover가 훑는 환경. 파일·프로세스 접근을 호출자가 정해 준다 — adapter가 임의로 뒤지지 않는다. */
+export type DiscoveryContext = {
+    /** 대상 프로젝트 뿌리. */
+    projectRoot: string;
+    /** 환경변수. 자격 **존재 여부** 판단에만 쓰고 값을 실어 나르지 않는다. */
+    env?: NodeJS.ProcessEnv;
+};
+export type ProbeResult = {
+    state: ProbeState;
+    /** 상태만 주면 고칠 수가 없다. UNCONFIGURED면 무엇을 채워야 하는지 말한다. */
+    detail?: string;
+    /** 실측으로 확인된 제공 범위. describe보다 좁을 수 있다. */
+    provides?: readonly BindingCandidate['provides'][number][];
+};
+/**
+ * adapter 자체가 지금 쓸 수 있는 상태인가 — **프로젝트와 무관한 사실**이다.
+ *
+ * 왜 binding probe와 나누는가: "도구는 깔려 있고 자격도 있다"와 "이 프로젝트가 그 도구에
+ * 연결돼 있다"는 다른 사실이다. 둘을 합치면 사람이 무엇을 해야 하는지 알 수 없다 —
+ * 도구를 설치할 일인지, 이 프로젝트를 붙일 일인지.
+ *
+ * 제공하지 않는 adapter는 그 구분이 필요 없다는 뜻이다.
+ */
+export type RuntimeStatus = {
+    state: ProbeState;
+    detail?: string;
+};
+export interface Adapter {
+    describe(): AdapterDescriptor;
+    /** 후보가 없으면 빈 배열. 그것도 사람이 알아야 할 사실이다. */
+    discover(context: DiscoveryContext): Promise<BindingCandidate[]>;
+    probe(candidate: BindingCandidate, context: DiscoveryContext): Promise<ProbeResult>;
+    runtime?(context: DiscoveryContext): Promise<RuntimeStatus>;
+}

package/dist/ports/adapter.js

@@ -0,0 +1,12 @@
+// Adapter Contract — 외부 시스템 하나를 ASC에 잇는 모듈의 공통 lifecycle (C-09 §5).
+//
+// 세 단계는 비용도 부작용도 다르다. 합치면 "설정을 안 한 것"과 "닿지 않는 것"이
+// 구분되지 않고, 계획을 세우려고 부른 함수가 네트워크를 친다.
+//
+//   describe()  정적 선언. 호출도 네트워크도 없다
+//   discover()  이 프로젝트·환경에서 연결 가능한 후보를 찾는다 (로컬 관찰)
+//   probe()     그 후보가 실제로 쓸 수 있는지 잰다 (외부 접촉 가능)
+//
+// adapter는 자기가 제공하는 Port만 구현한다. 전부 구현할 필요가 없다 —
+// 작업 추적기가 변경 경로를 모르고, 전달 채널은 그 둘 다 모른다 (C-09 §2.1).
+export {};

package/dist/ports/approval.d.ts

@@ -0,0 +1,98 @@
+import type { ApprovalDecision } from '../core/model/entities.ts';
+import type { DecisionView } from '../core/view/decision-view.ts';
+/**
+ * 채널이 지원하는 표현 수단 (OM §11.4). Profile은 원하는 UX만 선언하고, Adapter는
+ * 지원하지 못하는 수단을 아래로 degrade한다:
+ * rich → interactive → text → Local Inbox.
+ */
+export type ApprovalCapability = 'interactive_actions' | 'rich_blocks' | 'dialogs' | 'ephemeral_feedback' | 'threads' | 'priority' | 'acknowledgement' | 'silent_notification';
+/**
+ * 채널에 표시한 결과. Core는 이 값을 해석하지 않고 그대로 Adapter에게 돌려준다 —
+ * 외부 메시지 식별자(PresentationRecord)의 소유자는 Adapter다 (아래 주석 참조).
+ */
+export type PresentationOutcome = {
+    ok: true;
+    externalRef?: string;
+}
+/** best-effort 실패. canonical state에는 영향이 없어야 한다 (C-01 §9). */
+ | {
+    ok: false;
+    error: string;
+};
+/**
+ * PresentationRecord(request ↔ 외부 표시물 매핑) 소유 결정 — B-02에서 확정.
+ *
+ * **Adapter-owned metadata로 둔다. Core Logical Entity가 아니다.**
+ * 근거:
+ *  - Core가 채널별 매핑을 entity로 들면 채널이 늘 때마다 Core 스키마가 흔들린다.
+ *    Core는 플랫폼을 몰라야 한다는 OM §11.3과 정면으로 어긋난다.
+ *  - 매핑은 정본이 아니다 (C-01 §9). 정본 entity와 같은 저장·전이 규율을 줄 이유가 없다.
+ *  - 표시 갱신은 best-effort다. 실패가 canonical state에 영향을 주지 않으려면 매핑이
+ *    Core 전이 경로 밖에 있어야 한다.
+ * 저장 위치: StateStore.scope(adapterId)의 격리 공간 (ports/state-store.ts).
+ * Core가 하는 일은 상태가 바뀐 view를 채널들에 알리는 것까지이고, 어떤 메시지를
+ * 고칠지는 각 Adapter가 자기 매핑을 보고 정한다.
+ */
+export interface ApprovalChannel {
+    readonly id: string;
+    readonly capabilities: ReadonlySet<ApprovalCapability>;
+    /** 새 요청을 사람에게 보인다. */
+    present(view: DecisionView): Promise<PresentationOutcome>;
+    /**
+     * 상태가 바뀐 요청의 표현을 갱신한다 (다른 채널에서 결정됨 등).
+     * 실패해도 Core는 진행한다 — 낡은 버튼 입력은 어차피 CAS가 거절한다.
+     */
+    update(view: DecisionView): Promise<PresentationOutcome>;
+}
+/** 결정 제출 결과. 사람에게 무엇이 일어났는지 설명할 수 있을 만큼 구체적이어야 한다. */
+export type DecisionOutcome = {
+    ok: true;
+    view: DecisionView;
+}
+/** 다른 채널·다른 시점에 이미 결정됐다 (C-01 §7 STALE / ALREADY_DECIDED). */
+ | {
+    ok: false;
+    reason: 'ALREADY_DECIDED';
+    view: DecisionView;
+}
+/** 읽은 뒤 요청이 바뀌었다 — 다시 읽고 판단해야 한다. */
+ | {
+    ok: false;
+    reason: 'STALE';
+    view: DecisionView;
+}
+/** 승인 권한자가 아니다 (OM §11.6). 시도 자체를 History에 남긴다. */
+ | {
+    ok: false;
+    reason: 'FORBIDDEN_ACTOR';
+} | {
+    ok: false;
+    reason: 'NOT_ALLOWED_DECISION';
+} | {
+    ok: false;
+    reason: 'EXPIRED';
+} | {
+    ok: false;
+    reason: 'NOT_FOUND';
+};
+/**
+ * 채널이 Core로 결정을 밀어 넣는 입구. 방향이 중요하다 — Core가 채널을 폴링하지 않고,
+ * 채널이 사람의 명시적 입력을 받았을 때만 호출한다.
+ * Agent는 요청을 읽을 수 있지만 이 함수를 자기 판단으로 호출할 수 없다 (C-01 §5).
+ */
+export interface DecisionSink {
+    submit(decision: ApprovalDecision): Promise<DecisionOutcome>;
+}
+/**
+ * 결정 actor가 실제 승인 권한자인지 확인한다 (OM §11.6).
+ * Local이라는 이유로 무조건 신뢰하지 않는다 — Identity는 Credential이 아니며,
+ * Token은 Secret Store에 남고 여기에는 오지 않는다.
+ */
+export interface IdentityBinding {
+    /** channel에서 인증된 actor가 이 요청의 authorizedApprover와 같은 사람인가. */
+    verify(input: {
+        channel: string;
+        actor: string;
+        authorizedApprover: string;
+    }): Promise<boolean>;
+}

package/dist/ports/approval.js

@@ -0,0 +1,7 @@
+// Approval Port — 승인 요청을 사람에게 보이고 사람의 결정을 돌려받는 경계.
+// Core는 플랫폼 메시지 구조를 모른다 (OM §11.3). Messenger는 선택 구성요소이며,
+// 채널이 하나도 없어도 Local 경로만으로 승인 lifecycle이 완결되어야 한다.
+//
+// 멀티채널은 여러 요청이 아니라 하나의 요청에 대한 여러 표현이다 (C-01 §7) —
+// 모든 채널이 같은 requestId를 쓰고, 최초 유효 결정 이후의 입력은 CAS로 거절된다.
+export {};

package/dist/ports/change-context.d.ts

@@ -0,0 +1,22 @@
+export type ChangeSummary = {
+    reference: string;
+    /**
+     * 바뀐 경로들. ASC scope 문법과 대조 가능한 실제 경로여야 한다 (패턴이 아니다).
+     * provider가 일부만 주면 `truncated`로 그 사실을 알린다 — 없는 것을 없다고 하면
+     * "내 영역은 안 바뀌었다"는 틀린 판정이 나온다.
+     */
+    changedPaths: readonly string[];
+    truncated?: boolean;
+    /** 사람이 읽는 한두 줄. Core는 그대로 옮기고 요약하지 않는다. */
+    summary?: string;
+    /** 변경 묶음 식별자(커밋·리비전 등). adapter 소관 문자열. */
+    revisions?: readonly string[];
+    revisionMarker: string;
+    /** 검토·승인 상태. provider가 알려주는 만큼만. */
+    reviewState?: string;
+    missing?: boolean;
+};
+export interface ChangeContextPort {
+    readonly id: string;
+    getChange(reference: string): Promise<ChangeSummary>;
+}

package/dist/ports/change-context.js

@@ -0,0 +1,8 @@
+// Change Context Port — 무엇이 어디서 바뀌었는가 (C-09 §2.3).
+//
+// 이 Port가 따로 있는 이유는 relevance 판정 때문이다. "나를 불렀는가"가 아니라
+// "내 영역이 바뀌었는가"로 관련성을 보려면 변경 경로를 실제로 읽어야 한다 (C-07 §3.2).
+//
+// diff 전문을 다루지 않는다. Core는 경로와 요약까지만 필요하고, 그 이상은 사람이
+// provider에서 본다 — 전문을 끌어오면 조사 한 건이 통째로 비싸진다.
+export {};

package/dist/ports/event-source.d.ts

@@ -0,0 +1,42 @@
+import type { EventType, Priority } from '../core/model/entities.ts';
+/**
+ * 아직 분류되지 않은 원본 이벤트. eventKey는 provider가 만들고, dedupe는 log 훑기가
+ * 아니라 이 key의 exact lookup으로 한다 (OM §10.4).
+ */
+export type RawEvent = {
+    eventKey: string;
+    detectedAt: string;
+    reference: string;
+    /** Adapter가 아는 만큼의 힌트. 최종 분류·우선순위는 Monitor가 Profile 기준으로 정한다. */
+    hints?: {
+        type?: EventType;
+        priority?: Priority;
+        labels?: readonly string[];
+        actors?: readonly string[];
+    };
+    /** provider 원본. Phase B가 필요할 때만 들여다본다. */
+    raw?: unknown;
+};
+/** 다음 조회 시작점. 형태는 provider마다 다르므로 Core는 문자열로만 다룬다. */
+export type Cursor = string | null;
+export type EventBatch = {
+    events: RawEvent[];
+    cursor: Cursor;
+    /** 이번 회차에 더 남은 것이 있는가 — 폭주 시 나눠 가져오기 위함. */
+    hasMore?: boolean;
+};
+export interface EventSource {
+    readonly id: string;
+    /**
+     * "지금부터 보겠다"는 뜻의 cursor. 처음 붙인 저장소의 과거를 통째로 긁으면 그 자체가
+     * 잡음이 되므로, 시작점을 정해 두고 출발할 수 있어야 한다 (OM §18).
+     * 구현하지 않은 Adapter는 늘 처음부터 본다.
+     */
+    cursorFrom?(since: string): Cursor;
+    /**
+     * cursor 이후의 이벤트를 가져온다. 중간 실패 시 cursor를 전진시키지 않아도 되도록
+     * cursor 갱신 책임은 호출자(Monitor)에게 있다 — 누락보다 중복이 안전하고, 중복은
+     * dedupe가 거른다 (OM §10.5).
+     */
+    drain(cursor: Cursor): Promise<EventBatch>;
+}

package/dist/ports/event-source.js

@@ -0,0 +1,6 @@
+// Event Source Port — 외부 이벤트를 가져오는 경계. Monitor Engine이 특정 provider의
+// polling 구현에 묶이지 않게 한다 (OM §10.1).
+//
+// webhook·scheduled·manual scan도 같은 인터페이스로 노출한다: push형 Adapter는 수신분을
+// 내부 버퍼에 쌓아 두고 drain에서 돌려준다. Core가 두 가지 흐름 제어를 알 필요가 없다.
+export {};

package/dist/ports/inventory.d.ts

@@ -0,0 +1,53 @@
+/**
+ * provider가 아는 리소스 하나의 현재 모습. 필드는 **비교에 필요한 만큼만** 둔다 —
+ * 본문·댓글·변경 내용은 ResourceContext / ChangeContext의 몫이고, 여기에 끌어오면
+ * 전수 열거 한 번이 통째로 비싸진다.
+ */
+export type InventoryItem = {
+    /** provider-neutral 식별자. 문법은 adapter가 정하고 Core는 문자열로만 다룬다. */
+    reference: string;
+    /**
+     * provider의 상태 어휘를 그대로 둔다. Core는 이 값으로 분기하지 않고 비교만 한다 —
+     * 상태 이름을 Core가 해석하기 시작하면 provider 도메인이 Core로 올라온다.
+     */
+    state: string;
+    updatedAt: string;
+    /**
+     * 실질 변화 마커 (C-07 §4). adapter가 만들고 **Core는 같은지 다른지만 본다.**
+     * 무엇을 넣을지는 adapter가 정한다 — 갱신 시각 하나로는 댓글 외의 변화를 놓친다.
+     */
+    revisionMarker: string;
+    title?: string;
+    assignees?: readonly string[];
+    labels?: readonly string[];
+};
+export type InventoryQuery = {
+    /**
+     * 이 시각 이후 변한 것만. 생략하면 전부 — Census가 그렇게 쓴다.
+     * 상태로 거르지 않는다는 것이 이 Port의 계약이므로 state 필터는 두지 않는다.
+     */
+    updatedSince?: string;
+    /** adapter가 아는 리소스 갈래(이슈·변경요청·작업항목 등). 생략하면 adapter 기본값. */
+    kinds?: readonly string[];
+};
+export type InventoryPage = {
+    items: InventoryItem[];
+    /**
+     * 다음 페이지 시작점. 없으면 끝이다.
+     * 페이지를 다 돌지 못했는데 끝인 척하면 Census가 "사라졌다"를 잘못 만들어낸다.
+     */
+    next?: string;
+    /**
+     * **마지막 페이지에서만 true가 될 수 있다** — "여기까지 오는 동안 빠짐이 없었다"는 뜻이다.
+     * 중간 페이지는 아직 알 수 없으므로 false다. 모르면 false다 (C-07 §8.2).
+     *
+     * 이 값이 false인 열거로 missing reference를 판정해서는 안 된다 — 페이지를 다 돌지
+     * 못한 목록으로 비교하면 멀쩡한 리소스가 사라졌다고 나온다.
+     */
+    complete: boolean;
+};
+export interface InventoryPort {
+    readonly id: string;
+    /** 한 페이지씩. 전부 도는 것은 호출자의 몫이다 — 중단·재개 지점을 Core가 쥔다. */
+    enumerate(query: InventoryQuery, cursor?: string): Promise<InventoryPage>;
+}

package/dist/ports/inventory.js

@@ -0,0 +1,12 @@
+// Inventory Port — provider가 지금 들고 있는 목록을 상태 무관하게 열거한다 (C-09 §2).
+//
+// EventSource와 답하는 질문이 다르다:
+//   EventSource  "그 사이에 무슨 일이 있었나"  — 증분. 놓치면 그대로 놓친다
+//   Inventory    "지금 무엇이 있나"            — 전수. 놓친 것을 찾아낸다
+//
+// 그래서 **닫힌 것도 포함한다.** 닫힌 Issue에 새 댓글이 달리고, 병합된 변경에 논의가
+// 이어지고, 끝난 작업의 설명이 고쳐진다. open만 세는 열거는 그 전부를 놓친다.
+//
+// 여기서 목록을 받아 무엇이 달라졌는지 판정하는 것은 Monitor의 몫이다 — 이 Port는
+// 비교하지 않고, 우선순위를 매기지 않고, 무엇이 중요한지도 모른다.
+export {};

package/dist/ports/presentation.d.ts

@@ -0,0 +1,62 @@
+import type { Priority } from '../core/model/entities.ts';
+import type { DecisionSummary } from '../core/view/decision-view.ts';
+/**
+ * 채널 제품이 아니라 **할 수 있는 일**로 정의한다 (C-08 §1.1). 이름을 채널로 잡으면
+ * 메신저가 아닌 전달 수단이 2급이 된다.
+ */
+export type PresentationCapability = 
+/** 묶음을 보여줄 수 있다. */
+'presentation.digest'
+/** 급한 것을 눈에 띄게 전달할 수 있다. */
+ | 'presentation.priority'
+/** 그 자리에서 사람의 결정을 받을 수 있다 (ApprovalChannel 쪽 표면). */
+ | 'approval.interactive';
+/** 묶음 한 덩어리. 무엇을 어떻게 그릴지는 adapter가 정한다. */
+export type DigestBatch = {
+    /** 이 묶음을 만든 시각. 사람이 "언제 것"인지 알아야 한다. */
+    at: string;
+    /**
+     * 우선순위 구간별 항목. 전부 **같은 request의 또 하나의 표현**이며 새 request가 아니다
+     * (C-08 §3.1).
+     */
+    groups: readonly {
+        priority: Priority;
+        items: readonly DecisionSummary[];
+    }[];
+    /**
+     * 보이지 않게 걸러진 것의 수. 숫자만 알려도 사람은 "무엇을 못 보고 있는지"를 안다 —
+     * 0으로 감추면 걸러졌다는 사실 자체가 사라진다.
+     */
+    suppressed?: {
+        shadow: number;
+        alreadyDecided: number;
+    };
+    /**
+     * 빠른 경로가 아니라 회수 경로에서 발견된 항목 수. coverage에 대한 정보이며
+     * 우선순위와 무관하다 (C-07 §1.6).
+     */
+    recovered?: number;
+};
+export type DeliveryOutcome = {
+    ok: true;
+    externalRef?: string;
+}
+/** best-effort 실패. canonical state에 영향이 없어야 한다 (C-08 §1.3). */
+ | {
+    ok: false;
+    error: string;
+};
+export interface PresentationPort {
+    readonly id: string;
+    readonly capabilities: ReadonlySet<PresentationCapability>;
+    /** 묶음 전달. `presentation.digest`를 제공하는 adapter만 의미 있게 구현한다. */
+    presentDigest(batch: DigestBatch): Promise<DeliveryOutcome>;
+    /**
+     * 지금 끊어야 하는 한 건. `presentation.priority`가 없으면 호출자가 digest로 내린다 —
+     * 조용히 무시하지 않고 degrade한다.
+     *
+     * 요약을 받는다. 더 필요하면 채널이 `requestId`로 다시 읽는다 — Core가 전체 view를
+     * 만들어 넘기면 전달 한 번에 조사 한 번이 딸려 붙는다.
+     */
+    presentUrgent?(item: DecisionSummary): Promise<DeliveryOutcome>;
+}

package/dist/ports/presentation.js

@@ -0,0 +1,13 @@
+// Presentation Port — 판단 요청을 사람에게 건네는 경계 (C-08 §1).
+//
+// `ApprovalChannel`(ports/approval.ts)과의 관계를 먼저 밝힌다:
+//   ApprovalChannel  요청 **하나**를 보이고 갱신한다. 이미 있고, 그대로 쓴다
+//   PresentationPort 요청 **묶음**을 건넨다. 이것이 여기서 새로 생기는 것이다
+//
+// 둘을 합치지 않는 이유: 묶음 전달을 제공하지만 그 자리에서 결정을 못 받는 채널이 있고
+// (메일이 그렇다), 반대도 있다. 하나의 인터페이스로 묶으면 그런 채널이 전체를 구현하지
+// 못하거나 빈 구현으로 거짓말을 하게 된다.
+//
+// 이 Port에는 결정 제출 표면이 없다 (C-08 §4). 묶고 보여주는 데까지이며, approve/dismiss는
+// 사람의 명시적 의사표현을 받아 기존 결정 경로로만 간다.
+export {};

package/dist/ports/renderer.d.ts

@@ -0,0 +1,23 @@
+import type { DecisionSummary, DecisionView } from '../core/view/decision-view.ts';
+/** 표현 밀도. 같은 view에서 채널 UX에 맞게 접거나 펼친다 (C-01 §3). */
+export type RenderDensity = 'summary' | 'full' | 'collapsible';
+/**
+ * 렌더 결과. Core는 내용물을 해석하지 않는다 — 문자열이든 채널별 블록 구조든
+ * 그대로 Channel에 넘긴다.
+ */
+export type Rendered = {
+    density: RenderDensity;
+    text: string;
+    blocks?: unknown;
+};
+export interface Renderer {
+    readonly id: string;
+    /**
+     * 상세 표현. reference는 어떤 density에서도 생략하지 않는다 — 사용자가 다른 채널에서
+     * 같은 요청을 지목하는 유일한 수단이기 때문이다 (C-01 §2).
+     * Stored Packet과 Current Context Overlay는 구분해 보여야 한다 (C-01 §6).
+     */
+    renderDecision(view: DecisionView, density: RenderDensity): Rendered;
+    /** 목록 표현. 복수 후보를 사람이 고를 수 있게 나열한다 (C-01 §11). */
+    renderList(items: readonly DecisionSummary[]): Rendered;
+}

package/dist/ports/renderer.js

@@ -0,0 +1,7 @@
+// Renderer Port — Shared Decision View Model을 사람이 읽는 표현으로 바꾸는 경계.
+// CLI·Messenger·Web UI가 같은 view를 각자의 방식으로 그리되, 필드의 의미와 request
+// reference는 바꾸지 않는다 (C-01 §3).
+//
+// Approval Channel과 역할이 다르다: Channel은 전달과 결정 수신, Renderer는 표현 생성.
+// 한 Adapter가 둘 다 구현할 수 있지만 계약은 분리해 둔다.
+export {};

package/dist/ports/resource-context.d.ts

@@ -0,0 +1,51 @@
+/** 논의 한 조각. 전문을 통째로 넘기지 않기 위해 조사 단계가 개수를 정한다. */
+export type ContextComment = {
+    id: string;
+    author: string;
+    at: string;
+    body: string;
+    /** 아직 닫히지 않은 논의인가. provider가 알려주지 않으면 생략한다 — 추측하지 않는다. */
+    unresolved?: boolean;
+};
+export type ResourceSnapshot = {
+    reference: string;
+    state: string;
+    title: string;
+    body?: string;
+    author?: string;
+    assignees?: readonly string[];
+    labels?: readonly string[];
+    updatedAt: string;
+    revisionMarker: string;
+    /** 연결된 다른 리소스. 문법은 adapter 소관이고 Core는 식별자로만 다룬다. */
+    related?: readonly string[];
+    /** 사라졌거나 접근할 수 없다. 없는 것과 못 읽는 것을 구분해야 판정이 성립한다. */
+    missing?: boolean;
+};
+export type CommentQuery = {
+    /** 최근 몇 개까지. 조사 depth가 정한다 — Port가 기본값을 강요하지 않는다. */
+    limit?: number;
+    /** 이 시각 이후만. 직전 관측 이후의 변화를 볼 때 쓴다. */
+    since?: string;
+};
+export interface ResourceContextPort {
+    readonly id: string;
+    getResource(reference: string): Promise<ResourceSnapshot>;
+    getComments(reference: string, query?: CommentQuery): Promise<ContextComment[]>;
+}
+/**
+ * 경위 조회 (capability `context.history`). 별도 인터페이스인 이유는 제공하지 못하는
+ * adapter가 흔하기 때문이다 — 하나로 묶으면 이력을 모르는 adapter가 전체를 구현하지
+ * 못하거나 빈 배열로 거짓말을 하게 된다.
+ */
+export type HistoryEvent = {
+    at: string;
+    actor: string;
+    /** provider의 사건 어휘를 그대로. Core는 표시하고 나열할 뿐 해석하지 않는다. */
+    kind: string;
+    detail?: string;
+};
+export interface HistoryPort {
+    readonly id: string;
+    getHistory(reference: string, limit?: number): Promise<HistoryEvent[]>;
+}

package/dist/ports/resource-context.js

@@ -0,0 +1,9 @@
+// Resource Context Port — 리소스 하나의 현재 내용을 읽는다 (C-09 §2).
+//
+// 기존 ScmPort.getThread는 **변경 마커만** 돌려준다(Drift Guard가 대조할 값). 조사는
+// 실제 내용을 읽어야 하므로 같은 Port에 얹을 수 없다 — 마커를 얻으려던 호출이 매번
+// 스레드 전문을 끌고 오게 된다.
+//
+// 여기 있는 것은 읽기뿐이다. 무엇이 중요한 댓글인지, 무엇을 해야 하는지는 판정이고
+// Core가 한다.
+export {};

package/dist/ports/scm.d.ts

@@ -0,0 +1,40 @@
+import type { CanonicalSnapshot } from '../core/model/entities.ts';
+/** 스레드(Issue/PR/Review 등) 하나의 현재 상태. Drift Guard가 대조하는 값이다. */
+export type ThreadSnapshot = {
+    reference: string;
+    lastEventId: string;
+    /** 스레드가 사라졌거나 접근 불가 — 실행 중단 사유가 된다. */
+    missing?: boolean;
+};
+/** canonical source의 현재 baseline. multi-source이므로 source별로 조회한다 (OM §8). */
+export type BaselineQuery = {
+    sourceId: string;
+    ref?: string;
+    paths?: readonly string[];
+};
+/**
+ * Grant가 지시하는 단일 외부 Action. Executor는 payload를 재작성하지 않는다 —
+ * 사람이 승인한 내용 그대로 나간다.
+ */
+export type ExternalAction = {
+    action: string;
+    target: string;
+    payload: string;
+};
+export type ExternalActionResult = {
+    ok: true;
+    resultRef: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface ScmPort {
+    readonly id: string;
+    getThread(reference: string): Promise<ThreadSnapshot>;
+    getBaselines(queries: readonly BaselineQuery[]): Promise<CanonicalSnapshot[]>;
+    /**
+     * 외부 쓰기. Grant를 검증하고 Drift Guard를 통과시킨 Executor만 호출한다 —
+     * Port 자체는 권한을 판단하지 않으므로, 호출 지점이 좁게 유지되는 것이 계약이다.
+     */
+    execute(action: ExternalAction): Promise<ExternalActionResult>;
+}

package/dist/ports/scm.js

@@ -0,0 +1,6 @@
+// SCM / Issue Provider Port — 외부 협업 시스템(GitHub 등)의 읽기와, 승인된 단일 Action의
+// 실행. Core에는 provider 이름이 들어가지 않는다 (OM §12.4).
+//
+// 쓰기는 이 Port를 통해서만, 그리고 ExecutionGrant를 쥔 Executor를 통해서만 일어난다
+// (OM §11.5). Monitor는 이 Port의 읽기만 쓴다.
+export {};