@asc-agent/runtime 0.1.0

package/dist/adapters/local/presentation.js

@@ -0,0 +1,42 @@
+// Local Presentation — 마지막 안전망 (C-08 §1.3).
+//
+// 외부 채널이 하나도 없어도, 전부 실패해도, 판단 요청은 사라지지 않아야 한다. 그 보장을
+// 지는 것이 이 adapter다 — 여기까지 실패하면 그건 로컬 환경이 망가진 것이다.
+//
+// 세 능력을 다 제공한다: 묶음도 보이고, 급한 것도 따로 보이고, 결정도 여기서 받는다
+// (결정 자체는 기존 승인 경로가 처리한다 — 이 adapter는 보이는 데까지다).
+import { renderDigest } from "../../core/presentation/digest.js";
+export class LocalPresentation {
+    id = 'local';
+    capabilities = new Set([
+        'presentation.digest',
+        'presentation.priority',
+        'approval.interactive',
+    ]);
+    #write;
+    constructor(deps = {}) {
+        this.#write = deps.write ?? ((line) => console.log(line));
+    }
+    async presentDigest(batch) {
+        // 계획 없이 batch만 받았을 때도 같은 모양으로 보인다 — 표시 형식이 한 곳에만 있게.
+        const plan = {
+            urgent: batch.groups.find((g) => g.priority === 'P0')?.items.slice() ?? [],
+            batch,
+            skipped: {
+                alreadyDecided: batch.suppressed?.alreadyDecided ?? 0,
+                alreadyDelivered: 0,
+                shadow: batch.suppressed?.shadow ?? 0,
+            },
+            // Port는 batch만 받는다 — 감시 상태는 계획을 만든 쪽이 알고, 채널은 모른다
+            health: [],
+        };
+        for (const line of renderDigest(plan))
+            this.#write(line);
+        return { ok: true };
+    }
+    async presentUrgent(item) {
+        this.#write(`🔴 ${item.requestId}  ${item.reference}  ${item.title}`);
+        this.#write(`   지금 확인이 필요하다 — asc inbox show ${item.requestId}`);
+        return { ok: true };
+    }
+}

package/dist/adapters/markdown/layout.d.ts

@@ -0,0 +1,15 @@
+import type { EntityKind } from '../../ports/state-store.ts';
+export declare const CONTROL_STATE_FILE = "state.md";
+export declare const HISTORY_FILE = "monitor/log-current.md";
+export declare const VIEWS_DIR = "monitor/views";
+export declare const ADAPTER_SCOPE_DIR = "adapters";
+/**
+ * 파일명으로 쓸 수 없는 문자를 바꾼다. event key의 `comment:531245`가 대표적이다.
+ * 되돌릴 필요는 없다 — 원본 id는 파일 안에 그대로 들어 있고, 목록은 파일을 읽어 만든다.
+ */
+export declare function toFileName(id: string): string;
+export declare function entityDir(root: string, kind: EntityKind): string;
+export declare function entityFile(root: string, kind: EntityKind, id: string): string;
+export declare function archiveDir(root: string, kind: EntityKind): string;
+/** bootstrap 시 만들어 두는 디렉터리 목록. */
+export declare function allDirs(root: string): string[];

package/dist/adapters/markdown/layout.js

