@asc-agent/runtime 0.1.0

package/dist/cli/identity-config.d.ts

@@ -0,0 +1,7 @@
+import type { IdentityMap } from '../adapters/local/identity.ts';
+export declare const IDENTITY_FILE = "identities.json";
+/**
+ * `{ "controller-a": ["local:colosair", "mattermost:@colosair"] }` 형태.
+ * 이름과 채널만 담고 비밀은 담지 않는다 (OM §4.5).
+ */
+export declare function loadIdentityMap(root: string): Promise<IdentityMap>;

package/dist/cli/identity-config.js

@@ -0,0 +1,31 @@
+// 승인자 매핑 로드. Profile/Override에서 읽어오는 정식 경로는 B-10에서 붙고,
+// 그때까지는 `.asc/identities.json` 하나를 본다.
+//
+// 파일이 없으면 승인은 전부 거절된다. 매핑이 없다는 것은 "아직 누구도 승인자로 지정되지
+// 않았다"는 뜻이고, 그 상태에서 통과시키면 검증이 있으나 마나다 — 없으면 막는 쪽이
+// 기본값이어야 한다 (OM §11.6).
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const IDENTITY_FILE = 'identities.json';
+/**
+ * `{ "controller-a": ["local:colosair", "mattermost:@colosair"] }` 형태.
+ * 이름과 채널만 담고 비밀은 담지 않는다 (OM §4.5).
+ */
+export async function loadIdentityMap(root) {
+    try {
+        const parsed = JSON.parse(await readFile(join(root, IDENTITY_FILE), 'utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return {};
+        const map = {};
+        for (const [approver, ids] of Object.entries(parsed)) {
+            if (Array.isArray(ids))
+                map[approver] = ids.filter((id) => typeof id === 'string');
+        }
+        return map;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}

package/dist/composition/observe.d.ts

@@ -0,0 +1,21 @@
+import type { OwnershipMap } from '../core/policy/ownership.ts';
+import type { EventObservation } from '../core/monitor/engine.ts';
+import type { ChangeContextPort } from '../ports/change-context.ts';
+import type { RawEvent } from '../ports/event-source.ts';
+export type ObservationDeps = {
+    /** 무엇이 어디서 바뀌었는가. 이 통로가 없으면 관련성 판정 자체가 서지 않는다. */
+    change: ChangeContextPort;
+    /** Profile이 선언한 책임 지도 (C-04 §6). */
+    ownership?: OwnershipMap;
+    /** 이 사람이 맡은 역할들 (User Override). 선언이 없으면 ownership 근거는 성립하지 않는다. */
+    myRoles?: readonly string[];
+    /** 정본이 사는 경로. contract 근거와 canonical 신호의 기준이다. */
+    canonicalPaths?: readonly string[];
+};
+/**
+ * 사건 하나에 대한 관찰을 만든다.
+ *
+ * 실패는 전부 "모른다"로 접는다 — 관찰이 감지를 막지 않는다. 외부 조회가 흔들려서
+ * 판단 대기함이 비면 그건 조회 실패가 아니라 **감지 실패**로 보이기 때문이다.
+ */
+export declare function buildEventObservation(deps: ObservationDeps): (event: RawEvent) => Promise<EventObservation>;

package/dist/composition/observe.js

@@ -0,0 +1,72 @@
+// Observation Builder — Monitor가 사건마다 "밖에서 알아 올" 사실을 조립한다 (C-07 §2~§4).
+//
+// Engine은 `observe`를 받으면 신호·관련성·억제를 켜고, 받지 않으면 예전처럼 신호만으로
+// 판정한다. 그 dependency를 **production 조립에서 실제로 채우는 것**이 이 파일의 전부다.
+// 판정 자체는 Core(evaluateRelevance·ObservationLedger)가 하고 여기서는 하지 않는다.
+//
+// 가장 중요한 규칙은 **모르면 만들지 않는다**이다:
+//
+//   change를 못 읽음        → 아무것도 만들지 않는다 (신호만으로 판정)
+//   경로를 일부만 읽음      → 관련성·신호 금지, 실질 변화 마커만 살린다
+//   구조적 판정 근거 없음   → 관련성 자체를 만들지 않는다
+//
+// 마지막 줄이 핵심이다. evaluateRelevance는 구조적 근거가 하나도 없으면 actual=LOW를
+// 내고 그건 Shadow(숨김)가 된다. 그러니 근거를 댈 수 없는 상태에서 관련성을 만들어
+// 넘기면 **모든 사건이 조용히 숨는다** — 근거 없이 숨기는 것이 가장 나쁜 결과다.
+/** 역할 선언이 실제 ownership으로 풀리는가. 오타·미선언 역할은 근거가 아니다. */
+function ownedPaths(map, roles) {
+    if (!map || !roles?.length)
+        return [];
+    return roles.flatMap((role) => map[role]?.paths ?? []);
+}
+/**
+ * 사건 하나에 대한 관찰을 만든다.
+ *
+ * 실패는 전부 "모른다"로 접는다 — 관찰이 감지를 막지 않는다. 외부 조회가 흔들려서
+ * 판단 대기함이 비면 그건 조회 실패가 아니라 **감지 실패**로 보이기 때문이다.
+ */
+export function buildEventObservation(deps) {
+    const owned = ownedPaths(deps.ownership, deps.myRoles);
+    const canonicalPaths = deps.canonicalPaths?.length ? deps.canonicalPaths : undefined;
+    return async (event) => {
+        let change;
+        try {
+            change = await deps.change.getChange(event.reference);
+        }
+        catch {
+            // 못 읽은 것을 "안 바뀌었다"로 쓰지 않는다.
+            return {};
+        }
+        // 변경요청이 아니거나 못 읽었다. 둘 다 "모른다"이므로 마커도 만들지 않는다 —
+        // 없는 마커를 지어내면 다음 회차가 그것과 대조해 실질 변화를 잘못 판정한다.
+        if (change.missing)
+            return {};
+        const revisionMarker = change.revisionMarker || undefined;
+        // 경로를 일부만 봤다면 "내 영역은 안 바뀌었다"고 말할 수 없다. 관련성도 신호도
+        // 만들지 않되, 유효한 실질 변화 마커까지 버리지는 않는다 (중복 억제는 계속 선다).
+        if (change.truncated)
+            return revisionMarker ? { revisionMarker } : {};
+        const changedPaths = change.changedPaths;
+        if (changedPaths.length === 0)
+            return revisionMarker ? { revisionMarker } : {};
+        // 구조적 판정 근거가 최소 하나 성립할 때만 관련성을 만든다.
+        //   A. ownership — 역할 선언이 실제 경로로 풀린다
+        //   B. contract  — 정본 경로가 있어 접촉 여부를 판정할 수 있다
+        // 둘 다 없으면 관련성을 만들지 않는다 (신호만으로 판정 = 기존 동작).
+        const canJudge = owned.length > 0 || canonicalPaths !== undefined;
+        return {
+            ...(revisionMarker ? { revisionMarker } : {}),
+            signal: { changedPaths, ...(canonicalPaths ? { canonicalPaths } : {}) },
+            ...(canJudge
+                ? {
+                    relevance: {
+                        ...(deps.ownership ? { ownership: deps.ownership } : {}),
+                        ...(deps.myRoles?.length ? { myRoles: deps.myRoles } : {}),
+                        changedPaths,
+                        ...(canonicalPaths ? { canonicalPaths } : {}),
+                    },
+                }
+                : {}),
+        };
+    };
+}

package/dist/composition/registry.d.ts

@@ -0,0 +1,33 @@
+import type { BindingPlan } from '../core/binding/types.ts';
+import type { Adapter, DiscoveryContext } from '../ports/adapter.ts';
+/**
+ * 이 빌드에 들어 있는 adapter. 여기 없는 것은 존재하지 않는다.
+ *
+ * 목록에 있다고 켜지는 것이 아니다 — discover가 후보를 찾지 못하거나 probe가 쓸 수
+ * 없다고 하면 그 갈래는 조립되지 않는다 (C-09 §7).
+ */
+export declare function defaultAdapters(): Adapter[];
+export type BindingRole = {
+    adapterId: string;
+    resource: string;
+    role: string;
+};
+export type ComposeInput = {
+    context: DiscoveryContext;
+    /** 없으면 이 빌드의 기본 목록. 테스트가 다른 조합을 물릴 수 있다. */
+    adapters?: readonly Adapter[];
+    /**
+     * Profile이 선언한 역할 배정. **역할은 사람이 정한다** — 어느 binding이 code-primary인지
+     * ASC가 추론하지 않는다 (C-09 §3.1).
+     */
+    roles?: readonly BindingRole[];
+};
+/**
+ * describe → discover → probe → BindingPlan.
+ *
+ * provider 목록을 순회하는 코드가 아니다 — 등록된 adapter가 스스로 후보를 찾고,
+ * adapter가 없으면 그 갈래는 애초에 없다 (C-09 §7).
+ */
+export declare function composeBindings(input: ComposeInput): Promise<BindingPlan>;
+/** 설치된 adapter가 정적으로 선언하는 것. 네트워크도 파일 접근도 없다. */
+export declare function describeAll(adapters?: readonly Adapter[]): import("../core/binding/types.ts").AdapterDescriptor[];

package/dist/composition/registry.js

@@ -0,0 +1,62 @@
+// Composition Root — 실제 Adapter를 아는 유일한 자리 (C-09 §6).
+//
+// **이 파일은 `core/` 밖이다.** Core는 adapter를 import하지 않고, adapter id로 분기하지도
+// 않는다. 여기서 조립한 BindingPlan만 Core로 넘어간다.
+//
+// 정적 registry로 충분하다 (C-09 §6.2). 동적 로더·marketplace·서명·버전 협상은 만들지
+// 않는다 — 두세 개의 실제 adapter에서 같은 구조가 반복되는 것을 본 뒤에 검토한다.
+// 지금 만들면 쓰이지 않는 확장점의 유지 비용만 남는다.
+import { GitHubAdapter } from "../adapters/github/adapter.js";
+import { GitLabAdapter } from "../adapters/gitlab/adapter.js";
+import { JamAdapter } from "../adapters/jam/adapter.js";
+/**
+ * 이 빌드에 들어 있는 adapter. 여기 없는 것은 존재하지 않는다.
+ *
+ * 목록에 있다고 켜지는 것이 아니다 — discover가 후보를 찾지 못하거나 probe가 쓸 수
+ * 없다고 하면 그 갈래는 조립되지 않는다 (C-09 §7).
+ */
+export function defaultAdapters() {
+    return [new GitHubAdapter(), new GitLabAdapter(), new JamAdapter()];
+}
+/**
+ * describe → discover → probe → BindingPlan.
+ *
+ * provider 목록을 순회하는 코드가 아니다 — 등록된 adapter가 스스로 후보를 찾고,
+ * adapter가 없으면 그 갈래는 애초에 없다 (C-09 §7).
+ */
+export async function composeBindings(input) {
+    const adapters = input.adapters ?? defaultAdapters();
+    const bindings = [];
+    const runtimes = [];
+    for (const adapter of adapters) {
+        // 도구가 쓸 수 있는가와 이 프로젝트가 그 도구에 붙어 있는가는 다른 사실이다.
+        // 합치면 사람이 "설치할 일인지 붙일 일인지"를 알 수 없다.
+        if (adapter.runtime) {
+            const status = await adapter
+                .runtime(input.context)
+                .catch((error) => ({ state: 'UNAVAILABLE', detail: String(error) }));
+            runtimes.push({ adapterId: adapter.describe().id, ...status });
+        }
+        const candidates = await adapter.discover(input.context).catch(() => []);
+        for (const candidate of candidates) {
+            // probe가 터지는 것과 "안 된다"는 다르다. 예외를 UNAVAILABLE로 옮겨 적되
+            // 이유를 남긴다 — 조용히 후보에서 빼면 왜 안 보이는지 알 수 없다.
+            const result = await adapter
+                .probe(candidate, input.context)
+                .catch((error) => ({ state: 'UNAVAILABLE', detail: String(error) }));
+            const role = input.roles?.find((r) => r.adapterId === candidate.adapterId && r.resource === candidate.resource)?.role;
+            bindings.push({
+                ...candidate,
+                ...(result.provides ? { provides: result.provides } : {}),
+                state: result.state,
+                ...(result.detail ? { detail: result.detail } : {}),
+                ...(role ? { role } : {}),
+            });
+        }
+    }
+    return { bindings, ...(runtimes.length > 0 ? { runtimes } : {}) };
+}
+/** 설치된 adapter가 정적으로 선언하는 것. 네트워크도 파일 접근도 없다. */
+export function describeAll(adapters = defaultAdapters()) {
+    return adapters.map((adapter) => adapter.describe());
+}

package/dist/composition/runtime.d.ts

@@ -0,0 +1,63 @@
+import type { Capability, BindingPlan, ResolvedBinding } from '../core/binding/types.ts';
+import type { ChangeContextPort } from '../ports/change-context.ts';
+import type { EventSource } from '../ports/event-source.ts';
+import type { InventoryPort } from '../ports/inventory.ts';
+import type { ResourceContextPort } from '../ports/resource-context.ts';
+import type { ScmPort } from '../ports/scm.ts';
+export type RuntimePorts = {
+    eventSource?: EventSource;
+    scm?: ScmPort;
+    inventory?: InventoryPort;
+    resourceContext?: ResourceContextPort;
+    changeContext?: ChangeContextPort;
+    /** 무엇을 왜 못 만들었는지. 조용히 빠지면 사람이 이유를 알 수 없다. */
+    unavailable: string[];
+};
+export type BuildInput = {
+    plan: BindingPlan;
+    /**
+     * capability별로 어느 역할이 맡는지 (C-09 §4). Profile의 `bindings[]` 선언이 여기 온다.
+     * 역할을 주면 같은 capability를 여럿이 제공해도 갈리지 않는다.
+     */
+    roles?: Partial<Record<Capability, string>>;
+    /** JAM 같은 도구형 adapter를 조립하기 위한 통로. 없으면 그 갈래는 만들지 않는다. */
+    jam?: {
+        command: string;
+        args?: readonly string[];
+        cwd?: string;
+        /**
+         * JQL 날짜 리터럴을 해석할 Jira 계정 timezone(IANA). 선언하지 않으면 adapter가
+         * UTC로 읽는다 — 기계의 timezone을 쓰지 않는다(adapters/jam/ports.ts).
+         */
+        timezone?: string;
+    };
+    /** canonical source id → ref. Profile이 준다. */
+    sourceRefs?: Readonly<Record<string, {
+        ref: string;
+    }>>;
+    /** 이벤트 조회 페이지 크기. */
+    perPage?: number;
+    /** 자격 조회 통로 주입점(테스트용). adapter id를 받아 그 adapter의 자격을 돌려준다. */
+    findToken?: (adapterId: string) => Promise<string | null>;
+    /** 이 binding이 어느 주소를 가리키는지. 발견 단계가 알아낸 값을 그대로 잇는다. */
+    endpointFor?: (binding: ResolvedBinding) => string | undefined;
+};
+/**
+ * capability가 필요한 자리마다 어느 binding이 맡을지 정해 Port를 만든다.
+ *
+ * 후보가 갈리면 만들지 않는다 — `AMBIGUOUS_BINDING`은 사람이 정할 문제이고, 여기서 하나를
+ * 고르면 그 선택을 아무도 보지 못한다 (C-09 §4.2).
+ */
+/**
+ * Profile이 선언한 역할 배정을 capability별 역할로 옮긴다 (C-09 §3.1·§4).
+ *
+ * **추론하지 않는다.** 선언된 binding이 그 capability를 제공한다고 plan에 적혀 있을 때만
+ * 그 역할을 쓴다. 둘 이상이 같은 capability를 제공하면 고르지 않고 비워 둔다 —
+ * 그러면 resolve가 AMBIGUOUS로 표면화한다. 여기서 하나를 고르면 사람이 그걸 못 본다.
+ */
+export declare function rolesFor(plan: BindingPlan, declared: readonly {
+    role: string;
+    adapter: string;
+    resource: string;
+}[]): Partial<Record<Capability, string>>;
+export declare function buildRuntimePorts(input: BuildInput): Promise<RuntimePorts>;

package/dist/composition/runtime.js

@@ -0,0 +1,155 @@
+// Runtime 조립 — Binding에서 실제 Port 구현을 만든다 (C-09 §6).
+//
+// CLI가 adapter를 직접 `new` 하면 Surface가 provider를 아는 지점이 흩어지고, adapter를
+// 바꿀 때마다 호출부를 전부 고쳐야 한다. 조립을 여기 한 곳에 모으면 교체가 이 파일의
+// 변경으로 끝난다 — 그것이 "provider 교체는 Binding 교체" 의 실제 모습이다.
+//
+// **Core는 이 파일을 import하지 않는다.** 방향은 언제나 Composition → Core다.
+import { resolveCapability } from "../core/binding/types.js";
+import { GitHubClient, discoverToken } from "../adapters/github/client.js";
+import { GitHubChangeContext, GitHubInventory, GitHubResourceContext } from "../adapters/github/context.js";
+import { GitHubEventSource } from "../adapters/github/event-source.js";
+import { GitHubScm } from "../adapters/github/scm.js";
+import { GitLabClient, discoverToken as discoverGitLabToken } from "../adapters/gitlab/client.js";
+import { GitLabChangeContext, GitLabEventSource, GitLabInventory, GitLabResourceContext, } from "../adapters/gitlab/ports.js";
+import { JamMcpClient } from "../adapters/jam/mcp-client.js";
+import { JamEventSource } from "../adapters/jam/event-source.js";
+import { JamInventory, JamResourceContext } from "../adapters/jam/ports.js";
+const FACTORIES = {
+    gitlab(binding, input, token) {
+        // 자체 호스팅이 흔하다. 어디를 가리키는지는 발견 단계가 이미 알아냈으므로 같은 값을 쓴다.
+        const baseUrl = input.endpointFor?.(binding);
+        const client = new GitLabClient({ token, ...(baseUrl ? { baseUrl } : {}) });
+        const project = binding.resource;
+        return {
+            eventSource: new GitLabEventSource({ client, project, perPage: input.perPage ?? 30 }),
+            inventory: new GitLabInventory({ client, project }),
+            resourceContext: new GitLabResourceContext({ client, project }),
+            changeContext: new GitLabChangeContext({ client, project }),
+            // canonical·외부 write 통로는 아직 없다. 없는 것을 있는 척하지 않는다.
+        };
+    },
+    github(binding, input, token) {
+        const client = new GitHubClient({ token });
+        const repo = binding.resource;
+        return {
+            eventSource: new GitHubEventSource({ client, repo, perPage: input.perPage ?? 30 }),
+            scm: new GitHubScm({ client, defaultRepo: repo, sourceRefs: input.sourceRefs ?? {} }),
+            inventory: new GitHubInventory({ client, defaultRepo: repo }),
+            resourceContext: new GitHubResourceContext({ client, defaultRepo: repo }),
+            changeContext: new GitHubChangeContext({ client, defaultRepo: repo }),
+        };
+    },
+    jam(binding, input) {
+        // JAM은 토큰을 받지 않는다 — 자격은 도구가 자기 안에서 관리하고 ASC는 상태만 읽는다.
+        if (!input.jam)
+            return {};
+        const client = new JamMcpClient({
+            command: input.jam.command,
+            ...(input.jam.args ? { args: input.jam.args } : {}),
+            ...(input.jam.cwd ? { cwd: input.jam.cwd } : {}),
+        });
+        const projectKey = binding.resource;
+        const timezone = input.jam.timezone;
+        const inventory = new JamInventory({ client, projectKey, ...(timezone ? { timezone } : {}) });
+        return {
+            inventory,
+            resourceContext: new JamResourceContext({
+                client,
+                projectKey,
+                ...(timezone ? { timezone } : {}),
+            }),
+            // 푸시가 아니라 updated-since 증분 조회다 (C-07 §1.1) — adapter 주석 참조
+            eventSource: new JamEventSource({ inventory }),
+        };
+    },
+};
+/** 이 adapter는 토큰 없이 조립된다. 자격은 도구가 자기 안에서 진다. */
+const TOKENLESS = new Set(['jam']);
+/**
+ * capability와 Port의 대응. **이 표가 없으면 조립이 덮어쓰기가 된다** —
+ * 두 binding이 각각 다른 capability를 맡았는데 나중 것이 앞 것의 Port까지 밀어낸다.
+ */
+const PORT_OF = {
+    'observe.delta': 'eventSource',
+    'inventory.enumerate': 'inventory',
+    'context.change': 'changeContext',
+    'context.resource': 'resourceContext',
+    'canonical.read': 'scm',
+};
+/**
+ * capability가 필요한 자리마다 어느 binding이 맡을지 정해 Port를 만든다.
+ *
+ * 후보가 갈리면 만들지 않는다 — `AMBIGUOUS_BINDING`은 사람이 정할 문제이고, 여기서 하나를
+ * 고르면 그 선택을 아무도 보지 못한다 (C-09 §4.2).
+ */
+/**
+ * Profile이 선언한 역할 배정을 capability별 역할로 옮긴다 (C-09 §3.1·§4).
+ *
+ * **추론하지 않는다.** 선언된 binding이 그 capability를 제공한다고 plan에 적혀 있을 때만
+ * 그 역할을 쓴다. 둘 이상이 같은 capability를 제공하면 고르지 않고 비워 둔다 —
+ * 그러면 resolve가 AMBIGUOUS로 표면화한다. 여기서 하나를 고르면 사람이 그걸 못 본다.
+ */
+export function rolesFor(plan, declared) {
+    const roles = {};
+    const tagged = plan.bindings.filter((b) => b.role !== undefined);
+    const capabilities = new Set(tagged.flatMap((b) => [...b.provides]));
+    for (const capability of capabilities) {
+        const owners = new Set(tagged
+            .filter((b) => b.provides.includes(capability))
+            .filter((b) => declared.some((d) => d.adapter === b.adapterId && d.resource === b.resource))
+            .map((b) => b.role));
+        if (owners.size === 1)
+            roles[capability] = [...owners][0];
+    }
+    return roles;
+}
+export async function buildRuntimePorts(input) {
+    const ports = { unavailable: [] };
+    // 자격은 adapter마다 다른 곳에 있다. Core는 이 사실을 모르고, 여기서만 안다.
+    const findToken = input.findToken ??
+        (async (adapterId) => adapterId === 'gitlab' ? discoverGitLabToken() : await discoverToken());
+    // capability마다 따로 푼다. 한 binding이 여럿을 제공해도, 서로 다른 binding이 나눠
+    // 맡아도 같은 경로로 조립된다 — 어느 갈래가 어디서 왔는지가 Port마다 정확해야 한다.
+    const wanted = Object.keys(PORT_OF);
+    const built = new Map();
+    for (const capability of wanted) {
+        const role = input.roles?.[capability];
+        const resolution = resolveCapability(input.plan, { capability, ...(role ? { role } : {}) });
+        if (resolution.kind !== 'RESOLVED') {
+            ports.unavailable.push(resolution.kind === 'AMBIGUOUS'
+                ? `${capability}: 후보가 둘 이상이라 고르지 않았다 (${resolution.candidates
+                    .map((c) => `${c.adapterId}:${c.resource}`)
+                    .join(', ')}) — Profile bindings 로 역할을 정하라`
+                : `${capability}: ${resolution.detail}`);
+            continue;
+        }
+        const binding = resolution.binding;
+        const key = `${binding.adapterId}:${binding.resource}`;
+        let made = built.get(key);
+        if (!made) {
+            const factory = FACTORIES[binding.adapterId];
+            if (!factory) {
+                ports.unavailable.push(`${binding.adapterId}: 이 빌드에 조립 경로가 없다`);
+                continue;
+            }
+            const token = TOKENLESS.has(binding.adapterId) ? '' : await findToken(binding.adapterId);
+            if (token === null) {
+                ports.unavailable.push(`${binding.adapterId}: 자격이 없어 외부 조회를 만들지 않았다`);
+                continue;
+            }
+            made = factory(binding, input, token);
+            built.set(key, made);
+        }
+        // **그 capability에 해당하는 Port만 가져온다.** 통째로 assign하면 다른 binding이
+        // 맡기로 한 갈래까지 덮어쓴다 — multi-binding이 조용히 single-binding이 된다.
+        const portKey = PORT_OF[capability];
+        const port = made[portKey];
+        if (port === undefined) {
+            ports.unavailable.push(`${capability}: ${binding.adapterId} 가 이 갈래를 만들지 않았다`);
+            continue;
+        }
+        Object.assign(ports, { [portKey]: port });
+    }
+    return ports;
+}

package/dist/core/approval/service.d.ts

@@ -0,0 +1,17 @@
+import type { ApprovalDecision } from '../model/entities.ts';
+import type { ApprovalChannel, DecisionOutcome, DecisionSink, IdentityBinding } from '../../ports/approval.ts';
+import type { ScmPort } from '../../ports/scm.ts';
+import type { StateStore } from '../../ports/state-store.ts';
+export type ApprovalDeps = {
+    store: StateStore;
+    identity: IdentityBinding;
+    /** 결정 후 표시를 갱신할 채널들. 실패해도 결정은 유효하다 (C-01 §9). */
+    channels?: readonly ApprovalChannel[];
+    scm?: ScmPort;
+    now?: () => string;
+};
+export declare class ApprovalService implements DecisionSink {
+    #private;
+    constructor(deps: ApprovalDeps);
+    submit(decision: ApprovalDecision): Promise<DecisionOutcome>;
+}

package/dist/core/approval/service.js

@@ -0,0 +1,129 @@
+// 결정 제출 경로 — 사람의 명시적 의사표현을 ApprovalDecision으로 받아 상태를 옮긴다.
+//
+// 조회(LocalOperator)와 결정을 다른 파일에 둔 이유는 문 하나 차이다. 조회 객체가
+// submit을 갖고 있으면 요청을 읽던 Agent가 그대로 승인까지 이어가기 쉬워지고,
+// "AI 판단 ≠ Controller Decision"이 구조가 아니라 습관에 기대게 된다 (C-01 §5).
+//
+// **신뢰 경계 (현 단계 계약)**: `asc inbox decide` 같은 결정 표면을 사람이 조작하는
+// 표면으로 간주하고, Identity Binding으로 *승인자 identity*를 검증한다. 이것은
+// "지금 키보드를 두드린 것이 사람이다"라는 기술적 증명이 아니다 — 셸을 쓸 수 있는
+// Agent는 매핑된 이름을 댈 수 있다. OS 인증·서명·대화형 확인 같은 강한 local
+// authentication은 별도 후속 범위이며, 그전까지 이 계층이 막는 것은 "권한자로 지정되지
+// 않은 이름의 결정"까지다. 매핑에 없는 이름은 거절되고 시도가 History에 남는다 (OM §11.6).
+import { transitionRequest } from "../model/transitions.js";
+import { assembleView, assess, buildOverlay } from "../view/build-view.js";
+/**
+ * 사람의 선택이 요청을 어느 상태로 옮기는가.
+ * `revise`가 APPROVED로 가는 것은 "고쳐서 승인한다"이지 별도 상태가 아니다 —
+ * 무엇을 고쳤는지는 revision에 남고, 실제 실행은 그 revision을 payload로 쓴다.
+ */
+const TARGET_STATUS = {
+    approve: 'APPROVED',
+    revise: 'APPROVED',
+    queue: 'QUEUED',
+    defer: 'DEFERRED',
+    dismiss: 'DISMISSED',
+};
+/**
+ * 아직 사람의 판단을 더 받을 수 있는 상태.
+ * 보류는 결정을 미룬 것이지 끝낸 것이 아니므로 다시 판단할 수 있어야 한다 (OM §11.2).
+ * 판정 기준을 "결정 기록이 있는가"로 두면 defer가 사실상 terminal이 되어버린다 —
+ * 기록은 남기되 상태로 판단한다.
+ */
+const REOPENABLE = new Set(['AWAITING_APPROVAL', 'DEFERRED']);
+export class ApprovalService {
+    #store;
+    #identity;
+    #channels;
+    #scm;
+    #now;
+    constructor(deps) {
+        this.#store = deps.store;
+        this.#identity = deps.identity;
+        this.#channels = deps.channels ?? [];
+        this.#scm = deps.scm;
+        this.#now = deps.now ?? (() => new Date().toISOString());
+    }
+    async submit(decision) {
+        const request = await this.#store.get('request', decision.requestId);
+        if (!request)
+            return { ok: false, reason: 'NOT_FOUND' };
+        const authorized = await this.#identity.verify({
+            channel: decision.channel,
+            actor: decision.actor,
+            authorizedApprover: request.authorizedApprover,
+        });
+        if (!authorized) {
+            // 거절로 끝내지 않고 남긴다 — 누가 승인하려 했는지는 나중에 물을 수 있는 질문이다
+            await this.#store.appendHistory({
+                at: this.#now(),
+                actor: decision.actor,
+                kind: 'decision_rejected',
+                ref: request.id,
+                detail: `unauthorized via ${decision.channel} (${decision.kind})`,
+            });
+            return { ok: false, reason: 'FORBIDDEN_ACTOR' };
+        }
+        if (!request.allowedDecisions.includes(decision.kind))
+            return { ok: false, reason: 'NOT_ALLOWED_DECISION' };
+        if (request.expiresAt && request.expiresAt <= decision.decidedAt)
+            return { ok: false, reason: 'EXPIRED' };
+        // 읽은 뒤 상황이 바뀌었는지부터 본다. 끝난 요청과 그 사이 한 번 더 움직인 요청은
+        // 사용자에게 다른 이야기이므로 이유를 갈라서 돌려준다.
+        if (!REOPENABLE.has(request.status)) {
+            return { ok: false, reason: 'ALREADY_DECIDED', view: await this.#view(request) };
+        }
+        if (request.version !== decision.expectedVersion) {
+            return { ok: false, reason: 'STALE', view: await this.#view(request) };
+        }
+        const next = transitionRequest(request, TARGET_STATUS[decision.kind], 'controller', {
+            decision: {
+                kind: decision.kind,
+                actor: decision.actor,
+                channel: decision.channel,
+                ...(decision.revision !== undefined ? { revision: decision.revision } : {}),
+                decidedAt: decision.decidedAt,
+            },
+        });
+        const saved = await this.#store.compareAndSet('request', request.id, decision.expectedVersion, next);
+        if (!saved.ok) {
+            if (saved.reason === 'NOT_FOUND')
+                return { ok: false, reason: 'NOT_FOUND' };
+            // 다른 채널이 먼저 들어왔다. 그쪽이 요청을 끝냈다면 이미 결정된 것이고,
+            // 아직 판단을 더 받을 수 있는 상태라면 다시 보고 결정할 일이다.
+            const view = await this.#view(saved.current);
+            return REOPENABLE.has(saved.current.status)
+                ? { ok: false, reason: 'STALE', view }
+                : { ok: false, reason: 'ALREADY_DECIDED', view };
+        }
+        await this.#store.appendHistory({
+            at: decision.decidedAt,
+            actor: decision.actor,
+            kind: 'decision',
+            ref: request.id,
+            detail: `${decision.kind} via ${decision.channel}${decision.revision ? ' (revised)' : ''}`,
+        });
+        const view = await this.#view(saved.entity);
+        await this.#notifyChannels(view);
+        return { ok: true, view };
+    }
+    /** 표시 갱신은 best-effort다 — 채널이 죽어도 결정은 이미 확정됐고, 낡은 버튼은 CAS가 막는다. */
+    async #notifyChannels(view) {
+        for (const channel of this.#channels) {
+            try {
+                await channel.update(view);
+            }
+            catch {
+                // 채널 사정은 canonical state에 영향을 주지 않는다
+            }
+        }
+    }
+    async #view(request) {
+        const overlay = await buildOverlay(request, {
+            control: await this.#store.getControlState(),
+            observedAt: this.#now(),
+            ...(this.#scm ? { scm: this.#scm } : {}),
+        });
+        return assembleView(request, await assess(request, overlay, this.#scm), overlay);
+    }
+}