@g1cloud/ui-modeler-next 5.0.0-alpha.1

package/README.md

@@ -0,0 +1,140 @@
+# @g1cloud/ui-modeler-next
+
+> **비주얼 UI 모델러 / 화면 설계 에디터** Vue 3 라이브러리. 컴포넌트 기반 화면을 시각적으로 저작하고, **AI 에이전트로 화면 디자인을 생성**하는 것을 목표로 한다.
+
+- **패키지**: `@g1cloud/ui-modeler-next`
+- **스택**: TypeScript · Vue 3 · Vite(library mode) · Vitest
+- **상태**: `0.1.0-alpha.0` (활발한 개발 중)
+
+---
+
+## 개요
+
+~85종의 UI 파트를 다루는 **디자인시스템 중립** 라이브러리. 렌더링·데이터·명령·동시성·에이전트 계층이 분리되어 있고, 뷰는 교체 가능한 `RendererRegistry`를 통해 컴포넌트 셋에 바인딩된다.
+
+두 종류의 소비자를 지원한다.
+
+- **에디터 통합자** — Vue 앱(호스트)에 비주얼 모델러를 임베드. `createUiEditorController` + `view/` 컴포넌트 + op 전송층.
+- **에이전트/서버** — 사람 개입 없이 화면 구조를 읽고(`describeScreen`) 쓰는(`buildAgentBatch` → op 배치) 순수 함수 표면. 저장소 중립.
+
+## 핵심 설계
+
+- **2단계 컴파일러.** 라이브러리에 LLM SDK는 없다. 외부 LLM이 구조화된 symbolic op를 생성하고, 결정론적 `resolver`가 이를 모델로 하강(lowering)한다. resolve/assemble은 호스트에서 실행된다.
+- **AI-native clean 모델.** 인메모리 모델은 타입드 prop·`MultiLangText`·구조값을 쓰는 깨끗한 모델이다. 문자열 인코딩이나 attr 태깅 같은 표현이 모델 어휘에 새지 않는다.
+- **디자인시스템 중립.** 모델 어휘는 컴포넌트 셋에 독립. 디자인시스템 종속(스타일 클래스 문자열 등)은 `catalog/`에 *데이터*로만 존재하며, 컴포넌트 셋 교체 = `view/RendererRegistry` 대체 주입.
+- **단일 CAS 축.** 동시성 단위는 파트(`casUnit:'part'`) 하나. 레이아웃이 트리에 내재하므로 `RevCache`는 `partId`로 키잉한다.
+
+### 데이터 표현 3계층
+
+| 계층 | 형태 | 용도 |
+|---|---|---|
+| 인메모리 `EditorState` | 재귀 트리 `PartModel{children[]}` | command/resolver/view의 단일 소스 |
+| 영속 (op-write) | 평면 인접리스트 `partList` | op-set·동시성·에이전트 + 유일 write 포맷 |
+
+## 설치
+
+```bash
+pnpm add @g1cloud/ui-modeler-next
+```
+
+peer dependency:
+
+```jsonc
+{
+  "@g1cloud/open-bluesea-core": "1.0.0-alpha.9",
+  "vue": "^3.5.0"
+}
+```
+
+스타일시트가 필요하면 함께 임포트한다.
+
+```ts
+import '@g1cloud/ui-modeler-next/style.css'
+```
+
+## 빠른 시작 — 에디터 임베드
+
+```ts
+import { provide } from 'vue'
+import {
+  createUiEditorController,
+  EDITOR,
+  createCatalog,
+  fromPersistedV2,
+} from '@g1cloud/ui-modeler-next'
+
+// 호스트에서 v2 문서를 로드해 트리로 복원
+const root = fromPersistedV2(persistedV2Doc)
+
+const controller = createUiEditorController(root, {
+  catalog: createCatalog(),
+  modelId: docId,
+  // 트랙 B 마커 — 호스트가 주입. v2 + opWriteEnabled=true 여야 op-mode(편집) 활성.
+  meta: { schemaVersion: 2, opWriteEnabled: true },
+})
+
+// 뷰 컴포넌트가 inject로 소비
+provide(EDITOR, controller)
+```
+
+```vue
+<template>
+  <PartPalette />
+  <PartCanvas />
+  <PartTree />
+  <PropertyPanel />
+</template>
+
+<script setup lang="ts">
+import { PartPalette, PartCanvas, PartTree, PropertyPanel } from '@g1cloud/ui-modeler-next'
+</script>
+```
+
+op 동기화(낙관적 예측·CAS·hard-freeze)는 `OpSyncAdapter`(`command/opSync`)를 통해 호스트 전송층에 배선한다. 전송층은 op 배치를 호스트 엔드포인트로 POST하고 CAS 충돌만 `{ok:false}`로 반환하면 된다.
+
+## 에이전트 / 서버 표면
+
+사람 개입 없이 화면을 읽고 쓰는 순수 함수들. 저장소·프레임워크에 독립적이다.
+
+```ts
+import {
+  describeScreen,   // PartModel → AgentView (id·path·caption·agent-facing attrs 트리)
+  resolveOps,       // symbolicOp[] → ResolvedOp[] (핸들 해소: id → path → caption)
+  buildAgentBatch,  // ResolvedOp[] → OpShape 배치 (CAS revs·origin)
+  applyOpsToFlat,   // 평면 partList에 op 배치 적용 (호스트 mongo interpreter의 의미론 오라클)
+  toAgentCatalog,   // 카탈로그의 에이전트-정제 뷰 (G2)
+} from '@g1cloud/ui-modeler-next'
+```
+
+에이전트 접근의 불변 투자는 호스트 HTTP API 3종(`describeScreen` read · op write · `toAgentCatalog`)이며, skill/MCP 등 전송층은 그 위의 얇은 계층이다.
+
+## 실 미리보기 (전략 B)
+
+캔버스는 경량 스키매틱 렌더러로, 실 컴포넌트 미리보기는 격리된 iframe에서 렌더한다(`IframePreview` + postMessage 브릿지). iframe 경계가 디자인시스템 CSS/inject 충돌을 분리한다.
+
+## 공개 API 표면
+
+| 영역 | 주요 export |
+|---|---|
+| `core` | `PartModel`·`attrValue`·`MultiLangText`·`traverse`·`validatePartModel` |
+| `catalog` | `createCatalog`·`toAgentCatalog`·`STYLE_TOKENS`·containment 규칙 |
+| `adapter` | `fromPersistedV2`/`toPersistedV2`·`applyOpsToFlat` |
+| `command` | `CommandStack`·트리 4연산·`OpShape`·`RevCache`·`OpSyncAdapter` |
+| `agent` | `symbolicOp`·`resolver`·`schema`·`describeScreen`·`buildAgentBatch` |
+| `editor` | `createUiEditorController`·`EDITOR` inject key |
+| `view` | `RendererRegistry`·`PartCanvas`·`PartPalette`·`PropertyPanel`·`PartTree`·`IframePreview` |
+
+## 개발
+
+```bash
+pnpm dev          # 데모 하네스 (src/dev)
+pnpm test         # Vitest
+pnpm typecheck    # vue-tsc --noEmit
+pnpm build        # 라이브러리 빌드 → dist/
+```
+
+- Node `>= 24.10.0`
+
+## 라이선스
+
+`LicenseRef-LICENSE` — 저장소의 `LICENSE` 파일 참조.

