@underdogai/mesh-event-schemas 0.1.0

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @underdogai/mesh-event-schemas
+ *
+ * org.corp.* Matrix 커스텀 이벤트 + UI Block 데이터의 단일 진실 공급원.
+ * appservice-agent, erp-bridge, client-web, mcp-erp 가 공통으로 import 한다.
+ */
+export * from "./namespace.js";
+export * from "./blocks.js";
+export * from "./events.js";
+export * from "./registry.js";
+export * from "./capabilities.js";
+export * from "./templates.js";
+export * from "./surfaces.js";
+export * from "./apppacks.js";
+export * from "./plugins.js";

package/src/namespace.ts

@@ -0,0 +1,64 @@
+/**
+ * 커스텀 이벤트 네임스페이스.
+ *
+ * RFC §5: 모든 도메인 이벤트는 `org.corp.<domain>.<event>` 형태로 네임스페이스 + 버전을 가진다.
+ * 회사/배포별로 바꿀 수 있도록 한 곳(NS)에서만 정의한다.
+ */
+export const NS = "org.corp" as const;
+
+/** UI 카드를 일반 `m.room.message` 안에 끼워 넣을 때 쓰는 content 확장 키.
+ *  (지원하지 않는 클라이언트는 body 텍스트로 graceful degrade, 우리 클라는 이 키를 보고 렌더) */
+export const UI_CONTENT_KEY = `${NS}.ui` as const;
+
+/** 표준 이벤트 타입 상수. */
+export const EventType = {
+  /** 사용자/에이전트가 보내는 구조화된 명령 (선택적 — 보통은 m.room.message 텍스트를 에이전트가 파싱) */
+  Command: `${NS}.command`,
+  /** 에이전트 → 사용자: 인라인 렌더되는 UI 카드 (전용 이벤트 타입 형태) */
+  UiCard: `${NS}.ui.card`,
+  /** 사용자 → 에이전트: UI 카드 상호작용 결과 */
+  UiAction: `${NS}.ui.action`,
+  /** 상태 이벤트: 에이전트 역량 프로필 (state_key = 에이전트 MXID) */
+  AgentCapability: `${NS}.agent.capability`,
+  /** 상태 이벤트: 엔티티(방)의 현재 워크플로 상태 (last-writer-wins) */
+  WorkflowState: `${NS}.workflow.state`,
+  /** 상태 이벤트: 룸↔도메인 바인딩 — 룸이 자기 app/엔티티를 선언 (state_key = "") */
+  RoomBinding: `${NS}.room.binding`,
+  /** 상태 이벤트: 엔티티(방)의 표시용 필드 스냅샷 — 팩 서피스 {{binding}} 해석 소스 (state_key = "") */
+  EntitySnapshot: `${NS}.entity.snapshot`,
+  /** HITL 승인 라이프사이클: 승인 요청 (여러 승인자 대상, 메시지 이벤트) */
+  ApprovalRequest: `${NS}.approval.request`,
+  /** HITL 승인 라이프사이클: 승인자의 결정 (승인/반려, 요청 이벤트를 m.reference) */
+  ApprovalDecision: `${NS}.approval.decision`,
+  /** 에이전트 런 계획: 에이전트가 어떤 단계 계획으로 일하는지 (런 타임라인의 토대, 메시지 이벤트) */
+  AgentPlan: `${NS}.agent.plan`,
+  /** 에이전트 런 단계 갱신: 한 단계의 상태/공정률 진행 (plan 을 m.reference, 메시지 이벤트) */
+  AgentStep: `${NS}.agent.step`,
+  /** 작업항목 생성: 사람↔에이전트 공유 작업 라이프사이클의 루트 (메시지 이벤트) */
+  TaskCreate: `${NS}.task.create`,
+  /** 작업항목 갱신: 상태/배정/진행 변경 (create 를 m.reference, 메시지 이벤트) */
+  TaskUpdate: `${NS}.task.update`,
+  /** 에이전트 → 에이전트: 작업 위임 요청 (A2A) */
+  A2aRequest: `${NS}.a2a.request`,
+  /** 에이전트 → 에이전트: 위임 결과 회신 (A2A) */
+  A2aResult: `${NS}.a2a.result`,
+  /** 상태 이벤트: 앱(App Service)이 데이터로 실어 보내는 셸 서피스(패널/헤더) — "AS만 추가해도" 회사별 UI 등록 (state_key = "") */
+  AppSurface: `${NS}.app.surface`,
+  /** 상태 이벤트: Space(컨테이너)가 추가·관리하는 App Service(앱) 목록 — Space=앱 추가 단위 (state_key = "") */
+  SpaceApps: `${NS}.space.apps`,
+  /** 상태 이벤트: 룸(채널)이 직접 선언한 App Service(앱) 키 목록 — space.apps 의 per-room 짝, 탭으로 노출 (state_key = "") */
+  RoomApps: `${NS}.room.apps`,
+} as const;
+
+/** ERP 인바운드 이벤트 타입 접두사. 실제 타입은 `org.corp.erp.<entity>.<verb>` 로 만든다. */
+export const ERP_EVENT_PREFIX = `${NS}.erp.` as const;
+
+/** `org.corp.erp.invoice.updated` 같은 ERP 이벤트 타입 문자열을 생성한다. */
+export function erpEventType(entity: string, verb: string): string {
+  return `${ERP_EVENT_PREFIX}${entity}.${verb}`;
+}
+
+/** 주어진 이벤트 타입이 ERP 인바운드 이벤트인지 판별. */
+export function isErpEventType(type: string): boolean {
+  return type.startsWith(ERP_EVENT_PREFIX);
+}

