@asc-agent/runtime 0.1.0

package/dist/core/attach/bootstrap.d.ts

@@ -0,0 +1,102 @@
+import type { AdapterRuntime, BindingPlan, Capability, ResolvedBinding } from '../binding/types.ts';
+export type ProfileChoice = 
+/** 사람이 지정했다. */
+{
+    kind: 'GIVEN';
+    id: string;
+}
+/** 이미 붙어 있고 lock이 무엇으로 붙었는지 안다. */
+ | {
+    kind: 'ALREADY_ATTACHED';
+    id: string;
+}
+/** 후보는 있는데 정해지지 않았다. 하나뿐이어도 여기 머문다. */
+ | {
+    kind: 'UNDECIDED';
+    candidates: string[];
+}
+/** 붙어 있는데 무엇으로 붙었는지 읽지 못했다. 붙이다 만 상태다. */
+ | {
+    kind: 'ATTACHED_UNKNOWN';
+};
+export type HostState = {
+    id: string;
+    installed: boolean;
+};
+/**
+ * 정책은 사람이 정한다 (C-09 §7.1). adapter가 찾아 주는 것과 그것이 무슨 뜻인지 정하는 것은
+ * 다른 일이며, 후자를 대신 정하면 그건 wizard다 (C-06 §2).
+ */
+export declare const POLICY_QUESTIONS: readonly [{
+    readonly id: "canonical";
+    readonly question: "어느 branch·ref가 canonical인가";
+}, {
+    readonly id: "work-ssot";
+    readonly question: "작업 항목의 정본이 어디인가";
+}, {
+    readonly id: "ownership";
+    readonly question: "ownership path는 무엇인가";
+}, {
+    readonly id: "authority";
+    readonly question: "decision authority는 누구인가";
+}, {
+    readonly id: "digest-channel";
+    readonly question: "기본 전달 채널은 무엇인가";
+}];
+export type PolicyId = (typeof POLICY_QUESTIONS)[number]['id'];
+export type BootstrapPlan = {
+    projectRoot: string;
+    git: boolean;
+    attached: boolean;
+    profile: ProfileChoice;
+    hosts: HostState[];
+    /** 발견된 외부 연결 후보와 실측 상태 (C-09 §7). 없으면 로컬 루프만 도는 것이다. */
+    bindings: readonly ResolvedBinding[];
+    /**
+     * adapter 자체의 상태. binding과 나눠서 보여 준다 — "도구는 쓸 수 있는데 이 프로젝트가
+     * 아직 붙어 있지 않다"와 "도구가 없다"는 사람이 할 일이 다르다.
+     */
+    runtimes: readonly AdapterRuntime[];
+    /** 지금 실제로 쓸 수 있는 semantic capability. adapter 이름이 아니라 할 수 있는 일이다. */
+    capabilities: readonly Capability[];
+    /** 사람이 실행할 다음 명령. 문자열이다 — 자동으로 태우지 않는다. */
+    steps: string[];
+    /** 사람이 정해야 남은 것. 비어 있지 않으면 계획은 아직 계획일 뿐이다. */
+    undecided: string[];
+};
+export type BootstrapInput = {
+    cwd: string;
+    /** ASC 설치 경로. `profiles/` 를 여기서 읽는다. */
+    installRoot: string;
+    /**
+     * 이 위치가 붙어 있다면 그 runtime 뿌리. **Surface가 정해서 넘긴다** — Core가 여기서
+     * 다시 찾으면 저장소 안의 `.asc` 만 보게 되고, 그것이 기본이 아닌 지금은
+     * local scope로 붙은 workspace를 "안 붙었다"고 답하게 된다 (C-11 §3).
+     */
+    ascRoot?: string;
+    /** 사람이 지정한 Profile. 없으면 후보만 제시한다. */
+    profileId?: string;
+    /**
+     * Host 설치 상태. Core는 어떤 Host가 있는지 모른다 — Surface가 알아내 넘긴다.
+     * 이름이 이 파일에 들어오는 순간 Core가 provider를 아는 셈이 된다.
+     */
+    hosts?: readonly HostState[];
+    /**
+     * Composition이 조립한 Binding Plan (C-09 §7). 같은 이유로 여기서 adapter를 부르지 않는다 —
+     * 이 파일은 결과를 계획에 싣기만 한다.
+     */
+    bindings?: BindingPlan;
+    /**
+     * 이미 선언된 정책. **붙어 있다는 것이 정책이 전부 정해졌다는 뜻은 아니다** —
+     * Profile이 무엇을 선언했는지는 Surface가 읽어 알려 주고, 남은 것을 여기서 묻는다.
+     */
+    declaredPolicies?: readonly PolicyId[];
+    /** 정책 질문 자체를 생략할지. 계획만 보려는 호출용이다. */
+    askPolicy?: boolean;
+};
+/** 설치 경로의 Profile 후보. 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다. */
+export declare function availableProfiles(installRoot: string): Promise<string[]>;
+/** 감지하고 계획을 세운다. 파일은 하나도 건드리지 않는다. */
+export declare function planBootstrap(input: BootstrapInput): Promise<BootstrapPlan>;
+/** 사람이 읽는 계획. 무엇이 정해지지 않았는지가 먼저 오도록 짠다. */
+export declare function renderPlan(plan: BootstrapPlan): string;