package/dist/adapter/attrCodec.d.ts

@@ -0,0 +1,12 @@
+import { AttrKind, AttrVal } from '../core/attrValue';
+import { PAttrValue } from './persisted';
+/**
+ * @param valueType catalog가 선언한 kind(authoritative). 미지정 시 v1 태그로 추론.
+ * @returns 표현 가능한 clean 값, 또는 표현 불가 시 `undefined`(관찰적 폐기 대상).
+ */
+export declare function attrValFrom(p: PAttrValue, valueType?: AttrKind): AttrVal | undefined;
+/**
+ * v1 attrMap → clean attrs. 표현 불가 항목은 결과에서 제외하고 `onDiscard`로 보고한다.
+ * @param valueTypeOf 키별 catalog valueType 조회(없으면 태그 추론).
+ */
+export declare function attrMapFrom(m: Record<string, PAttrValue>, valueTypeOf?: (key: string) => AttrKind | undefined, onDiscard?: (key: string, p: PAttrValue) => void): Record<string, AttrVal>;

package/dist/adapter/interpretFlat.d.ts

@@ -0,0 +1,20 @@
+import { OpShape, OpCas, OpConflict, PartId } from '../command/op';
+import { PFlatPart } from './persisted';
+/** {@link applyOpsToFlat} 결과 — ok면 갱신 평면 리스트+touched 컨테이너 신 rev, 충돌이면 프리즈 트리거. */
+export type FlatApplyResult = {
+    ok: true;
+    partList: PFlatPart[];
+    revs: Record<PartId, number>;
+} | {
+    ok: false;
+    conflict: OpConflict;
+};
+/**
+ * op 배치를 평면 인접리스트에 적용한다(호스트 mongo interpreter의 의미론 오라클).
+ *
+ * @param partList pre-batch 평면 상태(입력은 변형하지 않음 — 클론에 적용).
+ * @param ops apply 순서의 op 어휘 배치.
+ * @param cas 컨테이너 base rev 단언(`revContainersOf` 파생, opSync가 합성).
+ * @returns ok+갱신 리스트/신 rev, 또는 conflict(rev 불일치 / 대상 소실). 충돌 시 부분 변형 없음.
+ */
+export declare function applyOpsToFlat(partList: PFlatPart[], ops: OpShape[], cas: OpCas): FlatApplyResult;

