@asc-agent/runtime 0.1.0 → 0.2.0

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

@@ -0,0 +1,38 @@
+/** git이 부르는 이름과 URL. 이름을 버리지 않는 이유는 `origin` 을 알아보기 위해서다. */
+export type RemoteEntry = {
+    name: string;
+    url: string;
+};
+export type AdoptInput = {
+    /** 프로젝트 뿌리의 디렉터리 이름. remote가 없을 때 id와 repository의 근거가 된다. */
+    dirName: string;
+    remotes: readonly RemoteEntry[];
+    /** 사람이 `--id` 로 준 이름. 있으면 추론보다 앞선다. */
+    requestedId?: string;
+    /**
+     * 이 host를 어느 SCM 이름으로 적을 것인가. 모르면 `'git'` 이면 된다 — 그것이 사실이다.
+     * provider를 아는 쪽(조립부)이 넘긴다.
+     */
+    scmForHost?: (host: string) => string;
+};
+export type AdoptedProfile = {
+    id: string;
+    /** `ProjectProfile` 로 파싱되는 객체. 파일에 그대로 쓴다. */
+    profile: Record<string, unknown>;
+    /** 추론하지 못해 비워 둔 것. 숨기지 않고 사람에게 보인다. */
+    warnings: string[];
+};
+export declare class AdoptError extends Error {
+    readonly code: 'NO_USABLE_ID';
+    constructor(code: 'NO_USABLE_ID', message: string);
+}
+/**
+ * 이름 하나를 id 문법으로 깎는다. 못 깎으면 `null` — 조용히 아무 이름이나 만들지 않는다.
+ * `.` 과 `..` 은 문법은 통과하지만 디렉터리로서 뜻이 다르므로 여기서 뺀다.
+ */
+export declare function toProfileId(name: string): string | null;
+/**
+ * 이 저장소를 설명하는 최소 Profile. **파일을 읽지도 쓰지도 않는다** — 사실은 호출자가
+ * 관측해 넘기고, 여기서는 판단만 한다. 그래야 같은 판단을 테스트가 그대로 돌린다.
+ */
+export declare function buildAdoptedProfile(input: AdoptInput): AdoptedProfile;

package/dist/core/attach/adopt.js

