@asc-agent/runtime 0.1.0

package/dist/core/attach/setup-plan.js

@@ -0,0 +1,177 @@
+// Setup — detect → plan → apply → verify (C-14 §6).
+//
+// **하나의 판단을 두 진입이 나눠 쓴다.** 사람이 보는 화면과 agent가 파싱하는 JSON은
+// 표현이 다를 뿐 같은 plan에서 나온다. 둘이 각자 판단하면 그 둘은 반드시 갈라진다.
+//
+// 이 파일은 **순수하다** — network·subprocess·clock·파일에 손대지 않는다. 세상의 사실은
+// caller가 관측해 `SetupState` 로 넘긴다. 그래야 "이 명령이 무엇을 바꿀 것인가"를
+// 아무것도 바꾸지 않고 물어볼 수 있다.
+import { portableCommand, RUNTIME_PACKAGE, shorthandCommand } from "../distribution/release.js";
+/**
+ * 무엇을 바꿀 것인가. **아무것도 바꾸지 않는다.**
+ *
+ * 사람이 답해야 하는 것(profile 선택·project 채택·설치물 수정)은 여기서 멈춘다 —
+ * agent라고 해서 대신 추측하지 않는다 (C-13 · C-14 §7.1).
+ */
+export function computeSetupPlan(state) {
+    const evidence = [
+        `project=${state.projectRoot}`,
+        state.git ? 'git=yes' : 'git=no',
+        state.ascRoot ? `attached=${state.ascRoot}` : 'attached=no',
+        `scope=${state.scope}`,
+    ];
+    // 지금 명령이 어디서 도는가. 설치된 `asc` 가 없으면 bootstrap이고, 그때 agent에게
+    // `asc …` 를 실행하라고 주면 안 된다 (C-14 §3.4 · 불변식 ⑯).
+    const mode = state.stableRuntime?.status === 'CURRENT' ? 'installed-runtime' : 'bootstrap';
+    const command = (args) => ({
+        display: shorthandCommand(args),
+        portable: mode === 'installed-runtime' ? shorthandCommand(args) : portableCommand(args),
+    });
+    const changes = [];
+    // stable runtime은 **프로젝트와도, profile 선택과도 무관하다.** 사람이 profile을
+    // 고르는 중이어도 이 설치는 안전한 준비이고, 그것 때문에 통째로 WAIT 하지 않는다
+    // (C-13 dependency-local progress와 같은 태도).
+    if (state.stableRuntime) {
+        const runtime = state.stableRuntime;
+        evidence.push(`runtime=${runtime.status}${runtime.installedVersion ? ` (${runtime.installedVersion})` : ''}`);
+        if (runtime.status !== 'CURRENT') {
+            changes.push({
+                target: 'runtime-install',
+                package: RUNTIME_PACKAGE,
+                version: runtime.expectedVersion,
+                strategy: 'npm-global',
+                from: runtime.status,
+            });
+        }
+    }
+    // Host는 붙어 있든 아니든 판정할 수 있다 — user-owned이고 프로젝트와 무관하다.
+    for (const host of state.host) {
+        if (host.status === 'INSTALLED_MODIFIED') {
+            evidence.push(`host:${host.id}=${host.status}`);
+            return {
+                status: 'user_action_required',
+                code: 'ASC_HOST_INSTALL_MODIFIED',
+                // 사람이 고친 것을 덮는 것은 사람이 정한다 — plan에 담아 몰래 적용하지 않는다.
+                // 다만 runtime 설치처럼 이 결정과 무관한 준비는 계획에 남는다.
+                changes,
+                requiresUserAction: true,
+                ...actions(mode, evidence, [
+                    { type: 'force_host_install', ...command(['host', host.id, 'install', '--force']) },
+                ]),
+            };
+        }
+        if (host.status !== 'INSTALLED_CURRENT') {
+            evidence.push(`host:${host.id}=${host.status}`);
+            changes.push({ target: 'host-install', host: host.id, from: host.status });
+        }
+    }
+    if (state.ascRoot) {
+        return finish(changes, evidence, state, mode, command);
+    }
+    // 아직 안 붙었다. 무엇으로 붙을지는 사람이 정한다.
+    const profile = state.requestedProfile ?? soleCandidate(state.profileCandidates);
+    if (!profile) {
+        evidence.push(`profile candidates=${state.profileCandidates.join(', ') || '(none)'}`);
+        return {
+            status: 'user_action_required',
+            code: 'ASC_PROFILE_SELECTION_REQUIRED',
+            changes,
+            requiresUserAction: true,
+            profiles: state.profileCandidates,
+            ...actions(mode, evidence, [
+                { type: 'select_profile', ...command(['setup', 'apply', '--profile', '<id>']) },
+            ]),
+        };
+    }
+    if (state.scope === 'project') {
+        // 저장소 안에 두는 것은 팀의 결정이고, 명시로만 표현된다. 여기서는 확인만 하고
+        // 그대로 계획에 담는다 — 사람이 이미 `--scope project` 라고 말했기 때문이다.
+        evidence.push('adoption=project (explicit)');
+    }
+    changes.push({ target: 'attach-workspace', scope: state.scope, profile });
+    evidence.push(`profile=${profile}${state.requestedProfile ? ' (given)' : ' (sole candidate)'}`);
+    return finish(changes, evidence, state, mode, command);
+}
+/** 후보가 하나뿐이어도 대신 고르지 않는다 — 여기서 돌려주는 것은 "고를 것이 없다"뿐이다. */
+function soleCandidate(candidates) {
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+/**
+ * 같은 것을 두 형태로 싣는다. `nextActions` 에는 **portable** 을 넣는다 —
+ * 기존 소비자가 그것을 실행 가능한 문자열로 읽고 있고, 설치 전에는 그것만 실제로 돈다.
+ */
+function actions(mode, evidence, list) {
+    return {
+        nextActions: list.map((action) => action.portable),
+        actions: list,
+        executionMode: mode,
+        evidence,
+    };
+}
+function finish(changes, evidence, state, mode, command) {
+    if (changes.length === 0) {
+        return {
+            status: 'already_configured',
+            changes,
+            requiresUserAction: false,
+            ...actions(mode, evidence, state.ascRoot ? [{ type: 'proceed', ...command(['proceed']) }] : []),
+        };
+    }
+    return {
+        status: 'ready_to_apply',
+        changes,
+        requiresUserAction: false,
+        ...actions(mode, evidence, [{ type: 'apply_setup', ...command(['setup', 'apply']) }]),
+    };
+}
+/**
+ * plan에 적힌 것만 실행한다. **다시 판단하지 않는다** (C-14 불변식 ⑩).
+ *
+ * 여기서 상태를 다시 보고 마음을 바꾸면, 사람이 승인한 plan과 실제로 일어난 일이
+ * 달라진다. 그 순간 plan은 아무것도 보장하지 않는 문서가 된다.
+ */
+export async function applySetupPlan(plan, effects) {
+    const applied = [];
+    for (const change of plan.changes) {
+        switch (change.target) {
+            case 'runtime-install':
+                await effects.installRuntime(change);
+                break;
+            case 'attach-workspace':
+                await effects.attachWorkspace(change);
+                break;
+            case 'host-install':
+                await effects.installHost(change);
+                break;
+        }
+        applied.push(change);
+    }
+    return { applied, changesApplied: applied.length > 0 };
+}
+/** 사람이 읽는 줄. 같은 plan에서 나온다 — agent가 보는 JSON과 다른 판단이 아니다. */
+export function renderSetupPlan(plan) {
+    const lines = [`Status: ${plan.status}${plan.code ? ` (${plan.code})` : ''}`];
+    if (plan.changes.length === 0)
+        lines.push('  nothing to change');
+    for (const change of plan.changes) {
+        lines.push(changeLine(change));
+    }
+    if (plan.profiles && plan.profiles.length > 0)
+        lines.push(`  choose one: ${plan.profiles.join(', ')}`);
+    else if (plan.profiles)
+        lines.push('  nothing to choose — this installation has no profile candidates');
+    // 사람에게는 짧은 형태를 보인다. agent가 실행하는 것은 `actions[].portable` 이다.
+    if (plan.actions.length > 0)
+        lines.push(`  next: ${plan.actions.map((a) => a.display).join(' · ')}`);
+    return lines;
+}
+function changeLine(change) {
+    switch (change.target) {
+        case 'runtime-install':
+            return `  install ${change.package}@${change.version} globally (currently ${change.from})`;
+        case 'attach-workspace':
+            return `  attach: ${change.profile} · scope ${change.scope}`;
+        case 'host-install':
+            return `  converge host installation: ${change.host} (currently ${change.from})`;
+    }
+}

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

@@ -0,0 +1,40 @@
+/** 붙어 있는 상태 자체. 이게 READY가 아니면 gate 판정보다 이쪽이 먼저 답이다. */
+export type AttachmentState = 'READY' | 'UNATTACHED' | 'BROKEN' | 'LOCK_DRIFT';
+/**
+ * OPEN 열림 · BLOCKED 못 씀 · DEGRADED 돌긴 하는데 반쪽.
+ *
+ * 반쪽을 BLOCKED로 적으면 사람이 "안 되는구나" 하고 덮어 버린다. monitor scan이 돌면서도
+ * 나에게 온 것을 못 알아보는 상태가 정확히 그렇다 — 실행 자체가 막힌 것과 구분해야 한다.
+ */
+export type GateState = 'OPEN' | 'BLOCKED' | 'DEGRADED';
+export type SetupGate = {
+    id: 'approval' | 'monitor' | 'external-write';
+    label: string;
+    state: GateState;
+    /** 무엇이 없어서 막혔는지. */
+    missing: string[];
+    /** 돌긴 하지만 알아야 할 것. */
+    warnings: string[];
+    /** 어떻게 여는지. 재고정이 필요한 것과 아닌 것을 구분해서 적는다. */
+    howTo: string[];
+};
+export type SetupStatus = {
+    attachment: AttachmentState;
+    /** 설정과 무관하게 지금 되는 것. */
+    ready: string[];
+    gates: SetupGate[];
+};
+export type SetupInput = {
+    attachment: AttachmentState;
+    /** 승인 권한자 매핑이 하나라도 있는가. */
+    hasApprovers: boolean;
+    /** override의 controller.identities가 채워졌는가. */
+    hasControllerIdentities: boolean;
+    /** override의 monitorIdentities가 채워졌는가. */
+    hasMonitorIdentities: boolean;
+    /** SCM 토큰을 찾았는가. 값은 받지 않는다 — 있는지만 안다. */
+    hasScmToken: boolean;
+};
+export declare function assessSetup(input: SetupInput): SetupStatus;
+/** 사람이 읽는 형태. 상태가 먼저 오고, 되는 것, 막힌 것 순이다. */
+export declare function renderSetup(status: SetupStatus): string;

package/dist/core/attach/setup.js

@@ -0,0 +1,140 @@
+// Setup 상태 — 지금 무엇이 되고 무엇이 막혀 있는가 (B-21).
+//
+// 근거(B-16): attach 후 override.json·identities.json을 손으로 채워야 했는데, 무엇을 왜
+// 채워야 하는지가 어디에도 없었다. 게다가 override는 고친 뒤 재고정하지 않으면 다음
+// 명령이 통째로 멈추는데 그 사실을 drift가 난 뒤에야 알게 된다.
+//
+// 다시 재어 본 결과 이 문제는 생각보다 좁았다 — **막히는 것은 바깥 경로뿐이고**
+// (외부 감시·승인 결정·외부 반영), 세션 발급부터 회수·마무리까지 로컬 루프는 설정 편집
+// 0회로 전부 돈다. 그래서 이 모듈이 하는 일은 "설정을 받아 채우는 것"이 아니라
+// **무엇이 열려 있고 무엇이 아직 안 열렸는지를 정직하게 말하는 것**이다.
+//
+// 판정만 한다. 파일도 env도 직접 읽지 않고 전부 주입받으며, 아무것도 고치지 않는다.
+/**
+ * 설정을 하나도 안 채워도 되는 것들. B-16 이후 늘어난 표면(progress·preflight·closure)까지
+ * 포함한다 — "attach가 끝나야 아무것도 할 수 있다"는 오해를 이 목록이 직접 깬다.
+ */
+const ALWAYS_READY = [
+    'issue, run, pause, resume and finish sessions (asc session, asc proceed)',
+    'record and read progress (asc progress)',
+    'check output paths up front (asc preflight)',
+    'collect finished work and confirm closure (asc controller collect, asc closure)',
+    'read incoming requests (asc inbox list/show)',
+    'install and check the host (asc host)',
+];
+const RESOLVE_AGAIN = 'after editing, re-lock with `asc profile resolve --write` (otherwise the next command stops)';
+export function assessSetup(input) {
+    return {
+        attachment: input.attachment,
+        ready: [...ALWAYS_READY],
+        gates: [approvalGate(input), monitorGate(input), externalWriteGate(input)],
+    };
+}
+/** 승인 결정. identities.json은 lock digest에 없어 재고정이 필요 없다. */
+function approvalGate(input) {
+    if (input.hasApprovers) {
+        return { id: 'approval', label: 'approval decisions', state: 'OPEN', missing: [], warnings: [], howTo: [] };
+    }
+    return {
+        id: 'approval',
+        label: 'approval decisions',
+        state: 'BLOCKED',
+        missing: ['identities.json lists no approver'],
+        warnings: [],
+        // 여기에 재고정을 적지 않는다 — 필요 없는 절차를 시키면 다음부터 안내를 안 믿는다
+        howTo: ['open identities.json and add an approver in the $example form (no re-lock needed)'],
+    };
+}
+/**
+ * 외부 감시. 두 설정이 서로 다른 것을 막는다 —
+ * controller.identities가 없으면 실행 자체가 안 되고(단 --as로 우회 가능),
+ * monitorIdentities가 없으면 실행은 되는데 나에게 온 것을 못 알아본다.
+ */
+function monitorGate(input) {
+    const missing = [];
+    const warnings = [];
+    const howTo = [];
+    if (!input.hasControllerIdentities) {
+        missing.push('controller.identities in override.json is empty');
+        howTo.push(`list an approver in controller.identities, or pass \`--as <name>\` — ${RESOLVE_AGAIN}`);
+    }
+    if (!input.hasMonitorIdentities) {
+        warnings.push('monitorIdentities is empty, so mentions and assignments to you are not recognised');
+        howTo.push(`put your account name in monitorIdentities — ${RESOLVE_AGAIN}`);
+    }
+    if (!input.hasScmToken) {
+        missing.push('no SCM token found');
+        howTo.push('set ASC_GITHUB_TOKEN, or run `gh auth login`');
+    }
+    return {
+        id: 'monitor',
+        label: 'external monitoring',
+        state: missing.length > 0 ? 'BLOCKED' : warnings.length > 0 ? 'DEGRADED' : 'OPEN',
+        missing,
+        warnings,
+        howTo,
+    };
+}
+/** 외부 반영. 승인된 Grant를 실제로 내보내려면 토큰과 발급 권한이 둘 다 있어야 한다. */
+function externalWriteGate(input) {
+    const missing = [];
+    const howTo = [];
+    if (!input.hasApprovers) {
+        missing.push('no one can issue a grant (identities.json)');
+        howTo.push('add an approver to identities.json (no re-lock needed)');
+    }
+    if (!input.hasScmToken) {
+        missing.push('no SCM token found');
+        howTo.push('set ASC_GITHUB_TOKEN, or run `gh auth login`');
+    }
+    return {
+        id: 'external-write',
+        label: 'external writes',
+        state: missing.length > 0 ? 'BLOCKED' : 'OPEN',
+        missing,
+        warnings: [],
+        howTo,
+    };
+}
+/** 사람이 읽는 형태. 상태가 먼저 오고, 되는 것, 막힌 것 순이다. */
+export function renderSetup(status) {
+    const lines = [];
+    switch (status.attachment) {
+        case 'UNATTACHED':
+            lines.push('Not attached yet — run `asc init --profile <id>` first.');
+            return lines.join('\n');
+        case 'BROKEN':
+            lines.push('Attachment is half-finished: a runtime exists but profile.lock does not.');
+            lines.push('  Re-attach with `asc init --profile <id>`, or lock it with `asc profile resolve --write`.');
+            return lines.join('\n');
+        case 'LOCK_DRIFT':
+            // 이 상태에서 gate를 나열하면 "설정이 덜 찼다"로 잘못 읽힌다. 원인을 먼저 말한다.
+            lines.push('Configuration differs from the lock, so commands stop — it was edited without re-locking.');
+            lines.push('  Re-lock with `asc profile resolve --write` and the state below applies again.');
+            lines.push('');
+            break;
+        case 'READY':
+            break;
+    }
+    lines.push('Working now:');
+    for (const item of status.ready)
+        lines.push(`  ${item}`);
+    const notOpen = status.gates.filter((g) => g.state !== 'OPEN');
+    const open = status.gates.filter((g) => g.state === 'OPEN');
+    if (open.length > 0) {
+        lines.push('', `Open outward paths: ${open.map((g) => g.label).join(' · ')}`);
+    }
+    if (notOpen.length > 0) {
+        lines.push('', 'Not open yet:');
+        for (const gate of notOpen) {
+            lines.push(`  [${gate.state === 'DEGRADED' ? '~' : ' '}] ${gate.label}`);
+            for (const item of gate.missing)
+                lines.push(`      ${item}`);
+            for (const item of gate.warnings)
+                lines.push(`      ${item}`);
+            for (const item of gate.howTo)
+                lines.push(`      → ${item}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/core/binding/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * provider-neutral semantic operation (C-09 §1.1). 이 목록이 정본이다.
+ *
+ * 여기에 provider 이름을 넣지 않는다 — `scm.<제품>` 같은 값은 capability가 아니라
+ * adapter identity이며, 그것으로 갈라지기 시작하면 Core가 provider를 아는 셈이 된다.
+ */
+export declare const CAPABILITIES: readonly ["observe.delta", "inventory.enumerate", "context.resource", "context.thread", "context.change", "context.history", "canonical.read", "action.comment", "action.update", "presentation.digest", "presentation.priority", "approval.interactive", "identity.resolve"];
+export type Capability = (typeof CAPABILITIES)[number];
+/** describe() 산출물 — 호출도 네트워크도 없는 정적 선언 (C-09 §5). */
+export type AdapterDescriptor = {
+    id: string;
+    version: string;
+    provides: readonly Capability[];
+    /**
+     * 자격이 필요하다는 **사실과 이름**까지만. 값은 여기에도, Profile에도 오지 않는다
+     * (OM §4.2·§4.5).
+     */
+    requiresCredential?: readonly string[];
+    /** 실행 전제(외부 실행파일·프로세스 경계 등)를 사람이 읽을 문장으로. */
+    prerequisites?: readonly string[];
+};
+/**
+ * probe 결과. Boolean이 아닌 이유: "내가 설정을 안 한 것"과 "저쪽이 안 되는 것"을
+ * 합치면 사람이 무엇을 해야 할지 알 수 없다 (C-09 §5.1).
+ */
+export type ProbeState = 'AVAILABLE' | 'DEGRADED' | 'UNCONFIGURED' | 'UNAVAILABLE';
+/** discover()가 찾아낸 후보 하나. 아직 쓸 수 있는지는 모른다. */
+export type BindingCandidate = {
+    adapterId: string;
+    /** 어느 리소스인가. 문법은 adapter 소관이고 Core는 문자열로만 다룬다. */
+    resource: string;
+    /** 이 후보가 실제로 제공할 수 있다고 말하는 capability. describe의 부분집합이다. */
+    provides: readonly Capability[];
+    /** 어떻게 찾았는지 — 사람이 "이게 왜 후보인가"를 알 수 있어야 한다. */
+    discoveredBy?: string;
+};
+/** probe까지 마친 Binding. role은 사람이 정한다 — Core가 추론하지 않는다. */
+export type ResolvedBinding = BindingCandidate & {
+    state: ProbeState;
+    /** DEGRADED·UNCONFIGURED·UNAVAILABLE의 이유. 상태만 주면 고칠 수가 없다. */
+    detail?: string;
+    /** 'code-primary' | 'work' | 'presentation' … Profile이 선언한 역할 이름. */
+    role?: string;
+};
+/**
+ * adapter 자체의 상태. **binding과 별개 사실이다** — 도구는 쓸 수 있는데 이 프로젝트가
+ * 붙어 있지 않을 수 있고, 그 둘은 사람이 할 일이 다르다.
+ */
+export type AdapterRuntime = {
+    adapterId: string;
+    state: ProbeState;
+    detail?: string;
+};
+export type BindingPlan = {
+    bindings: readonly ResolvedBinding[];
+    /** 상태를 보고하는 adapter만 실린다. */
+    runtimes?: readonly AdapterRuntime[];
+};
+export type CapabilityResolution = {
+    capability: Capability;
+    kind: 'RESOLVED';
+    binding: ResolvedBinding;
+}
+/** 아무 binding도 제공하지 않는다 — 그 기능만 끈다 (조용한 통과가 아니다). */
+ | {
+    capability: Capability;
+    kind: 'UNAVAILABLE';
+    detail: string;
+}
+/** 둘 이상이 제공하는데 고를 수 없다. 임의 선택하지 않는다 (C-09 §4.2). */
+ | {
+    capability: Capability;
+    kind: 'AMBIGUOUS';
+    candidates: readonly ResolvedBinding[];
+};
+/** 한 작업이 필요로 하는 것. "provider가 뭐냐"가 아니라 이것으로 묻는다 (C-09 §4.1). */
+export type CapabilityRequirement = {
+    capability: Capability;
+    /** 이 역할의 binding에서만 찾는다. 없으면 전체에서 찾는다. */
+    role?: string;
+};
+/**
+ * 요구 하나를 푼다.
+ *
+ * **쓸 수 있는 것만 후보다** — UNAVAILABLE·UNCONFIGURED는 애초에 세지 않는다.
+ * DEGRADED는 후보로 남긴다: 일부만 되는 것과 안 되는 것은 다르고, 어느 쪽을 쓸지는
+ * 호출자가 detail을 보고 정한다.
+ */
+export declare function resolveCapability(plan: BindingPlan, requirement: CapabilityRequirement): CapabilityResolution;
+/** 여러 요구를 한 번에. 하나라도 못 풀면 그 사실이 결과에 남는다 — 부분 성공을 감추지 않는다. */
+export declare function resolveAll(plan: BindingPlan, requirements: readonly CapabilityRequirement[]): CapabilityResolution[];
+/** 지금 실제로 쓸 수 있는 capability 목록. setup·bootstrap 표면이 사람에게 보여준다. */
+export declare function availableCapabilities(plan: BindingPlan): Capability[];

package/dist/core/binding/types.js

@@ -0,0 +1,74 @@
+// Adapter / Binding 어휘 — Core가 외부 시스템을 모른 채 조립을 판정하기 위한 타입 (C-09).
+//
+// 여기에는 provider 이름이 없다. adapter id는 **문자열로 실려 지나갈 뿐** Core가 그 값으로
+// 행동을 바꾸지 않는다 (C-09 §6.1). 실제 adapter를 import하고 조립하는 곳은 Core 밖이다.
+//
+// 두 개념을 계속 구분한다 (C-09 §1):
+//   Interface(Port)  행동 계약 — 무엇을 어떻게 부르는가
+//   Capability       availability descriptor — 그 행동을 지금 이 Binding에서 쓸 수 있는가
+/**
+ * provider-neutral semantic operation (C-09 §1.1). 이 목록이 정본이다.
+ *
+ * 여기에 provider 이름을 넣지 않는다 — `scm.<제품>` 같은 값은 capability가 아니라
+ * adapter identity이며, 그것으로 갈라지기 시작하면 Core가 provider를 아는 셈이 된다.
+ */
+export const CAPABILITIES = [
+    'observe.delta',
+    'inventory.enumerate',
+    'context.resource',
+    'context.thread',
+    'context.change',
+    'context.history',
+    'canonical.read',
+    'action.comment',
+    'action.update',
+    'presentation.digest',
+    'presentation.priority',
+    'approval.interactive',
+    'identity.resolve',
+];
+/**
+ * 요구 하나를 푼다.
+ *
+ * **쓸 수 있는 것만 후보다** — UNAVAILABLE·UNCONFIGURED는 애초에 세지 않는다.
+ * DEGRADED는 후보로 남긴다: 일부만 되는 것과 안 되는 것은 다르고, 어느 쪽을 쓸지는
+ * 호출자가 detail을 보고 정한다.
+ */
+export function resolveCapability(plan, requirement) {
+    const usable = plan.bindings.filter((b) => (b.state === 'AVAILABLE' || b.state === 'DEGRADED') &&
+        b.provides.includes(requirement.capability) &&
+        (requirement.role === undefined || b.role === requirement.role));
+    if (usable.length === 0) {
+        // 후보가 아예 없는 것과, 있었는데 지금 못 쓰는 것을 구분해 말해 준다.
+        const blocked = plan.bindings.filter((b) => b.provides.includes(requirement.capability));
+        return {
+            capability: requirement.capability,
+            kind: 'UNAVAILABLE',
+            detail: blocked.length > 0
+                ? `'${requirement.capability}' 를 제공하는 binding이 있으나 지금 쓸 수 없다 (${blocked
+                    .map((b) => `${b.adapterId}: ${b.state}`)
+                    .join(', ')})`
+                : `'${requirement.capability}' 를 제공하는 binding이 없다`,
+        };
+    }
+    // 하나로 좁혀지지 않으면 고르지 않는다. 임의 선택은 그 선택을 사람이 영영 보지 못하게 한다.
+    if (usable.length > 1) {
+        return { capability: requirement.capability, kind: 'AMBIGUOUS', candidates: usable };
+    }
+    return { capability: requirement.capability, kind: 'RESOLVED', binding: usable[0] };
+}
+/** 여러 요구를 한 번에. 하나라도 못 풀면 그 사실이 결과에 남는다 — 부분 성공을 감추지 않는다. */
+export function resolveAll(plan, requirements) {
+    return requirements.map((r) => resolveCapability(plan, r));
+}
+/** 지금 실제로 쓸 수 있는 capability 목록. setup·bootstrap 표면이 사람에게 보여준다. */
+export function availableCapabilities(plan) {
+    const found = new Set();
+    for (const binding of plan.bindings) {
+        if (binding.state !== 'AVAILABLE' && binding.state !== 'DEGRADED')
+            continue;
+        for (const capability of binding.provides)
+            found.add(capability);
+    }
+    return [...found].sort();
+}

package/dist/core/distribution/release.d.ts

@@ -0,0 +1,15 @@
+export declare const RUNTIME_PACKAGE = "@asc-agent/runtime";
+export declare const BOOTSTRAP_PACKAGE = "@asc-agent/bootstrap";
+/** runtime과 bootstrap은 초기 release에서 lockstep이다. */
+export declare const RELEASE_VERSION = "0.1.0";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.1.0";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.1.0";
+/**
+ * 아직 설치되지 않은 machine에서 그대로 실행되는 형태 (C-14 §3.4).
+ *
+ * 사람이 읽는 `asc …` 는 설치 뒤에만 성립한다. agent에게 실행하라고 주는 것은
+ * 지금 상태에서 도는 것이어야 한다 (불변식 ⑯).
+ */
+export declare function portableCommand(args: readonly string[]): string;
+/** 설치된 뒤 사람이 치는 형태. runtime이 CURRENT면 이것이 곧 portable이다. */
+export declare function shorthandCommand(args: readonly string[]): string;

package/dist/core/distribution/release.js

@@ -0,0 +1,27 @@
+// Release 상수 — 이 build가 어느 release에 속하는가 (C-14 §8).
+//
+// **exact pin on purpose.** `@latest` 도, major alias도 쓰지 않는다 — 테스트하지 않은
+// runtime을 installer가 몰래 부르면 안 된다 (불변식 ⑧).
+//
+// 여기 값과 package.json 이 어긋나면 `npm run release:check` 가 잡는다. 소비자 환경에서
+// package.json 을 런타임에 읽어 오는 방식은 쓰지 않는다 — 그 편의는 설치 형태마다 다르게
+// 깨지고, drift는 어차피 사람이 release 직전에 한 번 확인하면 되는 문제다.
+export const RUNTIME_PACKAGE = '@asc-agent/runtime';
+export const BOOTSTRAP_PACKAGE = '@asc-agent/bootstrap';
+/** runtime과 bootstrap은 초기 release에서 lockstep이다. */
+export const RELEASE_VERSION = '0.1.0';
+export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
+export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
+/**
+ * 아직 설치되지 않은 machine에서 그대로 실행되는 형태 (C-14 §3.4).
+ *
+ * 사람이 읽는 `asc …` 는 설치 뒤에만 성립한다. agent에게 실행하라고 주는 것은
+ * 지금 상태에서 도는 것이어야 한다 (불변식 ⑯).
+ */
+export function portableCommand(args) {
+    return `npx --yes ${BOOTSTRAP_SPEC} ${args.join(' ')}`;
+}
+/** 설치된 뒤 사람이 치는 형태. runtime이 CURRENT면 이것이 곧 portable이다. */
+export function shorthandCommand(args) {
+    return `asc ${args.join(' ')}`;
+}

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

@@ -0,0 +1,50 @@
+/** 명령 하나를 돌리고 결과를 돌려준다. 테스트는 가짜를, pilot은 진짜 npm을 넣는다. */
+export type ProcessRunner = (command: string, args: readonly string[]) => Promise<{
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}>;
+export type StableInstallStatus = 'NOT_INSTALLED'
+/** 기대한 exact version이 전역에 있고 실행물이 보인다. */
+ | 'CURRENT'
+/** 설치는 돼 있는데 버전이 다르다. */
+ | 'VERSION_MISMATCH'
+/** package는 있는데 실행물이 안 보이거나 조회가 깨졌다. */
+ | 'BROKEN';
+export type StableInstallState = {
+    status: StableInstallStatus;
+    expectedVersion: string;
+    /** 전역에 실제로 있는 버전. 없으면 undefined. */
+    installedVersion?: string;
+    /** `asc` 가 이 프로세스에서 보이는가. */
+    executableVisible: boolean;
+    detail?: string;
+};
+/**
+ * 전역 설치 상태를 읽는다. **읽기만 한다** (C-14 §6 detect).
+ *
+ * `npm ls -g --json` 은 전역 트리만 본다 — bootstrap이 들고 온 자기 의존성은 여기 안 나온다.
+ * 그것이 이 함수가 `npm ls` 를 쓰는 이유다.
+ */
+export declare function detectStableInstall(run: ProcessRunner, expectedVersion?: string): Promise<StableInstallState>;
+export type InstallOutcome = {
+    ok: boolean;
+    detail?: string;
+};
+/**
+ * 전역에 exact version으로 설치한다. **exact 말고는 쓰지 않는다** (불변식 ⑧).
+ *
+ * 여기서 조건을 다시 따지지 않는다 — 무엇을 설치할지는 plan이 이미 정했다 (불변식 ⑩).
+ */
+export declare function installStableRuntime(run: ProcessRunner, version?: string): Promise<InstallOutcome>;
+/**
+ * 설치했다고 끝이 아니다 — exit 0은 "npm이 화내지 않았다"까지다 (C-14 §3.3).
+ *
+ * 버전이 맞는지, 그리고 **실행물이 실제로 보이는지**까지 본다. 안 보이면 성공으로
+ * 뭉개지 않고 새 터미널을 열라고 말한다.
+ */
+export declare function verifyStableInstall(run: ProcessRunner, expectedVersion?: string): Promise<{
+    ok: boolean;
+    state: StableInstallState;
+    remedy?: string;
+}>;