package/dist/adapter/legacyGridSort.d.ts

@@ -0,0 +1,11 @@
+import { GridDefaultSort } from '../core/gridDefaultSort';
+/**
+ * 레거시 그리드 정렬 문자열(`propId:ORDER:dataMapping:name`, 리스트는 세미콜론 join)의
+ * **v1-read 파서**. → {@link GridDefaultSort}(구조 객체). 역방향 직렬화(write-back)는 폐기(G6).
+ *
+ * 파생 원본: bluework-uimodeler-model/.../ui/GridDefaultSort.java (parse/toString)
+ */
+/** `propId:ORDER:dataMapping:name` 단일 항목 파싱. */
+export declare function parseGridSort(str: string): GridDefaultSort;
+/** 세미콜론 구분 리스트 파싱(빈 항목 무시). */
+export declare function parseGridSortList(str: string | null | undefined): GridDefaultSort[];

package/dist/adapter/legacyText.d.ts

@@ -0,0 +1,31 @@
+import { MultiLangText, MultiLangString } from '../core/lang';
+/**
+ * 레거시 텍스트 형태({@code UiKeyText})의 **v1-read 디코더**. `#{key}` 인코딩·key/text/msgMap
+ * 형태는 legacy 저장 관심사이므로 여기(단일 v1-read 경계)에만 두고, clean 모델은 {@link MultiLangText}만
+ * 다룬다(G6). 역방향 인코딩(write-back)은 폐기.
+ *
+ * 파생 원본: bluework-uimodeler-model/.../ui/shared/UiKeyText.java(+ encodeKeyText/decodeKeyText)
+ */
+/** 레거시 v1 텍스트 형태. 저장 시 `key`가 canonical(UiKeyText.java 주석). */
+export interface UiKeyText {
+    key?: string;
+    text?: string;
+    msgMap?: MultiLangString;
+    children?: UiKeyText[];
+}
+/**
+ * `#{key}` 인코딩 문자열을 {@link UiKeyText}로 디코딩. 레거시 {@code decodeKeyText(msg, null)}과 동치:
+ * - `#{key}` → { key }  (resolver 없으므로 text 미설정)
+ * - 그 외    → { text }
+ */
+export declare function decodeKeyText(msg: string | null | undefined): UiKeyText | undefined;
+/**
+ * {@link UiKeyText}(v1) → clean {@link MultiLangText}로 브릿지.
+ * - `key` 보유 → 메시지 키 참조 `{ key }`(운영 caption의 사실상 전부 · 무손실).
+ * - `msgMap` 보유 → locale 맵.
+ * - `text`만 → 평문 string.
+ * - 비어 있으면 undefined.
+ */
+export declare function uiKeyTextToMultiLang(t: UiKeyText | undefined): MultiLangText | undefined;
+/** v1 저장 문자열(`#{key}` 또는 평문) → clean {@link MultiLangText}. adapter 텍스트 디코드 진입점. */
+export declare function decodeToMultiLang(msg: string | null | undefined): MultiLangText | undefined;

package/dist/adapter/legacyValidator.d.ts

@@ -0,0 +1,2 @@
+import { ValidatorConfig } from '../core/validatorConfig';
+export declare function parseValidatorString(s: string | null | undefined): ValidatorConfig;

package/dist/adapter/migrate.d.ts