@@ -0,0 +1,104 @@
+// 지금 이 저장소를 설명하는 Profile을 만든다 (P0 — Two-URL agent bootstrap).
+//
+// **왜 필요한가**: 배포본에는 예시 Profile 둘뿐이고 둘 다 실 프로젝트용이 아니다. URL만
+// 받은 agent는 `ASC_PROFILE_SELECTION_REQUIRED` 앞에서 고를 것이 없어 사람에게 되물었다.
+// 되물음을 없애려면 "고른다"가 아니라 "만든다"가 있어야 한다.
+//
+// **무엇을 만드는가 — 추론 가능한 최소치뿐이다.** git remote에서 읽히는 사실
+// (id · scm · repository)만 적는다. branch 정본·role 경계·정책은 이 저장소를 봐서
+// 알 수 없다. 모르는 것을 그럴듯하게 채우면 두 가지가 같이 무너진다:
+//
+//   canonical source를 지어내면  세션 발급이 그 정본을 실제로 읽으려 하고, 자격이 없는
+//                               기계에서 issue 자체가 실패한다 (session.ts §readBaselines)
+//   role 경계를 지어내면         지어낸 경계가 곧 사람이 겪는 SCOPE_ESCALATION이 된다 —
+//                               FAIL 회차에서 번들 Profile이 정확히 그렇게 막았다
+//
+// 그래서 adopt의 산출물은 **시작점**이다. 팀의 정책은 팀이 이 파일을 키워서 정한다.
+//
+// **provider 어휘는 여기 없다** (C-09 §6.1). 어느 host가 어느 provider인지는 Adapter를
+// 아는 쪽이 정하고, 여기서는 `scmForHost` 로 받는다 — core가 특정 provider 이름으로
+// 갈라지기 시작하면 그 다음 provider는 반드시 이 파일을 고쳐야 들어온다.
+import { normalizeRemote } from "../workspace/identity.js";
+export class AdoptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AdoptError';
+        this.code = code;
+    }
+}
+/** Profile id는 디렉터리 이름 한 칸이다 (profile-source.ts SAFE_ID와 같은 문법). */
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * 이름 하나를 id 문법으로 깎는다. 못 깎으면 `null` — 조용히 아무 이름이나 만들지 않는다.
+ * `.` 과 `..` 은 문법은 통과하지만 디렉터리로서 뜻이 다르므로 여기서 뺀다.
+ */
+export function toProfileId(name) {
+    const cut = name
+        .trim()
+        .replace(/\.git$/, '')
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/^[^A-Za-z0-9]+/, '')
+        .replace(/-+$/, '');
+    if (!cut || cut === '.' || cut === '..' || !SAFE_ID.test(cut))
+        return null;
+    return cut;
+}
+/** `origin` 이 있으면 그것이다. 없으면 첫 번째 — 다만 그 사실을 경고로 남긴다. */
+function primaryRemote(remotes) {
+    return remotes.find((r) => r.name === 'origin') ?? remotes[0];
+}
+/**
+ * 이 저장소를 설명하는 최소 Profile. **파일을 읽지도 쓰지도 않는다** — 사실은 호출자가
+ * 관측해 넘기고, 여기서는 판단만 한다. 그래야 같은 판단을 테스트가 그대로 돌린다.
+ */
+export function buildAdoptedProfile(input) {
+    const warnings = [];
+    const remote = primaryRemote(input.remotes);
+    const distinctUrls = new Set(input.remotes.map((r) => r.url));
+    if (remote && remote.name !== 'origin' && distinctUrls.size > 1) {
+        warnings.push(`No 'origin' remote — used '${remote.name}' (${remote.url}) to identify this project.`);
+    }
+    // `host/group/project` 로 정규화된다. 자격·포트·질의는 여기 들어오지 않는다.
+    const alias = remote ? normalizeRemote(remote.url) : null;
+    const slash = alias?.indexOf('/') ?? -1;
+    const host = alias && slash > 0 ? alias.slice(0, slash) : null;
+    // repository는 host를 뺀 `owner/repo` 다 — Adapter가 API에 그대로 넘기는 형태가 그것이다.
+    const repository = alias && slash > 0 ? alias.slice(slash + 1) : null;
+    const id = input.requestedId ?? (repository ? toProfileId(repository.split('/').pop()) : null) ?? toProfileId(input.dirName);
+    if (id === null) {
+        throw new AdoptError('NO_USABLE_ID', `Could not make a profile id out of '${input.dirName}' — pass one with --id <name> (letters, digits, '.', '_', '-').`);
+    }
+    if (input.requestedId !== undefined && !SAFE_ID.test(input.requestedId)) {
+        throw new AdoptError('NO_USABLE_ID', `'${input.requestedId}' is not a profile id — use a single name made of letters, digits, '.', '_' or '-'.`);
+    }
+    if (!repository) {
+        warnings.push(remote
+            ? `Remote '${remote.url}' is not a shared repository address — this profile describes a local project.`
+            : 'This repository has no remote — this profile describes a local project.');
+    }
+    warnings.push('canonical.sources is empty: no branch is treated as the source of truth yet. Declare one before' +
+        ' relying on canonical verification.');
+    warnings.push('policy.roleScopes is empty: no role is narrowed yet. Declare scopes when the team agrees on them.');
+    return {
+        id,
+        warnings,
+        profile: {
+            schemaVersion: 1,
+            $comment: 'Adopted from this repository by `asc profile adopt`. It carries only what a git remote can prove —' +
+                ' the project identity. Canonical branches, role boundaries and policy are decisions this tool cannot' +
+                ' make for you: add them here as the team agrees on them.',
+            id,
+            project: {
+                // 공유 주소가 없으면 로컬 프로젝트다. 있으면 host를 아는 쪽이 이름을 준다.
+                scm: host === null ? 'local' : (input.scmForHost?.(host) ?? 'git'),
+                repository: repository ?? `local/${toProfileId(input.dirName) ?? id}`,
+            },
+            canonical: {
+                $comment: 'Empty means canonical verification does not apply. Add a source (id, provider, remote, ref) to' +
+                    ' have sessions check the project against a real baseline.',
+                sources: [],
+            },
+        },
+    };
+}

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