package/dist/core/attach/bootstrap.js

@@ -0,0 +1,178 @@
+// Bootstrap Resolver — 붙이기 전에 무엇이 있고 무엇이 정해지지 않았는지 본다 (C-06).
+//
+// 두 진입(CLI의 `asc init` / 자연어 "ASC로 진행해")이 여기서 만난다. 진입만 다르고 판정은 하나여야
+// 한다 — 자연어 경로가 CLI 경로보다 더 할 수 있는 것도, 덜 할 수 있는 것도 없다.
+//
+// 이 모듈은 **아무것도 쓰지 않는다.** 감지하고, 무엇을 할지 적고, 돌려준다. 실행은 기존
+// 표면(init / host install / profile resolve)이 그대로 한다 — 새 orchestration 계층을
+// 만들면 같은 일을 하는 경로가 둘이 되고, 그때부터 둘이 조금씩 달라진다.
+//
+// 후보를 찾아 주는 것과 그중 하나를 대신 고르는 것은 다른 일이다. 후보가 하나뿐이어도
+// 고르지 않는다 (C-06 §2) — Profile 선택은 그 프로젝트가 어떤 규칙 아래 돌지를 정하는
+// 결정이고, 그건 사람 몫이다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { availableCapabilities } from "../binding/types.js";
+import { discoverProjectRoot, exists } from "./init.js";
+/**
+ * 정책은 사람이 정한다 (C-09 §7.1). adapter가 찾아 주는 것과 그것이 무슨 뜻인지 정하는 것은
+ * 다른 일이며, 후자를 대신 정하면 그건 wizard다 (C-06 §2).
+ */
+export const POLICY_QUESTIONS = [
+    { id: 'canonical', question: '어느 branch·ref가 canonical인가' },
+    { id: 'work-ssot', question: '작업 항목의 정본이 어디인가' },
+    { id: 'ownership', question: 'ownership path는 무엇인가' },
+    { id: 'authority', question: 'decision authority는 누구인가' },
+    { id: 'digest-channel', question: '기본 전달 채널은 무엇인가' },
+];
+/** 설치 경로의 Profile 후보. 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다. */
+export async function availableProfiles(installRoot) {
+    try {
+        const entries = await readdir(join(installRoot, 'profiles'), { withFileTypes: true });
+        const ids = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (await exists(join(installRoot, 'profiles', entry.name, 'profile.json')))
+                ids.push(entry.name);
+        }
+        return ids.sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** 붙어 있다면 무엇으로 붙었는가. lock을 읽지 못하면 붙이다 만 상태로 본다. */
+async function attachedProfile(ascRoot) {
+    try {
+        const lock = JSON.parse(await readFile(join(ascRoot, 'profile.lock'), 'utf8'));
+        return typeof lock.profile?.id === 'string' ? lock.profile.id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 감지하고 계획을 세운다. 파일은 하나도 건드리지 않는다. */
+export async function planBootstrap(input) {
+    const { root: projectRoot, git } = await discoverProjectRoot(input.cwd);
+    // 넘겨받은 것이 없을 때만 저장소 안을 본다 — 옛 경로를 계속 지원하되 기본으로 두지 않는다.
+    const ascRoot = input.ascRoot ?? join(projectRoot, '.asc');
+    const attached = await exists(ascRoot);
+    const candidates = await availableProfiles(input.installRoot);
+    const hosts = [...(input.hosts ?? [])];
+    const plan = input.bindings ?? { bindings: [] };
+    const locked = attached ? await attachedProfile(ascRoot) : null;
+    const profile = input.profileId
+        ? { kind: 'GIVEN', id: input.profileId }
+        : locked
+            ? { kind: 'ALREADY_ATTACHED', id: locked }
+            : attached
+                ? { kind: 'ATTACHED_UNKNOWN' }
+                : { kind: 'UNDECIDED', candidates };
+    const steps = [];
+    const undecided = [];
+    if (profile.kind === 'UNDECIDED') {
+        undecided.push(candidates.length === 0
+            ? '쓸 수 있는 Profile이 없다 — 설치 경로에 profiles/<id>/profile.json 이 있어야 한다'
+            : `어떤 Profile로 붙일지 (후보: ${candidates.join(', ')})`);
+        if (candidates.length > 0)
+            steps.push('asc init --profile <위 후보 중 하나>');
+    }
+    else if (profile.kind === 'ATTACHED_UNKNOWN') {
+        // 통과시키면 무엇으로 도는지 모르는 채 굴러간다 — bootstrapGuard가 막는 것과 같은 상태다
+        undecided.push('.asc/ 는 있는데 profile.lock 을 읽지 못했다 — 붙이다 만 상태다');
+        steps.push('asc init --profile <id> 로 다시 붙이거나 asc profile resolve --write 로 고정한다');
+    }
+    else if (!attached) {
+        steps.push(`asc init --profile ${profile.id}`);
+    }
+    for (const host of hosts) {
+        if (!host.installed)
+            steps.push(`asc host ${host.id} install`);
+    }
+    // 설정만 채우면 열리는 것과 지금 닿지 않는 것을 나눠 말한다 — 합치면 사람이 무엇을
+    // 해야 하는지 알 수 없다 (C-09 §5.1).
+    for (const binding of plan.bindings) {
+        if (binding.state === 'UNCONFIGURED') {
+            undecided.push(`${binding.adapterId} (${binding.resource}): ${binding.detail ?? '설정이 필요하다'}`);
+        }
+    }
+    if (input.askPolicy !== false) {
+        const declared = new Set(input.declaredPolicies ?? []);
+        for (const policy of POLICY_QUESTIONS) {
+            if (!declared.has(policy.id))
+                undecided.push(policy.question);
+        }
+    }
+    steps.push('asc setup status');
+    if (attached)
+        steps.push('asc proceed');
+    return {
+        projectRoot,
+        git,
+        attached,
+        profile,
+        hosts,
+        bindings: plan.bindings,
+        runtimes: plan.runtimes ?? [],
+        capabilities: availableCapabilities(plan),
+        steps,
+        undecided,
+    };
+}
+/** 사람이 읽는 계획. 무엇이 정해지지 않았는지가 먼저 오도록 짠다. */
+export function renderPlan(plan) {
+    const lines = [];
+    lines.push(`프로젝트: ${plan.projectRoot}${plan.git ? '' : ' (git 저장소가 아니다)'}`);
+    lines.push(plan.attached ? 'ASC: 이미 붙어 있다' : 'ASC: 아직 붙지 않았다');
+    if (plan.profile.kind === 'UNDECIDED') {
+        lines.push(plan.profile.candidates.length > 0
+            ? `Profile 후보: ${plan.profile.candidates.join(', ')}`
+            : 'Profile 후보: 없음');
+    }
+    else if (plan.profile.kind === 'ATTACHED_UNKNOWN') {
+        lines.push('Profile: 알 수 없음 (profile.lock 을 읽지 못했다)');
+    }
+    else {
+        lines.push(`Profile: ${plan.profile.id}`);
+    }
+    for (const host of plan.hosts) {
+        lines.push(`Host ${host.id}: ${host.installed ? '설치됨' : '설치되지 않음'}`);
+    }
+    if (plan.runtimes.length > 0) {
+        lines.push('', '도구 상태 (이 프로젝트와 무관한 사실):');
+        for (const runtime of plan.runtimes) {
+            lines.push(`  ${runtime.adapterId}  ${runtime.state}${runtime.detail ? ` — ${runtime.detail}` : ''}`);
+        }
+    }
+    lines.push('', '발견된 외부 연결:');
+    if (plan.bindings.length === 0) {
+        lines.push('  (없음)');
+    }
+    else {
+        for (const binding of plan.bindings) {
+            const role = binding.role ? ` [${binding.role}]` : '';
+            const detail = binding.detail ? ` — ${binding.detail}` : '';
+            lines.push(`  ${binding.adapterId} ${binding.resource}${role}  ${binding.state}${detail}`);
+        }
+    }
+    // 도구는 되는데 이 프로젝트가 안 붙어 있는 경우를 따로 말한다. 그러지 않으면
+    // "도구는 쓸 수 있다는데 왜 아무것도 안 보이지"에서 사람이 멈춘다.
+    for (const runtime of plan.runtimes) {
+        if (runtime.state !== 'AVAILABLE')
+            continue;
+        if (plan.bindings.some((binding) => binding.adapterId === runtime.adapterId))
+            continue;
+        lines.push(`  ${runtime.adapterId}  NOT DISCOVERED — 도구는 쓸 수 있으나 이 프로젝트에 연결 선언이 없다`);
+    }
+    lines.push('', `지금 쓸 수 있는 것: ${plan.capabilities.join(', ') || '없음'}`);
+    if (plan.undecided.length > 0) {
+        lines.push('', '정해지지 않은 것 (ASC가 대신 정하지 않는다):');
+        for (const item of plan.undecided)
+            lines.push(`  - ${item}`);
+    }
+    lines.push('', '다음 순서:');
+    for (const step of plan.steps)
+        lines.push(`  ${step}`);
+    return lines.join('\n');
+}

package/dist/core/attach/init.d.ts

@@ -0,0 +1,29 @@
+export declare function exists(path: string): Promise<boolean>;
+/** `.git`이 있는 곳까지 올라간다. 없으면 여기가 프로젝트 뿌리다. */
+export declare function discoverProjectRoot(start: string): Promise<{
+    root: string;
+    git: boolean;
+}>;
+export type ExcludeOutcome = 'added' | 'already' | 'no-git';
+/**
+ * `.asc/`를 Git 추적에서 뺀다. 프로젝트의 `.gitignore`는 팀 파일이라 손대지 않는다 —
+ * ASC를 쓰지 않는 사람에게 ASC의 흔적이 보이면 안 된다 (OM §1.2).
+ *
+ * **project scope에서만 부른다** (C-11 §5). local scope는 저장소 파일을 한 바이트도
+ * 건드리지 않으므로 여기에 오지 않는다 — `.git/info/exclude` 자기등록은 legacy·전환기
+ * 안전장치이지 개인 사용의 정상 경로가 아니다.
+ */
+export declare function excludeFromGit(projectRoot: string): Promise<ExcludeOutcome>;
+/** 개인 몫 서식. 처음 한 번만 만들고 이후엔 사람 것이다 (OM §4.4). */
+export declare function overrideTemplate(): string;
+/**
+ * 승인자 매핑 서식. 비어 있으면 어떤 승인도 통과하지 않는다 (OM §11.6).
+ *
+ * 예시를 `$example` 안에 두는 이유: loadIdentityMap은 값이 배열인 항목만 매핑으로 받으므로
+ * 이 키는 조용히 무시된다. 반대로 예시를 실제 매핑 형태로 바로 적으면 **그 이름이 유효한
+ * 승인자가 되어** 아무도 지정하지 않은 사람이 승인을 통과시킨다. 형식을 보여주되 살아나지
+ * 않는 자리에 둔다.
+ */
+export declare function identitiesTemplate(): string;
+/** 이미 있으면 건드리지 않는다. 사람이 채운 것을 덮지 않기 위해서다. */
+export declare function writeIfAbsent(path: string, content: string): Promise<boolean>;

package/dist/core/attach/init.js

@@ -0,0 +1,100 @@
+// Project Attach — 프로젝트 하나에 Runtime을 붙인다 (OM §3.3~3.4, C-11 §2·§5).
+//
+// **기본은 local scope이고, 그때 프로젝트에는 아무것도 생기지 않는다.** runtime은 사용자
+// 소유 공간(`ASC_HOME/workspaces/<W-id>`)에 있다. 프로젝트 안의 `.asc/`는 팀이 그렇게
+// 하기로 정한 project scope이거나 아직 옮기지 않은 legacy일 때만 존재한다.
+//
+// 프로젝트는 ASC를 몰라야 하며, runtime을 지우면 아무 일도 없었던 것이 되어야 한다.
+import { access, appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const EXCLUDE_LINE = '.asc/';
+export async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `.git`이 있는 곳까지 올라간다. 없으면 여기가 프로젝트 뿌리다. */
+export async function discoverProjectRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (await exists(join(dir, '.git')))
+            return { root: dir, git: true };
+        const parent = dirname(dir);
+        if (parent === dir)
+            return { root: resolve(start), git: false };
+        dir = parent;
+    }
+}
+/**
+ * `.asc/`를 Git 추적에서 뺀다. 프로젝트의 `.gitignore`는 팀 파일이라 손대지 않는다 —
+ * ASC를 쓰지 않는 사람에게 ASC의 흔적이 보이면 안 된다 (OM §1.2).
+ *
+ * **project scope에서만 부른다** (C-11 §5). local scope는 저장소 파일을 한 바이트도
+ * 건드리지 않으므로 여기에 오지 않는다 — `.git/info/exclude` 자기등록은 legacy·전환기
+ * 안전장치이지 개인 사용의 정상 경로가 아니다.
+ */
+export async function excludeFromGit(projectRoot) {
+    const gitDir = join(projectRoot, '.git');
+    if (!(await exists(gitDir)))
+        return 'no-git';
+    const excludePath = join(gitDir, 'info', 'exclude');
+    await mkdir(dirname(excludePath), { recursive: true });
+    let current = '';
+    try {
+        current = await readFile(excludePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (current.split('\n').some((line) => line.trim() === EXCLUDE_LINE))
+        return 'already';
+    const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
+    await appendFile(excludePath, `${prefix}${EXCLUDE_LINE}\n`, 'utf8');
+    return 'added';
+}
+/** 개인 몫 서식. 처음 한 번만 만들고 이후엔 사람 것이다 (OM §4.4). */
+export function overrideTemplate() {
+    return `${JSON.stringify({
+        $comment: '개인 몫입니다. 팀원마다 이 파일만 다릅니다. 토큰은 값이 아니라 이름으로만 적습니다.',
+        // 이 파일은 profile.lock의 digest에 들어간다. 고치고 재고정하지 않으면 다음 명령이
+        // LOCK_DRIFT로 멈추는데, 그때 가서 알면 늦다 — 파일을 열었을 때 여기 적혀 있어야 한다.
+        $afterEdit: '이 파일을 고친 뒤에는 `asc profile resolve --write` 로 재고정하세요.',
+        schemaVersion: 1,
+        monitorIdentities: [],
+        controller: { identities: {} },
+        approval: { preferredChannel: 'local' },
+    }, null, 2)}\n`;
+}
+/**
+ * 승인자 매핑 서식. 비어 있으면 어떤 승인도 통과하지 않는다 (OM §11.6).
+ *
+ * 예시를 `$example` 안에 두는 이유: loadIdentityMap은 값이 배열인 항목만 매핑으로 받으므로
+ * 이 키는 조용히 무시된다. 반대로 예시를 실제 매핑 형태로 바로 적으면 **그 이름이 유효한
+ * 승인자가 되어** 아무도 지정하지 않은 사람이 승인을 통과시킨다. 형식을 보여주되 살아나지
+ * 않는 자리에 둔다.
+ */
+export function identitiesTemplate() {
+    return `${JSON.stringify({
+        $comment: '승인 권한자 이름과, 그 사람을 알아볼 채널:계정을 잇습니다. 비밀·토큰은 넣지 않습니다. ' +
+            '아래 $example 을 참고해 같은 형태로 항목을 추가하세요 ($example 자체는 무시됩니다).',
+        $example: { 'controller-이름': ['local:내-계정', '<채널>:@내-계정'] },
+    }, null, 2)}\n`;
+}
+/** 이미 있으면 건드리지 않는다. 사람이 채운 것을 덮지 않기 위해서다. */
+export async function writeIfAbsent(path, content) {
+    try {
+        await writeFile(path, content, { encoding: 'utf8', flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+}

package/dist/core/attach/setup-plan.d.ts

@@ -0,0 +1,125 @@
+import type { StableInstallState } from '../distribution/runtime-install.ts';
+/** 세상의 스냅샷. 읽기만 해서 만든다. */
+export type SetupState = {
+    projectRoot: string;
+    git: boolean;
+    /** 이미 붙어 있으면 그 runtime 뿌리. 없으면 안 붙은 것이다. */
+    ascRoot?: string;
+    /** 붙어 있다면 무엇으로 붙었는가. */
+    attachedProfile?: string;
+    /** 사람이 `--profile` 로 지정한 것. */
+    requestedProfile?: string;
+    /** 이 설치본이 아는 Profile 후보. */
+    profileCandidates: readonly string[];
+    /** 채택 범위. 기본은 개인이다 (C-11 §2). */
+    scope: 'local' | 'project';
+    /** Host 설치 상태 — L-5 판정을 그대로 쓴다. */
+    host: {
+        id: string;
+        status: string;
+    }[];
+    /**
+     * 이 machine에 stable `asc` 가 있는가 (C-14 §3).
+     *
+     * **bootstrap이 들고 온 임시 runtime과 다른 축이다** — 없으면 이 축을 그리지 않고,
+     * 그때는 설치된 `asc` 를 전제하지 않는다.
+     */
+    stableRuntime?: StableInstallState;
+};
+export type SetupChange = 
+/**
+ * 이 machine에 stable `asc` 를 놓는다 (C-14 §3.1).
+ *
+ * **설치도 plan에 드러나는 mutation이다** — bootstrap이 몰래 하지 않는다 (불변식 ⑩).
+ */
+{
+    target: 'runtime-install';
+    package: string;
+    version: string;
+    strategy: 'npm-global';
+    from: string;
+}
+/** 이 checkout에 runtime을 붙인다. local scope면 저장소에는 아무것도 만들지 않는다. */
+ | {
+    target: 'attach-workspace';
+    scope: 'local' | 'project';
+    profile: string;
+}
+/** Host 설치물을 지금 source에 맞춘다. 왜 필요한지까지 든다. */
+ | {
+    target: 'host-install';
+    host: string;
+    from: string;
+};
+export type SetupStatus = 'already_configured' | 'ready_to_apply' | 'user_action_required';
+export type SetupCode = 
+/** 후보가 여럿이거나 없다 — 고르는 것은 사람이다 (C-06 §2). */
+'ASC_PROFILE_SELECTION_REQUIRED'
+/** 저장소에 두는 것은 팀의 결정이다 (C-11 불변식 ⑤). */
+ | 'ASC_PROJECT_SCOPE_REQUIRES_CONSENT'
+/** 설치물을 사람이 고쳤다 — 덮는 것은 사람이 정한다 (L-5). */
+ | 'ASC_HOST_INSTALL_MODIFIED';
+/**
+ * 다음에 할 일 하나. **두 형태를 함께 든다** (C-14 §3.4, 불변식 ⑯).
+ *
+ * `display` 는 사람이 읽는 짧은 형태이고, `portable` 은 **지금 이 machine 상태에서
+ * 그대로 실행되는** 형태다. runtime이 아직 없으면 둘이 다르고, 설치된 뒤에는 같다.
+ * agent는 `portable` 만 실행하면 되고, 산문을 읽을 필요가 없다.
+ */
+export type NextAction = {
+    type: 'select_profile' | 'install_runtime' | 'apply_setup' | 'proceed' | 'force_host_install';
+    display: string;
+    portable: string;
+};
+export type SetupPlan = {
+    status: SetupStatus;
+    code?: SetupCode;
+    /** apply가 할 일. 여기 없는 변경은 일어나지 않는다 (C-14 불변식 ⑩). */
+    changes: SetupChange[];
+    requiresUserAction: boolean;
+    /** 사람이 골라야 할 때 무엇 중에서 고르는가. 대신 고르지 않는다. */
+    profiles?: readonly string[];
+    /**
+     * 명령 문자열. **설치 이전에는 `asc …` 를 전제하지 않는다** — 아래 `actions` 의
+     * `portable` 과 같은 값이다. 기존 소비자를 위해 유지한다.
+     */
+    nextActions: string[];
+    /** 같은 것을 두 형태로. agent는 `portable`, 사람은 `display`. */
+    actions: NextAction[];
+    /** 지금 명령을 어디서 실행하고 있는가 — 설치 전이면 bootstrap이다. */
+    executionMode: 'bootstrap' | 'installed-runtime';
+    /** 왜 이 판정인가. 산문이 아니라 사실이다. */
+    evidence: string[];
+};
+/**
+ * 무엇을 바꿀 것인가. **아무것도 바꾸지 않는다.**
+ *
+ * 사람이 답해야 하는 것(profile 선택·project 채택·설치물 수정)은 여기서 멈춘다 —
+ * agent라고 해서 대신 추측하지 않는다 (C-13 · C-14 §7.1).
+ */
+export declare function computeSetupPlan(state: SetupState): SetupPlan;
+/** apply가 실제로 부를 것들. Core는 무엇이 그것을 하는지 모른다. */
+export type SetupEffects = {
+    installRuntime(change: Extract<SetupChange, {
+        target: 'runtime-install';
+    }>): Promise<void>;
+    attachWorkspace(change: Extract<SetupChange, {
+        target: 'attach-workspace';
+    }>): Promise<void>;
+    installHost(change: Extract<SetupChange, {
+        target: 'host-install';
+    }>): Promise<void>;
+};
+export type ApplyResult = {
+    applied: SetupChange[];
+    changesApplied: boolean;
+};
+/**
+ * plan에 적힌 것만 실행한다. **다시 판단하지 않는다** (C-14 불변식 ⑩).
+ *
+ * 여기서 상태를 다시 보고 마음을 바꾸면, 사람이 승인한 plan과 실제로 일어난 일이
+ * 달라진다. 그 순간 plan은 아무것도 보장하지 않는 문서가 된다.
+ */
+export declare function applySetupPlan(plan: SetupPlan, effects: SetupEffects): Promise<ApplyResult>;
+/** 사람이 읽는 줄. 같은 plan에서 나온다 — agent가 보는 JSON과 다른 판단이 아니다. */
+export declare function renderSetupPlan(plan: SetupPlan): string[];