@@ -0,0 +1,47 @@
+import { PartModel } from '../core/types';
+import { PartCatalog } from '../catalog/types';
+import { PPartModel, PUiModelV2 } from './persisted';
+import { CoverageReport } from './uiModelAdapter';
+/**
+ * v1→v2 마이그레이션 도구(G6 · 불변식 #5). 폐기된 무손실 왕복(write-back)을 대체하는
+ * **일방향 이관 파이프**: 레거시 v1 Jackson JSON({@link PPartModel})을 읽어 clean 트리로 디코드하고
+ * (레거시 적대성 흡수), 신규 편집기의 유일 write 포맷인 v2 평면 문서({@link PUiModelV2})로 재직렬화한다.
+ *
+ * 이 도구는 두 순수 함수의 얇은 조립일 뿐이다: `fromPersisted`(v1-read 디코더) → `toPersistedV2`(v2 write).
+ * 존재 이유는 **커버리지 리포트의 표면화**다 — v1 디코드가 조용히 버린 것(미지 partType·표현 불가 attr·
+ * 신모델 미표현 필드)을 {@link CoverageReport}로 모아 반환해, 운영자가 v2를 영속화하기 전에 폐기 내역을
+ * 감사·리뷰할 수 있게 한다(관찰적 폐기 원칙).
+ *
+ * 호스트 무의존 순수 함수다(파일 I/O·DB 없음). 실제 적재/기록은 호출부(마이그레이션 스크립트·호스트 route)가
+ * 맡는다. v1→clean의 구조 동치·`#{key}` 비누출·왕복 대칭은 `_migration-oracle.test.ts`가 실샘플로 실증한다.
+ */
+export interface MigrateV1ToV2Options {
+    /** attr 타이핑 authoritative 소스 + unknown partType/attr 판정용. 생략 시 태그 추론. */
+    catalog?: PartCatalog;
+    /** v2 문서 메타로 전달({@link toPersistedV2}). */
+    opWriteEnabled?: boolean;
+    /** v2 문서 메타로 전달({@link toPersistedV2}). */
+    version?: number;
+    /**
+     * 배치 마이그레이션 시 여러 문서의 폐기를 하나의 리포트에 누적하고 싶을 때 주입.
+     * 생략 시 문서마다 fresh 리포트를 생성한다({@link FromPersistedOptions.report}와 동일 규약).
+     */
+    report?: CoverageReport;
+}
+export interface MigrateV1ToV2Result {
+    /** 신규 편집기 유일 write 포맷. 호스트가 그대로 영속화한다. */
+    v2: PUiModelV2;
+    /** 관찰적 폐기 내역. 영속화 전 감사·리뷰 대상(unknownPartTypes/discardedAttrs/droppedFields). */
+    report: CoverageReport;
+    /**
+     * v1-read 중간 산출물 clean 트리. `toPersistedV2`의 입력이자, 호출부가 영속화 전
+     * `validatePartModel`(M5)로 카탈로그 규칙을 재검증하고 싶을 때 재계산 없이 재사용하는 seam.
+     */
+    model: PartModel;
+}
+/**
+ * v1 문서 하나를 v2로 이관한다. 반환된 {@link MigrateV1ToV2Result.report}가 비어 있으면 무손실 흡수,
+ * 항목이 있으면 그 내역이 폐기 결정의 감사 근거다. 배치 이관은 호출부가 문서마다 호출하며,
+ * `opts.report`를 공유하면 폐기 내역이 한 리포트에 누적된다.
+ */
+export declare function migrateV1ToV2(doc: PPartModel, opts?: MigrateV1ToV2Options): MigrateV1ToV2Result;

package/dist/adapter/persisted.d.ts

