@underdogai/mesh-app-sdk 0.1.0

package/src/app.ts

@@ -0,0 +1,350 @@
+/**
+ * defineApp — 한 "앱"(회사 ERP 등)을 한 폴더에서 선언한다.
+ *
+ * App 은 Plugin 의 상위집합이라, enabledPlugins(@chatops/app-plugins)에 한 줄 올리면 클라/AS/브리지가
+ * 같은 스키마를 등록한다(SEC-2 로드 경로 재사용 = "Matrix App Service 만 추가"의 봉합선).
+ *
+ * 한 앱이 묶는 삼각형:
+ *  - events:   커스텀 이벤트 → 카드(데이터) 결합("어떤 UI가 어떤 이벤트에"). messageForEvent 로 AS가 전송.
+ *  - actions/handlers: 카드 버튼 ↔ 서버 핸들러(동작). dispatchAction(runtime)이 게이트 후 실행.
+ *  - on:       구독 선언("남이 낸 이벤트가 오면 반응"). dispatchEvent(runtime)가 라우팅(이벤트 드리븐 통로).
+ *  - sidebar/header:   우측 셸 서피스(데이터). surfaceState 로 AS가 상태 이벤트(org.corp.app.surface)로 전송.
+ *  + theme: 회사별 토큰 오버라이드(데이터). 전부 "기존 어휘 조합 = 데이터" → 클라 무변경.
+ */
+import type { z } from "zod";
+import {
+  EventType,
+  NS,
+  buildAppSurface,
+  buildUiMessageContent,
+  registerEventEntry,
+  type AgentDockSpec,
+  type AppSurfaceContent,
+  type CanvasSpec,
+  type CommandPaletteSpec,
+  type ComposerSpec,
+  type HeaderSpec,
+  type ModalSpec,
+  type ObjectMapSpec,
+  type PanelSpec,
+  type Plugin,
+  type PluginCapabilities,
+  type Publisher,
+  type UiCardContent,
+} from "@underdogai/mesh-event-schemas";
+import type { AppAction } from "./action.js";
+import type { ActionHandler, EventHandler } from "./runtime.js";
+
+export interface AppEventDef<S extends z.ZodTypeAny = z.ZodTypeAny> {
+  /** 이 도메인 이벤트 content 스키마(레지스트리에 등록 → validateEvent/canPublish 가 인식). */
+  schema: S;
+  /** 이 이벤트가 들어오면 어떤 카드(기존 블록 조합)로 그릴지 — 이벤트 ↔ UI 결합. */
+  view: (content: z.infer<S>) => UiCardContent;
+  publishableBy?: Publisher[];
+}
+
+export interface AppDef {
+  /** 전역 고유 id(패키지 1개 = 1개). */
+  id: string;
+  /** room.binding/app.surface 의 app 키(작성자/도메인 식별자). */
+  app: string;
+  displayName?: string;
+  entityTypes: string[];
+  /**
+   * 코어 앱 여부 — true 면 이 앱의 액션은 *모든* 방에서 동작한다(room.binding 격리 면제). 에이전트 자신의
+   * 내장 능력(예: finance 의 invoice 승인)을 표현한다. false(기본)인 도메인 앱(acme/northwind 등)은
+   * 자기 방에 바인딩됐을 때만 동작한다(per-room 격리). 보안 게이트(scope/PL)는 코어 앱에도 그대로 적용된다.
+   * ⚠️ 신뢰 경계: core 는 격리를 면제하므로 *호스트가 신뢰하는* 1st-party 앱만 가져야 한다. 서드파티 로딩(G5)에선
+   * 앱이 self-declare 한 core 를 그대로 믿으면 안 되고, 호스트가 manifest 검수 단계에서 core 부여를 통제해야 한다.
+   */
+  core?: boolean;
+  /** 커스텀 이벤트 → 카드 결합(이벤트 타입 → { schema, view }). */
+  events?: Record<string, AppEventDef>;
+  /**
+   * 구독 선언 — "이 이벤트 타입이 오면 반응한다"(이벤트 타입 → 핸들러). events.view 가 *렌더링*이라면
+   * on 은 *반응*이다. 남(다른 앱·브리지)의 타입을 들어도 되고, 여러 앱이 같은 타입을 함께 들어도 된다
+   * (이벤트 드리븐 — 주소 없음). 라우팅은 호스트가 dispatchEvent 로 한다. org.corp.ui.action 구독은
+   * 정의 시점에 거부한다 — 액션의 유일한 진입로는 게이트를 지나는 dispatchAction 이다(권한 우회 차단).
+   */
+  on?: Record<string, EventHandler>;
+  /** 액션 컨트랙트(버튼 + scope). */
+  actions?: AppAction[];
+  /** action_id → 서버 핸들러(동작). actions 와 짝(서비스 면). */
+  handlers?: Record<string, ActionHandler>;
+  /** 우측 셸 패널(데이터). surfaceState 로 상태 이벤트화. */
+  sidebar?: PanelSpec;
+  /** 메인 영역 서피스(데이터, 선택) — 룸 본문에 탭으로 그릴 중앙 콘텐츠. sidebar 와 함께 발행된다. */
+  main?: PanelSpec;
+  /** 룸 헤더(데이터, 선택). */
+  header?: HeaderSpec;
+  // --- M3 셸(선택, 전부 데이터) — 와이어(org.corp.app.surface)로 실려 클라가 렌더한다(외부 SDK 개방). ---
+  /** 이벤트 캔버스(보드). */
+  canvas?: CanvasSpec;
+  /** 우측 에이전트 도크. */
+  dock?: AgentDockSpec;
+  /** 컴포저(슬래시 명령·퀵액션·@엔티티 자동완성). */
+  composer?: ComposerSpec;
+  /** ⌘K 커맨드 팔레트 엔트리. */
+  commandPalette?: CommandPaletteSpec;
+  /** 객체 맵(엔티티 관계 그래프). */
+  objectMap?: ObjectMapSpec;
+  /** 선언형 모달/시트(확인 다이얼로그) — 같은 id 의 셸 액션이 열고, 확인 시 confirm.action_id 발행. */
+  modals?: ModalSpec[];
+  /** 회사별 브랜드 토큰 오버라이드(데이터). */
+  theme?: Record<string, string>;
+  /**
+   * 핸들러 지연 등록(런타임 경계 물리화) — true 면 defineApp 은 핸들러 없이 App 을 만들고, 파괴적-액션-핸들러
+   * 링크검사를 미룬다. 호스트(AS)가 부팅 시 attachHandlers(app, handlers) 로 *service 서브패스*의 핸들러를 붙이며
+   * 그때 전체 링크검사를 한다. 효과: 핸들러(동작) 코드가 클라 번들에 실리지 않는다(클라는 contract/surface 만 로드).
+   */
+  deferHandlers?: boolean;
+}
+
+export interface App extends Plugin {
+  actions: Map<string, AppAction>;
+  handlers: Map<string, ActionHandler>;
+  events: Record<string, AppEventDef>;
+  /** 구독 선언(이벤트 타입 → 핸들러) — AppDef.on. 호스트가 dispatchEvent 로 라우팅한다. */
+  on: Map<string, EventHandler>;
+  /** 코어 앱(모든 방에서 동작, room.binding 격리 면제) 여부 — AppDef.core. 호스트 라우터가 격리 검사 때 본다. */
+  core: boolean;
+  /** 도메인 이벤트 content → 보낼 메시지(데이터, org.corp.ui 카드 포함). 미등록/검증실패 시 null. */
+  messageForEvent(type: string, content: unknown): ReturnType<typeof buildUiMessageContent> | null;
+  /** 우측 셸 서피스를 상태 이벤트 content(데이터)로. sidebar 없으면 null. */
+  surfaceState(): AppSurfaceContent | null;
+}
+
+export function defineApp(def: AppDef): App {
+  const actions = new Map<string, AppAction>();
+  for (const a of def.actions ?? []) actions.set(a.id, a);
+  const handlers = new Map<string, ActionHandler>();
+  for (const [id, h] of Object.entries(def.handlers ?? {})) handlers.set(id, h);
+  const events = def.events ?? {};
+  const on = new Map<string, EventHandler>();
+  for (const [type, h] of Object.entries(def.on ?? {})) on.set(type, h);
+
+  // ui.action 구독 금지(fail-fast) — 액션은 권한 게이트를 지나는 dispatchAction 만이 진입로다.
+  // on 으로 받으면 scope/PL/발행자격 검사를 전부 우회하게 되므로 정의 시점에 거부한다.
+  if (on.has(EventType.UiAction)) {
+    throw new Error(
+      `[app-sdk] 앱 '${def.app}': '${EventType.UiAction}' 은 on 으로 구독할 수 없습니다 — ` +
+        `액션 수신은 actions/handlers(권한 게이트 경유)로 선언하세요.`,
+    );
+  }
+
+  // 액션 id 네임스페이스 강제 — 핸들러 유무와 무관하게 정의 시점에 항상 검사한다(deferHandlers 여도).
+  assertActionNamespace(def.app, actions);
+
+  // 부팅 링크검사(fail-fast) — 흩어진 버튼/핸들러/스코프 연결의 정합성을 정의 시점에 확인한다.
+  // deferHandlers(런타임 경계 분리)면 핸들러는 나중에 attachHandlers 가 붙이며 그때 검사한다 → 여기선 건너뛴다.
+  if (!def.deferHandlers) assertActionHandlerLinks(def.app, actions, handlers);
+
+  // 앱은 자기 네임스페이스(org.corp.<app>.) 안에서만 이벤트를 등록할 수 있다(소유 강제).
+  const nsPrefix = `${NS}.${def.app}.`;
+  // Plugin.register — 부팅 시 1회(registerPlugin 가 plugin.id 로 멱등 가드). 도메인 이벤트 스키마를 레지스트리에 등록(클라/AS 공통).
+  const register = (): void => {
+    for (const [type, ev] of Object.entries(events)) {
+      if (!type.startsWith(nsPrefix)) {
+        throw new Error(
+          `[app-sdk] 앱 '${def.app}': 이벤트 타입 '${type}' 가 앱 네임스페이스 '${nsPrefix}' 밖입니다 — 남의 네임스페이스 등록 금지.`,
+        );
+      }
+      // register 는 멱등 가드 뒤라 1회만 호출되므로, false 는 *진짜 충돌*(다른 앱이 같은 타입/접두사 섀도잉)이다 → throw.
+      const ok = registerEventEntry({
+        type,
+        kind: "message",
+        schema: ev.schema,
+        publishableBy: ev.publishableBy ?? ["bridge", "agent"],
+        description: `${def.app} 앱 도메인 이벤트`,
+      });
+      if (!ok) {
+        throw new Error(
+          `[app-sdk] 앱 '${def.app}': 이벤트 타입 '${type}' 등록 실패(이미 등록됨/접두사 충돌) — 타입 충돌을 확인하세요.`,
+        );
+      }
+    }
+    // 서피스는 데이터(org.corp.app.surface 상태 이벤트)로 흐르므로 registerAppPack(클라 평면) 불필요.
+  };
+
+  return {
+    id: def.id,
+    app: def.app,
+    displayName: def.displayName,
+    entityTypes: def.entityTypes,
+    core: def.core ?? false,
+    provides: { events: Object.keys(events) },
+    capabilities: deriveCapabilities(actions),
+    register,
+    actions,
+    handlers,
+    events,
+    on,
+    messageForEvent(type, content) {
+      const ev = events[type];
+      if (!ev) return null;
+      const parsed = ev.schema.safeParse(content);
+      if (!parsed.success) return null;
+      return buildUiMessageContent(ev.view(parsed.data));
+    },
+    surfaceState() {
+      // panel(=sidebar)은 필수 와이어 필드라 sidebar 없으면 서피스를 발행하지 않는다.
+      // main 은 sidebar 와 함께만 실어 보낸다(메인 영역 탭 콘텐츠). main 만 있는 앱은 v1 미지원.
+      if (!def.sidebar) return null;
+      return buildAppSurface({
+        app: def.app,
+        display_name: def.displayName,
+        entity_type: def.entityTypes[0],
+        panel: def.sidebar,
+        main: def.main,
+        header: def.header,
+        canvas: def.canvas,
+        dock: def.dock,
+        composer: def.composer,
+        commandPalette: def.commandPalette,
+        objectMap: def.objectMap,
+        modals: def.modals,
+        theme: def.theme,
+      });
+    },
+  };
+}
+
+/**
+ * 액션↔핸들러 부팅 링크검사(fail-fast). defineApp 과 withActions 가 공유한다.
+ * (1) 핸들러 키가 액션에 없으면 = 오타/유령 핸들러 → throw(게이트는 통과하나 효과 0개로 status:"ran" 인데
+ *     아무 일도 안 일어나는 조용한 함정 차단). (2) 파괴적 액션에 핸들러 없으면 = 게이트만 통과하고 효과 없음 → throw.
+ */
+/**
+ * 액션 id 네임스페이스 강제(부팅 fail-fast) — 액션 id 는 `<app>.` 으로 시작해야 한다.
+ *
+ * 이벤트 타입에 이미 적용하던 소유 규칙(register 의 nsPrefix 검사)을 액션에도 똑같이 건다. action_id 는
+ * App 간 전역 고유해야 하고(buildActionIndex 가 충돌을 throw), 코어 프리미티브(approve/reject/cancel/send…)
+ * 와도 겹치면 안 되는데 — 평문 id 는 앱이 늘수록 충돌이 확정적이다(실제로 forgejo 의 PR 승인이 코어 invoice
+ * 의 "approve" 와 부딪혀 한 차례 우회한 전례가 있다). 소유자를 id 에 박아 구조적으로 막는다.
+ */
+function assertActionNamespace(label: string, actions: Map<string, AppAction>): void {
+  const prefix = `${label}.`;
+  for (const id of actions.keys()) {
+    if (!id.startsWith(prefix)) {
+      throw new Error(
+        `[app-sdk] 앱 '${label}': 액션 id '${id}' 가 앱 네임스페이스 '${prefix}' 밖입니다 — ` +
+          `'${prefix}${id}' 처럼 앱 키를 접두사로 두세요(코어 프리미티브·타 앱과의 action_id 충돌 방지).`,
+      );
+    }
+  }
+}
+
+/**
+ * App 의 액션에서 capability 표면(scope/backendTools)을 자동 도출한다 — manifest.capabilities 로 게시되며,
+ * 코드(액션)와 선언이 한 출처라 어긋나지 않는다(서드파티 로딩 감사용 신분증). 액션 0개면 undefined.
+ */
+function deriveCapabilities(actions: Map<string, AppAction>): PluginCapabilities | undefined {
+  const scopes = [...new Set([...actions.values()].map((a) => a.scope))];
+  const backendTools = [...new Set([...actions.values()].flatMap((a) => a.tools ?? []))];
+  if (!scopes.length && !backendTools.length) return undefined;
+  return { ...(scopes.length ? { scopes } : {}), ...(backendTools.length ? { backendTools } : {}) };
+}
+
+function assertActionHandlerLinks(
+  label: string,
+  actions: Map<string, AppAction>,
+  handlers: Map<string, ActionHandler>,
+): void {
+  for (const id of handlers.keys()) {
+    if (!actions.has(id)) {
+      throw new Error(
+        `[app-sdk] 앱 '${label}': 핸들러 '${id}' 에 대응하는 액션이 없습니다(오타 가능). actions 에 정의하거나 핸들러 키를 고치세요.`,
+      );
+    }
+  }
+  for (const a of actions.values()) {
+    if (a.destructive && !handlers.has(a.id)) {
+      throw new Error(
+        `[app-sdk] 앱 '${label}': 파괴적 액션 '${a.id}' 에 핸들러가 없습니다 — 핸들러를 정의하거나 destructive 를 내리세요.`,
+      );
+    }
+  }
+}
+
+/**
+ * service 핸들러를 (deferHandlers 로 만든) App 에 부착한다 — 런타임 경계 물리화의 호스트 측 절반.
+ * 클라는 contract/surface(핸들러 0)만 로드해 App 을 만들고, AS 만 `@chatops/app-<x>/service` 의 핸들러를 import 해
+ * 부팅 시 이걸 호출한다 → 핸들러(동작) 코드가 클라 번들에 실리지 않는다. 붙일 때 전체 링크검사를 수행한다(fail-fast).
+ * 같은 App 싱글톤의 handlers Map 을 채우므로 actionIndex/appsByName 가 참조하던 App 에 즉시 반영된다.
+ */
+export function attachHandlers(app: App, handlers: Record<string, ActionHandler>): App {
+  for (const [id, h] of Object.entries(handlers)) app.handlers.set(id, h);
+  assertActionHandlerLinks(app.app, app.actions, app.handlers);
+  return app;
+}
+
+/**
+ * 레거시 플러그인(forgejo/ops 등 = AppPack/템플릿으로 카드를 그리지만 핸들러가 없던 것)에 액션/핸들러를 부착해
+ * App(=actionIndex 가 픽업하는 상위집합)으로 증강한다. 플러그인의 register()(AppPack/템플릿/이벤트 등록)는
+ * 그대로 보존하므로 풍부한 서피스를 잃지 않는다 — defineApp 전체 전환 없이 "카드 버튼이 핸들러로 왕복"만 켠다.
+ *
+ * 코어 변경 0: enabledPlugins 의 원소를 plain plugin → withActions(plugin, …) 로 바꾸면 그 도메인의 버튼이 살아난다.
+ * 도메인 앱이므로 core=false(방의 room.binding 에 바인딩됐을 때만 동작) — 보안 게이트는 그대로 서버.
+ * App.surface(서피스-as-데이터)는 발행하지 않는다(레거시는 AppPack 클라 평면으로 렌더) → surfaceState=null.
+ */
+export function withActions(
+  plugin: Plugin,
+  opts: { actions: AppAction[]; handlers: Record<string, ActionHandler> },
+): App {
+  const app = (plugin as Partial<App>).app ?? plugin.id;
+  const actions = new Map<string, AppAction>();
+  for (const a of opts.actions) actions.set(a.id, a);
+  const handlers = new Map<string, ActionHandler>();
+  for (const [id, h] of Object.entries(opts.handlers)) handlers.set(id, h);
+  assertActionNamespace(app, actions);
+  assertActionHandlerLinks(app, actions, handlers);
+  return {
+    ...plugin,
+    app,
+    core: false,
+    // 레거시 manifest 의 capabilities 를 액션에서 도출한 값으로 덮어쓴다(withActions 로 부착한 액션의 실제 표면).
+    capabilities: deriveCapabilities(actions),
+    actions,
+    handlers,
+    events: {},
+    on: new Map(),
+    // 레거시 플러그인은 App.messageForEvent(이벤트→카드) 대신 자기 toCard/템플릿으로 렌더하고,
+    // 서피스는 AppPack(클라 평면)으로 등록한다 → App 의 데이터 평면 두 메서드는 비활성(null).
+    messageForEvent: () => null,
+    surfaceState: () => null,
+  };
+}
+
+/** Plugin 이 App(=defineApp 산출물)인지 판정 — 액션/핸들러/이벤트를 가진 상위집합. 라이브 AS 가 enabledPlugins 에서 App 만 추릴 때 쓴다. */
+export function isApp(p: Plugin): p is App {
+  const a = p as Partial<App>;
+  return a.actions instanceof Map && a.handlers instanceof Map && typeof a.messageForEvent === "function";
+}
+
+/** Plugin 목록(클라/AS 공통 enabledPlugins)에서 App 만 추린다. */
+export function enabledApps(plugins: Plugin[]): App[] {
+  return plugins.filter(isApp);
+}
+
+/**
+ * action_id → 소유 App 인덱스 — 라이브 AS 가 들어온 org.corp.ui.action 을 어느 App 의 핸들러로 보낼지 결정한다
+ * (이게 onUiAction 을 도메인 하드코딩 대신 제너릭 dispatchAction 루프로 만드는 빠진 이음새였다).
+ * 충돌(같은 action_id 를 두 App 이 소유)은 부팅 시 즉시 throw(fail-fast) — registry 의 prefix-shadow
+ * 가드와 같은 보수적 거부 정책(조용한 first-writer-wins 금지). action_id 는 App 간 고유해야 하며,
+ * 앱은 자기 네임스페이스로 두는 게 안전하다.
+ */
+export function buildActionIndex(apps: App[]): Map<string, App> {
+  const index = new Map<string, App>();
+  for (const app of apps) {
+    for (const id of app.actions.keys()) {
+      const owner = index.get(id);
+      if (owner && owner !== app) {
+        throw new Error(
+          `[app-sdk] action_id 충돌: '${id}' 를 앱 '${owner.app}' 와 '${app.app}' 가 모두 소유합니다. action_id 는 App 간 고유해야 합니다(앱 네임스페이스 권장).`,
+        );
+      }
+      if (!owner) index.set(id, app);
+    }
+  }
+  return index;
+}