package/src/plugins.ts

@@ -0,0 +1,118 @@
+/**
+ * 플러그인 레지스트리 — 활성화된 도메인 플러그인의 "신분증"(manifest)을 모으고,
+ * 부팅 시 각 plugin.register() 를 호출해 App Pack·이벤트·템플릿을 레지스트리에 wiring 한다.
+ *
+ * 한 플러그인 = 한 도메인(`packages/plugin-<domain>`). 클라이언트는 활성(enabled) 목록을
+ * loadPlugins() 한 번으로 부팅 시 등록한다 → 새 도메인 추가 = enabled 배열에 한 줄.
+ * (docs/dev-plan.md §1.4 / docs/extensibility.md §10 / TASK.yml P0-3)
+ *
+ * App Pack(getAppPack) 처럼 클라/UI 평면의 봉합선이며, 데이터/AS 평면(events·templates)은
+ * 각 plugin.register() 안에서 함께 등록한다. 임의 코드 실행 없이 "선언된 것만" 꽂는 구조.
+ */
+
+import { z } from "zod";
+
+/**
+ * 플러그인이 선언하는 capability 표면(서드파티 로딩 1차 슬라이스 = 신뢰 경계의 *명시적 선언*).
+ * 호스트가 "이 앱은 어떤 scope/백엔드 도구를 쓸 수 있는가"를 부팅 전에 감사할 수 있게 한다.
+ * App(defineApp/withActions)은 이 값을 *자기 액션에서 자동 도출*하므로 코드와 선언이 어긋나지 않는다(drift 0).
+ * 런타임 강제는 이미 존재한다: scope=서버 게이트(evaluateAction), backendTools=액션별 화이트리스트(dispatchAction).
+ * 즉 이 manifest 는 그 둘의 *감사 가능한 상한 선언*이다(샌드박스/서명/별프로세스는 여기 범위 밖 = G5/SEC-2 이후).
+ */
+export interface PluginCapabilities {
+  /** 이 앱의 액션이 요구하는 capability scope 합집합(서버 게이트가 검사하는 것). */
+  scopes?: string[];
+  /** 이 앱의 핸들러가 부를 수 있는 MCP 백엔드 도구 합집합(액션별 화이트리스트의 합). */
+  backendTools?: string[];
+}
+
+/** 플러그인 매니페스트 — 플러그인의 신분증(런타임 등록 없이 메타데이터만). */
+export interface PluginManifest {
+  /** 전역 고유 ID(패키지 1개 = 1개). */
+  id: string;
+  /** 사람이 읽는 이름. */
+  displayName?: string;
+  /** 룸 바인딩(org.corp.room.binding)의 app 키 — App Pack 의 app 과 일치. */
+  app: string;
+  /** 이 플러그인이 다루는 엔티티 타입(예: ["lead"], ["repo","pr","issue"]). */
+  entityTypes: string[];
+  /** 매니페스트 스키마 버전(전방호환 — 미래 필드 추가 시 협상 기준). 없으면 1. */
+  manifestVersion?: number;
+  /**
+   * 이 플러그인이 register() 에서 레지스트리에 등록하는 것의 선언(문서/검수용 메타).
+   * 코어가 아니라 플러그인이 소유하는 도메인 이벤트/템플릿/서피스를 명시한다 — "도메인=플러그인"의 신분증.
+   */
+  provides?: {
+    /** registerEventEntry 로 등록하는 이벤트 타입(예: ["org.corp.forgejo.pr.review"]). */
+    events?: string[];
+    /** registerTemplate 로 등록하는 템플릿 이름(예: ["scmRef","prReview","ciRun"]). */
+    templates?: string[];
+    /** registerAppPack 으로 기여하는 App Pack app 키(예: ["forgejo"]). */
+    surfaces?: string[];
+  };
+  /** 선언된 capability 상한(scope/backendTools) — App 은 자기 액션에서 자동 도출(드리프트 0). */
+  capabilities?: PluginCapabilities;
+}
+
+/** 매니페스트 검증 스키마 — 부팅(loadPlugins) 시 모든 플러그인 신분증을 검증한다(서드파티 로딩 신뢰 경계). */
+export const PluginManifestSchema = z.object({
+  id: z.string().min(1),
+  displayName: z.string().optional(),
+  app: z.string().min(1),
+  entityTypes: z.string().array(),
+  manifestVersion: z.number().int().min(1).optional(),
+  provides: z
+    .object({
+      events: z.string().array().optional(),
+      templates: z.string().array().optional(),
+      surfaces: z.string().array().optional(),
+    })
+    .optional(),
+  capabilities: z
+    .object({
+      scopes: z.string().array().optional(),
+      backendTools: z.string().array().optional(),
+    })
+    .optional(),
+});
+
+/** 플러그인 = manifest + 부팅 시 1회 호출되는 register(). 클라 enabled 목록의 원소. */
+export interface Plugin extends PluginManifest {
+  /** App Pack·이벤트·템플릿을 레지스트리에 등록한다(부팅 시 1회). */
+  register: () => void;
+}
+
+const registry = new Map<string, Plugin>();
+
+/**
+ * 단일 플러그인을 등록하고 register() 를 호출한다.
+ * 중복 id 는 graceful 하게 무시한다(먼저 등록된 것 유지 → 멱등). 이 패키지는 서버/클라/MCP
+ * 공용 스키마라 환경(console 등)에 의존하지 않는다 — 충돌 가시화는 호출측(로더)의 몫.
+ */
+export function registerPlugin(plugin: Plugin): void {
+  if (registry.has(plugin.id)) return;
+  // 신뢰 경계(서드파티 로딩 1차): register() 가 레지스트리를 건드리기 *전에* 매니페스트(신분증)를 검증한다.
+  // 잘못된 신분증은 부팅을 멈춘다(fail-fast) — 잘못 등록된 채 절반만 동작하는 것보다 즉시 가시화가 안전.
+  const valid = PluginManifestSchema.safeParse(plugin);
+  if (!valid.success) {
+    const detail = valid.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+    throw new Error(`[plugins] 매니페스트 검증 실패 (id=${(plugin as { id?: string }).id ?? "?"}): ${detail}`);
+  }
+  registry.set(plugin.id, plugin);
+  plugin.register();
+}
+
+/** 활성(enabled) 플러그인 목록을 순서대로 등록한다. */
+export function loadPlugins(plugins: Plugin[]): void {
+  for (const plugin of plugins) registerPlugin(plugin);
+}
+
+/** 등록된 플러그인 목록. */
+export function listPlugins(): Plugin[] {
+  return [...registry.values()];
+}
+
+/** id 로 등록된 플러그인을 조회한다. */
+export function getPlugin(id: string): Plugin | undefined {
+  return registry.get(id);
+}