@@ -0,0 +1,75 @@
+import { PartInfo } from '../core/types';
+import { AttrVal } from '../core/attrValue';
+import { MultiLangText } from '../core/lang';
+import { CaseMessage } from '../core/caseMessage';
+/**
+ * 레거시 영속 형태(v1) — **읽기·마이그레이션 소스 전용**(G6, write-back 폐기).
+ * {@code UiModelerUtils.partModelToJson}(Jackson, Include.NON_NULL)의 JSON 구조를 그대로 표현한다.
+ * 필드명은 레거시 getter 기준: partId/partType/partInfo/attrMap/comment/caseMsgList/children/
+ * layoutAttrMap/extraAttrMap. AttrValue → {type,val}.
+ *
+ * 파생 원본: bluework-uimodeler-model/.../ui/shared/{PartModel,AttrValue,PartInfo,CaseMessage}.java
+ */
+/**
+ * 레거시 `AttrType` enum 이름(v1 저장 태그). clean 모델엔 존재하지 않고 v1-read 디코더에만 산다.
+ * `M_REF`/`DS_REF`/`DM_REF`(원문 보존용 왕복)·`ETC`(미지 태그)는 write-back 폐기로 clean kind로
+ * 매핑되지 않는다 → 관찰적 폐기(커버리지 리포트).
+ */
+export type AttrTypeTag = 'S' | 'I' | 'B' | 'M' | 'M_REF' | 'DS' | 'DS_REF' | 'DM' | 'DM_REF' | 'ETC';
+export interface PAttrValue {
+    type: AttrTypeTag | string;
+    val: string;
+}
+export interface PPartInfo {
+    draggable: boolean;
+    droppable: boolean;
+    selectable: boolean;
+    deletable: boolean;
+}
+export interface PCaseMessage {
+    caseText?: Record<string, string>;
+    msgType?: string;
+    msgText?: string;
+}
+export interface PPartModel {
+    partId: string;
+    partType: string;
+    partInfo?: PPartInfo;
+    attrMap?: Record<string, PAttrValue>;
+    comment?: Record<string, string>;
+    caseMsgList?: PCaseMessage[];
+    children?: PPartModel[];
+    layoutAttrMap?: Record<string, PAttrValue>;
+    extraAttrMap?: Record<string, string>;
+    [key: string]: unknown;
+}
+/** 평면 인접리스트의 한 노드 — clean `PartModel`에서 children을 걷어내고 parentId/order/rev를 부여. */
+export interface PFlatPart {
+    partId: string;
+    /** 부모 partId. root는 null. */
+    parentId: string | null;
+    /** 형제 내 정렬 키(0-base). 트리 children[] 순서를 평면에서 복원하는 근거. */
+    order: number;
+    /** CAS 축 rev(불변식 #2). 신규 write/서브트리 seed 시 0. */
+    rev: number;
+    partType: string;
+    info?: PartInfo;
+    /** 컴포넌트 속성(타입드 clean 값). */
+    attrs?: Record<string, AttrVal>;
+    /** 부모 레이아웃 부과 속성(정렬/expandRatio 등). */
+    layoutAttrs?: Record<string, AttrVal>;
+    extraAttrs?: Record<string, string>;
+    comment?: MultiLangText;
+    caseMessages?: CaseMessage[];
+}
+/** v2 문서 루트 — 평면 partList + 메타. */
+export interface PUiModelV2 {
+    schemaVersion: 2;
+    /** op-write 활성 플래그(호스트가 낙관 write 경로 게이팅). */
+    opWriteEnabled?: boolean;
+    /** 문서 리비전(전체 로드 낙관 락 보조 — part rev와 독립). */
+    version?: number;
+    /** 트리 재구성 진입점(parentId=null 노드와 일치). */
+    rootId: string;
+    partList: PFlatPart[];
+}

package/dist/adapter/uiModelAdapter.d.ts