@@ -66,8 +66,13 @@ export type BootstrapPlan = {
 };
 export type BootstrapInput = {
     cwd: string;
-    /** ASC 설치 경로. `profiles/` 를 여기서 읽는다. */
+    /** ASC 설치 경로. 내장 `profiles/` 를 여기서 읽는다. */
     installRoot: string;
+    /**
+     * 사용자 소유 Profile 디렉터리(보통 `ASC_HOME/profiles`). **Surface가 정해서 넘긴다** —
+     * Core가 홈 경로를 스스로 알면 그 순간 저장소·사용자 공간의 경계를 Core가 쥐게 된다.
+     */
+    externalProfileRoot?: string;
     /**
      * 이 위치가 붙어 있다면 그 runtime 뿌리. **Surface가 정해서 넘긴다** — Core가 여기서
      * 다시 찾으면 저장소 안의 `.asc` 만 보게 되고, 그것이 기본이 아닌 지금은
@@ -94,8 +99,13 @@ export type BootstrapInput = {
     /** 정책 질문 자체를 생략할지. 계획만 보려는 호출용이다. */
     askPolicy?: boolean;
 };
-/** 설치 경로의 Profile 후보. 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다. */
-export declare function availableProfiles(installRoot: string): Promise<string[]>;
+/**
+ * 지금 고를 수 있는 Profile. 설치된 배포본 안과 **사용자 소유 공간** 둘 다 본다 —
+ * 팀이 나눠 갖는 실 Profile은 배포본에 들어가지 않으므로 후자가 없으면 후보가 없다.
+ *
+ * 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다.
+ */
+export declare function availableProfiles(installRoot: string, externalProfileRoot?: string): Promise<string[]>;
 /** 감지하고 계획을 세운다. 파일은 하나도 건드리지 않는다. */
 export declare function planBootstrap(input: BootstrapInput): Promise<BootstrapPlan>;
 /** 사람이 읽는 계획. 무엇이 정해지지 않았는지가 먼저 오도록 짠다. */

package/dist/core/attach/bootstrap.js

