@g1cloud/entity-modeler-next 5.0.0-alpha.9 → 5.0.0-beta.10

package/dist/core/types.d.ts

@@ -103,6 +103,52 @@ export interface GroupCodeCatalogEntry {
     codes: GroupCodeValue[];
 }
 export type GroupCodeCatalog = GroupCodeCatalogEntry[];
+/**
+ * 슈퍼클래스 카탈로그 — `Entity.superClass`(예: BaseEntity)가 상속시키는 컬럼(감사필드 createdBy/
+ * createdAt/updatedBy/updatedAt 등)의 정의. 상속 컬럼은 모델에 물질화되지 않으므로(syncPlaybook §G4
+ * 상속필드 의도적 부재) 인덱스 대상으로 참조하려면 이 카탈로그로 파생 투영한다(`inheritedColumns.ts`).
+ * EmbeddableCatalog와 동형으로 **호스트가 주입**하며(shared/ 하드코딩 상수, 완전 통합 시 superClassCatalog
+ * 엔드포인트) 코어는 소비만 한다. 빈 배열이면 상속 컬럼 투영이 나오지 않는다(inert — 인덱스는 로컬
+ * dbAttr만 참조 가능).
+ */
+export interface SuperClassColumnDef {
+    /** 논리 필드명 = 합성 modelId(`inherited:<class>:<field>`) 키. 카탈로그 물리명이 바뀌어도 안정(D6). 예: 'createdAt'. */
+    field: string;
+    /** 물리 컬럼명(@Index columnList 코드젠용). 예: 'created_at'. */
+    physicalName: string;
+    /** dbTypes 카탈로그 값. 예: 'TIMESTAMP'. */
+    dataType: string;
+    /** 표시용 논리명(선택). */
+    logicalName?: MultiLangText;
+    length?: number;
+    scale?: number;
+}
+export interface SuperClassDef {
+    /** `Entity.superClass`와 매칭되는 클래스명(예: BaseEntity). 카탈로그 내 유일. */
+    name: string;
+    /**
+     * JPA 상속 종류. 초기엔 mapped-superclass만 — @Index(columnList=)가 상속 물리 컬럼을 유효하게
+     * 참조하는 전제(상속 컬럼이 자식 테이블에 병합됨). 다른 전략(JOINED 등)은 별도 트랙.
+     */
+    kind: 'MAPPED_SUPERCLASS';
+    /**
+     * base 클래스의 자바 패키지(FQN 구성용). 예: 'net.g1project.ecp.common.domain'.
+     * **현재 lib 소비처 없음** — 상속 컬럼 인덱스 모델링은 field/physicalName/dataType만 쓴다.
+     * 코드젠이 `import <packageName>.<name>;` + `extends <name>`를 낼 때를 위한 forward 슬롯(호스트 소유).
+     * 카탈로그를 base 클래스 단일 SoT로 키우려는 방향(embeddable/javaType 카탈로그 계열)의 provisioning.
+     */
+    packageName?: string;
+    /**
+     * 이 base가 프로젝트 **암묵 default**인지. `Entity.superClass`가 비어 있으면(레거시 관례상
+     * 명시 안 함 = 코드젠이 `extends <default>`를 냄) 이 base가 상속 컬럼을 기여한다.
+     * 카탈로그 내 최대 하나만 표시(여럿이면 첫 항목). 명시적 `superClass='Object'`는 non-empty라
+     * 이 폴백에 걸리지 않고 카탈로그 미스 → 상속 없음(자바 `extends Object` = default 상속 opt-out 트릭).
+     */
+    default?: boolean;
+    /** 이 슈퍼클래스가 기여하는 컬럼(선언 순서 보존). */
+    columns: SuperClassColumnDef[];
+}
+export type SuperClassCatalog = SuperClassDef[];
 export interface DbColumn {
     modelId: ModelId;
     physicalName: string;
@@ -269,13 +315,19 @@ export interface AssociationEnd {
     multiplicity: Multiplicity;
     navigable: boolean;
     composition: boolean;
-    /** FK/조인을 표현하는 속성 (RELATION_OWN/REF) */
+    /**
+     * FK/조인 또는 inverse nav를 표현하는 속성. owner end=RELATION_OWN(FK), 부모(navigable) end=
+     * RELATION_REF(inverse nav). 레거시 crossed nav는 로드 시 소유 엔티티에 RELATION_REF로 승격되고
+     * 이 ref가 그것을 가리킨다(diagramAdapter.assocFromHydrated). 레이아웃 앵커는 layout.sourceColumnRef로 분리.
+     */
     attributeRef?: ModelId;
     /**
-     * 라운드트립 전용 — 레거시 crossed 직렬화의 nav 참조 속성 원형(신규 모델에 표현 슬롯 없음).
-     * 로드 시 어댑터가 보관, 저장 시 그대로 환원한다. UI·전파는 무시한다.
+     * inverse nav(RELATION_REF) 미실체화 시 마지막 nav 필드명 기억용. navigable=false면 nav 속성 자체는
+     * 삭제되어(불변식 "navigable=true ⟺ nav 속성 존재" 유지·코드젠 무영향) 저장된 이름이 없다 — 이 힌트가
+     * 사용자가 편집했던 이름을 보관해, 인스펙터 비활성 필드 표시 및 재활성화 시 기본명 대신 복원에 쓰인다.
+     * 실체화되면 속성 name이 SoT이므로 이 힌트는 정리(재-off 시 현재 name을 다시 캡처).
      */
-    legacyNavRaw?: Record<string, unknown>;
+    navFieldNameHint?: string;
     /**
      * 라운드트립 전용 — 레거시 EMBED 직렬화의 인라인 속성 원형(EMBED_REF/EMBED_OWN).
      * EMBED hydration은 load-only라 저장 시 소유자로 펼친 표시 속성을 버리고 이 원형을 verbatim 환원한다

package/dist/core/validation.d.ts

@@ -1,14 +1,21 @@
-import { EmbeddableCatalog, LogicalModel, ModelId } from './types';
+import { Attribute, DbColumn, EmbeddableCatalog, LogicalModel, ModelId, SuperClassCatalog } from './types';
 export declare const PHYSICAL_NAME_MAX_LENGTH = 63;
 /**
- * 물리명이 이식성 권장 한도를 초과하면 경고 메시지, 아니면 null(비차단 — 호출부는 저장을 막지 않는다).
- * 빈값/미설정은 경고 없음(레거시 isNotEmpty 게이트 동형).
+ * 물리명이 이식성 권장 한도를 초과하면 **초과 길이(문자 수)**, 아니면 null(비차단 — 호출부는 저장을
+ * 막지 않는다). 빈값/미설정은 경고 없음(레거시 isNotEmpty 게이트 동형).
+ *
+ * 이전엔 완성된 경고 문자열을 반환했으나, i18n(P3)로 core가 표시 문자열을 만들지 않게 되어 길이만
+ * 돌려준다 — 컬럼·테이블·인덱스 3곳이 이 값을 `CHK-NAME-5` params `{max,len}`로 재사용(단일 출처).
  */
-export declare function physicalNameWarning(name: string | null | undefined): string | null;
+export declare function physicalNameLengthOverflow(name: string | null | undefined): number | null;
 export type IssueSeverity = 'error' | 'warning' | 'info';
 export type IssueTargetKind = 'entity' | 'attribute' | 'column' | 'association' | 'index' | 'group' | 'model';
 export interface ValidationIssue {
-    /** 규칙 식별자(예: 'CHK-NAME-1'). 엔진 불변식 INV-*와 다른 네임스페이스(위반 가능·수정 대상). */
+    /**
+     * 규칙 식별자(예: 'CHK-NAME-1'). 엔진 불변식 INV-*와 다른 네임스페이스(위반 가능·수정 대상).
+     * **메시지 code**를 겸한다 — 뷰가 `ruleId`(+targetKind/params 변형)로 i18n 키를 해석해 로컬라이즈
+     * (`view/validationDisplay.issueMessageKey`). core는 문자열을 만들지 않는다(D3, 논리↔표시 분리).
+     */
     ruleId: string;
     severity: IssueSeverity;
     targetKind: IssueTargetKind;
@@ -16,7 +23,12 @@ export interface ValidationIssue {
     targetRef?: ModelId;
     /** 보조 ref(예: 컬럼/속성 이슈의 소속 엔티티) — 뷰 그룹핑/내비용. */
     contextRef?: ModelId;
-    message: string;
+    /**
+     * 메시지 보간 파라미터 — 뷰가 `c.t(key, params)`로 치환. 값은 식별자/카운트/JPA 리터럴 등
+     * **번역 대상이 아닌 데이터**(name·dataType·which='end1'/'end2'·cascade='ALL'/'REMOVE' 등).
+     * 정적 메시지 규칙은 생략. i18n 카탈로그(`em.i18n`)에 의존하지 않도록 구조만 노출(순수성 유지).
+     */
+    params?: Record<string, string | number>;
 }
 /** 카탈로그 의존 규칙을 켜는 선택 주입 — 미주입 시 해당 규칙 skip(범위 밖 아님, 컨텍스트 부재). */
 export interface ValidationContext {
@@ -43,7 +55,26 @@ export interface ValidationContext {
      * 타입 출처. 호스트/dev 주입(reservedWords와 동형 ctx 게이트). 미주입/빈 배열이면 CHK-TYPE-3 skip.
      */
     embeddableCatalog?: EmbeddableCatalog;
+    /**
+     * 슈퍼클래스 카탈로그 — CHK-DSN-5(dangling 인덱스 대상)가 인덱스 columnRef의 상속 컬럼(`inherited:`
+     * 합성 ref)을 유효한 대상으로 인지하는 화이트리스트 출처. 호스트/dev 주입(embeddableCatalog 동형 ctx
+     * 게이트). 미주입/빈 배열이면 상속 컬럼을 인지하지 못하므로, superClass 상속 컬럼을 참조하는 인덱스가
+     * dangling으로 오탐될 수 있다 — 카탈로그가 주입돼야 정확 판정(로컬 컬럼만 참조하는 모델은 무영향).
+     */
+    superClassCatalog?: SuperClassCatalog;
 }
+/** 같은 키를 2회 이상 갖는 항목만 중복으로 — 중복 그룹의 모든 멤버를 반환(어느 쪽이든 보고 고치게). */
+/**
+ * 임베드 서브컬럼의 **실효 물리명** — 물리명 override(비어있지 않은 physicalName)가 있으면 그 값, 없으면
+ * 상속 기본값을 해석한다. EMBED_PREDEF·EMBED_OWN의 빈 슬롯은 "미매핑"이 아니라 카탈로그/임베더블 source의
+ * 기본 컬럼명을 상속하므로(JPA @Embedded는 @AttributeOverride 부재 시 임베더블 선언 컬럼명 사용), 컬럼 충돌
+ * 판정은 raw '' 가 아닌 이 실효 물리명으로 해야 한다. 특히 한 테이블에 같은 임베더블(예: Money)이 여러 번
+ * 쓰이고 서브컬럼을 비워두면 전부 같은 기본명으로 상속돼 실제 컬럼 충돌이 난다.
+ *  - EMBED_PREDEF: 카탈로그 fields[index].physicalName (ctx 미주입이면 해석 불가 → '' 로 graceful degrade).
+ *  - EMBED_OWN: 임베더블 엔터티 source 컬럼[index]의 physicalName(선언순 평탄화 = flattenEmbeddableColumns 동형).
+ *  - NORMAL 등 그 외: raw physicalName 그대로(빈 값은 '' → 충돌 판정 제외).
+ */
+export declare function resolveColumnPhysicalName(attr: Attribute, col: DbColumn, index: number, model: LogicalModel, ctx?: Pick<ValidationContext, 'embeddableCatalog'>): string;
 /**
  * 설계 품질 검증 — 논리 모델(+선택 컨텍스트)을 받아 이슈 목록을 돌려준다.
  * 순수 함수. 호출부가 심각도/차단정책/표시시점을 해석한다(예: 빈 이름 info는 저장 시점에만 표시).

package/dist/editor/controller.d.ts

@@ -6,8 +6,16 @@ import { OpSyncTransport } from '../command/opSync';
 import { FieldAuditRecord } from '../core/projectFieldAudit';
 import { ResolvedDiagram } from '../core/resolve';
 import { RoutingMode } from '../core/routing';
+import { MergeDiagramSource } from '../core/mergeDiagram';
 import { ValidationIssue } from '../core/validation';
-import { AssociationEnd, Attribute, DisplayMode, EmbeddableCatalog, Entity, EntityIndex, Geo, GroupCodeCatalog, LangCode, LogicalGroup, ModelId, Operation, Point, PredefinedCustomTypeCatalog } from '../core/types';
+import { UiLocale, Translator } from '../i18n';
+import { AssociationEnd, Attribute, DisplayMode, EmbeddableCatalog, Entity, EntityIndex, Geo, GroupCodeCatalog, LangCode, LogicalGroup, ModelId, Multiplicity, Operation, Point, PredefinedCustomTypeCatalog, SuperClassCatalog } from '../core/types';
+import * as cmd from '../command/commands';
+/**
+ * 관계 파생 FK 직접 삭제 시도 시의 안내 — 뷰 tooltip(어포던스)과 차단 시 토스트(피드백)가 공유한다.
+ * FK는 관계가 소유·관리하므로 컬럼을 직접 지우는 대신 연관관계선을 삭제해야 한다(Option B).
+ */
+export declare const FK_MANAGED_DELETE_MESSAGE = "\uC678\uB798\uD0A4\uB294 \uC5F0\uAD00\uAD00\uACC4\uC5D0\uC11C \uD30C\uC0DD\uB429\uB2C8\uB2E4. \uC0AD\uC81C\uD558\uB824\uBA74 \uC5F0\uAD00\uAD00\uACC4\uC120\uC744 \uC120\uD0DD\uD574 \uC0AD\uC81C\uD558\uC138\uC694.";
 /** 엔티티 내부 속성을 가리키는 주소 원자 — 선택·컨텍스트·재정렬·연결 등 속성 단위 기능의 공통 참조점. */
 export type AttrRef = {
     entityId: ModelId;
@@ -24,6 +32,11 @@ export type ClipboardContent = {
     kind: 'entity';
     entity: Entity;
     geo: Geo;
+    layoutExtras?: cmd.EntityLayoutExtras;
+} | {
+    kind: 'entities';
+    source: MergeDiagramSource;
+    selectedIds: ModelId[];
 } | {
     kind: 'attribute';
     attributes: Attribute[];
@@ -66,6 +79,10 @@ export interface EditorController {
      * targetRef 없는 이슈(model 레벨)는 인덱스에서 제외(인라인 매칭 대상 아님).
      */
     issuesByRef: ComputedRef<Map<ModelId, ValidationIssue[]>>;
+    /** 이 이슈에 결정적 quick-fix가 있는지(뷰가 '수정' 버튼 노출 여부 판단). 조회 모드에선 항상 false. */
+    hasQuickFix(issue: ValidationIssue): boolean;
+    /** 이슈의 quick-fix 적용(단일 command·undo 가능). 적용됐으면 true, 불가(없음·조회·잠금)면 false. */
+    applyQuickFix(issue: ValidationIssue): boolean;
     /**
      * CHK-DSN-3(모델링된 관계 없는 엔티티) 활성 토글 — 사용자가 검증 패널에서 켠다(기본 off).
      * 비형식 FK 오탐 가능성이 있어 옵트인. read-only에서도 토글 가능(표시 제어라 editable 무관).
@@ -76,6 +93,14 @@ export interface EditorController {
     dirty: Ref<boolean>;
     /** 모델 변경 신호 — 명령 적용마다 단조 증가. 외부 관찰자(감사 패널 등)가 재조회 트리거로 watch(디바운스 권장). */
     revision: Ref<number>;
+    /**
+     * 사용자에게 표시할 일시적 안내(차단된 동작 등) — 뷰가 구독해 토스트로 표시하고 자체 타이머로 dismiss.
+     * `id`는 같은 `text` 반복 시에도 재표시를 트리거하기 위한 단조 증가 값(동일 값 재대입은 watch 미발화이므로).
+     */
+    notice: Ref<{
+        text: string;
+        id: number;
+    } | null>;
     /**
      * 편집 가능 여부 — false(조회 모드)면 모든 모델 변경(추가·삭제·이동·편집·재정렬·연결·붙여넣기·
      * undo/redo·저장)이 차단된다. 선택·팬/줌·hover 강조·복사·export 같은 읽기성 동작은 유지.
@@ -272,6 +297,15 @@ export interface EditorController {
     predefinedCustomTypeCatalog: Ref<PredefinedCustomTypeCatalog>;
     /** 카탈로그 교체(호스트 props 갱신·dev 토글). reactive하므로 셀렉트가 즉시 반영된다. */
     setPredefinedCustomTypeCatalog(catalog: PredefinedCustomTypeCatalog): void;
+    /**
+     * 슈퍼클래스 카탈로그(호스트 주입) — `superClass`(예: BaseEntity) 상속 컬럼(감사필드)을 인덱스 대상
+     * picker/라벨에 파생 투영(projectInheritedColumns)하는 소스. embeddableCatalog와 동형 — dev는 프리셋,
+     * 완전 통합 시 호스트가 superClassCatalog API 값을 주입한다. 비어 있으면 상속 컬럼이 투영되지 않는다
+     * (인덱스는 로컬 컬럼만 참조 — 기능 게이트).
+     */
+    superClassCatalog: Ref<SuperClassCatalog>;
+    /** 카탈로그 교체(호스트 props 갱신·dev 토글). reactive하므로 인덱스 picker가 즉시 반영된다. */
+    setSuperClassCatalog(catalog: SuperClassCatalog): void;
     /**
      * 입력 가능 언어셋(호스트 주입) — 다국어 텍스트(설명·논리명·그룹명) 편집 UI가 노출할 언어 탭 목록·순서.
      * 비어 있으면 안 되며(입력 불가) 미주입 시 기본 4언어(ko/en/ja/zh). reactive하므로 .value 갱신 시 즉시 반영.
@@ -283,6 +317,16 @@ export interface EditorController {
      * languages[0]로 폴백. 미주입 시 'ko'. 라벨 우선 표시 등 확장 여지의 기준점.
      */
     userLanguage: Ref<LangCode>;
+    /**
+     * 툴 크롬(버튼·라벨·툴팁·검증 메시지) 언어(호스트 주입) — 콘텐츠 축 `userLanguage`와 **별개**.
+     * 미주입 시 'ko'(무회귀). reactive하므로 .value 갱신 시 UI 문자열이 즉시 재렌더.
+     */
+    uiLocale: Ref<UiLocale>;
+    /**
+     * UI 문자열 해석기 — `t('mode.edit')` 형태로 뷰가 소비. uiLocale.value를 읽으므로 템플릿에서
+     * 호출 시 로케일 변경에 반응한다. 파라미터는 `{name}` 형태로 치환.
+     */
+    t: Translator;
     /**
      * dataType 셀렉트 후보 셋(CHK-TYPE-1과 공유하는 단일 출처) — dataType 드롭다운(dbTypeSelectItems)이
      * 이 값을 후보로 쓴다. 검증 ctx.selectableDataTypes와 같은 ref라 어포던스(드롭다운)·검증이 어긋나지
@@ -350,13 +394,15 @@ export interface EditorController {
      */
     addEmbedAssociation(ownerEntityId: ModelId, embeddableEntityId: ModelId): ModelId | undefined;
     /**
-     * 임베드 단일(`@Embedded`)↔컬렉션(`@ElementCollection`) 모드 토글. 컬렉션 판정 권위는 임베더블
-     * end multiplicity(결정 3)이며, 이 intent가 multiplicity 변경 + 표시 속성 평탄화 컬럼 재구성 +
-     * collection 메타 set/clear를 **한 composite**로 묶어 모순 상태(컬렉션인데 평탄화 컬럼 잔존)를
-     * 구조적으로 차단한다. COLLECTION→SINGLE 복귀 시 owner 슬롯 `@AttributeOverride`는 버린다(결정 3,
-     * load-only 철학). assocId가 EMBED association이 아니거나 이미 해당 mode면 no-op.
+     * 임베드 카디널리티 설정 — 임베더블 end multiplicity를 지정 값으로 바꾼다. 컬렉션(`@ElementCollection`)
+     * 여부는 이 multiplicity에서 파생되는 값(권위=multiplicity, 결정 3): `*_MORE`(0..N / 1..N)면 컬렉션,
+     * 그 외(1·0..1)면 단일 `@Embedded`(0..1은 nullable). single↔collection **경계를 넘을 때만** 표시 속성
+     * 평탄화 컬럼 재구성 + collection 메타 set/clear를 **한 composite**로 묶어 모순 상태(컬렉션인데 평탄화
+     * 컬럼 잔존)를 구조적으로 차단한다. 단일 내부 전이(1↔0..1)는 평탄화 불변이라 순수 multiplicity patch다.
+     * 컬렉션→단일 복귀 시 owner 슬롯 `@AttributeOverride`는 버린다(결정 3, load-only 철학).
+     * assocId가 EMBED association이 아니거나 이미 해당 multiplicity면 no-op.
      */
-    setEmbedCollectionMode(assocId: ModelId, mode: 'SINGLE' | 'COLLECTION'): void;
+    setEmbedCardinality(assocId: ModelId, multiplicity: Multiplicity): void;
     removeAssociation(assocId: ModelId): void;
     /**
      * 식별 관계 토글 — 자식 FK의 identifier 플래그를 동기화하고, 식별자 집합 변동이
@@ -390,11 +436,34 @@ export interface EditorController {
     autoLayout(): void;
     /**
      * 복사/붙여넣기 클립보드. 엔티티 선택 → 엔티티 통째(새 modelId·offset),
-     * 속성 선택 → 선택 집합(붙여넣기는 현재 선택 엔티티/부모에 append, 동명 충돌 시 _copy).
+     * 속성 선택 → 선택 집합(붙여넣기는 현재 선택 엔티티/부모에 append, 동명 충돌 시 _copy),
+     * 명시 엔티티 집합(다중 선택·그룹 멤버 확장) → 서브그래프(유도 관계·그룹 포함, mergeDiagram 재사용).
      */
     clipboard: Ref<ClipboardContent | null>;
-    copy(): void;
-    paste(): void;
+    /**
+     * @param entityIds 서브그래프로 복사할 엔티티 id 집합(뷰가 다중 선택·그룹 멤버 확장으로 판단해 전달).
+     *   비어 있거나 미전달이면 현재 선택(단일 엔티티/속성 집합) 복사. 단일 엔티티 복사는 뷰가 무인자로 호출.
+     */
+    copy(entityIds?: ModelId[]): void;
+    /** @returns 붙여넣은 엔티티 modelId 목록(뷰가 캔버스 다중선택 반영에 사용). 속성 붙여넣기·무동작 시 빈 배열. */
+    paste(): ModelId[];
+    /**
+     * 타 다이어그램(비즈모듈)의 선택 서브그래프를 현재 다이어그램에 병합 임포트(G1).
+     * 깊은 복사(새 id) + 경계 강등 + 물리명 충돌 suffix는 순수 `mergeDiagram`이 수행하고,
+     * 여기서는 결과를 기존 다이어그램 우측 빈 영역에 배치해 단일 composite로 실행한다(재전파 없음 — D6).
+     */
+    importEntities(source: MergeDiagramSource, selectedIds: ModelId[], opts?: {
+        includeRelated?: boolean;
+        /** 이름/물리명 충돌 접미사(mergeDiagram 위임, 기본 `_imported`). 클립보드 붙여넣기는 `_copy`. */
+        collisionSuffix?: string;
+        /**
+         * 배치 전략. 기본 `'append-right'`(기존 다이어그램 우측 빈 영역 — G1 import).
+         * `{ offset }` 이면 서브그래프를 그 오프셋만큼 통째 시프트(클립보드 붙여넣기 — 원본 근처).
+         */
+        placement?: 'append-right' | {
+            offset: Point;
+        };
+    }): ModelId[];
 }
 export declare const EDITOR: InjectionKey<EditorController>;
 export declare function emptyState(modelId?: string, diagramId?: string): EditorState;
@@ -402,8 +471,11 @@ export declare function createEditorController(initial?: EditorState, options?:
     embeddableCatalog?: EmbeddableCatalog;
     groupCodeCatalog?: GroupCodeCatalog;
     predefinedCustomTypeCatalog?: PredefinedCustomTypeCatalog;
+    superClassCatalog?: SuperClassCatalog;
     languages?: LangCode[];
     userLanguage?: LangCode;
+    /** 툴 크롬 언어(콘텐츠 축 `userLanguage`와 별개). 미주입 시 'ko'(무회귀). */
+    uiLocale?: UiLocale;
     /** `fromPersisted` 산출 meta(트랙 B 마커 + revSeed). schemaVersion·opWriteEnabled로 opMode·read-only 판정. */
     meta?: DiagramMeta;
     /**
@@ -424,6 +496,12 @@ export declare function createEditorController(initial?: EditorState, options?:
      * 미주입이어도 어댑터가 콘솔에 남긴다(정상 rev/layout 충돌은 이 경로가 아님 — throw만).
      */
     onOpError?: (err: unknown) => void;
+    /**
+     * 사용자 안내 통지(차단된 동작 등) — 주입 시 호스트가 자신의 토스트/알림 시스템으로 표시하고,
+     * lib 내장 토스트는 표시하지 않는다(호스트에서 서버 에러 토스트 등과 UX 일원화). 미주입(dev
+     * 하니스·미배선 호스트)이면 lib이 `notice` ref로 자체 토스트를 표시한다. `onOpError`와 동형 seam.
+     */
+    onNotice?: (message: string) => void;
     /**
      * 검증 컨텍스트 — 카탈로그/정책 의존 규칙을 깨우는 호스트 주입(미주입 시 해당 규칙 skip).
      * selectableDataTypes(CHK-TYPE-1)는 코어 상수(SELECTABLE_DATA_TYPES)라 dev/호스트가 즉시 주입 가능.