@@ -0,0 +1,80 @@
+import { PartModel } from '../core/types';
+import { PartCatalog } from '../catalog/types';
+import { PPartModel, PFlatPart, PUiModelV2 } from './persisted';
+/**
+ * 레거시 v1 Jackson JSON({@link PPartModel}) → 인메모리 clean 트리({@link PartModel})의
+ * **단방향 lossy-observable 디코더**(G6 — write-back·무손실 왕복 폐기).
+ *
+ * "손실"은 조용히 버리지 않고 {@link CoverageReport}로 표면화한다(관찰적 폐기):
+ * - `unknownPartTypes`: catalog에 없는 partType.
+ * - `discardedAttrs`: clean 모델이 표현할 수 없는 attr(`M_REF`/`ETC`/미지 태그 등).
+ * - `droppedFields`: 신모델이 표현하지 않는 최상위 필드(구 `legacyRaw`).
+ *
+ * catalog를 넘기면 attr 타이핑이 catalog {@code valueType}로 authoritative해지고(`validate`→구조값 등),
+ * unknown partType/attr이 리포트에 잡힌다. catalog 없이도 태그 추론으로 동작한다.
+ */
+export interface DiscardedAttr {
+    partId: string;
+    partType: string;
+    key: string;
+    tag: string;
+    layout: boolean;
+}
+export interface CoverageReport {
+    unknownPartTypes: {
+        partId: string;
+        partType: string;
+    }[];
+    discardedAttrs: DiscardedAttr[];
+    droppedFields: {
+        partId: string;
+        partType: string;
+        field: string;
+    }[];
+}
+export declare function emptyCoverageReport(): CoverageReport;
+export interface FromPersistedOptions {
+    /** attr 타이핑 authoritative 소스 + unknown partType/attr 판정용. */
+    catalog?: PartCatalog;
+    /** 관찰적 폐기 집계 리포트(호출부가 넘겨 누적). */
+    report?: CoverageReport;
+}
+/**
+ * v1 문서를 clean 트리로 읽어 들인다. `opts.report`를 넘기면 관찰적 폐기가 집계된다.
+ * write-back(toPersisted)은 존재하지 않는다 — v1→v2 마이그레이션은 별도 도구(v2 write 경로).
+ */
+export declare function fromPersisted(doc: PPartModel, opts?: FromPersistedOptions): PartModel;
+/**
+ * 서브트리를 평면 레코드 배열로 펼친다(pre-order). 전 노드에 **동일 `rev`를 stamp**한다(기본 0) —
+ * part.add inline-fold 서브트리 seed(불변식 #3)와 초기 v2 write의 rev 재시드에 공용으로 쓰인다.
+ * `order`는 형제 내 인덱스로, root(또는 서브트리 최상위)는 `startOrder`.
+ * opSync(낙관 캐시 seed)와 호스트 interpreter가 같은 평탄화 규칙을 공유하도록 여기 한 곳에 둔다.
+ */
+export declare function flattenSubtree(part: PartModel, parentId?: string | null, startOrder?: number, rev?: number): PFlatPart[];
+/**
+ * 인메모리 clean 트리 → v2 평면 문서. **초기 write/마이그레이션 시 전 노드 rev를 0으로 재시드**한다
+ * (이후 rev는 op-write CAS가 파트별로 $inc). 이 문서를 다시 트리로 읽는 v2-read(flat→tree)는
+ * 호스트가 실제 영속 문서를 적재하는 M10에서 대칭 구현한다(§G6). opSync는 write + RevCache seed만 소비.
+ */
+export declare function toPersistedV2(root: PartModel, opts?: {
+    opWriteEnabled?: boolean;
+    version?: number;
+}): PUiModelV2;
+/** {@link fromPersistedV2} 결과 — clean 트리 + RevCache seed(controller `UiModelMeta.revSeed`로 주입). */
+export interface FromPersistedV2Result {
+    root: PartModel;
+    /** partId→rev. 호스트가 op-mode 진입 시 opSync `seed`로 주입(불변식 #2 단일 'part' 축). */
+    revSeed: {
+        revs: Record<string, number>;
+    };
+}
+/**
+ * v2 평면 문서를 clean 트리로 재구성한다({@link toPersistedV2}의 역, round-trip deep-equal).
+ * `parentId`/`order`로 부모-자식·형제 순서를 복원하고 각 파트 `rev`를 `revSeed`로 산출한다.
+ *
+ * v2는 v1과 달리 우리 자신의 clean write 포맷이므로 **lossy-observable이 아니라 구조적 역함수**다 —
+ * 손상(중복 partId·부모 부재·root 부재/비-null·순환·도달 불가 파트)은 관찰적 폐기가 아니라 데이터 무결성
+ * 위반이므로 조용히 넘기지 않고 즉시 throw한다(호스트 저장/interpreter 버그를 조기 노출; M5 검증은 정상
+ * 트리의 카탈로그 규칙 위반을 다루는 별개 계층).
+ */
+export declare function fromPersistedV2(doc: PUiModelV2): FromPersistedV2Result;

package/dist/agent/buildAgentBatch.d.ts