@@ -0,0 +1,49 @@
+// `.asc/` 파일 배치. 이건 Markdown Adapter의 표현일 뿐 Core Contract가 아니다 —
+// Core는 entity kind와 id만 알고, 어느 디렉터리에 놓이는지는 모른다 (OM §7.0).
+// 배치 근거: OM §7.1.
+import { join } from 'node:path';
+/** entity 한 종류가 사는 디렉터리. 파일 하나가 entity 하나다 (OM §7.2). */
+const ENTITY_DIR = {
+    session: 'sessions/active',
+    request: 'monitor/inbox',
+    grant: 'monitor/grants',
+    queueItem: 'monitor/queue',
+    event: 'monitor/events',
+};
+export const CONTROL_STATE_FILE = 'state.md';
+export const HISTORY_FILE = 'monitor/log-current.md';
+export const VIEWS_DIR = 'monitor/views';
+export const ADAPTER_SCOPE_DIR = 'adapters';
+/**
+ * 파일명으로 쓸 수 없는 문자를 바꾼다. event key의 `comment:531245`가 대표적이다.
+ * 되돌릴 필요는 없다 — 원본 id는 파일 안에 그대로 들어 있고, 목록은 파일을 읽어 만든다.
+ */
+export function toFileName(id) {
+    return id.replace(/[^A-Za-z0-9._-]/g, '-');
+}
+export function entityDir(root, kind) {
+    return join(root, ENTITY_DIR[kind]);
+}
+export function entityFile(root, kind, id) {
+    return join(entityDir(root, kind), `${toFileName(id)}.md`);
+}
+/** 끝난 entity가 가는 곳. 종류마다 자기 보관함을 갖는다 (OM §7.4). */
+const ARCHIVE_DIR = {
+    session: 'sessions/archive',
+    request: 'monitor/archive/inbox',
+    grant: 'monitor/archive/grants',
+    queueItem: 'monitor/archive/queue',
+    event: 'monitor/archive/events',
+};
+export function archiveDir(root, kind) {
+    return join(root, ARCHIVE_DIR[kind]);
+}
+/** bootstrap 시 만들어 두는 디렉터리 목록. */
+export function allDirs(root) {
+    return [
+        ...Object.values(ENTITY_DIR).map((dir) => join(root, dir)),
+        join(root, VIEWS_DIR),
+        join(root, ADAPTER_SCOPE_DIR),
+        ...Object.values(ARCHIVE_DIR).map((dir) => join(root, dir)),
+    ];
+}

package/dist/adapters/markdown/serialize.d.ts

@@ -0,0 +1,9 @@
+import type { EntityKind, EntityMap } from '../../ports/state-store.ts';
+export declare class ParseError extends Error {
+    file: string;
+    constructor(file: string, detail: string);
+}
+export declare function serializeEntity<K extends EntityKind>(kind: K, entity: EntityMap[K]): string;
+export declare function parseEntity(text: string, file?: string): unknown;
+/** 현재 판단 대기 목록. 원본에서 언제든 다시 만들 수 있는 Derived View다 (OM §7.3). */
+export declare function renderInboxView(requests: readonly EntityMap['request'][]): string;

package/dist/adapters/markdown/serialize.js

