@underdogai/mesh-event-schemas 0.1.0

package/dist/registry.js

@@ -0,0 +1,212 @@
+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";
+/**
+ * 코어(빌트인) 이벤트 엔트리 — 항상 조회 우선이며 플러그인이 덮어쓸 수 없다(코어 격리).
+ * 플러그인은 자기 `org.corp.<domain>.*` 엔트리를 registerEventEntry 로 런타임 추가한다.
+ */
+export const EVENT_REGISTRY = [
+    {
+        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 = [];
+/** 엔트리의 식별 키 — 정확 타입 또는 접두사. */
+function entryKey(entry) {
+    return entry.type ?? entry.prefix;
+}
+/** 코어 + 런타임 엔트리 전체 (코어가 앞 = 조회/매칭 우선). */
+export function listEventEntries() {
+    return [...EVENT_REGISTRY, ...runtimeEntries];
+}
+/**
+ * 플러그인 이벤트 엔트리를 런타임 등록한다 (부팅 시 plugin.register() 안에서 호출).
+ * - type/prefix 중 하나는 있어야 한다(없으면 무시).
+ * - 코어/기존 엔트리와 키가 겹치면 무시(코어 격리·멱등).
+ * 등록되면 true, 무시되면 false.
+ */
+export function registerEventEntry(entry) {
+    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) {
+    return listEventEntries().find((e) => (e.type ? e.type === type : e.prefix ? type.startsWith(e.prefix) : false));
+}
+/**
+ * 이벤트 content를 레지스트리로 검증한다.
+ * 알 수 없는 타입 → unknown_type, 스키마 불일치 → schema_mismatch.
+ */
+export function validateEvent(type, content) {
+    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, publisher) {
+    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) {
+    const localpart = senderId.split(":")[0] ?? "";
+    if (localpart.startsWith("@agent_"))
+        return "agent";
+    if (localpart.startsWith("@erp_"))
+        return "bridge";
+    return "human";
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}