@@ -0,0 +1,22 @@
+import { OpOrigin, OpShape, PartId, PersistedOpBatch } from '../command/op';
+import { ResolvedOp } from './resolver';
+/**
+ * resolver `ResolvedOp` → M6 wire `OpShape`. 필드명 브릿지 + part.update 두 축→patch 합성.
+ * part.update patch는 M6 `updatePart` 관례를 미러 — **비어있지 않은 축만** 키로 포함(빈 patch 허용).
+ */
+export declare function toOpShape(op: ResolvedOp): OpShape;
+export interface BuildAgentBatchOptions {
+    /** clientOpId(멱등 키) 발급기 — 주입 시 테스트 결정성. 기본 newPartId(crypto.randomUUID). */
+    mkClientOpId?: () => string;
+    /** op 출처 — 기본 'agent'(감사·aggregation 트리거 분기). REST 브리지면 'rest'. */
+    origin?: OpOrigin;
+}
+/**
+ * 에이전트/REST 경로의 stateless 배치 조립.
+ *
+ * @param modelId 대상 모델 doc id(호스트 라우트가 bizModule→DBRef로 해소).
+ * @param revs base rev 스냅샷(컨테이너 partId→rev). 호스트가 M10에서 v2 문서→revSeed로 공급,
+ *   테스트는 손수 주입. touched 컨테이너에 대해서만 `cas.revs`에 반영.
+ * @param ops resolver 산출 `ResolvedOp` 배치(한 원자 단위). 내부에서 `toOpShape`로 브릿지.
+ */
+export declare function buildAgentBatch(modelId: string, revs: Record<PartId, number>, ops: ResolvedOp[], options?: BuildAgentBatchOptions): PersistedOpBatch;

package/dist/agent/describeScreen.d.ts

@@ -0,0 +1,21 @@
+import { PartType } from '../core/partType';
+import { PartModel } from '../core/types';
+import { PartCatalog } from '../catalog/types';
+/**
+ * 화면 트리의 agent-facing 노드. write `PartSpec`의 read 대칭.
+ * - id: 1차 핸들(항상 포함 — "id 선호" 강제).
+ * - path: 2차 핸들(`FormLayout[0]/TextField[2]`). resolver `pathOf`·`byPath`와 동일 문법.
+ * - caption: 3차 핸들 — captionProp가 가리키는 attr 값(string/text 리터럴만).
+ * - attrs: agent 노출 subset. 노출 prop 값 + G1 css→token 역매핑한 스타일 토큰(dim→token)을 평면 병합.
+ */
+export interface AgentNode {
+    id: string;
+    partType: PartType;
+    path: string;
+    caption?: string;
+    attrs: Record<string, unknown>;
+    children: AgentNode[];
+}
+export type AgentView = AgentNode;
+/** PartModel 트리 → AgentView(정제 read 뷰). 호스트 무관 — 순수 함수. */
+export declare function describeScreen(root: PartModel, catalog: PartCatalog): AgentView;

package/dist/agent/resolver.d.ts

@@ -0,0 +1,72 @@
+import { AttrVal } from '../core/attrValue';
+import { PartModel } from '../core/types';
+import { PartCatalog } from '../catalog/types';
+import { Handle, SymbolicOp } from './symbolicOp';
+/** 핸들 후보(모호성 escalation·describeScreen seed). */
+export interface HandleCandidate {
+    partId: string;
+    path: string;
+    caption?: string;
+}
+export type ResolveIssue = {
+    kind: 'handle-not-found';
+    ref: string;
+    by?: string;
+} | {
+    kind: 'handle-ambiguous';
+    ref: string;
+    candidates: HandleCandidate[];
+} | {
+    kind: 'unknown-style-dim';
+    dim: string;
+} | {
+    kind: 'unknown-style-token';
+    dim: string;
+    token: string;
+};
+/** 하강된 op(M6 OpShape seed). */
+export type ResolvedOp = {
+    kind: 'part.add';
+    parentId: string | null;
+    index?: number;
+    part: PartModel;
+} | {
+    kind: 'part.update';
+    targetId: string;
+    attrs: Record<string, AttrVal>;
+    layoutAttrs: Record<string, AttrVal>;
+} | {
+    kind: 'part.remove';
+    targetId: string;
+};
+export interface ResolveResult {
+    ops: ResolvedOp[];
+    issues: ResolveIssue[];
+}
+export interface ResolveContext {
+    /** 핸들 해석 대상 기존 트리(루트). part.add parent=null이면 무관. */
+    root?: PartModel;
+    /** captionProp 조회(caption 핸들·검증). 미지정 시 caption 축 비활성. */
+    catalog?: PartCatalog;
+    /** partId 생성기(테스트 결정성 주입용). 기본 crypto.randomUUID. */
+    newId?: () => string;
+}
+/** root→partId 경로를 `Type[i]/Type[j]` 문자열로. i=형제 중 동일 partType 순번(0-base). */
+export declare function pathOf(root: PartModel, partId: string): string | undefined;
+/**
+ * captionProp가 가리키는 attr의 비교용 문자열(string/text 리터럴만; 맵/키형은 비교 대상 밖).
+ * describeScreen(G3)이 caption 핸들 산출에 **동일 규칙 재사용**(read↔write 대칭) — export.
+ */
+export declare function captionText(part: PartModel, catalog: PartCatalog | undefined): string | undefined;
+type HandleResolution = {
+    ok: true;
+    partId: string;
+} | {
+    ok: false;
+    issue: ResolveIssue;
+};
+/** 핸들 하나를 partId로. by 미지정 시 id → path → caption 순. 모호하면 후보 반환. */
+export declare function resolveHandle(h: Handle, ctx: ResolveContext): HandleResolution;
+/** SymbolicOp 배치를 ResolvedOp[]로 하강. 실패는 issues로 수집(해당 op 생략). */
+export declare function resolveOps(ops: SymbolicOp[], ctx?: ResolveContext): ResolveResult;
+export {};