@@ -0,0 +1,120 @@
+// entity ↔ 파일 내용.
+//
+// 한 파일이 두 독자를 섬긴다: 기계는 HTML 주석 안의 JSON 블록을 읽고, 사람은 그 아래
+// Markdown 본문을 읽는다. 정본은 JSON 쪽이고 본문은 매번 다시 그려지는 projection이다 —
+// 사람이 본문만 고쳐 봐야 다음 저장에서 덮인다는 뜻이고, 그래서 본문을 정본으로
+// 삼으려는 유혹이 애초에 생기지 않는다.
+//
+// 왕복 무손실은 JSON 블록이 보장한다. 본문 렌더링이 아무리 성기어도 데이터는 잃지 않는다.
+const OPEN = '<!-- asc:entity';
+const CLOSE = '-->';
+export class ParseError extends Error {
+    file;
+    constructor(file, detail) {
+        super(`${file}: ${detail}`);
+        this.file = file;
+        this.name = 'ParseError';
+    }
+}
+export function serializeEntity(kind, entity) {
+    const json = JSON.stringify(entity, null, 2);
+    return `${OPEN}\n${json}\n${CLOSE}\n\n${renderBody(kind, entity)}\n`;
+}
+export function parseEntity(text, file = '<memory>') {
+    const start = text.indexOf(OPEN);
+    if (start === -1)
+        throw new ParseError(file, 'missing asc:entity block');
+    const end = text.indexOf(CLOSE, start + OPEN.length);
+    if (end === -1)
+        throw new ParseError(file, 'unterminated asc:entity block');
+    const json = text.slice(start + OPEN.length, end).trim();
+    try {
+        return JSON.parse(json);
+    }
+    catch (error) {
+        throw new ParseError(file, `invalid JSON — ${error.message}`);
+    }
+}
+// ── 사람이 읽는 본문 ────────────────────────────────────────────────────────
+// 상태를 눈으로 좇을 수 있을 만큼만 그린다. 완전한 표현은 Renderer Port의 몫이다.
+function renderBody(kind, entity) {
+    const lines = [];
+    switch (kind) {
+        case 'session': {
+            const s = entity;
+            lines.push(`# ${s.id} — ${s.role}`, '', `Status: ${s.status} (v${s.version})`, `Goal: ${s.goal}`);
+            if (s.owner)
+                lines.push(`Owner: ${s.owner}`);
+            if (s.writeBoundary?.length)
+                lines.push(`Write Boundary: ${s.writeBoundary.join(', ')}`);
+            for (const domain of s.decisionDomains ?? []) {
+                lines.push(`Decision: ${domain} → ${s.decisionAuthority?.[domain] ?? '(Profile ownership)'}`);
+            }
+            if (s.dependencies?.length)
+                lines.push(`Dependency: ${s.dependencies.join(', ')}`);
+            if (s.policyExceptions?.length)
+                lines.push(`Policy Exception: ${s.policyExceptions.join(', ')}`);
+            if (s.doneCriteria.length > 0) {
+                lines.push('', '## Done Criteria', ...s.doneCriteria.map((c) => `- ${c}`));
+            }
+            if (s.checkpoint)
+                lines.push('', '## CHECKPOINT', s.checkpoint.position, `다음: ${s.checkpoint.nextAction}`);
+            if (s.handoff) {
+                lines.push('', '## HANDOFF', `DONE: ${s.handoff.done.join(', ')}`, `NEXT: ${s.handoff.next}`);
+                if (s.handoff.unresolved?.length)
+                    lines.push(`UNRESOLVED: ${s.handoff.unresolved.join(' / ')}`);
+            }
+            break;
+        }
+        case 'request': {
+            const r = entity;
+            lines.push(`# ${r.id} · ${r.priority} · ${r.source.reference}`, '', `Status: ${r.status} (v${r.version})`, `Detected: ${r.detectedAt}`, '', '## 상황', r.situation);
+            if (r.draft)
+                lines.push('', '## 답변 초안', r.draft);
+            if (r.snapshot?.length) {
+                lines.push('', '## 정본 스냅샷', ...r.snapshot.map((s) => `- ${s.sourceId} @ ${s.baseline}`));
+            }
+            if (r.decision)
+                lines.push('', '## 처리 기록', `${r.decision.kind} — ${r.decision.actor} (${r.decision.channel})`);
+            break;
+        }
+        case 'grant': {
+            const g = entity;
+            lines.push(`# ${g.id} — ${g.action}`, '', `Status: ${g.status} (v${g.version})`, `Target: ${g.target}`, `Request: ${g.requestId}`, `Expires: ${g.expiresAt}`);
+            if (g.resultRef)
+                lines.push(`Result: ${g.resultRef}`);
+            break;
+        }
+        case 'queueItem': {
+            const q = entity;
+            lines.push(`# ${q.id} — ${q.title}`, '', `State: ${q.state} (v${q.version})`);
+            if (q.sessionId)
+                lines.push(`Session: ${q.sessionId}`);
+            break;
+        }
+        case 'event': {
+            const e = entity;
+            lines.push(`# ${e.eventKey}`, '', `${e.type} · ${e.suggestedPriority} · ${e.processing} (v${e.version})`, `Detected: ${e.detectedAt}`, `Inbox 후보: ${e.inboxCandidate ? 'yes' : 'no'}`);
+            break;
+        }
+    }
+    return lines.join('\n');
+}
+/** 현재 판단 대기 목록. 원본에서 언제든 다시 만들 수 있는 Derived View다 (OM §7.3). */
+export function renderInboxView(requests) {
+    const pending = requests.filter((r) => r.status === 'AWAITING_APPROVAL' || r.status === 'APPROVED');
+    const lines = [
+        '<!-- asc:view — 자동 생성물. 직접 고치지 마세요. -->',
+        '',
+        '# Inbox — 판단 대기',
+        '',
+        pending.length === 0 ? '_대기 중인 요청 없음_' : '| Request | 우선순위 | 상태 | 감지 | 제목 |',
+    ];
+    if (pending.length > 0) {
+        lines.push('|---|---|---|---|---|');
+        for (const r of [...pending].sort((a, b) => a.detectedAt.localeCompare(b.detectedAt))) {
+            lines.push(`| ${r.id} | ${r.priority} | ${r.status} | ${r.detectedAt} | ${r.title} |`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/adapters/markdown/state-store.d.ts

@@ -0,0 +1,23 @@
+import type { ControlState } from '../../core/model/entities.ts';
+import { type CasResult, type CreateResult, type EntityKind, type EntityMap, type HistoryEntry, type ListFilter, type ScopedStore, type StateStore } from '../../ports/state-store.ts';
+export declare class MarkdownStateStore implements StateStore {
+    #private;
+    constructor(root: string);
+    /** `.asc/` 위치. 감추지 않는다 — 디버깅과 direct-read fallback이 이 경로를 쓴다 (C-01 §12). */
+    get root(): string;
+    /** `.asc/` 뼈대를 만든다. 이미 있으면 그대로 쓴다. */
+    static open(root: string): Promise<MarkdownStateStore>;
+    get<K extends EntityKind>(kind: K, id: string): Promise<EntityMap[K] | null>;
+    list<K extends EntityKind>(kind: K, filter?: ListFilter<K>): Promise<EntityMap[K][]>;
+    create<K extends EntityKind>(kind: K, entity: EntityMap[K]): Promise<CreateResult<EntityMap[K]>>;
+    compareAndSet<K extends EntityKind>(kind: K, id: string, expectedVersion: number, next: EntityMap[K]): Promise<CasResult<EntityMap[K]>>;
+    /** 파일을 보관 디렉터리로 옮긴다. 내용은 그대로다 — 요약도 삭제도 하지 않는다. */
+    archive<K extends EntityKind>(kind: K, id: string): Promise<boolean>;
+    getControlState(): Promise<ControlState>;
+    setControlState(expectedVersion: number, next: ControlState): Promise<CasResult<ControlState>>;
+    appendHistory(entry: HistoryEntry): Promise<void>;
+    readHistory(limit?: number): Promise<HistoryEntry[]>;
+    scope(adapterId: string): ScopedStore;
+    /** 지워도 되고 언제든 다시 만들 수 있다 (OM §7.3). */
+    refreshViews(): Promise<void>;
+}

package/dist/adapters/markdown/state-store.js

@@ -0,0 +1,316 @@
+// Markdown State Store — 기본 State Store 구현 (OM §7.0~7.2).
+//
+// 동시성 전략은 두 층이다:
+//   생성  — O_EXCL(`wx`)이 파일시스템 차원에서 중복을 막는다. 락이 필요 없다.
+//   갱신  — 읽기·검사·쓰기가 한 덩어리여야 하므로 락 파일로 임계구역을 만들고,
+//           내용은 임시 파일에 쓴 뒤 rename으로 갈아 끼운다. rename은 원자적이라
+//           절반만 쓰인 파일이 남지 않는다.
+//
+// 락 대기와 CAS 충돌은 다른 사건이다. 락은 순간적이므로 잠깐 스핀해 기다리고,
+// version 불일치는 "그 사이 누가 결정했다"는 사실이므로 기다리지 않고 그대로 보고한다.
+import { constants } from 'node:fs';
+import { access, appendFile, mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ENTITY_KEY, } from "../../ports/state-store.js";
+import { ADAPTER_SCOPE_DIR, CONTROL_STATE_FILE, archiveDir, HISTORY_FILE, VIEWS_DIR, allDirs, entityDir, entityFile, toFileName, } from "./layout.js";
+import { parseEntity, renderInboxView, serializeEntity } from "./serialize.js";
+const LOCK_SPIN_MS = 5;
+const LOCK_ATTEMPTS = 200;
+/** 이보다 오래된 락은 죽은 프로세스가 남긴 것으로 보고 회수한다. */
+const LOCK_STALE_MS = 30_000;
+const EMPTY_CONTROL_STATE = {
+    version: 0,
+    activeSessions: [],
+    writeBoundaryOccupancy: [],
+    awaitingController: [],
+    controllerAttention: [],
+};
+let tmpCounter = 0;
+async function writeAtomic(file, content) {
+    const tmp = `${file}.tmp.${process.pid}.${tmpCounter++}`;
+    await writeFile(tmp, content, 'utf8');
+    await rename(tmp, file);
+}
+async function exists(file) {
+    try {
+        await access(file, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class MarkdownStateStore {
+    #root;
+    constructor(root) {
+        this.#root = root;
+    }
+    /** `.asc/` 위치. 감추지 않는다 — 디버깅과 direct-read fallback이 이 경로를 쓴다 (C-01 §12). */
+    get root() {
+        return this.#root;
+    }
+    /** `.asc/` 뼈대를 만든다. 이미 있으면 그대로 쓴다. */
+    static async open(root) {
+        for (const dir of allDirs(root))
+            await mkdir(dir, { recursive: true });
+        return new MarkdownStateStore(root);
+    }
+    // ── 락 ────────────────────────────────────────────────────────────────────
+    async #acquire(file) {
+        const lock = `${file}.lock`;
+        for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+            try {
+                const handle = await open(lock, 'wx');
+                await handle.close();
+                return async () => {
+                    await rm(lock, { force: true });
+                };
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                // ponytail: mtime 하나로 판단하는 stale 회수. 한 호스트에서만 쓰는 동안은 충분하고,
+                // 여러 호스트가 같은 .asc/를 공유하게 되면 임차(lease) 방식으로 올려야 한다.
+                try {
+                    const age = Date.now() - (await stat(lock)).mtimeMs;
+                    if (age > LOCK_STALE_MS)
+                        await rm(lock, { force: true });
+                }
+                catch {
+                    // 그 사이 풀렸다 — 다음 시도에서 잡으면 된다
+                }
+                await delay(LOCK_SPIN_MS);
+            }
+        }
+        throw new Error(`could not acquire lock for ${file}`);
+    }
+    async #withLock(file, fn) {
+        const release = await this.#acquire(file);
+        try {
+            return await fn();
+        }
+        finally {
+            await release();
+        }
+    }
+    // ── entity ────────────────────────────────────────────────────────────────
+    async #read(kind, file) {
+        try {
+            const text = await readFile(file, 'utf8');
+            return parseEntity(text, file);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    async get(kind, id) {
+        return this.#read(kind, entityFile(this.#root, kind, id));
+    }
+    async list(kind, filter = {}) {
+        const dir = entityDir(this.#root, kind);
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const rows = [];
+        for (const name of names) {
+            // 락·임시 파일은 entity가 아니다
+            if (!name.endsWith('.md'))
+                continue;
+            const entity = await this.#read(kind, join(dir, name));
+            if (entity)
+                rows.push(entity);
+        }
+        const where = filter.where;
+        const matched = where
+            ? rows.filter((row) => Object.entries(where).every(([f, v]) => row[f] === v))
+            : rows;
+        return matched.slice(0, filter.limit ?? matched.length);
+    }
+    async create(kind, entity) {
+        const id = String(entity[ENTITY_KEY[kind]]);
+        const file = entityFile(this.#root, kind, id);
+        try {
+            // 'wx'가 원자적 배타 생성이라 락 없이도 중복이 걸린다
+            await writeFile(file, serializeEntity(kind, entity), { encoding: 'utf8', flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const current = (await this.#read(kind, file));
+            return { ok: false, reason: 'ALREADY_EXISTS', current };
+        }
+        if (kind === 'request')
+            await this.refreshViews();
+        return { ok: true, entity };
+    }
+    async compareAndSet(kind, id, expectedVersion, next) {
+        if (next.version !== expectedVersion + 1) {
+            throw new Error(`CAS contract: next.version must be ${expectedVersion + 1}, got ${next.version}`);
+        }
+        const file = entityFile(this.#root, kind, id);
+        const result = await this.#withLock(file, async () => {
+            const current = await this.#read(kind, file);
+            if (!current)
+                return { ok: false, reason: 'NOT_FOUND' };
+            if (current.version !== expectedVersion)
+                return { ok: false, reason: 'VERSION_CONFLICT', current };
+            await writeAtomic(file, serializeEntity(kind, next));
+            return { ok: true, entity: next };
+        });
+        if (result.ok && kind === 'request')
+            await this.refreshViews();
+        return result;
+    }
+    /** 파일을 보관 디렉터리로 옮긴다. 내용은 그대로다 — 요약도 삭제도 하지 않는다. */
+    async archive(kind, id) {
+        const from = entityFile(this.#root, kind, id);
+        if (!(await exists(from)))
+            return false;
+        const dir = archiveDir(this.#root, kind);
+        await mkdir(dir, { recursive: true });
+        await rename(from, join(dir, `${toFileName(id)}.md`));
+        return true;
+    }
+    // ── Control State ─────────────────────────────────────────────────────────
+    async getControlState() {
+        const file = join(this.#root, CONTROL_STATE_FILE);
+        try {
+            return parseEntity(await readFile(file, 'utf8'), file);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { ...EMPTY_CONTROL_STATE };
+            throw error;
+        }
+    }
+    async setControlState(expectedVersion, next) {
+        if (next.version !== expectedVersion + 1) {
+            throw new Error(`CAS contract: next.version must be ${expectedVersion + 1}, got ${next.version}`);
+        }
+        const file = join(this.#root, CONTROL_STATE_FILE);
+        return this.#withLock(file, async () => {
+            const current = await this.getControlState();
+            if (current.version !== expectedVersion)
+                return { ok: false, reason: 'VERSION_CONFLICT', current };
+            await writeAtomic(file, renderControlState(next));
+            return { ok: true, entity: next };
+        });
+    }
+    // ── History ───────────────────────────────────────────────────────────────
+    async appendHistory(entry) {
+        const file = join(this.#root, HISTORY_FILE);
+        const line = [entry.at, entry.actor, entry.kind, entry.ref, entry.detail ?? ''].join(' | ');
+        // append-only. 요약하거나 줄이지 않는다 — 오래된 것은 archive로 옮길 뿐이다 (OM §7.4).
+        await this.#withLock(file, () => appendFile(file, `${line}\n`, 'utf8'));
+    }
+    async readHistory(limit) {
+        const file = join(this.#root, HISTORY_FILE);
+        if (!(await exists(file)))
+            return [];
+        const rows = (await readFile(file, 'utf8'))
+            .split('\n')
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            // detail에 구분자가 들어 있어도 잃지 않도록 앞 네 칸만 자르고 나머지는 합친다
+            const [at, actor, kind, ref, ...rest] = line.split(' | ');
+            const detail = rest.join(' | ');
+            return { at: at, actor: actor, kind: kind, ref: ref, ...(detail ? { detail } : {}) };
+        });
+        return limit ? rows.slice(-limit) : rows;
+    }
+    // ── Adapter scope ─────────────────────────────────────────────────────────
+    scope(adapterId) {
+        const dir = join(this.#root, ADAPTER_SCOPE_DIR, toFileName(adapterId));
+        const fileFor = (key) => join(dir, `${toFileName(key)}.json`);
+        return {
+            async get(key) {
+                try {
+                    return JSON.parse(await readFile(fileFor(key), 'utf8')).value;
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        return null;
+                    throw error;
+                }
+            },
+            async set(key, value) {
+                await mkdir(dir, { recursive: true });
+                // key도 함께 적는다 — 파일명은 문자를 바꿔 저장하므로 되돌릴 수 없다
+                await writeAtomic(fileFor(key), JSON.stringify({ key, value }, null, 2));
+            },
+            async setIfAbsent(key, value) {
+                await mkdir(dir, { recursive: true });
+                try {
+                    // 'wx'가 파일시스템 차원의 배타 생성이라, 프로세스가 여럿이어도 하나만 성공한다
+                    await writeFile(fileFor(key), JSON.stringify({ key, value }, null, 2), { encoding: 'utf8', flag: 'wx' });
+                    return true;
+                }
+                catch (error) {
+                    if (error.code === 'EEXIST')
+                        return false;
+                    throw error;
+                }
+            },
+            async delete(key) {
+                await rm(fileFor(key), { force: true });
+            },
+            async keys(prefix = '') {
+                let names;
+                try {
+                    names = await readdir(dir);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        return [];
+                    throw error;
+                }
+                const keys = [];
+                for (const name of names) {
+                    if (!name.endsWith('.json'))
+                        continue;
+                    const { key } = JSON.parse(await readFile(join(dir, name), 'utf8'));
+                    if (typeof key === 'string' && key.startsWith(prefix))
+                        keys.push(key);
+                }
+                return keys;
+            },
+        };
+    }
+    // ── Derived View ──────────────────────────────────────────────────────────
+    /** 지워도 되고 언제든 다시 만들 수 있다 (OM §7.3). */
+    async refreshViews() {
+        const requests = await this.list('request');
+        await mkdir(join(this.#root, VIEWS_DIR), { recursive: true });
+        await writeAtomic(join(this.#root, VIEWS_DIR, 'inbox.md'), renderInboxView(requests));
+    }
+}
+function renderControlState(state) {
+    const lines = [
+        '<!-- asc:entity',
+        JSON.stringify(state, null, 2),
+        '-->',
+        '',
+        '# Execution',
+        `활성 Block: ${state.activeBlock ?? '없음'}`,
+        `활성 세션: ${state.activeSessions.join(', ') || '없음'}`,
+        `Write Boundary 점유: ${state.writeBoundaryOccupancy.join(', ') || '없음'}`,
+        `승인 대기: ${state.awaitingController.join(', ') || '없음'}`,
+        '',
+        '# Monitoring',
+        '포인터만 둔다 — 숫자·시각은 갱신자가 없으므로 적지 않는다.',
+        'Inbox 미처분: monitor/views/inbox.md',
+        '',
+        '# Controller Attention',
+        ...(state.controllerAttention.length > 0 ? state.controllerAttention.map((a) => `- ${a}`) : ['- (없음)']),
+    ];
+    return lines.join('\n') + '\n';
+}

package/dist/adapters/mattermost/client.d.ts

@@ -0,0 +1,23 @@
+import type { MattermostPost, MattermostTransport } from './presentation.ts';
+export type MattermostClientDeps = {
+    /** `https://mm.example.com` — 팀마다 자체 호스팅이 흔하다. */
+    baseUrl: string;
+    token: string;
+    /** 요청 통로 주입점. 테스트가 실제 네트워크를 치지 않기 위한 자리다. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+/** 환경에서만 읽는다. 값의 존재 여부만 밖에 알린다. */
+export declare function discoverToken(env?: NodeJS.ProcessEnv): string | null;
+export declare function discoverBaseUrl(env?: NodeJS.ProcessEnv): string | null;
+export declare class MattermostClient implements MattermostTransport {
+    #private;
+    constructor(deps: MattermostClientDeps);
+    post(payload: MattermostPost): Promise<{
+        ok: true;
+        id: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}

package/dist/adapters/mattermost/client.js

@@ -0,0 +1,54 @@
+// Mattermost transport — HTTP 한 겹 (B-13).
+//
+// 자격은 **환경에서만** 온다. Profile·lock·docs·log 어디에도 남기지 않는다 (C-11 §8).
+// 이 파일이 토큰을 아는 것은 요청 헤더를 만드는 순간뿐이며, 실패 메시지에도 싣지 않는다 —
+// 오류 로그가 자격 유출 경로가 되는 것은 흔한 사고다.
+/** 환경에서만 읽는다. 값의 존재 여부만 밖에 알린다. */
+export function discoverToken(env = process.env) {
+    return env.ASC_MATTERMOST_TOKEN ?? env.MATTERMOST_TOKEN ?? null;
+}
+export function discoverBaseUrl(env = process.env) {
+    return env.ASC_MATTERMOST_URL ?? env.MATTERMOST_URL ?? null;
+}
+export class MattermostClient {
+    #baseUrl;
+    #token;
+    #fetch;
+    #timeoutMs;
+    constructor(deps) {
+        this.#baseUrl = deps.baseUrl.replace(/\/+$/, '');
+        this.#token = deps.token;
+        this.#fetch = deps.fetchImpl ?? fetch;
+        this.#timeoutMs = deps.timeoutMs ?? 10_000;
+    }
+    async post(payload) {
+        const controller = new AbortController();
+        // 매달린 요청이 회차를 통째로 잡아먹지 않게 한다
+        const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+        try {
+            const response = await this.#fetch(`${this.#baseUrl}/api/v4/posts`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#token}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                // 본문에 토큰이 되비쳐 오는 provider도 있다. 상태 코드까지만 옮긴다.
+                return { ok: false, error: `HTTP ${response.status}` };
+            }
+            const body = (await response.json());
+            return body.id ? { ok: true, id: body.id } : { ok: false, error: '응답에 post id가 없다' };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            // 자격이 메시지에 섞여 나가지 않게 한 번 더 거른다
+            return { ok: false, error: detail.replace(this.#token, '<redacted>') };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}