package/src/registry.ts

@@ -0,0 +1,261 @@
+/**
+ * 이벤트 스키마 레지스트리 (RFC §5).
+ *
+ * "어떤 타입이 존재하고, 스키마가 무엇이며, 누가 발행할 수 있는지"를 한 곳에서 통제한다.
+ * 이게 없으면 규모가 커질 때 "이벤트 수프"가 된다. appservice는 들어온 이벤트를 여기로
+ * 검증(validateEvent)하고, 클라이언트는 알 수 없는 타입을 안전하게 무시한다.
+ */
+import type { z } from "zod";
+import {
+  A2aRequestContentSchema,
+  A2aResultContentSchema,
+  AgentCapabilityContentSchema,
+  AgentPlanContentSchema,
+  AgentStepContentSchema,
+  ApprovalDecisionContentSchema,
+  ApprovalRequestContentSchema,
+  CommandContentSchema,
+  EntitySnapshotContentSchema,
+  ErpEventContentSchema,
+  RoomAppsContentSchema,
+  RoomBindingContentSchema,
+  TaskCreateContentSchema,
+  TaskUpdateContentSchema,
+  UiActionContentSchema,
+  UiCardContentSchema,
+  WorkflowStateContentSchema,
+} from "./events.js";
+import { ERP_EVENT_PREFIX, EventType } from "./namespace.js";
+import { AppSurfaceContentSchema } from "./surfaces.js";
+
+/** 누가 이 이벤트를 발행할 자격이 있는가 (서버측 검증의 1차 힌트). */
+export type Publisher = "human" | "agent" | "bridge";
+
+/** 메시지 이벤트(타임라인)인지 상태 이벤트(state, last-writer-wins)인지. */
+export type EventKind = "message" | "state";
+
+export interface RegistryEntry {
+  /** 정확한 타입 매칭. prefix가 설정된 엔트리는 type 대신 prefix로 매칭한다. */
+  type?: string;
+  /** `org.corp.erp.` 처럼 접두사 매칭이 필요한 경우. */
+  prefix?: string;
+  kind: EventKind;
+  schema: z.ZodTypeAny;
+  publishableBy: Publisher[];
+  description: string;
+}
+
+/**
+ * 코어(빌트인) 이벤트 엔트리 — 항상 조회 우선이며 플러그인이 덮어쓸 수 없다(코어 격리).
+ * 플러그인은 자기 `org.corp.<domain>.*` 엔트리를 registerEventEntry 로 런타임 추가한다.
+ */
+export const EVENT_REGISTRY: RegistryEntry[] = [
+  {
+    type: EventType.Command,
+    kind: "message",
+    schema: CommandContentSchema,
+    publishableBy: ["human", "agent"],
+    description: "구조화된 명령 (선택적; 보통은 m.room.message 텍스트를 에이전트가 파싱)",
+  },
+  {
+    type: EventType.UiCard,
+    kind: "message",
+    schema: UiCardContentSchema,
+    publishableBy: ["agent"],
+    description: "에이전트 → 사용자: 인라인 렌더되는 UI 카드 (전용 이벤트 타입 형태)",
+  },
+  {
+    type: EventType.UiAction,
+    kind: "message",
+    schema: UiActionContentSchema,
+    publishableBy: ["human", "agent"],
+    description: "사용자 → 에이전트: UI 카드 상호작용 결과",
+  },
+  {
+    prefix: ERP_EVENT_PREFIX,
+    kind: "message",
+    schema: ErpEventContentSchema,
+    publishableBy: ["bridge"],
+    description: "ERP 인바운드 이벤트 (org.corp.erp.<entity>.<verb>)",
+  },
+  {
+    type: EventType.AgentCapability,
+    kind: "state",
+    schema: AgentCapabilityContentSchema,
+    publishableBy: ["agent"],
+    description: "에이전트 역량 프로필 (상태 이벤트, state_key = 에이전트 MXID)",
+  },
+  {
+    type: EventType.WorkflowState,
+    kind: "state",
+    schema: WorkflowStateContentSchema,
+    publishableBy: ["agent", "bridge"],
+    description: "엔티티(방)의 현재 워크플로 상태 (상태 이벤트, LWW)",
+  },
+  {
+    type: EventType.RoomBinding,
+    kind: "state",
+    schema: RoomBindingContentSchema,
+    publishableBy: ["human", "agent", "bridge"],
+    description: "룸↔도메인 바인딩: 룸이 자기 app/엔티티를 선언 (상태 이벤트, state_key = '')",
+  },
+  {
+    type: EventType.RoomApps,
+    kind: "state",
+    schema: RoomAppsContentSchema,
+    publishableBy: ["human", "agent"],
+    description: "룸이 탭으로 노출하는 App Service 키 목록 — space.apps 의 per-room 짝. 사람(채널설정)·에이전트(프로비저너)만 선언, 브리지 금지. 거버넌스=부모 space.apps 부분집합 (상태 이벤트, state_key = '')",
+  },
+  {
+    type: EventType.EntitySnapshot,
+    kind: "state",
+    schema: EntitySnapshotContentSchema,
+    publishableBy: ["human", "agent", "bridge"],
+    description: "엔티티 표시 필드 스냅샷 (상태 이벤트, LWW) — 팩 서피스 {{binding}} 해석 소스",
+  },
+  {
+    type: EventType.AppSurface,
+    kind: "state",
+    schema: AppSurfaceContentSchema,
+    publishableBy: ["human", "agent", "bridge"],
+    description: "앱이 데이터로 실어 보내는 셸 서피스(패널/헤더) — AS만 추가해도 회사별 UI 등록 (상태 이벤트, state_key='')",
+  },
+  {
+    type: EventType.ApprovalRequest,
+    kind: "message",
+    schema: ApprovalRequestContentSchema,
+    publishableBy: ["human", "agent"],
+    description: "HITL 승인 요청 (다단계 승인자 대상) — 사람/에이전트가 발행",
+  },
+  {
+    type: EventType.ApprovalDecision,
+    kind: "message",
+    schema: ApprovalDecisionContentSchema,
+    publishableBy: ["human", "agent"],
+    description: "HITL 승인 결정 (승인/반려) — 승인자(사람/에이전트)가 발행, 요청을 m.reference",
+  },
+  {
+    type: EventType.AgentPlan,
+    kind: "message",
+    schema: AgentPlanContentSchema,
+    publishableBy: ["agent"],
+    description: "에이전트 런 계획 (단계 골격 + 공정률) — 에이전트가 발행, 런 타임라인의 토대",
+  },
+  {
+    type: EventType.AgentStep,
+    kind: "message",
+    schema: AgentStepContentSchema,
+    publishableBy: ["agent"],
+    description: "에이전트 런 단계 갱신 (상태/공정률) — 에이전트가 발행, plan 을 m.reference",
+  },
+  {
+    type: EventType.TaskCreate,
+    kind: "message",
+    schema: TaskCreateContentSchema,
+    publishableBy: ["human", "agent"],
+    description: "작업항목 생성 (사람↔에이전트 공유 작업 라이프사이클의 루트) — 사람/에이전트가 발행",
+  },
+  {
+    type: EventType.TaskUpdate,
+    kind: "message",
+    schema: TaskUpdateContentSchema,
+    publishableBy: ["human", "agent"],
+    description: "작업항목 갱신 (상태/배정/진행) — 사람/에이전트가 발행, create 를 m.reference",
+  },
+  {
+    type: EventType.A2aRequest,
+    kind: "message",
+    schema: A2aRequestContentSchema,
+    publishableBy: ["agent"],
+    description: "에이전트 → 에이전트 작업 위임 요청 (A2A)",
+  },
+  {
+    type: EventType.A2aResult,
+    kind: "message",
+    schema: A2aResultContentSchema,
+    publishableBy: ["agent"],
+    description: "에이전트 → 에이전트 위임 결과 회신 (A2A)",
+  },
+];
+
+/** 플러그인이 런타임에 추가한 엔트리(org.corp.<domain>.*). 코어 뒤에 둔다 = 코어 우선. */
+const runtimeEntries: RegistryEntry[] = [];
+
+/** 엔트리의 식별 키 — 정확 타입 또는 접두사. */
+function entryKey(entry: RegistryEntry): string | undefined {
+  return entry.type ?? entry.prefix;
+}
+
+/** 코어 + 런타임 엔트리 전체 (코어가 앞 = 조회/매칭 우선). */
+export function listEventEntries(): RegistryEntry[] {
+  return [...EVENT_REGISTRY, ...runtimeEntries];
+}
+
+/**
+ * 플러그인 이벤트 엔트리를 런타임 등록한다 (부팅 시 plugin.register() 안에서 호출).
+ * - type/prefix 중 하나는 있어야 한다(없으면 무시).
+ * - 코어/기존 엔트리와 키가 겹치면 무시(코어 격리·멱등).
+ * 등록되면 true, 무시되면 false.
+ */
+export function registerEventEntry(entry: RegistryEntry): boolean {
+  const key = entryKey(entry);
+  if (!key) return false;
+  const existing = listEventEntries();
+  if (existing.some((e) => entryKey(e) === key)) return false;
+  // 정확-타입 엔트리가 기존 prefix 엔트리 아래로 떨어지면 lookupEntry 가 prefix 를 먼저 매칭해 영원히 가려진다
+  // (등록은 됐다고 true 를 주지만 schema/publishableBy 가 절대 안 쓰임). 그런 조용한 섀도잉을 거부한다.
+  const t = entry.type;
+  if (t && existing.some((e) => e.prefix && t.startsWith(e.prefix))) return false;
+  runtimeEntries.push(entry);
+  return true;
+}
+
+/** 주어진 이벤트 타입에 해당하는 레지스트리 엔트리를 찾는다 (정확/접두사 매칭, 코어 우선). */
+export function lookupEntry(type: string): RegistryEntry | undefined {
+  return listEventEntries().find((e) => (e.type ? e.type === type : e.prefix ? type.startsWith(e.prefix) : false));
+}
+
+export type ValidationResult =
+  | { ok: true; type: string; kind: EventKind; data: unknown }
+  | { ok: false; type: string; reason: "unknown_type" | "schema_mismatch"; issues?: string[] };
+
+/**
+ * 이벤트 content를 레지스트리로 검증한다.
+ * 알 수 없는 타입 → unknown_type, 스키마 불일치 → schema_mismatch.
+ */
+export function validateEvent(type: string, content: unknown): ValidationResult {
+  const entry = lookupEntry(type);
+  if (!entry) return { ok: false, type, reason: "unknown_type" };
+  const parsed = entry.schema.safeParse(content);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      type,
+      reason: "schema_mismatch",
+      issues: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`),
+    };
+  }
+  return { ok: true, type, kind: entry.kind, data: parsed.data };
+}
+
+/** 발행자가 해당 타입을 보낼 자격이 있는지 (서버측 권한 검증의 보조). */
+export function canPublish(type: string, publisher: Publisher): boolean {
+  const entry = lookupEntry(type);
+  return entry ? entry.publishableBy.includes(publisher) : false;
+}
+
+/**
+ * 발신자 MXID 를 발행자 분류(human/agent/bridge)로 매핑한다 (docs/tickets/SEC-3).
+ *
+ * 서버가 인바운드 이벤트를 받을 때 `canPublish(type, classifySender(sender))` 로 "이 발신자가 이 타입을
+ * 보낼 자격이 있는가"를 강제하는 데 쓴다. 분류는 AS 독점 네임스페이스 관례를 따른다
+ * (infra/registration: `@agent_*` = 에이전트, `@erp_*` = 브리지, 그 외 = 사람).
+ *
+ * ⚠️ 반드시 홈서버가 서명·귀속한 event.sender 로 호출할 것 — 본문(content)의 from_* 필드는 위조 가능하다.
+ */
+export function classifySender(senderId: string): Publisher {
+  const localpart = senderId.split(":")[0] ?? "";
+  if (localpart.startsWith("@agent_")) return "agent";
+  if (localpart.startsWith("@erp_")) return "bridge";
+  return "human";
+}