package/dist/agent/schema.d.ts

@@ -0,0 +1,15 @@
+type JsonSchema = Record<string, unknown>;
+/**
+ * inline-fold unroll 최대 깊이. self-`$ref` 재귀를 대체하는 고정 깊이(§R-schema 판정).
+ * L0(루트 spec)부터 L{MAX}(children 없는 leaf)까지 (MAX+1)개 레벨. 이보다 깊은 중첩은 별도 배치.
+ */
+export declare const MAX_INLINE_DEPTH = 4;
+/** 단일 SymbolicOp의 JSON Schema(kind로 판별되는 anyOf). $defs는 최상위에서 정의. */
+export declare const SYMBOLIC_OP_SCHEMA: JsonSchema;
+/**
+ * 호스트 `applyOps` 도구의 input_schema. 한 배치 = 한 원자 단위(resolver가 전부 해소 or 전부 실패).
+ * description은 "언제 호출하는지"를 명시 — 최신 모델은 도구를 보수적으로 집으므로 트리거 조건이 호출률을 좌우.
+ * 모든 $defs는 여기 최상위에 모은다(엄격 서브셋: nested $defs 금지).
+ */
+export declare const APPLY_UI_OPS_INPUT_SCHEMA: JsonSchema;
+export {};

package/dist/agent/strictSubset.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ── Anthropic structured-outputs 엄격 서브셋 적합성 검증기 ──
+ *
+ * `agent/schema.ts`가 방출하는 JSON Schema가 Anthropic structured-outputs / strict tool use의
+ * **엄격 서브셋**을 지키는지 기계적으로 검사한다. 이 검증기는 두 목적을 겸한다:
+ *   1. 스키마 drift 게이트 — 미지원 키워드·additionalProperties 누락을 CI에서 잡는다.
+ *   2. **R-schema 실증(exit #3)** — inline-fold `partSpec.children`의 self-`$ref`(재귀)가 이 서브셋에서
+ *      거부됨을 코드로 증명한다(재귀 탐지가 self-loop/사이클을 위반으로 보고). 라이브러리엔 LLM이
+ *      없으므로(불변식) 라이브 API 프로브 대신 문서-권위 제약을 검증기로 코드화한다.
+ *
+ * 엄격 서브셋 규칙(claude-api: Structured Outputs → JSON Schema Limitations):
+ * - 지원: object/array/string/integer/number/boolean/null, enum, const, anyOf, allOf, $ref/$defs,
+ *   string formats, 모든 object에 `additionalProperties: false`.
+ * - 미지원: **재귀 스키마**, 수치 제약(minimum/maximum/multipleOf), 문자열 제약(minLength/maxLength/pattern),
+ *   복합 배열 제약(minItems/maxItems/uniqueItems), `additionalProperties`가 false 아닌 값.
+ */
+export interface StrictSubsetViolation {
+    /** 위반 규칙 슬러그. */
+    rule: 'missing-additional-properties-false' | 'unsupported-keyword' | 'nested-$defs' | 'recursion' | 'dangling-$ref';
+    /** 스키마 내 위치(디버그용 경로). */
+    path: string;
+    detail: string;
+}
+/**
+ * 스키마가 Anthropic 엄격 서브셋을 지키는지 검사. 위반 배열 반환(빈 배열 = 적합).
+ * @param root 루트 스키마(도구 input_schema — `$defs`는 여기 최상위).
+ */
+export declare function checkStrictSubset(root: unknown): StrictSubsetViolation[];
+/** 적합 여부 단축 판정. */
+export declare function isStrictSubset(root: unknown): boolean;