@asc-agent/runtime 0.3.2 → 0.5.0

package/README.md

@@ -7,7 +7,7 @@ proceed-by-default, escalation, audit, the external-write guard, host integratio
 here.
 
 ```bash
-npm install -g @asc-agent/runtime@0.3.2
+npm install -g @asc-agent/runtime@0.5.0
 ```
 
 npm owns the executable link (on Windows, npm's own `asc.cmd`). This package never edits

package/dist/adapters/claude-code/install.d.ts

@@ -1,6 +1,13 @@
 export type InstallPaths = {
     /** 보통 ~/.claude — 테스트가 격리 디렉터리를 넘긴다. */
     claudeHome: string;
+    /**
+     * 이 hook들을 부를 ASC CLI의 경로. SessionStart hook이 상태를 물어볼 곳이다.
+     *
+     * 없으면 SessionStart는 설치되지 않는다 — 어디를 부를지 모르는 hook을 심느니
+     * 그 기능이 없는 편이 낫다.
+     */
+    entry?: string;
 };
 export declare const defaultPaths: () => InstallPaths;
 export type InstallOutcome = {

package/dist/adapters/claude-code/install.js

@@ -14,12 +14,15 @@ import { mkdir, readFile, rm, rmdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { hookScript } from "./guard.js";
+import { sessionStartScript } from "./session-start.js";
 import { skillBundle } from "./skill.js";
 const sha = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
 export const defaultPaths = () => ({ claudeHome: join(homedir(), '.claude') });
-const HOOK_MATCHER = 'Bash';
 const HOOK_MARKER = 'asc-external-write-guard';
+const FRONT_MARKER = 'asc-front-binding';
 function locate(paths) {
+    const guard = join(paths.claudeHome, 'asc', 'guard-hook.mjs');
+    const front = join(paths.claudeHome, 'asc', 'front-hook.mjs');
     return {
         /** Bundle 전체. 파일이 늘어도 아래 계약(manifest·digest·멱등)은 그대로다 (C-05 §5). */
         skills: skillBundle().map((skill) => ({
@@ -28,11 +31,84 @@ function locate(paths) {
             text: skill.text,
         })),
         /** hook은 **하나**로 둔다. guard는 안전 층이고 중복 등록은 그 자체가 위험이다. */
-        hook: join(paths.claudeHome, 'asc', 'guard-hook.mjs'),
+        hook: guard,
+        front,
         settings: join(paths.claudeHome, 'settings.json'),
         manifest: join(paths.claudeHome, 'asc', 'install-manifest.json'),
+        hooks: (() => {
+            const specs = [
+                { event: 'PreToolUse', marker: HOOK_MARKER, matcher: 'Bash', script: guard },
+            ];
+            // 부를 곳을 모르면 심지 않는다 (§InstallPaths.entry)
+            if (paths.entry)
+                specs.push({ event: 'SessionStart', marker: FRONT_MARKER, script: front });
+            return specs;
+        })(),
     };
 }
+/**
+ * settings.json 의 hook 목록에서 **우리 항목만** 손본다 (C-03 §5.1).
+ *
+ * 표식이 없는 남의 항목은 읽지도 고치지도 않는다. 여기가 "사용자의 host integration을
+ * 보존한다"가 실제로 지켜지는 자리다 — 사람이 넣어 둔 SessionStart hook 옆에 우리 것을
+ * **더할** 뿐이다.
+ *
+ * 표식 없이 우리 스크립트를 가리키는 항목은 **옛 설치본이다.** 그것을 남으로 보면 재설치가
+ * 같은 guard를 하나 더 등록해 버린다 (실측: 표식 이전 버전으로 설치한 기계에서 그렇게
+ * 됐다). 그래서 명령이 우리 스크립트를 가리키면 그 항목을 우리 것으로 **입양한다**.
+ */
+function reconcileHooks(settings, specs) {
+    const hooks = { ...(settings.hooks ?? {}) };
+    const changed = [];
+    for (const spec of specs) {
+        const command = hookCommand(spec.script);
+        const entries = [...(hooks[spec.event] ?? [])];
+        let touched = false;
+        // 표식 없이 우리 스크립트를 가리키는 옛 항목을 입양한다
+        for (const entry of entries) {
+            for (const hook of entry.hooks ?? []) {
+                if (hook._asc === undefined && hook.command === command) {
+                    hook._asc = spec.marker;
+                    touched = true;
+                }
+            }
+        }
+        const ours = entries.filter((entry) => entry.hooks?.some((h) => h._asc === spec.marker));
+        if (ours.length === 0) {
+            entries.push({
+                ...(spec.matcher ? { matcher: spec.matcher } : {}),
+                hooks: [{ type: 'command', command, _asc: spec.marker }],
+            });
+            touched = true;
+        }
+        else {
+            // 등록은 돼 있는데 **다른 곳을 가리키는** 경우가 있다 — 그 상태에서 "설치됨"이라고
+            // 하면 hook이 없는데 있다고 믿는다. 우리 항목만 지금 경로로 고친다.
+            for (const entry of ours) {
+                for (const hook of entry.hooks ?? []) {
+                    if (hook._asc === spec.marker && hook.command !== command) {
+                        hook.command = command;
+                        touched = true;
+                    }
+                }
+            }
+            // 같은 표식이 여럿이면 하나만 남긴다 — 중복 등록은 그 자체가 결함이다
+            if (ours.length > 1) {
+                for (const extra of ours.slice(1)) {
+                    const at = entries.indexOf(extra);
+                    if (at >= 0)
+                        entries.splice(at, 1);
+                }
+                touched = true;
+            }
+        }
+        if (touched) {
+            hooks[spec.event] = entries;
+            changed.push(spec.event);
+        }
+    }
+    return { settings: changed.length > 0 ? { ...settings, hooks } : settings, changed };
+}
 async function readJson(path) {
     try {
         return JSON.parse(await readFile(path, 'utf8'));
@@ -60,6 +136,8 @@ export async function install(paths, now = () => new Date().toISOString(), opts
     for (const [path, content] of [
         ...where.skills.map((skill) => [skill.path, skill.text]),
         [where.hook, hookScript()],
+        // 부를 CLI를 모르면 SessionStart hook 자체를 만들지 않는다
+        ...(paths.entry ? [[where.front, sessionStartScript(paths.entry)]] : []),
     ]) {
         const existing = await readFile(path, 'utf8').catch(() => null);
         const state = fileState(existing, content, manifest.files[path]);
@@ -81,30 +159,12 @@ export async function install(paths, now = () => new Date().toISOString(), opts
         manifest.files[path] = sha(content);
         written.push(path);
     }
-    // settings.json에 PreToolUse hook 등록 — ASC 항목만 다루고 나머지는 손대지 않는다
-    const settings = (await readJson(where.settings)) ?? {};
-    const hooks = (settings.hooks ?? {});
-    const preToolUse = (hooks.PreToolUse ?? []);
-    const command = hookCommand(where.hook);
-    const ours = preToolUse.filter((entry) => entry.hooks?.some((h) => h._asc === HOOK_MARKER));
-    // 등록은 돼 있는데 **다른 곳을 가리키는** 경우가 있다 — 그 상태에서 "설치됨"이라고
-    // 하면 guard가 없는데 있다고 믿는다. 우리 항목만 지금 경로로 고친다.
-    const misdirected = ours.some((entry) => entry.hooks?.some((h) => h._asc === HOOK_MARKER && h.command !== command));
-    if (ours.length === 0) {
-        preToolUse.push({ matcher: HOOK_MATCHER, hooks: [{ type: 'command', command, _asc: HOOK_MARKER }] });
-    }
-    else if (misdirected) {
-        for (const entry of ours) {
-            for (const h of entry.hooks ?? [])
-                if (h._asc === HOOK_MARKER)
-                    h.command = command;
-        }
-    }
-    if (ours.length === 0 || misdirected) {
-        settings.hooks = { ...hooks, PreToolUse: preToolUse };
+    // settings.json 의 hook 등록 — **ASC 항목만** 다루고 나머지는 한 글자도 건드리지 않는다
+    const reconciled = reconcileHooks((await readJson(where.settings)) ?? {}, where.hooks);
+    if (reconciled.changed.length > 0) {
         await mkdir(dirname(where.settings), { recursive: true });
-        await writeFile(where.settings, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-        written.push(`${where.settings} (PreToolUse hook)`);
+        await writeFile(where.settings, JSON.stringify(reconciled.settings, null, 2) + '\n', 'utf8');
+        written.push(`${where.settings} (${reconciled.changed.join(', ')} hook)`);
     }
     manifest.settingsHook = true;
     await mkdir(dirname(where.manifest), { recursive: true });
@@ -131,6 +191,7 @@ export async function verifyInstall(paths) {
     const expected = [
         ...where.skills.map((skill) => [skill.path, skill.text]),
         [where.hook, hookScript()],
+        ...(paths.entry ? [[where.front, sessionStartScript(paths.entry)]] : []),
     ];
     const files = [];
     for (const [path, content] of expected) {
@@ -138,11 +199,16 @@ export async function verifyInstall(paths) {
         files.push({ path, state: fileState(existing, content, manifest?.files[path]) });
     }
     const settings = await readJson(where.settings);
-    const preToolUse = (settings?.hooks?.PreToolUse ?? []);
-    const ourHooks = preToolUse.flatMap((entry) => (entry.hooks ?? []).filter((h) => h._asc === HOOK_MARKER));
-    const hookRegistered = ourHooks.length > 0;
+    // 이벤트마다 우리 항목이 있는가. 하나라도 없으면 등록이 성립하지 않은 것으로 본다 —
+    // 반쯤 등록된 상태를 "설치됨"이라 부르면 없는 hook을 있다고 믿게 된다.
+    const registrations = where.hooks.map((spec) => {
+        const entries = (settings?.hooks?.[spec.event] ?? []);
+        const mine = entries.flatMap((entry) => (entry.hooks ?? []).filter((h) => h._asc === spec.marker));
+        return { present: mine.length > 0, pointsHere: mine.some((h) => h.command === hookCommand(spec.script)) };
+    });
+    const hookRegistered = registrations.every((r) => r.present);
     // 등록은 있는데 다른 곳을 가리키면 설치본이 뒤처진 것이다 — 없는 것으로 치지 않고 stale로 본다
-    const hookMisdirected = hookRegistered && !ourHooks.some((h) => h.command === hookCommand(where.hook));
+    const hookMisdirected = registrations.some((r) => r.present && !r.pointsHere);
     const status = (() => {
         if (!manifest && files.every((f) => f.state === 'missing') && !hookRegistered)
             return 'NOT_INSTALLED';
@@ -179,7 +245,7 @@ export function installReportLines(report) {
         lines.push(`  [${file.state}] ${file.path}`);
     }
     if (!report.hookRegistered)
-        lines.push('  [missing] PreToolUse hook registration in settings.json');
+        lines.push('  [missing] an ASC hook registration in settings.json');
     return lines;
 }
 /** manifest로 증명되는 것만 제거한다. 사용자가 고친 파일은 남기고 이유를 말한다. */
@@ -201,22 +267,32 @@ export async function uninstall(paths) {
         await rm(path);
         removed.push(path);
     }
-    // settings에서 ASC hook 항목만 걷어낸다 — 무관한 설정은 그대로
+    // settings에서 ASC hook 항목만 걷어낸다 — 무관한 설정은 그대로.
+    // 표식(`_asc`)이 소유권의 근거다: 사람이 넣은 SessionStart hook은 그 자리에 남는다.
     const settings = await readJson(where.settings);
     if (settings?.hooks) {
         const hooks = settings.hooks;
-        const preToolUse = (hooks.PreToolUse ?? []);
-        const filtered = preToolUse.filter((entry) => !entry.hooks?.some((h) => h._asc === HOOK_MARKER));
-        if (filtered.length !== preToolUse.length) {
-            if (filtered.length > 0)
-                hooks.PreToolUse = filtered;
+        // 지금 설치가 SessionStart를 안 심었더라도 옛 설치가 남긴 것은 걷는다 —
+        // 우리 표식이 붙은 것은 전부 우리 것이다.
+        const markers = new Set([HOOK_MARKER, FRONT_MARKER]);
+        const dropped = [];
+        for (const [event, value] of Object.entries(hooks)) {
+            const entries = (value ?? []);
+            const kept = entries.filter((entry) => !entry.hooks?.some((h) => h._asc && markers.has(h._asc)));
+            if (kept.length === entries.length)
+                continue;
+            if (kept.length > 0)
+                hooks[event] = kept;
             else
-                delete hooks.PreToolUse;
+                delete hooks[event];
+            dropped.push(event);
+        }
+        if (dropped.length > 0) {
             // 우리가 만든 hooks 컨테이너가 비면 키째 걷는다 — 빈 {}도 원래 없던 흔적이다
             if (Object.keys(hooks).length === 0)
                 delete settings.hooks;
             await writeFile(where.settings, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-            removed.push(`${where.settings} (PreToolUse hook entry)`);
+            removed.push(`${where.settings} (${dropped.join(', ')} hook entry)`);
         }
     }
     await rm(where.manifest, { force: true });

package/dist/adapters/claude-code/session-start.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SessionStart hook이 stdout으로 내는 봉투.
+ *
+ * 보여 줄 것이 없으면 **아무것도 내지 않는다** (`null`). 빈 봉투를 내면 ASC와 무관한
+ * 프로젝트의 모든 세션 첫 화면에 빈 블록이 붙는다 — 남의 도구를 방해하지 않는다
+ * (C-11 불변식 ⑪).
+ */
+export declare function sessionStartPayload(lines: readonly string[]): string | null;
+/**
+ * SessionStart hook 본문.
+ *
+ * `entry` 는 이 hook을 설치한 CLI의 경로다. 그 CLI가 다시 선택된 build로 넘긴다
+ * (`runtime use development` 도 그래서 그대로 먹는다) — hook이 build를 고르지 않는다.
+ *
+ * 계약 셋:
+ *   세션을 절대 막지 않는다        — 무슨 일이 나도 exit 0, stdout은 비거나 봉투 하나
+ *   ASC 무관 프로젝트에서 조용하다  — index에 없으면 CLI를 부르지도 않는다
+ *   기다리게 하지 않는다           — 상한을 두고, 넘으면 그냥 지나간다
+ */
+export declare function sessionStartScript(entry: string): string;

package/dist/adapters/claude-code/session-start.js

@@ -0,0 +1,111 @@
+// Claude Host — 세션이 열리면 지금 상태를 되찾는다 (C-12 §4·C-03 §5.6).
+//
+// Core는 "여기서 Front가 열렸다"까지만 안다 (`openFront`). 이 파일이 하는 일은 그 판정을
+// **Claude Code의 형식으로 옮기는 것**뿐이다:
+//
+//   Host lifecycle (SessionStart)  →  asc front open  →  additionalContext
+//
+// hook은 관찰이지 전이 권한이 아니다 (C-03 §5.6). 여기서 세션을 만들지 않고, 상태를
+// 옮기지 않으며, 승인 대기를 소비하지 않는다 — 읽고 보여 주는 것이 전부다.
+//
+// **다른 Host가 생겨도 Core는 그대로다.** 바뀌는 것은 이 파일 같은 adapter 하나다.
+/**
+ * SessionStart hook이 stdout으로 내는 봉투.
+ *
+ * 보여 줄 것이 없으면 **아무것도 내지 않는다** (`null`). 빈 봉투를 내면 ASC와 무관한
+ * 프로젝트의 모든 세션 첫 화면에 빈 블록이 붙는다 — 남의 도구를 방해하지 않는다
+ * (C-11 불변식 ⑪).
+ */
+export function sessionStartPayload(lines) {
+    if (lines.length === 0)
+        return null;
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'SessionStart',
+            additionalContext: ['ASC — what is open in this workspace right now:', ...lines].join('\n'),
+        },
+    });
+}
+/**
+ * SessionStart hook 본문.
+ *
+ * `entry` 는 이 hook을 설치한 CLI의 경로다. 그 CLI가 다시 선택된 build로 넘긴다
+ * (`runtime use development` 도 그래서 그대로 먹는다) — hook이 build를 고르지 않는다.
+ *
+ * 계약 셋:
+ *   세션을 절대 막지 않는다        — 무슨 일이 나도 exit 0, stdout은 비거나 봉투 하나
+ *   ASC 무관 프로젝트에서 조용하다  — index에 없으면 CLI를 부르지도 않는다
+ *   기다리게 하지 않는다           — 상한을 두고, 넘으면 그냥 지나간다
+ */
+export function sessionStartScript(entry) {
+    return `#!/usr/bin/env node
+// ASC front binding (SessionStart) — 설치·갱신은 \`asc host claude install\` 로만.
+// 이 자리에 붙은 ASC workspace가 있으면 지금 무엇이 걸려 있는지 세션 첫 화면에 얹는다.
+// ASC와 무관한 프로젝트에서는 아무것도 하지 않는다.
+//
+// **이 hook은 무엇도 막지 않는다.** 어떤 실패도 exit 0 이고, 그때 stdout은 비어 있다 —
+// 상태를 못 읽었다고 사람의 세션이 안 열리면 그것이 더 큰 고장이다.
+//
+// **workspace 신원을 여기서 판정하지 않는다.** 예전에는 index를 직접 뒤져 걸리지 않으면
+// 빠져나갔는데, 그러면 아직 등록되지 않은 linked worktree에서 Host를 처음 여는 경우가
+// 통째로 빠진다 — 그 자리를 풀 수 있는 것은 공용 resolver뿐이다 (C-11 §1.3).
+// 여기서 보는 것은 "이 기계가 ASC를 쓰기는 하는가" 한 가지이고, 그것은 신원이 아니다.
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const ENTRY = ${JSON.stringify(entry)}
+/** 이 안에 못 끝내면 지나간다. 세션 시작을 기다리게 하지 않는다. */
+const BUDGET_MS = 10_000
+
+/**
+ * 이 기계에 ASC runtime state가 있는가 — 파일 존재 확인 하나.
+ *
+ * 없으면 어느 경로도 ASC 자리일 수 없으므로 CLI를 부르지 않는다. 이것은 workspace
+ * 판정이 아니라 "부를 이유가 있는가"이며, 그 판정은 아래 \`front open\` 이 한다.
+ */
+function ascUsedHere() {
+  const home = process.env.ASC_HOME || join(homedir(), '.asc')
+  return existsSync(join(home, 'workspace-index.json')) || existsSync(join(home, 'workspaces'))
+}
+
+function main() {
+  let cwd = process.cwd()
+  try {
+    // SessionStart 입력에 cwd가 실린다. 없으면 프로세스의 cwd가 곧 그 자리다.
+    const raw = readFileSync(0, 'utf8')
+    if (raw.trim()) cwd = JSON.parse(raw).cwd || cwd
+  } catch {
+    // 읽지 못해도 계속한다 — 입력 형식 하나 때문에 복원을 통째로 버리지 않는다
+  }
+
+  if (!ascUsedHere()) return
+
+  // 붙지 않은 자리에서도 이 명령은 성공하고 조용하다. 판정은 전부 저쪽이 한다.
+  const run = spawnSync(process.execPath, [ENTRY, 'front', 'open', '--json'], {
+    cwd,
+    encoding: 'utf8',
+    timeout: BUDGET_MS,
+    env: process.env,
+  })
+  if (run.status !== 0 || !run.stdout) return
+
+  let payload
+  try {
+    payload = JSON.parse(run.stdout).payload
+  } catch {
+    return
+  }
+  if (typeof payload === 'string' && payload) process.stdout.write(payload)
+}
+
+try {
+  main()
+} catch {
+  // 세션을 막지 않는다
+}
+process.exit(0)
+`;
+}

package/dist/adapters/fixture-surface/index.d.ts

@@ -0,0 +1,33 @@
+import type { CoordinationSurfacePort, PublicPayload, SurfaceCandidate, SurfaceQuery, SurfaceSnapshot } from '../../ports/coordination-surface.ts';
+import type { RemoteIdentity } from '../../core/runtime/coordination.ts';
+type Stored = {
+    objectId: string;
+    payload: PublicPayload;
+    correlation: string;
+    workReference?: string;
+    closed?: boolean;
+};
+export type FixtureSurfaceDeps = {
+    /** 이 횟수만큼은 만들고 나서 응답을 잃는다. 객체는 남는다 — 그것이 이 사고의 요점이다. */
+    loseNextResponses?: number;
+    /** 주소를 어떻게 짓는가. 판정이 주소에 기대고 있으면 이 값을 바꿔 보면 드러난다. */
+    locatorShape?: (objectId: string) => string;
+    /** 찾기가 실패하는가. 못 찾은 것과 없는 것은 다른 사실이다. */
+    findFails?: boolean;
+};
+export declare class FixtureSurfaceAdapter implements CoordinationSurfacePort {
+    #private;
+    readonly id = "fixture-surface";
+    readonly objects: Stored[];
+    /** 실제로 만들기가 몇 번 일어났는가. 중복 생성 0 을 세는 자리다. */
+    createCalls: number;
+    constructor(deps?: FixtureSurfaceDeps);
+    find(query: SurfaceQuery): Promise<SurfaceCandidate[]>;
+    create(payload: PublicPayload, query: SurfaceQuery): Promise<RemoteIdentity>;
+    read(identity: Pick<RemoteIdentity, 'objectType' | 'objectId'>): Promise<SurfaceSnapshot | null>;
+    /** 밖에서 일어난 일을 흉내 낸다 — 시험이 게시물을 닫거나 남의 것을 심을 때 쓴다. */
+    seed(stored: Omit<Stored, 'objectId'> & {
+        objectId?: string;
+    }): RemoteIdentity;
+}
+export {};

package/dist/adapters/fixture-surface/index.js

@@ -0,0 +1,97 @@
+// Fixture Coordination Surface — 조율 표면 계약을 provider 없이 돌린다 (R7).
+//
+// 왜 있는가: 조율이 특정 회사 도구의 성질이 아니라는 것은, 그 도구가 아닌 것으로도
+// 같은 계약이 성립할 때만 증명된다. 여기 있는 것은 메모리 위의 게시판 하나이며,
+// Core 는 이것과 실제 adapter 를 구분하지 못한다 — 구분하면 그것이 결함이다.
+//
+// 실 사고를 흉내 낼 수 있어야 쓸모가 있다. 그래서 두 개의 손잡이가 있다:
+//   `loseNextResponses` — 만들어지긴 하는데 응답을 잃는다 (중복 생성의 실제 원인)
+//   `locatorShape`      — 주소 모양이 바뀐다 (주소로 판정하면 여기서 깨진다)
+export class FixtureSurfaceAdapter {
+    id = 'fixture-surface';
+    objects = [];
+    /** 실제로 만들기가 몇 번 일어났는가. 중복 생성 0 을 세는 자리다. */
+    createCalls = 0;
+    #lose;
+    #locator;
+    #findFails;
+    constructor(deps = {}) {
+        this.#lose = deps.loseNextResponses ?? 0;
+        this.#locator = deps.locatorShape ?? ((objectId) => `fixture://board/${objectId}`);
+        this.#findFails = deps.findFails ?? false;
+    }
+    #identity(stored) {
+        return {
+            adapter: this.id,
+            objectType: 'thread',
+            objectId: stored.objectId,
+            resource: 'board',
+            locator: this.#locator(stored.objectId),
+        };
+    }
+    async find(query) {
+        if (this.#findFails)
+            throw new Error('surface unreachable');
+        const out = [];
+        const seen = new Set();
+        const push = (stored, matchedBy) => {
+            if (seen.has(stored.objectId))
+                return;
+            seen.add(stored.objectId);
+            out.push({
+                identity: this.#identity(stored),
+                title: stored.payload.title,
+                matchedBy,
+                ...(stored.closed ? { closed: true } : {}),
+            });
+        };
+        for (const known of query.known ?? []) {
+            const hit = this.objects.find((stored) => stored.objectId === known.objectId);
+            if (hit)
+                push(hit, 'known-identity');
+        }
+        for (const stored of this.objects) {
+            if (stored.correlation === query.correlation)
+                push(stored, 'correlation');
+        }
+        if (query.workReference) {
+            for (const stored of this.objects) {
+                if (stored.workReference === query.workReference)
+                    push(stored, 'work-reference');
+            }
+        }
+        return out;
+    }
+    async create(payload, query) {
+        this.createCalls += 1;
+        const stored = {
+            objectId: `OBJ-${this.objects.length + 1}`,
+            payload,
+            correlation: query.correlation,
+            ...(query.workReference ? { workReference: query.workReference } : {}),
+        };
+        // 먼저 남기고 나서 응답을 잃는다 — 반대로 하면 이 fixture 가 흉내 내는 사고가 아니다.
+        this.objects.push(stored);
+        if (this.#lose > 0) {
+            this.#lose -= 1;
+            throw new Error('response lost after the object was created');
+        }
+        return this.#identity(stored);
+    }
+    async read(identity) {
+        const hit = this.objects.find((stored) => stored.objectId === identity.objectId);
+        if (!hit)
+            return null;
+        return {
+            identity: this.#identity(hit),
+            title: hit.payload.title,
+            ...(hit.closed ? { closed: true } : {}),
+        };
+    }
+    /** 밖에서 일어난 일을 흉내 낸다 — 시험이 게시물을 닫거나 남의 것을 심을 때 쓴다. */
+    seed(stored) {
+        const full = { objectId: stored.objectId ?? `OBJ-${this.objects.length + 1}`, ...stored };
+        this.objects.push(full);
+        return this.#identity(full);
+    }
+}

package/dist/adapters/gitlab/adapter.js

@@ -12,6 +12,7 @@ const PROVIDES = [
     'context.resource',
     'context.thread',
     'context.change',
+    'coordination.surface',
 ];
 /**
  * 이 host는 다른 adapter가 맡는다. 여기서 후보로 잡으면 같은 remote를 둘이 주장한다.

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

@@ -28,23 +28,37 @@ export declare function glabAvailable(run: ProcessRunner): Promise<boolean>;
  * `glab api` 를 읽기 통로로 감싼 클라이언트. GET 만 다룬다 — 쓰기는 Grant 를 지나야 하고,
  * 그 경로를 우회하는 통로를 여기에 만들지 않는다.
  */
-export declare class GlabApiClient implements GitLabReader {
+export declare class GlabApiClient implements GitLabReader, GitLabWriter {
     #private;
     constructor(run: ProcessRunner);
     get<T>(path: string): Promise<GitLabResponse<T>>;
+    post<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
 }
 /**
  * 읽기 통로. GitLabClient(토큰)와 GlabApiClient(로그인된 도구) 둘 다 이것이다 —
  * Port 들은 어느 쪽인지 몰라야 한다. 통로가 바뀌었다고 조회 코드가 바뀌면, 통로를 늘릴
  * 때마다 같은 코드가 갈라진다.
  */
+/**
+ * 쓰기 통로. **읽기와 일부러 갈라 둔다** — 조회 코드가 쓰기를 할 수 있으면 어디서 무엇이
+ * 나가는지 아무도 세지 못한다. 이것을 쥔 곳은 조율 표면 하나뿐이고, 거기서 나가는 것은
+ * 공개 payload 로 제한돼 있다.
+ *
+ * 승인(Grant)을 지나는 외부 Action 과는 다른 경로다. 그쪽은 사람이 승인한 단일 행동을
+ * 그대로 내보내는 통로이고, 이쪽은 물어본 것이 밖에 실제로 있게 하는 조율 행위다.
+ * 둘을 한 통로로 합치면 승인의 의미가 흐려진다.
+ */
+export interface GitLabWriter {
+    post<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
+}
 export interface GitLabReader {
     get<T>(path: string): Promise<GitLabResponse<T>>;
 }
-export declare class GitLabClient implements GitLabReader {
+export declare class GitLabClient implements GitLabReader, GitLabWriter {
     #private;
     constructor(deps: GitLabClientDeps);
     get<T>(path: string): Promise<GitLabResponse<T>>;
+    post<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
 }
 /** `group/sub/project!19` 또는 `group/project#7` 을 쪼갠다. */
 export declare function parseRef(reference: string): {

package/dist/adapters/gitlab/client.js

@@ -39,6 +39,18 @@ export class GlabApiClient {
             return { ok: false, status: 0, data: null, error: String(error.message ?? error).slice(0, 200) };
         }
     }
+    async post(path, body) {
+        // 값 하나가 한 필드다. 문자열을 만들어 붙이지 않는다 — 그렇게 하면 본문에 개행이나
+        // 따옴표가 있을 때 조용히 다른 것이 나간다.
+        const fields = Object.entries(body).flatMap(([key, value]) => value === undefined ? [] : ['-f', `${key}=${String(value)}`]);
+        try {
+            const stdout = await this.#run('glab', ['api', '--method', 'POST', path.replace(/^\//, ''), ...fields]);
+            return { ok: true, status: 201, data: JSON.parse(stdout) };
+        }
+        catch (error) {
+            return { ok: false, status: 0, data: null, error: String(error.message ?? error).slice(0, 200) };
+        }
+    }
 }
 export class GitLabClient {
     #token;
@@ -65,6 +77,21 @@ export class GitLabClient {
             ...(nextPage ? { nextPage } : {}),
         };
     }
+    async post(path, body) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/json',
+                'private-token': this.#token,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            return { ok: false, status: response.status, data: null, error: `HTTP ${response.status}` };
+        }
+        return { ok: true, status: response.status, data: (await response.json()) };
+    }
 }
 /** `group/sub/project!19` 또는 `group/project#7` 을 쪼갠다. */
 export function parseRef(reference) {

package/dist/adapters/gitlab/coordination.d.ts

@@ -0,0 +1,19 @@
+import type { CoordinationSurfacePort, PublicPayload, SurfaceCandidate, SurfaceQuery, SurfaceSnapshot } from '../../ports/coordination-surface.ts';
+import type { RemoteIdentity } from '../../core/runtime/coordination.ts';
+import { type GitLabReader, type GitLabWriter } from './client.ts';
+/** 상관 관계를 심는 방법. 라벨 하나이고, 그 안에 들어가는 것은 기대 id 뿐이다. */
+export declare const CORRELATION_LABEL = "asc-coordination";
+export type GitLabCoordinationDeps = {
+    reader: GitLabReader;
+    /** 없으면 만들 수 없다. **없는 것을 있는 척하지 않는다** — create 가 그렇게 답한다. */
+    writer?: GitLabWriter;
+    project: string;
+};
+export declare class GitLabCoordinationSurface implements CoordinationSurfacePort {
+    #private;
+    readonly id = "gitlab";
+    constructor(deps: GitLabCoordinationDeps);
+    find(query: SurfaceQuery): Promise<SurfaceCandidate[]>;
+    create(payload: PublicPayload, query: SurfaceQuery): Promise<RemoteIdentity>;
+    read(identity: Pick<RemoteIdentity, 'objectType' | 'objectId'>): Promise<SurfaceSnapshot | null>;
+}