package/src/builders.ts

@@ -0,0 +1,87 @@
+/**
+ * 카드/패널 빌더 — "이미 있는 닫힌 블록/바디"를 조합해 데이터(UiCardContent / PanelSpec)를 만든다.
+ *
+ * 핵심: 새 블록을 만들지 않는다(코어 어휘만 조합). 그래서 결과가 "데이터"로 남고 — App Service 가
+ * 그대로 와이어에 실어 보내면 클라가 가진 렌더러로 그린다(클라 무변경 = "AS만 추가해도 UI 등록").
+ */
+import {
+  buildUiCardContent,
+  type Block,
+  type PanelSpec,
+  type SurfaceSection,
+  type UiCardContent,
+} from "@underdogai/mesh-event-schemas";
+import type { ButtonElement } from "./action.js";
+
+export interface CardOpts {
+  title?: string;
+  fallback?: string;
+  state?: UiCardContent["state"];
+  context?: UiCardContent["context"];
+}
+
+/** 타임라인 카드(UiCardContent) 빌더 — 기존 블록 조합 → 검증된 데이터. */
+export const card = {
+  /** 닫힌 블록 트리로 카드를 구성(반환 즉시 zod 검증된 UiCardContent). */
+  build(card_id: string, blocks: Block[], opts: CardOpts = {}): UiCardContent {
+    return buildUiCardContent({
+      card_id,
+      title: opts.title,
+      fallback: opts.fallback ?? opts.title ?? card_id,
+      state: opts.state,
+      context: opts.context,
+      blocks,
+    });
+  },
+  fields(items: { label: string; value: string; short?: boolean }[]): Block {
+    return { type: "fields", items };
+  },
+  text(text: string): Block {
+    return { type: "text", text };
+  },
+  actions(elements: ButtonElement[]): Block {
+    return { type: "actions", elements };
+  },
+  // --- 폼 입력 블록(2단계 폼 카드용 — 폼 방식 결정: 모달 폼 대신 폼 카드) ---
+  // 클라가 name 으로 값을 모아 제출 버튼의 action_id 로 org.corp.ui.action.values 에 실어 보낸다.
+  // 핸들러는 action.values.parse(ctx.values) 로 타입 확보(defineAction 의 values 스키마와 짝).
+  /** 텍스트/숫자/날짜 입력 — input 종류는 "text"(기본)·"textarea"·"number"·"date"·"datetime"·"time". */
+  input(name: string, opts: { label?: string; input?: "text" | "textarea" | "number" | "date" | "datetime" | "time"; placeholder?: string; required?: boolean; value?: string } = {}): Block {
+    return { type: "input", name, ...opts };
+  },
+  /** 드롭다운 선택(단일/다중). */
+  select(name: string, options: { value: string; label: string }[], opts: { label?: string; placeholder?: string; value?: string; multi?: boolean } = {}): Block {
+    return { type: "select", name, options, ...opts };
+  },
+  /** 라디오 그룹(옵션이 펼쳐져 보이는 단일 선택). */
+  radio(name: string, options: { value: string; label: string }[], opts: { label?: string; value?: string } = {}): Block {
+    return { type: "radio", name, options, ...opts };
+  },
+  /** 체크박스(불리언 수집). */
+  checkbox(name: string, label: string, opts: { checked?: boolean } = {}): Block {
+    return { type: "checkbox", name, label, ...opts };
+  },
+  /** 토글 스위치(불리언 수집, on/off 어포던스). */
+  toggle(name: string, label: string, opts: { checked?: boolean; onText?: string; offText?: string } = {}): Block {
+    return { type: "toggle", name, label, ...opts };
+  },
+};
+
+/** 우측 셸 패널(PanelSpec) 빌더 — 닫힌 SurfaceBody 조합. value 문자열의 {{entity.path}} 는 클라가 바인딩. */
+export const panel = {
+  sections(sections: SurfaceSection[]): PanelSpec {
+    return { sections };
+  },
+  fields(id: string, title: string, items: { label: string; value: string }[]): SurfaceSection {
+    return { id, title, body: { kind: "fields", items } };
+  },
+  list(id: string, title: string, items: { primary: string; secondary?: string }[]): SurfaceSection {
+    return { id, title, body: { kind: "list", items } };
+  },
+  memo(id: string, title: string, summary: string, updates?: string[]): SurfaceSection {
+    return { id, title, body: { kind: "memo", summary, updates } };
+  },
+  card(id: string, title: string, embedded: UiCardContent): SurfaceSection {
+    return { id, title, body: { kind: "card", card: embedded } };
+  },
+};

