@asc-agent/runtime 0.1.0

package/dist/core/distribution/runtime-install.js

@@ -0,0 +1,90 @@
+// 이 machine에 stable `asc` 가 있는가 (C-14 §3).
+//
+// **두 가지를 절대 혼동하지 않는다.**
+//
+// ```text
+// bootstrap이 자기 의존성으로 들고 온 runtime      임시다. 프로세스가 끝나면 없다.
+// 이 machine에 전역 설치된 runtime                 지속된다. 그것이 `asc` 다.
+// ```
+//
+// npx 캐시나 node_modules 안에 runtime이 보인다고 "이미 설치됐다"고 하면, bootstrap이
+// 끝난 뒤 사용자에게는 아무 명령도 남지 않는다. 그래서 판정은 **전역 설치 조회**로만 한다.
+//
+// 실행물 링크는 npm의 몫이다 (불변식 ⑰). 여기서 PATH도 shell도 고치지 않는다.
+import { RELEASE_VERSION, RUNTIME_PACKAGE } from "./release.js";
+/**
+ * 전역 설치 상태를 읽는다. **읽기만 한다** (C-14 §6 detect).
+ *
+ * `npm ls -g --json` 은 전역 트리만 본다 — bootstrap이 들고 온 자기 의존성은 여기 안 나온다.
+ * 그것이 이 함수가 `npm ls` 를 쓰는 이유다.
+ */
+export async function detectStableInstall(run, expectedVersion = RELEASE_VERSION) {
+    const listed = await run('npm', ['ls', '-g', '--depth=0', '--json', RUNTIME_PACKAGE]);
+    const installedVersion = parseGlobalVersion(listed.stdout);
+    // 실행물이 보이는가는 별개 사실이다. node manager에 따라 설치는 됐는데 이 프로세스의
+    // PATH에는 없을 수 있고, 그때 "설치됨"이라고만 말하면 사람이 갇힌다 (C-14 §3.3).
+    const which = await run(process.platform === 'win32' ? 'where' : 'which', ['asc']);
+    const executableVisible = which.ok && which.stdout.trim().length > 0;
+    if (!installedVersion) {
+        return { status: 'NOT_INSTALLED', expectedVersion, executableVisible };
+    }
+    if (installedVersion !== expectedVersion) {
+        return {
+            status: 'VERSION_MISMATCH',
+            expectedVersion,
+            installedVersion,
+            executableVisible,
+            detail: `global ${RUNTIME_PACKAGE} is ${installedVersion}, expected ${expectedVersion}`,
+        };
+    }
+    if (!executableVisible) {
+        return {
+            status: 'BROKEN',
+            expectedVersion,
+            installedVersion,
+            executableVisible,
+            detail: '`asc` is not visible in this process — npm global prefix or PATH',
+        };
+    }
+    return { status: 'CURRENT', expectedVersion, installedVersion, executableVisible };
+}
+/** `npm ls --json` 에서 이 패키지의 버전만 꺼낸다. 못 읽으면 없는 것으로 본다. */
+function parseGlobalVersion(stdout) {
+    try {
+        const tree = JSON.parse(stdout);
+        const version = tree.dependencies?.[RUNTIME_PACKAGE]?.version;
+        return typeof version === 'string' ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 전역에 exact version으로 설치한다. **exact 말고는 쓰지 않는다** (불변식 ⑧).
+ *
+ * 여기서 조건을 다시 따지지 않는다 — 무엇을 설치할지는 plan이 이미 정했다 (불변식 ⑩).
+ */
+export async function installStableRuntime(run, version = RELEASE_VERSION) {
+    const spec = `${RUNTIME_PACKAGE}@${version}`;
+    const result = await run('npm', ['install', '-g', spec]);
+    return result.ok ? { ok: true } : { ok: false, detail: result.stderr.trim() || result.stdout.trim() };
+}
+/**
+ * 설치했다고 끝이 아니다 — exit 0은 "npm이 화내지 않았다"까지다 (C-14 §3.3).
+ *
+ * 버전이 맞는지, 그리고 **실행물이 실제로 보이는지**까지 본다. 안 보이면 성공으로
+ * 뭉개지 않고 새 터미널을 열라고 말한다.
+ */
+export async function verifyStableInstall(run, expectedVersion = RELEASE_VERSION) {
+    const state = await detectStableInstall(run, expectedVersion);
+    if (state.status === 'CURRENT')
+        return { ok: true, state };
+    if (state.status === 'BROKEN' && state.installedVersion === expectedVersion) {
+        return {
+            ok: false,
+            state,
+            remedy: 'Runtime package was installed, but `asc` is not visible in this process. Open a new terminal and run `asc setup status`.',
+        };
+    }
+    return { ok: false, state, remedy: state.detail };
+}

package/dist/core/distribution/runtime-select.d.ts

@@ -0,0 +1,74 @@
+/** 이 패키지의 이름. development checkout이 진짜 ASC인지 여기에 견준다. */
+export declare const RUNTIME_PACKAGE = "@asc-agent/runtime";
+/** build 산출물의 진입점. checkout 뿌리 기준 상대경로다. */
+export declare const RUNTIME_ENTRY: string;
+export declare const SELECTION_FILE = "runtime.json";
+export type RuntimeMode = 'package' | 'development';
+export type RuntimeSelection = {
+    version: 1;
+    runtime: {
+        mode: 'package';
+    };
+} | {
+    version: 1;
+    runtime: {
+        mode: 'development';
+        source: string;
+    };
+};
+export type ResolvedTarget = 
+/** 설치된 실행물이 스스로 돈다. 중간 프로세스도, network도 없다. */
+{
+    kind: 'package';
+}
+/** 지정된 checkout의 build를 대신 실행한다. */
+ | {
+    kind: 'development';
+    source: string;
+    entry: string;
+};
+export type ResolveFailure = {
+    code: 'ASC_DEVELOPMENT_SOURCE_INVALID';
+    detail: string;
+    /** 사람이 실행할 한 줄. 무엇이 틀렸는지만 말하고 끝내지 않는다. */
+    nextCommand: string;
+    /**
+     * 이 해법이 **어느 checkout에 대한 것인가**.
+     *
+     * 지금 cwd가 그 checkout이라는 보장이 없다. `npm run build` 한 줄만 주면 엉뚱한
+     * 프로젝트에서 빌드가 돈다 — 실제로 그럴 수 있는 배치다(작업 중인 저장소 ≠ ASC checkout).
+     */
+    remediationTarget?: string;
+};
+export declare const selectionPath: (ascHome: string) => string;
+/**
+ * 읽지 못하는 선택은 **없는 것으로 본다** (C-14 §5).
+ *
+ * 반쯤 해석해서 엉뚱한 build를 부르는 것보다, 선택이 없다고 말하고 기본으로 도는 것이 낫다.
+ */
+export declare function readRuntimeSelection(ascHome: string): Promise<RuntimeSelection | undefined>;
+/** 손으로 고칠 수 있는 파일이다. 형식이 어긋나면 받아들이지 않는다. */
+export declare function normalizeSelection(value: unknown): RuntimeSelection | undefined;
+/** tmp+rename — 중간에 끊겨도 반쯤 쓰인 선택이 남지 않는다. */
+export declare function writeRuntimeSelection(ascHome: string, selection: RuntimeSelection): Promise<void>;
+/**
+ * 어느 build를 부를 것인가. **거절은 여기서 끝낸다** (C-14 §4.1).
+ *
+ * 경로가 틀렸거나 build가 없는 것을 통과시키면 사람은 한참 뒤에 module-not-found를
+ * 맞는다. 무엇이 없는지 아는 곳에서 말하는 것이 싸다.
+ */
+export declare function resolveRuntimeTarget(selection: RuntimeSelection | undefined): Promise<ResolvedTarget | ResolveFailure>;
+/** 사람이 읽는 한 줄. 지금 무엇이 돌지가 먼저다. */
+export declare function runtimeSelectionLine(target: ResolvedTarget | ResolveFailure): string;
+/**
+ * 해법을 사람에게 말한다. **무엇에 대한 해법인지 먼저 말한다** (C-14 §3.4의 태도).
+ *
+ * `npm run build` 만 던지면 지금 열려 있는 저장소에서 그것을 실행할 사람이 있다.
+ */
+export declare function remediationLines(failure: ResolveFailure): string[];
+/** agent가 그대로 소비하는 형태. 어느 checkout인지가 데이터로 들어 있다. */
+export declare function remediationAction(failure: ResolveFailure): {
+    type: 'build_development_runtime' | 'select_development_runtime';
+    source?: string;
+    display: string;
+};

package/dist/core/distribution/runtime-select.js

@@ -0,0 +1,149 @@
+// 어느 build를 부를 것인가 (C-14 §4·§5).
+//
+// **이것은 C-12의 "always-on runtime"과 다른 축이다.** 저쪽은 상태가 어떻게 지속되는가고,
+// 여기는 실행물이 어느 build인가다. 같은 낱말을 쓰지만 섞으면 안 된다.
+//
+// 이 파일은 선택만 안다 — credential·project key·workspace state는 여기 오지 않는다.
+// 그리고 **선택을 바꾸는 것은 project를 바꾸는 것이 아니다** (불변식 ⑤).
+import { constants } from 'node:fs';
+import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** 이 패키지의 이름. development checkout이 진짜 ASC인지 여기에 견준다. */
+export const RUNTIME_PACKAGE = '@asc-agent/runtime';
+/** build 산출물의 진입점. checkout 뿌리 기준 상대경로다. */
+export const RUNTIME_ENTRY = join('dist', 'cli', 'asc.js');
+export const SELECTION_FILE = 'runtime.json';
+const exists = async (path) => {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const selectionPath = (ascHome) => join(ascHome, SELECTION_FILE);
+/**
+ * 읽지 못하는 선택은 **없는 것으로 본다** (C-14 §5).
+ *
+ * 반쯤 해석해서 엉뚱한 build를 부르는 것보다, 선택이 없다고 말하고 기본으로 도는 것이 낫다.
+ */
+export async function readRuntimeSelection(ascHome) {
+    let raw;
+    try {
+        raw = await readFile(selectionPath(ascHome), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return normalizeSelection(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 손으로 고칠 수 있는 파일이다. 형식이 어긋나면 받아들이지 않는다. */
+export function normalizeSelection(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const record = value;
+    if (record.version !== 1)
+        return undefined;
+    const runtime = record.runtime;
+    if (!runtime)
+        return undefined;
+    if (runtime.mode === 'package')
+        return { version: 1, runtime: { mode: 'package' } };
+    if (runtime.mode === 'development') {
+        const source = runtime.source;
+        if (typeof source !== 'string' || source.trim() === '')
+            return undefined;
+        return { version: 1, runtime: { mode: 'development', source } };
+    }
+    return undefined;
+}
+/** tmp+rename — 중간에 끊겨도 반쯤 쓰인 선택이 남지 않는다. */
+export async function writeRuntimeSelection(ascHome, selection) {
+    const target = selectionPath(ascHome);
+    await mkdir(dirname(target), { recursive: true });
+    const tmp = `${target}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(selection, null, 2)}\n`, 'utf8');
+    await rename(tmp, target);
+}
+/**
+ * 어느 build를 부를 것인가. **거절은 여기서 끝낸다** (C-14 §4.1).
+ *
+ * 경로가 틀렸거나 build가 없는 것을 통과시키면 사람은 한참 뒤에 module-not-found를
+ * 맞는다. 무엇이 없는지 아는 곳에서 말하는 것이 싸다.
+ */
+export async function resolveRuntimeTarget(selection) {
+    // 선택이 없으면 지금 도는 실행물이 곧 답이다 — 첫 실행이 설정을 요구하지 않는다.
+    if (!selection || selection.runtime.mode === 'package')
+        return { kind: 'package' };
+    const source = selection.runtime.source;
+    const reject = (detail) => ({
+        code: 'ASC_DEVELOPMENT_SOURCE_INVALID',
+        detail,
+        nextCommand: `asc runtime use development ${source}`,
+    });
+    if (!(await exists(source)))
+        return reject(`${source} does not exist — it was moved or removed`);
+    const manifest = join(source, 'package.json');
+    if (!(await exists(manifest)))
+        return reject(`${source} has no package.json`);
+    let name;
+    try {
+        name = JSON.parse(await readFile(manifest, 'utf8')).name;
+    }
+    catch {
+        return reject(`${manifest} could not be read`);
+    }
+    if (name !== RUNTIME_PACKAGE) {
+        return reject(`${source} is not ${RUNTIME_PACKAGE} (found ${String(name)})`);
+    }
+    const entry = join(source, RUNTIME_ENTRY);
+    if (!(await exists(entry))) {
+        return {
+            code: 'ASC_DEVELOPMENT_SOURCE_INVALID',
+            detail: `${source} has not been built yet`,
+            // 이 경우만 다르다 — 경로는 맞고 build만 없다. **어느 checkout인지 함께 든다**:
+            // 지금 cwd가 그곳이라고 가정하면 남의 프로젝트를 빌드하게 만든다.
+            nextCommand: 'npm run build',
+            remediationTarget: source,
+        };
+    }
+    return { kind: 'development', source, entry };
+}
+/** 사람이 읽는 한 줄. 지금 무엇이 돌지가 먼저다. */
+export function runtimeSelectionLine(target) {
+    if ('code' in target)
+        return `Runtime selection does not resolve — ${target.detail}`;
+    return target.kind === 'package'
+        ? 'runtime: package (the installed executable)'
+        : `runtime: development (${target.source})`;
+}
+/**
+ * 해법을 사람에게 말한다. **무엇에 대한 해법인지 먼저 말한다** (C-14 §3.4의 태도).
+ *
+ * `npm run build` 만 던지면 지금 열려 있는 저장소에서 그것을 실행할 사람이 있다.
+ */
+export function remediationLines(failure) {
+    const lines = [`${failure.code}: ${failure.detail}`];
+    if (failure.remediationTarget) {
+        lines.push(`  target: ${failure.remediationTarget}`);
+        lines.push(`  Build that checkout and retry — do not run this in the current directory.`);
+    }
+    lines.push(`  Run: ${failure.nextCommand}`);
+    return lines;
+}
+/** agent가 그대로 소비하는 형태. 어느 checkout인지가 데이터로 들어 있다. */
+export function remediationAction(failure) {
+    return failure.remediationTarget
+        ? {
+            type: 'build_development_runtime',
+            source: failure.remediationTarget,
+            display: failure.nextCommand,
+        }
+        : { type: 'select_development_runtime', display: failure.nextCommand };
+}

package/dist/core/execution/executor.d.ts

@@ -0,0 +1,51 @@
+import type { ExecutionGrant } from '../model/entities.ts';
+import type { ScmPort } from '../../ports/scm.ts';
+import type { StateStore } from '../../ports/state-store.ts';
+export type ExecuteOutcome = {
+    ok: true;
+    grant: ExecutionGrant;
+    resultRef: string;
+} | {
+    ok: false;
+    reason: 'NOT_FOUND';
+}
+/** 이미 누군가 집었거나 끝난 Grant. 재실행이 막히는 지점이다. */
+ | {
+    ok: false;
+    reason: 'NOT_CLAIMABLE';
+    status: ExecutionGrant['status'];
+} | {
+    ok: false;
+    reason: 'CLAIMED_BY_OTHER';
+} | {
+    ok: false;
+    reason: 'EXPIRED';
+}
+/** 계약이 허용하지 않는 행위다 — 계약서와 다른 일을 하려는 것이므로 실행하지 않는다. */
+ | {
+    ok: false;
+    reason: 'FORBIDDEN_ACTION';
+    detail: string;
+}
+/** 승인 이후 대상이 움직였다 — 실행하지 않고 되돌린다. */
+ | {
+    ok: false;
+    reason: 'DRIFT';
+    detail: string;
+} | {
+    ok: false;
+    reason: 'ACTION_FAILED';
+    detail: string;
+};
+export type ExecutorDeps = {
+    store: StateStore;
+    scm: ScmPort;
+    /** 이 Physical Run의 식별자. 누가 집었는지 Grant에 남는다. */
+    runId: string;
+    now?: () => string;
+};
+export declare class Executor {
+    #private;
+    constructor(deps: ExecutorDeps);
+    run(grantId: string): Promise<ExecuteOutcome>;
+}

package/dist/core/execution/executor.js

@@ -0,0 +1,106 @@
+// Ephemeral Executor — Grant 하나를 집어 외부 행위 한 번을 수행하고 끝난다.
+//
+// 이 파일이 시스템에서 유일하게 외부 write를 부르는 지점이다. 순서가 곧 안전장치다:
+//
+//   CLAIM (원자적)  →  계약 범위 확인  →  Drift Guard  →  외부 행위 1회  →  EXECUTED
+//
+// CLAIM을 먼저 하는 이유는 두 Executor가 같은 Grant로 같은 댓글을 두 번 달지 않게 하기
+// 위해서고, Drift Guard를 그 다음에 두는 이유는 승인 이후 스레드가 움직였을 때 오래된
+// 초안이 나가지 않게 하기 위해서다 (OM §11.9). 둘 다 실패는 조용히 넘어가지 않는다.
+import { transitionGrant, transitionRequest } from "../model/transitions.js";
+import { applyTransition } from "../runtime/store-ops.js";
+export class Executor {
+    #store;
+    #scm;
+    #runId;
+    #now;
+    constructor(deps) {
+        this.#store = deps.store;
+        this.#scm = deps.scm;
+        this.#runId = deps.runId;
+        this.#now = deps.now ?? (() => new Date().toISOString());
+    }
+    async run(grantId) {
+        const grant = await this.#store.get('grant', grantId);
+        if (!grant)
+            return { ok: false, reason: 'NOT_FOUND' };
+        if (grant.status !== 'READY')
+            return { ok: false, reason: 'NOT_CLAIMABLE', status: grant.status };
+        const at = this.#now();
+        if (grant.expiresAt && grant.expiresAt <= at) {
+            await this.#close(grant.id, 'EXPIRED', at, '만료');
+            return { ok: false, reason: 'EXPIRED' };
+        }
+        // 1. CLAIM — 두 Run이 동시에 들어와도 하나만 통과한다
+        const claimed = await applyTransition(this.#store, 'grant', grant.id, (g) => transitionGrant(g, 'CLAIMED', 'executor', { claimedBy: this.#runId }));
+        if (!claimed.ok) {
+            if (claimed.reason === 'NOT_FOUND')
+                return { ok: false, reason: 'NOT_FOUND' };
+            return { ok: false, reason: 'CLAIMED_BY_OTHER' };
+        }
+        // 2. 계약 범위 확인 — 허용 목록에 없는 행위는 하지 않는다 (fail-closed).
+        //    계약 자체가 모순이면 외부 상태를 조회할 이유도 없으므로 Drift Guard보다 앞에 둔다.
+        if (!claimed.entity.allowedWrites.includes(claimed.entity.action)) {
+            const detail = `'${claimed.entity.action}' is not in allowed writes [${claimed.entity.allowedWrites.join(', ')}]`;
+            await this.#close(grant.id, 'INVALIDATED', this.#now(), detail);
+            return { ok: false, reason: 'FORBIDDEN_ACTION', detail };
+        }
+        // 3. Drift Guard — 승인 시점의 기준선과 지금을 대조한다
+        const drift = await this.#detectDrift(claimed.entity);
+        if (drift) {
+            await this.#close(grant.id, 'INVALIDATED', this.#now(), drift);
+            return { ok: false, reason: 'DRIFT', detail: drift };
+        }
+        // 4. 외부 행위 1회. payload는 승인된 내용 그대로 나간다
+        const result = await this.#scm.execute({
+            action: claimed.entity.action,
+            target: claimed.entity.target,
+            payload: claimed.entity.payload,
+        });
+        if (!result.ok) {
+            // 재시도하지 않는다. 실패한 호출이 정말 나가지 않았는지는 여기서 알 수 없고,
+            // 모른 채 다시 부르면 같은 글이 두 번 올라간다. 사람이 확인하고 새 Grant를 낸다.
+            await this.#close(grant.id, 'INVALIDATED', this.#now(), `실행 실패: ${result.error}`);
+            return { ok: false, reason: 'ACTION_FAILED', detail: result.error };
+        }
+        // 5. 소비 기록 — 성공한 Grant는 다시 쓸 수 없다
+        const executedAt = this.#now();
+        const executed = await applyTransition(this.#store, 'grant', grant.id, (g) => transitionGrant(g, 'EXECUTED', 'executor', { resultRef: result.resultRef, consumedAt: executedAt }));
+        if (!executed.ok)
+            return { ok: false, reason: 'CLAIMED_BY_OTHER' };
+        // 6. 요청을 닫는다. 외부에 무엇이 남았는지 요청에서 바로 따라갈 수 있어야 한다
+        await applyTransition(this.#store, 'request', claimed.entity.requestId, (r) => transitionRequest(r, 'DONE', 'executor', { resultRef: result.resultRef }));
+        await this.#store.appendHistory({
+            at: executedAt,
+            actor: this.#runId,
+            kind: 'external_action',
+            ref: grant.id,
+            detail: `${grant.action} → ${grant.target} = ${result.resultRef}`,
+        });
+        return { ok: true, grant: executed.entity, resultRef: result.resultRef };
+    }
+    /** 무엇이 달라졌는지 문장으로 돌려준다. 달라진 것이 없으면 null. */
+    async #detectDrift(grant) {
+        if (grant.threadLastEventId !== undefined) {
+            const thread = await this.#scm.getThread(grant.target);
+            if (thread.missing)
+                return `대상 스레드를 찾을 수 없다 (${grant.target})`;
+            if (thread.lastEventId !== grant.threadLastEventId) {
+                return `스레드에 새 이벤트가 있다 (${grant.threadLastEventId} → ${thread.lastEventId})`;
+            }
+        }
+        if (grant.snapshot.length > 0) {
+            const current = await this.#scm.getBaselines(grant.snapshot.map((s) => ({ sourceId: s.sourceId })));
+            for (const now of current) {
+                const before = grant.snapshot.find((s) => s.sourceId === now.sourceId)?.baseline;
+                if (before !== now.baseline)
+                    return `정본이 바뀌었다 (${now.sourceId}: ${before} → ${now.baseline})`;
+            }
+        }
+        return null;
+    }
+    async #close(grantId, to, at, detail) {
+        await applyTransition(this.#store, 'grant', grantId, (g) => transitionGrant(g, to, 'executor'));
+        await this.#store.appendHistory({ at, actor: this.#runId, kind: `grant_${to.toLowerCase()}`, ref: grantId, detail });
+    }
+}

package/dist/core/execution/grant.d.ts

@@ -0,0 +1,42 @@
+import { ExecutionGrant } from '../model/entities.ts';
+import type { IdentityBinding } from '../../ports/approval.ts';
+import type { StateStore } from '../../ports/state-store.ts';
+export type IssueGrantInput = {
+    grantId: string;
+    requestId: string;
+    /** 발급자. 그 요청의 승인 권한자로 매핑돼 있어야 한다 — 임의 문자열로는 발급되지 않는다. */
+    issuedBy: string;
+    /** 발급이 들어온 표면. Identity 검증은 채널까지 함께 본다. */
+    channel: string;
+    /** '<adapter>.<행위>' 형태의 행위 키. Adapter가 해석한다. */
+    action: string;
+    target: string;
+    expiresAt?: string;
+    /** 이 계약으로 허용되는 행위 목록. 비우면 `action` 하나만 허용된다. */
+    allowedWrites?: string[];
+    issuedAt: string;
+};
+export type IssueFailure = {
+    kind: 'REQUEST_NOT_FOUND';
+} | {
+    kind: 'NOT_APPROVED';
+    status: string;
+} | {
+    kind: 'FORBIDDEN_ISSUER';
+} | {
+    kind: 'NO_PAYLOAD';
+} | {
+    kind: 'GRANT_EXISTS';
+};
+export type IssueResult = {
+    ok: true;
+    grant: ExecutionGrant;
+} | {
+    ok: false;
+    failure: IssueFailure;
+};
+export declare class GrantService {
+    #private;
+    constructor(store: StateStore, identity: IdentityBinding);
+    issue(input: IssueGrantInput): Promise<IssueResult>;
+}

package/dist/core/execution/grant.js

@@ -0,0 +1,78 @@
+// Execution Grant 발급 — 승인된 요청 하나를 밖으로 내보낼 수 있는 일회용 계약을 만든다.
+//
+// 승인은 게시 권한이 아니다 (OM §11.8). APPROVED는 "사람이 내용에 동의했다"까지이고,
+// 실제로 무엇을 어디에 쓸 것인지는 Controller가 별도로 지정한다. 그래서 Grant는 Policy
+// hierarchy의 예외가 아니라 그 바깥에서 새로 만들어지는 계약이다 (OM §5.2·§11.5).
+//
+// 승인 즉시 자동 발급하지 않는 이유도 같다. 두 행위를 붙여 놓으면 "승인했으니 나갔겠지"가
+// 되고, 무엇이 언제 나갔는지 사람이 따로 붙잡을 지점이 사라진다.
+import { ExecutionGrant } from "../model/entities.js";
+export class GrantService {
+    #store;
+    #identity;
+    constructor(store, identity) {
+        this.#store = store;
+        this.#identity = identity;
+    }
+    async issue(input) {
+        const request = await this.#store.get('request', input.requestId);
+        if (!request)
+            return { ok: false, failure: { kind: 'REQUEST_NOT_FOUND' } };
+        if (request.status !== 'APPROVED') {
+            return { ok: false, failure: { kind: 'NOT_APPROVED', status: request.status } };
+        }
+        // 발급도 Controller의 행위다. 승인만 검증하고 발급을 열어 두면 승인 이후 구간이
+        // 통째로 무방비가 된다 — 정작 외부로 나가는 권한은 여기서 만들어지기 때문이다.
+        const authorized = await this.#identity.verify({
+            channel: input.channel,
+            actor: input.issuedBy,
+            authorizedApprover: request.authorizedApprover,
+        });
+        if (!authorized) {
+            await this.#store.appendHistory({
+                at: input.issuedAt,
+                actor: input.issuedBy,
+                kind: 'grant_rejected',
+                ref: input.requestId,
+                detail: `unauthorized issuer via ${input.channel} (${input.action})`,
+            });
+            return { ok: false, failure: { kind: 'FORBIDDEN_ISSUER' } };
+        }
+        // 내보낼 내용은 승인된 것에서만 나온다. 호출자가 payload를 주입할 수 있으면
+        // 사람이 본 적 없는 글이 사람의 승인 기록을 달고 나갈 수 있다.
+        // 다른 내용을 보내려면 새 Decision을 받아야 한다.
+        const payload = request.decision?.revision ?? request.draft;
+        if (payload === undefined)
+            return { ok: false, failure: { kind: 'NO_PAYLOAD' } };
+        const grant = ExecutionGrant.parse({
+            id: input.grantId,
+            version: 0,
+            requestId: request.id,
+            status: 'READY',
+            issuedBy: input.issuedBy,
+            issuedAt: input.issuedAt,
+            ...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
+            singleUse: true,
+            action: input.action,
+            target: input.target,
+            payload,
+            // 이 시점의 정본이 Drift Guard의 기준선이 된다 (OM §11.9)
+            snapshot: request.snapshot,
+            ...(request.source.threadLastEventId !== undefined
+                ? { threadLastEventId: request.source.threadLastEventId }
+                : {}),
+            allowedWrites: input.allowedWrites ?? [input.action],
+        });
+        const created = await this.#store.create('grant', grant);
+        if (!created.ok)
+            return { ok: false, failure: { kind: 'GRANT_EXISTS' } };
+        await this.#store.appendHistory({
+            at: input.issuedAt,
+            actor: input.issuedBy,
+            kind: 'grant_issued',
+            ref: grant.id,
+            detail: `${grant.action} → ${grant.target} (request ${grant.requestId})`,
+        });
+        return { ok: true, grant: created.entity };
+    }
+}