@@ -13,6 +13,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { availableCapabilities } from "../binding/types.js";
+import { listProfileLocations } from "../resolver/profile-source.js";
 import { discoverProjectRoot, exists } from "./init.js";
 /**
  * 정책은 사람이 정한다 (C-09 §7.1). adapter가 찾아 주는 것과 그것이 무슨 뜻인지 정하는 것은
@@ -25,22 +26,18 @@ export const POLICY_QUESTIONS = [
     { 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 [];
-    }
+/**
+ * 지금 고를 수 있는 Profile. 설치된 배포본 안과 **사용자 소유 공간** 둘 다 본다 —
+ * 팀이 나눠 갖는 실 Profile은 배포본에 들어가지 않으므로 후자가 없으면 후보가 없다.
+ *
+ * 없으면 빈 목록이다 — 그것도 사람이 알아야 할 사실이다.
+ */
+export async function availableProfiles(installRoot, externalProfileRoot) {
+    const found = await listProfileLocations({
+        installRoot,
+        ...(externalProfileRoot ? { externalRoot: externalProfileRoot } : {}),
+    });
+    return [...new Set(found.map((location) => location.id))].sort();
 }
 /** 붙어 있다면 무엇으로 붙었는가. lock을 읽지 못하면 붙이다 만 상태로 본다. */
 async function attachedProfile(ascRoot) {
@@ -58,7 +55,7 @@ export async function planBootstrap(input) {
     // 넘겨받은 것이 없을 때만 저장소 안을 본다 — 옛 경로를 계속 지원하되 기본으로 두지 않는다.
     const ascRoot = input.ascRoot ?? join(projectRoot, '.asc');
     const attached = await exists(ascRoot);
-    const candidates = await availableProfiles(input.installRoot);
+    const candidates = await availableProfiles(input.installRoot, input.externalProfileRoot);
     const hosts = [...(input.hosts ?? [])];
     const plan = input.bindings ?? { bindings: [] };
     const locked = attached ? await attachedProfile(ascRoot) : null;

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

@@ -67,7 +67,7 @@ export type SetupCode =
  * agent는 `portable` 만 실행하면 되고, 산문을 읽을 필요가 없다.
  */
 export type NextAction = {
-    type: 'select_profile' | 'install_runtime' | 'apply_setup' | 'proceed' | 'force_host_install';
+    type: 'select_profile' | 'adopt_profile' | 'install_runtime' | 'apply_setup' | 'proceed' | 'force_host_install';
     display: string;
     portable: string;
 };

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

@@ -66,6 +66,11 @@ export function computeSetupPlan(state) {
         }
     }
     if (state.ascRoot) {
+        // 붙어 있어도 **무엇을 고를 수 있었는지**는 사실이다. 사용자 소유 Profile을 새로 놓고
+        // 계획을 물었을 때 그것이 어디에도 안 보이면, 놓은 사람은 경로를 의심하게 된다.
+        if (state.profileCandidates.length > 0) {
+            evidence.push(`profile candidates=${state.profileCandidates.join(', ')}`);
+        }
         return finish(changes, evidence, state, mode, command);
     }
     // 아직 안 붙었다. 무엇으로 붙을지는 사람이 정한다.
@@ -78,9 +83,21 @@ export function computeSetupPlan(state) {
             changes,
             requiresUserAction: true,
             profiles: state.profileCandidates,
-            ...actions(mode, evidence, [
-                { type: 'select_profile', ...command(['setup', 'apply', '--profile', '<id>']) },
-            ]),
+            // 고를 것이 **없을** 수도 있다 — 배포본이 들고 있는 것은 예시뿐이고, 이 프로젝트를
+            // 설명하는 Profile은 아직 아무도 만들지 않았다. 그때 "골라라"만 주면 막다른 길이
+            // 된다(FAIL 회차에서 agent가 사람에게 되물은 자리). 만드는 길을 함께 든다.
+            //
+            // 순서는 **지금 무엇이 실제로 길을 여는가**로 정한다. 첫 action이 늘 같으면
+            // agent는 첫 줄만 보고 막힌 길로 간다.
+            ...actions(mode, evidence, state.profileCandidates.length > 0
+                ? [
+                    { type: 'select_profile', ...command(['setup', 'apply', '--profile', '<id>']) },
+                    { type: 'adopt_profile', ...command(['profile', 'adopt', '--json']) },
+                ]
+                : [
+                    { type: 'adopt_profile', ...command(['profile', 'adopt', '--json']) },
+                    { type: 'select_profile', ...command(['setup', 'apply', '--profile', '<id>']) },
+                ]),
         };
     }
     if (state.scope === 'project') {

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

@@ -20,12 +20,22 @@ export type SetupGate = {
 };
 export type SetupStatus = {
     attachment: AttachmentState;
+    /** 지금 붙어 있는 Profile과 그 출처. 붙지 않았으면 없다. */
+    profile?: {
+        id: string;
+        origin: 'built-in' | 'external';
+    };
     /** 설정과 무관하게 지금 되는 것. */
     ready: string[];
     gates: SetupGate[];
 };
 export type SetupInput = {
     attachment: AttachmentState;
+    /** 붙어 있는 Profile의 id와 출처. **Surface가 읽어 넘긴다** — Core는 경로를 모른다. */
+    profile?: {
+        id: string;
+        origin: 'built-in' | 'external';
+    };
     /** 승인 권한자 매핑이 하나라도 있는가. */
     hasApprovers: boolean;
     /** override의 controller.identities가 채워졌는가. */

package/dist/core/attach/setup.js

@@ -26,6 +26,7 @@ const RESOLVE_AGAIN = 'after editing, re-lock with `asc profile resolve --write`
 export function assessSetup(input) {
     return {
         attachment: input.attachment,
+        ...(input.profile ? { profile: input.profile } : {}),
         ready: [...ALWAYS_READY],
         gates: [approvalGate(input), monitorGate(input), externalWriteGate(input)],
     };
@@ -116,6 +117,15 @@ export function renderSetup(status) {
         case 'READY':
             break;
     }
+    // 어떤 Profile로 도는지, 그리고 그것이 **어디서 왔는지**. 배포본에 딸려 온 예시로
+    // 실 프로젝트를 돌리고 있는 상태를 사람이 모르고 지나가지 않게 한다.
+    if (status.profile) {
+        const origin = status.profile.origin === 'external'
+            ? 'your own profile directory'
+            : 'bundled with the installed package';
+        lines.push(`profile: ${status.profile.id} — ${origin}`);
+        lines.push('');
+    }
     lines.push('Working now:');
     for (const item of status.ready)
         lines.push(`  ${item}`);

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

@@ -1,9 +1,9 @@
 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";
+export declare const RELEASE_VERSION = "0.2.0";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.2.0";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.2.0";
 /**
  * 아직 설치되지 않은 machine에서 그대로 실행되는 형태 (C-14 §3.4).
  *

package/dist/core/distribution/release.js

@@ -9,7 +9,7 @@
 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 RELEASE_VERSION = '0.2.0';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**

package/dist/core/monitor/observation.d.ts

@@ -25,16 +25,16 @@ export declare const Observation: z.ZodObject<{
     reference: string;
     disposition: "INBOX" | "SHADOW";
     evidence: string[];
+    lastSeenAt: string;
     revisionMarker: string;
     firstSeenAt: string;
-    lastSeenAt: string;
     reason?: string | undefined;
 }, {
     reference: string;
     disposition: "INBOX" | "SHADOW";
+    lastSeenAt: string;
     revisionMarker: string;
     firstSeenAt: string;
-    lastSeenAt: string;
     evidence?: string[] | undefined;
     reason?: string | undefined;
 }>;

package/dist/core/resolver/load.d.ts

@@ -1,10 +1,13 @@
 import { OperationalPreset, ProfileLock, ProjectProfile, UserOverride } from '../../schemas/profile.ts';
 import type { MonitorConfig } from '../monitor/signals.ts';
 import type { OwnershipMap } from '../policy/ownership.ts';
+import { type ProfileOrigin } from './profile-source.ts';
 import { type ConfigLayer, type ResolvedProfile } from './resolve.ts';
 export type LoadedLayers = {
     profile: ProjectProfile;
     profileSource: string;
+    /** 그 Profile이 어디서 왔는가 — 배포본 안인가, 사용자 소유 공간인가. */
+    profileOrigin: ProfileOrigin;
     preset?: OperationalPreset;
     presetSource?: string;
     override?: UserOverride;
@@ -23,12 +26,18 @@ export type ResolvedRuntime = {
 };
 export declare const digest: (value: unknown) => string;
 /**
- * 설치 경로에서 Profile과 Preset을, 프로젝트에서 Override를 읽는다.
+ * Profile과 Preset을 읽고, 프로젝트에서 Override를 읽는다.
  * Override가 없는 것은 정상이다 — 팀 설정만으로도 돌아가야 한다.
+ *
+ * Profile은 설치 경로 안일 수도, 사용자 소유 공간일 수도 있다. **어디서 고를지는
+ * 여기서 정하지 않는다** — profile-source.ts가 정하고 여기는 그 결과를 읽는다.
+ * Preset은 아직 배포본 안에만 있다(팀이 나눠 갖는 것은 Profile 쪽이다).
  */
 export declare function loadLayers(input: {
     installRoot: string;
     profileId: string;
+    /** 사용자 소유 Profile 디렉터리. 보통 `ASC_HOME/profiles`. */
+    externalProfileRoot?: string;
     presetId?: string;
     overridePath?: string;
 }): Promise<LoadedLayers>;
@@ -113,6 +122,8 @@ export type BootstrapOutcome = {
 export declare function bootstrapGuard(input: {
     ascRoot: string;
     installRoot: string;
+    /** 사용자 소유 Profile 디렉터리. 붙을 때 쓴 것과 같은 자리를 봐야 한다. */
+    externalProfileRoot?: string;
     profileId?: string;
     presetId?: string;
     capabilities: readonly string[];

package/dist/core/resolver/load.js

@@ -13,6 +13,7 @@ import { constants } from 'node:fs';
 import { access, mkdir, readFile, rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { OperationalPreset, ProfileLock, ProjectProfile, UserOverride } from "../../schemas/profile.js";
+import { ProfileSourceError, resolveProfileLocation } from "./profile-source.js";
 import { resolveProfile } from "./resolve.js";
 import { satisfies } from "./version.js";
 async function pathExists(path) {
@@ -29,12 +30,30 @@ async function readJson(path) {
     return JSON.parse(await readFile(path, 'utf8'));
 }
 /**
- * 설치 경로에서 Profile과 Preset을, 프로젝트에서 Override를 읽는다.
+ * Profile과 Preset을 읽고, 프로젝트에서 Override를 읽는다.
  * Override가 없는 것은 정상이다 — 팀 설정만으로도 돌아가야 한다.
+ *
+ * Profile은 설치 경로 안일 수도, 사용자 소유 공간일 수도 있다. **어디서 고를지는
+ * 여기서 정하지 않는다** — profile-source.ts가 정하고 여기는 그 결과를 읽는다.
+ * Preset은 아직 배포본 안에만 있다(팀이 나눠 갖는 것은 Profile 쪽이다).
  */
 export async function loadLayers(input) {
-    const profileSource = join(input.installRoot, 'profiles', input.profileId, 'profile.json');
+    const location = await resolveProfileLocation(input.profileId, {
+        installRoot: input.installRoot,
+        ...(input.externalProfileRoot ? { externalRoot: input.externalProfileRoot } : {}),
+    });
+    const profileSource = location.path;
     const profile = ProjectProfile.parse(await readJson(profileSource));
+    // 디렉터리 이름과 선언된 id가 다르면 여기서 멈춘다.
+    //
+    // 둘이 다르면 lock에는 **선언된 id**가 박히고 다음 실행은 그 id로 파일을 찾는다 —
+    // 그런 디렉터리는 없으므로 붙자마자 아무 명령도 돌지 않는 workspace가 된다.
+    // 독립 검증이 실물로 보인 결함이고, 되돌리려면 `.asc/` 를 손으로 지워야 했다.
+    if (profile.id !== input.profileId) {
+        throw new ProfileSourceError('PROFILE_ID_MISMATCH', `${profileSource} declares id '${profile.id}' but lives in a directory named ` +
+            `'${input.profileId}'. Make the two the same — everything after this point looks ` +
+            'the profile up by the id it declares.');
+    }
     let preset;
     let presetSource;
     if (input.presetId) {
@@ -54,6 +73,7 @@ export async function loadLayers(input) {
     return {
         profile,
         profileSource,
+        profileOrigin: location.origin,
         ...(preset ? { preset } : {}),
         ...(presetSource ? { presetSource } : {}),
         ...(override ? { override } : {}),
@@ -220,6 +240,7 @@ export async function bootstrapGuard(input) {
     const locked = ProfileLock.parse(JSON.parse(lockedRaw));
     const layers = await loadLayers({
         installRoot: input.installRoot,
+        ...(input.externalProfileRoot ? { externalProfileRoot: input.externalProfileRoot } : {}),
         profileId: input.profileId ?? locked.profile.id,
         ...(input.presetId ?? locked.preset?.id ? { presetId: input.presetId ?? locked.preset.id } : {}),
         overridePath: join(input.ascRoot, 'override.json'),

package/dist/core/resolver/profile-source.d.ts

@@ -0,0 +1,29 @@
+export type ProfileOrigin = 'built-in' | 'external';
+export type ProfileLocation = {
+    id: string;
+    origin: ProfileOrigin;
+    /** `profile.json` 의 절대 경로. 파일이 아직 없을 수도 있다 — 읽는 쪽이 그 사실을 만난다. */
+    path: string;
+};
+export type ProfileRoots = {
+    /** 설치된 배포본의 뿌리. `profiles/` 가 그 아래 있다. */
+    installRoot: string;
+    /** 사용자 소유 Profile 디렉터리. 보통 `ASC_HOME/profiles`. 없으면 external은 없는 것이다. */
+    externalRoot?: string;
+};
+/** 왜 Profile을 고르지 못했는가. 문장이 아니라 코드로 든다 — Surface가 다르게 말해야 한다. */
+export type ProfileSourceCode = 'INVALID_PROFILE_ID' | 'PROFILE_COLLISION' | 'PROFILE_ESCAPES_ROOT' | 'PROFILE_ID_MISMATCH';
+export declare class ProfileSourceError extends Error {
+    code: ProfileSourceCode;
+    constructor(code: ProfileSourceCode, message: string);
+}
+export declare function assertProfileId(id: string): void;
+/** 이 뿌리들 아래에 실제로 있는 Profile 전부. external이 먼저 온다. */
+export declare function listProfileLocations(roots: ProfileRoots): Promise<ProfileLocation[]>;
+/**
+ * 이 id의 Profile은 어디 있는가.
+ *
+ * 아무 데도 없으면 **built-in 자리를 돌려준다** — 파일이 없다는 사실은 읽는 쪽에서
+ * 그대로 드러나야 하고, 그 오류 모양은 v0.1과 같아야 한다.
+ */
+export declare function resolveProfileLocation(id: string, roots: ProfileRoots): Promise<ProfileLocation>;

package/dist/core/resolver/profile-source.js

@@ -0,0 +1,139 @@
+// Profile이 어디서 오는가 — 설치된 배포본 안, 그리고 사용자 소유 공간.
+//
+// v0.1까지 Profile은 **설치 경로 안에만** 있었다. 그래서 공개 패키지를 설치한 사람은
+// 자기 프로젝트의 Profile을 쓸 방법이 없었다 — 팀에 배포할 수 없다는 뜻이다.
+// 여기서 여는 것은 그 한 갈래다: `ASC_HOME/profiles/<id>/profile.json`.
+//
+// 자리를 고르는 규칙이 이 파일의 전부다:
+//   1. 사람이 명시한 것            Surface가 이미 id로 넘긴다
+//   2. 사용자 소유 external        ASC_HOME — 팀이 나눠 갖는 실 Profile이 여기 온다
+//   3. 배포본 내장 built-in        예시·fixture. 아무것도 없을 때의 바닥
+//
+// **같은 id가 양쪽에 있으면 멈춘다.** 조용히 하나를 고르면 "무엇을 읽었는가"를 사람이
+// 알 수 없고, 그 답이 정책이 되므로 틀린 쪽으로 조용히 도는 것보다 서는 편이 낫다.
+//
+// Profile은 코드가 아니라 데이터다. 여기서 하는 일은 **경로를 고르는 것뿐**이고,
+// 읽기·검증·digest는 기존 resolver 계약(load.ts)이 그대로 한다.
+import { constants } from 'node:fs';
+import { access, readdir, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+export class ProfileSourceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ProfileSourceError';
+        this.code = code;
+    }
+}
+/**
+ * Profile id는 **디렉터리 이름 한 칸**이다.
+ *
+ * 경로 조각을 허용하면 id 하나로 `profiles/` 밖의 파일을 읽게 된다 — `../../secrets`
+ * 같은 것. 그래서 여기서 문법으로 막고, 아래에서 실제 경로가 뿌리 안에 있는지 한 번 더 본다
+ * (문법만 믿지 않는다 — symlink는 문법을 통과한다).
+ */
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function assertProfileId(id) {
+    if (!SAFE_ID.test(id) || id === '.' || id === '..') {
+        throw new ProfileSourceError('INVALID_PROFILE_ID', `'${id}' is not a profile id — use a single name made of letters, digits, '.', '_' or '-'`);
+    }
+}
+/** 글자만 보고 판단한다. 첫 번째 자물쇠 — symlink·junction은 여기를 그냥 통과한다. */
+function withinLexically(root, target) {
+    const rel = relative(resolve(root), resolve(target));
+    return rel !== '' && !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel);
+}
+/**
+ * **실제로** 그 뿌리 안인가. 두 번째 자물쇠다.
+ *
+ * 글자 검사만으로는 부족하다는 것을 독립 검증이 실물로 보였다 — Windows junction
+ * (`mklink /J`)이나 symlink를 `profiles/` 안에 만들면 이름은 한 칸이고 경로도 뿌리 안처럼
+ * 보이는데, 실제 파일은 바깥에 있다. 그 파일이 프로젝트의 정책이 되면 lock에 적히는
+ * 출처마저 link 경로라 사람이 진짜 자리를 알 수 없다.
+ *
+ * 그래서 존재하는 것은 realpath로 한 번 더 본다. 없는 경로는 판정 대상이 아니다.
+ */
+async function withinReally(root, target) {
+    try {
+        const [realRoot, realTarget] = await Promise.all([realpath(root), realpath(target)]);
+        return withinLexically(realRoot, realTarget);
+    }
+    catch {
+        // 아직 없는 파일이면 글자 판단만으로 충분하다 — 읽는 쪽에서 없다는 사실을 만난다.
+        return withinLexically(root, target);
+    }
+}
+const profilePath = (root, id) => join(root, id, 'profile.json');
+const exists = async (path) => {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** 이 뿌리들 아래에 실제로 있는 Profile 전부. external이 먼저 온다. */
+export async function listProfileLocations(roots) {
+    const found = [];
+    const dirs = [
+        ['external', roots.externalRoot],
+        ['built-in', join(roots.installRoot, 'profiles')],
+    ];
+    for (const [origin, dir] of dirs) {
+        if (!dir)
+            continue;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // 없는 디렉터리는 "Profile 0개"다. 오류가 아니다.
+        }
+        for (const entry of entries) {
+            // junction·symlink는 Windows에서 `isDirectory()` 가 아니다. 목록에서만 빼면
+            // "후보에는 없는데 --profile 로는 붙는" 상태가 되므로 여기서도 같이 본다 —
+            // 발견과 해석이 다른 답을 하면 사람은 둘 다 못 믿는다.
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            if (!SAFE_ID.test(entry.name))
+                continue; // 이름이 문법 밖이면 고를 수 없는 것이다
+            const path = profilePath(dir, entry.name);
+            if (!(await withinReally(dir, path)))
+                continue;
+            if (await exists(path))
+                found.push({ id: entry.name, origin, path });
+        }
+    }
+    return found;
+}
+/**
+ * 이 id의 Profile은 어디 있는가.
+ *
+ * 아무 데도 없으면 **built-in 자리를 돌려준다** — 파일이 없다는 사실은 읽는 쪽에서
+ * 그대로 드러나야 하고, 그 오류 모양은 v0.1과 같아야 한다.
+ */
+export async function resolveProfileLocation(id, roots) {
+    assertProfileId(id);
+    const builtInDir = join(roots.installRoot, 'profiles');
+    const builtIn = profilePath(builtInDir, id);
+    const externalDir = roots.externalRoot;
+    const external = externalDir ? profilePath(externalDir, id) : undefined;
+    if (external && !withinLexically(externalDir, external)) {
+        throw new ProfileSourceError('INVALID_PROFILE_ID', `'${id}' escapes the profile directory`);
+    }
+    const hasExternal = external ? await exists(external) : false;
+    if (external && hasExternal && !(await withinReally(externalDir, external))) {
+        throw new ProfileSourceError('PROFILE_ESCAPES_ROOT', `'${id}' points outside ${externalDir} — a link leads to another place on disk. ` +
+            'Put the profile itself in the directory: policy must not come from somewhere the ' +
+            'recorded source does not name.');
+    }
+    const hasBuiltIn = await exists(builtIn);
+    if (hasExternal && hasBuiltIn) {
+        throw new ProfileSourceError('PROFILE_COLLISION', `two profiles claim the id '${id}' — ${external} and ${builtIn}. ` +
+            'Rename one of them: which policy applies must not depend on lookup order.');
+    }
+    if (hasExternal)
+        return { id, origin: 'external', path: external };
+    return { id, origin: 'built-in', path: builtIn };
+}