package/src/host.ts

@@ -0,0 +1,87 @@
+/**
+ * 호스트 활성화 배선 — "봇이 초대되면 자동으로 참여하고, 그 방에 서피스를 **한 번** 발행한다"(킥오프 §2.4)를
+ * 호스트 무관으로 제공한다. AS 에이전트(appservice-agent)와 봇 모드 serve()(Phase 3)가 같은 코드를 쓴다.
+ *
+ * 여기 있는 것은 *앱-제너릭* 절반뿐이다 — 어떤 방이 어떤 앱을 호스팅하는가(room.apps/space.apps 거버넌스),
+ * capability 게시, 잔존 서피스 정리 같은 호스트 정책은 호스트가 소유한다(applyEffects 와 같은 의존성 역전).
+ */
+import { EventType } from "@underdogai/mesh-event-schemas";
+import type { App } from "./app.js";
+import type { MatrixSendClient } from "./runtime.js";
+
+/**
+ * 호스트가 주입하는 Matrix 핸들(활성화용) — matrix-bot-sdk 의 MatrixClient 가 구조적으로 그대로 만족한다.
+ * getRoomStateEvent 는 선택(중복 발행 방지용) — 없거나 실패하면 무조건 발행으로 폴백한다.
+ */
+export interface MatrixHostClient extends MatrixSendClient {
+  /** 초대 수락(참여). */
+  joinRoom(roomId: string): Promise<unknown>;
+  /** 현재 상태 읽기(있으면 중복 발행 방지에 쓴다). 상태 없음은 throw 로 신호해도 된다(M_NOT_FOUND 등). */
+  getRoomStateEvent?(roomId: string, eventType: string, stateKey: string): Promise<unknown>;
+}
+
+export type PublishSurfaceResult = "published" | "unchanged" | "no_surface";
+
+export interface PublishSurfaceInput {
+  client: MatrixHostClient | (MatrixSendClient & Pick<MatrixHostClient, "getRoomStateEvent">);
+  app: App;
+  roomId: string;
+  /** 멀티앱 방 키잉(보통 app.app). 레거시 단일-앱 방은 ""(기본). */
+  stateKey?: string;
+}
+
+/**
+ * 앱 서피스(org.corp.app.surface)를 방에 **1회** 발행한다 — 이미 같은 내용이 올라가 있으면 재발행하지 않는다.
+ * (킥오프 §7 함정: 상태 이벤트를 매 틱 재발행하면 타임라인이 설정값으로 덮여 방을 열었을 때 카드가 안 보인다.
+ *  서피스는 상태 이벤트라 한 번 올리면 영속한다 — 부팅/초대/바인딩 변경마다 불러도 안전한 멱등 연산이어야 한다.)
+ * sidebar 없는 앱은 발행할 것이 없다(no_surface).
+ */
+export async function publishSurface(input: PublishSurfaceInput): Promise<PublishSurfaceResult> {
+  const surface = input.app.surfaceState();
+  if (!surface) return "no_surface";
+  const stateKey = input.stateKey ?? "";
+  if (input.client.getRoomStateEvent) {
+    try {
+      const existing = await input.client.getRoomStateEvent(input.roomId, EventType.AppSurface, stateKey);
+      // 서버가 돌려준 현재 상태가 지금 발행하려는 내용과 같으면 중복 — 재발행하지 않는다.
+      // ⚠️ 비교는 canonical(키 정렬) — 홈서버는 canonical JSON(키 알파벳순)으로 재직렬화해 돌려주는 반면
+      // zod 산출물은 스키마 선언 순서(v 가 맨 앞)라, 순서 민감 비교면 실서버 상대로 unchanged 가 절대 안 나온다.
+      if (existing && canonicalStringify(existing) === canonicalStringify(surface)) return "unchanged";
+    } catch {
+      // 상태 없음(M_NOT_FOUND)/조회 실패 → 발행 진행(중복 방지는 best-effort, 발행이 우선).
+    }
+  }
+  await input.client.sendStateEvent(input.roomId, EventType.AppSurface, stateKey, surface);
+  return "published";
+}
+
+/** 키 순서 무관 비교용 canonical 직렬화(재귀 키 정렬) — Matrix canonical JSON 과 같은 정렬 기준(코드 유닛). */
+function canonicalStringify(v: unknown): string {
+  return JSON.stringify(sortKeysDeep(v));
+}
+
+function sortKeysDeep(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeysDeep);
+  if (v && typeof v === "object") {
+    return Object.fromEntries(
+      Object.entries(v as Record<string, unknown>)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, val]) => [k, sortKeysDeep(val)]),
+    );
+  }
+  return v;
+}
+
+/**
+ * 초대 활성화 시퀀스 — 참여 → 서피스 1회 발행. "봇을 초대하면 활성화된다, 사용자가 따로 설정할 게 없다"(§2.4)
+ * 의 앱-제너릭 절반. 호스트는 자기 정책(capability 게시·멀티앱 키잉 등)을 이 앞뒤에 끼운다.
+ */
+export async function activateOnInvite(input: {
+  client: MatrixHostClient;
+  app: App;
+  roomId: string;
+  stateKey?: string;
+}): Promise<PublishSurfaceResult> {
+  await input.client.joinRoom(input.roomId);
+  return publishSurface(input);
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @underdogai/mesh-app-sdk — App Service ↔ UI 연결 SDK (v0).
+ *
+ * 한 폴더(한 App)에서 커스텀 이벤트 ↔ 카드(데이터) · 카드 버튼 ↔ 타입드 액션/핸들러 · 우측 셸 서피스(데이터)를
+ * 함께 선언한다. App = Plugin 상위집합 → enabledPlugins 한 줄로 클라/AS/브리지가 같은 스키마를 등록한다.
+ * 보안(권한 게이트)은 호스트가 주입(의존성 역전) — SDK 는 scope/destructive 를 데이터로만 공급한다.
+ *
+ * 설계/로드맵: docs/sdk-plan.md, 필요성 기록: docs/sdk.md.
+ */
+export * from "./action.js";
+export * from "./builders.js";
+export * from "./app.js";
+export * from "./runtime.js";
+export * from "./host.js";
+export * from "./serve.js";