@cardenelabs/dragon 0.28.0 → 0.30.0

package/src/json-parser.ts

@@ -6,7 +6,7 @@
  * で確実に生成できるよう、 flat な object array を優先した shape になっている。
  *
  * 使い方 (LLM):
- *   1. `packages/dragon/schemas/diagram.json` の JSON Schema を LLM の tool schema に注入
+ *   1. `packages/dragon/src/schemas/diagram.json` の JSON Schema を LLM の tool schema に注入
  *   2. LLM が JSON を返す
  *   3. `jsonToDiagram(json)` で CdlDiagram に変換
  *   4. validation error は throw、 retry loop で LLM に修正させる
@@ -34,6 +34,8 @@ import {
   部品の組の表,
   つまみの表,
   EVENT_KINDS,
+  EVENT_TARGET_KEYS,
+  EVENT_REQUIRED_KEYS,
   type 図形の定義,
 } from "./v05/parser";
 // 図の配色 (#1553)。 記法の読み手と同じ解決を通す = 別名 (`生成り` / `青磁`) の受け方が
@@ -71,7 +73,15 @@ import type {
   DslDynShape,
 } from "./types";
 import { checkValueExpression, isValueName, valueNameIssue } from "./value-syntax";
+import { 近い名前 } from "./near-name";
+import { 書いた場所の鍵, type 書いた行の表 } from "./json-line-map";
 import { compileToCdl } from "./compile";
+import {
+  RELATIVE_DIRECTIONS,
+  findRelativeProblems,
+  type RelativeDirection,
+  type RelativePos,
+} from "./relative-pos";
 
 /**
  * LLM 向け JSON DSL の入力 shape。 YAML DSL と 1:1 対応、 top-level は flat な object。
@@ -211,6 +221,24 @@ export interface DragonJson {
   palette?: DslPalette;
 }
 
+/**
+ * 位置を他の要素からの相対で書く指定の、JSON 側の形 (#2039)。
+ *
+ * 記法の `位置: Web の右 200` を 3 つの欄に開いたもの。 内側の値は `RelativePos` と同じで、
+ * 向きの語も同じ 4 つ (`right` / `left` / `above` / `below`) を使う。
+ *
+ * **向きの語を並べ直さない**。 `RelativeDirection` をそのまま使うことで、本文側に向きを
+ * 足した時に JSON 側が黙って取り残される形を作らない。
+ */
+export interface JsonRelativePos {
+  /** 基準にする相手の名前。 `actors:` に書かれた名前をそのまま書く */
+  anchor: string;
+  /** 基準からどちら側に置くか */
+  dir: RelativeDirection;
+  /** 相手との間隔。 書かなければ `RELATIVE_GAP_DEFAULT` */
+  gap?: number;
+}
+
 export interface JsonActor {
   name: string;
   /**
@@ -239,8 +267,9 @@ export interface JsonActor {
   renderOffsetX?: number | string;
   renderOffsetY?: number | string;
   /**
-   * CAR-1657 unified syntax = 既存 NodeKind (28 個) に加えて parts identifier (arc-gauge 等) を
-   * accept する。 未知 kind 値は parts 候補として partId に格納、 compile 側 partsCatalog で解決。
+   * CAR-1657 unified syntax = 既存 NodeKind (一覧は `v05/parser.ts` の `NODE_KIND_VALID`) に
+   * 加えて parts identifier (arc-gauge 等) を accept する。
+   * 未知 kind 値は parts 候補として partId に格納、 compile 側 partsCatalog で解決。
    * LLM structured output の typing 制約を緩めるため union に string 追加。
    * `string & {}` = NodeKind の候補を IDE 補完で提示しつつ任意 string も許容する idiom。
    * 素の `NodeKind | string` は no-redundant-type-constituents に抵触し補完も潰れる (#865)。
@@ -266,6 +295,17 @@ export interface JsonActor {
    * と同じで、読み方は `DslActor.layoutPos` が持つ。
    */
   pos?: LayoutPos;
+  /**
+   * 位置を他の要素からの相対で書く指定 (#2039)。 記法の `位置: Web の右 200` と同じ。
+   *
+   * 記法は 1 本の文字列に「誰の」「どちら側に」「どれだけ離して」 を詰めるが、JSON では
+   * 3 つの欄に分ける。 文字列を組み立てて渡す形にすると、書く側が記法の並び順と区切りを
+   * 覚える必要が出る = JSON を書くのは主に LLM で、読み取りの規則は欄の名前で示す方が短い。
+   *
+   * 組み立ての段階で基準の実座標から `posX` / `posY` に直すため、解決した後は座標を直接
+   * 書いた時と同じ経路を通る。 `pos` (配置後のずらし幅) とは別の欄。
+   */
+  posRel?: JsonRelativePos;
   /**
    * CAR-1657 parts state override (kind = parts identifier 時のみ有効)。
    * LLM JSON DSL では nested 明示 = `{ "state": { "v": 50 } }` が natural、 human 側の
@@ -325,6 +365,17 @@ export interface JsonActor {
    * 読めない項目名として知らせる)。
    */
   scale?: number;
+  /**
+   * 見本が持つ段を使うか (#2125)。 記法の `{ kind: wave-gauge, phase: false }` と同じ。
+   *
+   * 既定 (書かない) は見本の段を書いた段と番号ごとに並べて再生する。 `false` を書くと
+   * 見本の段の中身 (点灯と値の変化) を空にし、値は書いた段だけが動かす。
+   *
+   * 見本 (parts) にしか効かない。 中身は状態の上書き (`state`) に `phase` として入る =
+   * `"state": { "phase": false }` と同じ所へ届く。 記法が中括弧の中に 1 つの名前として
+   * 書ける以上、JSON でも同じ名前で書けるようにする (入口で書き方が分かれない)。
+   */
+  phase?: boolean;
   /** 行頭の印 (#1466)。 行と対で読む。 語の意味は図の種類が決める */
   marks?: string[];
 }
@@ -451,11 +502,13 @@ export interface JsonDslError {
  * 受け付ける種類 (`kind`)。 **記法側と同じ集合を使う** (`v05/parser.ts` の `NODE_KIND_VALID`)。
  *
  * ここに無い値は見本 (parts) の名前とみなし、`partId` へ退避して箱を `actor` に倒す
- * (CAR-1657 の unified syntax)。 つまりこの集合が小さいほど、**書いた種類が黙って消える**。
+ * (CAR-1657 の unified syntax)。 つまりこの集合が小さいほど、**書いた種類が箱の見た目に効かなくなる**。
+ * 部品を持つ一覧を渡した組み立てでは一覧に無い名前を知らせる (`part-not-found`、#2113) が、
+ * 一覧を渡さない組み立てと部品を持たない一覧の組み立てでは `console.warn` にしか残らない。
  *
  * 以前はここに一覧を写していたため、記法に種類が増えても JSON 経路が古い一覧のまま
  * 見本の名前として扱った (実測 = 記法が知る 108 種のうち 77 種が該当、`shape-*` は全滅)。
- * カタログに無い名前は `console.warn` にしか残らず `onNotice` を呼ばないため、
+ * 当時はカタログに無い名前が `console.warn` にしか残らず `onNotice` を呼ばなかったため、
  * 画面には何も出ないまま `actor` の箱が描かれていた (#1293)。
  *
  * 型が 2 箇所に散らばると、必ずどちらかが古くなる。 `VALID_PRESETS` (図種) と同じ扱いにする。
@@ -557,6 +610,10 @@ export const ACCEPTED_KEYS = {
     "renderOffsetY",
     // 行頭の印 (#1466)。 行ごとに 1 つ、図の種類ごとの語で書く
     "marks",
+    // 位置を他の要素からの相対で書く指定 (#2039)
+    "posRel",
+    // 見本が持つ段を使うか (#2125)
+    "phase",
   ],
   step: [
     "from",
@@ -602,6 +659,8 @@ export const ACCEPTED_KEYS = {
   axesX: ["left", "right"],
   axesY: ["bottom", "top"],
   layoutPos: ["x", "y"],
+  // 位置を他の要素からの相対で書く指定 (#2039)。 間隔は書かなくてよい
+  posRel: ["anchor", "dir", "gap"],
 } as const satisfies Record<string, readonly string[]>;
 
 /** 受ける項目を持つ階層の名前 */
@@ -643,6 +702,8 @@ export type 欄の型 =
   | "線種"
   | "辺"
   | "端の形"
+  // 相対で置く時の向き (#2039)。 書けば必ず要る = 向きが無いとどちら側か決まらない
+  | "必須の向き"
   | "色か色番号"
   | "描くもの"
   | "必須の図種"
@@ -724,6 +785,10 @@ export const 欄の型表 = {
     renderOffsetY: "数か文字列",
     // 行頭の印 (#1466)
     marks: "文字列の並び",
+    // 相対で置く指定 (#2039)。 中身の形は `validateRelativePos` が見る
+    posRel: "object",
+    // 見本が持つ段を使うか (#2125)
+    phase: "真偽",
   },
   step: {
     from: "必須の文字列",
@@ -795,6 +860,8 @@ export const 欄の型表 = {
   axesY: { bottom: "文字列", top: "文字列" },
   // 位置は書けば x と y の両方が要る。 片方だけでは寄せ幅が決まらない
   layoutPos: { x: "必須の数", y: "必須の数" },
+  // 相対で置く指定 (#2039)。 相手と向きは必ず要り、間隔は書かなければ既定で置く
+  posRel: { anchor: "必須の非空文字列", dir: "必須の向き", gap: "数" },
 } as const satisfies {
   [層 in 階層]: { [欄 in (typeof ACCEPTED_KEYS)[層][number]]: 欄の型 };
 };
@@ -839,6 +906,8 @@ function JSONの色名か(v: string): boolean {
 export const 見本にしか効かない欄 = [
   "state",
   "scale",
+  // 見本が持つ段を使うか (#2125)。 普通の箱は自分の段を持たないので効かない
+  "phase",
 ] as const satisfies readonly (typeof ACCEPTED_KEYS.actor)[number][];
 
 /**
@@ -997,6 +1066,17 @@ function 値を検査(
         });
       }
       return;
+    case "必須の向き":
+      // 受ける語は記法と同じ一覧を見る (`RELATIVE_DIRECTIONS`)。 写すと向きが増えた時に
+      // 片方だけ古くなる
+      if (typeof v !== "string" || !(RELATIVE_DIRECTIONS as readonly string[]).includes(v)) {
+        errors.push({
+          path,
+          message: `${名前} must be one of: ${RELATIVE_DIRECTIONS.join(", ")}`,
+          hint: typeof v === "string" ? `got "${v}"` : `got ${v === undefined ? "nothing" : typeof v}`,
+        });
+      }
+      return;
     case "端の形":
       if (v === undefined) return;
       // 受ける語は記法と同じ一覧を見る (`EDGE_HEAD_VALUES`)。 写すと描画側が形を増やした時に
@@ -1086,48 +1166,6 @@ function 表で検査(
   }
 }
 
-/**
- * 綴り違いの候補を返す (#1295)。
- *
- * 「知らない項目です」 だけだと、`animations` と書いた人は正しい綴りを探しに行く必要がある。
- * 1 文字の違い (足りない / 多い / 入れ替わり / 別の字) までを候補とする。
- *
- * 遠い名前は勧めない。 無関係な項目名を勧めると、書いた人がそちらへ直して二度手間になる。
- */
-function 近い項目名(key: string, 候補: readonly string[]): string | undefined {
-  const 小文字 = key.toLowerCase();
-  let 最短: { 名: string; 距離: number } | undefined;
-  for (const c of 候補) {
-    const d = 編集距離(小文字, c.toLowerCase(), 2);
-    if (d <= 2 && (最短 === undefined || d < 最短.距離)) 最短 = { 名: c, 距離: d };
-  }
-  return 最短?.名;
-}
-
-/**
- * 2 つの語の編集距離 (上限付き)。
- *
- * 上限を持つのは、長い語どうしで表を全部埋めないため。 上限を超えた時点で打ち切る。
- */
-function 編集距離(a: string, b: string, 上限: number): number {
-  if (Math.abs(a.length - b.length) > 上限) return 上限 + 1;
-  let 前 = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i += 1) {
-    const 今: number[] = [i];
-    let 行の最小 = i;
-    for (let j = 1; j <= b.length; j += 1) {
-      const 費用 = a[i - 1] === b[j - 1] ? 0 : 1;
-      const v = Math.min(今[j - 1]! + 1, 前[j]! + 1, 前[j - 1]! + 費用);
-      今.push(v);
-      if (v < 行の最小) 行の最小 = v;
-    }
-    // その行の最小が上限を超えたら、以降どう進んでも上限以下にはならない
-    if (行の最小 > 上限) return 上限 + 1;
-    前 = 今;
-  }
-  return 前[b.length]!;
-}
-
 /**
  * 知らない項目を誤りとして積む (#1295)。
  *
@@ -1139,7 +1177,7 @@ function checkUnknownKeys(v: unknown, 層: 階層, path: string, errors: JsonDsl
   const 受ける = ACCEPTED_KEYS[層] as readonly string[];
   for (const key of Object.keys(v)) {
     if (受ける.includes(key)) continue;
-    const 候補 = 近い項目名(key, 受ける);
+    const 候補 = 近い名前(key, 受ける);
     errors.push({
       path: `${path}.${key}`,
       message: `unknown key "${key}"`,
@@ -1148,10 +1186,6 @@ function checkUnknownKeys(v: unknown, 層: 階層, path: string, errors: JsonDsl
   }
 }
 
-/**
- * shape validation。 layer 1 = 必須 field + 型 check、 layer 2 は compile 側の validation に委譲。
- * fail-fast ではなく全 error 収集して返す (LLM に一括で修正させるため)。
- */
 /**
  * CAR-1693 Phase 1: DSL 表面 `pos: {x, y}` の型 check helper。 finite number pair を必須にし、
  * `NaN` / `Infinity` / non-number は reject する (組み立ての出口 `applyLayoutOffsets` が配置後の位置に足すため)。
@@ -1167,6 +1201,77 @@ function validateLayoutPos(v: unknown, path: string, errors: JsonDslError[]): vo
   表で検査(p, "layoutPos", path, "pos", errors);
 }
 
+/**
+ * 相対で置く指定の形を見る (#2039)。
+ *
+ * 相手の名前が実在するかはここでは見ない。 組み立て側 (`resolveRelativeDoc`) が figure 全体を
+ * 組んだ後に照合し、いない相手を指した時は知らせを出す。 入口ごとに別の場所で判定すると、
+ * 本文で書いた時と JSON で書いた時で返るものが変わる。
+ */
+function validateRelativePos(v: unknown, path: string, errors: JsonDslError[]): void {
+  if (v === undefined) return;
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    errors.push({ path, message: "posRel must be an object with anchor and dir" });
+    return;
+  }
+  const p = v as Record<string, unknown>;
+  checkUnknownKeys(p, "posRel", path, errors);
+  表で検査(p, "posRel", path, "posRel", errors);
+}
+
+/**
+ * 図全体として相対の指定が解けるかを見る (#2039)。
+ *
+ * 判定は `relative-pos.ts` の `findRelativeProblems` が持つ。 記法側も同じ判定を呼ぶので、
+ * 同じ書き方が入口によって通ったり通らなかったりしない。
+ *
+ * 誤りの文だけをここで作る = 記法側は行番号を、こちらは欄の場所を添えるため。
+ */
+function validateRelativeAnchors(actors: readonly unknown[], errors: JsonDslError[]): void {
+  const items: Array<{ name: string; rel?: RelativePos }> = [];
+  const 場所 = new Map<string, number>();
+  actors.forEach((a, i) => {
+    if (!a || typeof a !== "object" || Array.isArray(a)) return;
+    const o = a as Record<string, unknown>;
+    if (typeof o.name !== "string") return;
+    const rel = o.posRel;
+    // 形の誤りは `validateRelativePos` が既に返している。 ここは形の整った指定だけを見る
+    const 整った =
+      rel !== null &&
+      typeof rel === "object" &&
+      !Array.isArray(rel) &&
+      typeof (rel as Record<string, unknown>).anchor === "string" &&
+      typeof (rel as Record<string, unknown>).dir === "string";
+    items.push({ name: o.name, rel: 整った ? (rel as RelativePos) : undefined });
+    if (!場所.has(o.name)) 場所.set(o.name, i);
+  });
+
+  const named = items.map((i) => i.name);
+  for (const p of findRelativeProblems(items)) {
+    const i = 場所.get(p.name) ?? 0;
+    errors.push({
+      path: `$.actors[${i}].posRel`,
+      ...(p.kind === "self"
+        ? {
+            message: `posRel.anchor must not be the actor itself: "${p.name}"`,
+            hint: "別の登場人物の名前を書く",
+          }
+        : p.kind === "missing-anchor"
+          ? {
+              message: `posRel.anchor must name an actor: "${p.anchor ?? ""}"`,
+              hint:
+                named.length > 0
+                  ? `actors に書かれている名前 = ${named.join(", ")}`
+                  : "actors に基準にする登場人物を書く",
+            }
+          : {
+              message: `posRel.anchor must not form a cycle: "${p.name}"`,
+              hint: "どれか 1 つは posX / posY か自動配置にする",
+            }),
+    });
+  }
+}
+
 /**
  * 見本 (parts) の名前として扱う値かどうか (#1294)。
  *
@@ -1196,22 +1301,13 @@ function validateViewport(v: unknown, errors: JsonDslError[]): void {
 }
 
 /**
- * 鍵を利用者が決める入れ物 (縦列 / 群) を見る (#1304)。
- *
- * `lanes` / `groups` は id を鍵に持つため、鍵そのものは縛れない。 縛れるのは
- * 「入れ物が plain object か」 と「各 id の中身の項目名と値の型」 の 2 つ。
- *
- * #1304 まで外側の形が違う入力 (`lanes: 5`) は走査ごと飛ばされ、誤りが 1 件も返らなかった。
- * 形が違うものを黙って捨てると、書いた縦列が 1 つも効かない図が知らせなしで出る。
- */
-/**
- * 図形と部品の中身を、記法と **同じ表** で検査する (#1374)。
+ * 選択肢の組が受ける項目。 どれも必ず書く (#2258)。
  *
- * 表を 2 つ持つと片方だけ直してずれる。 記法側 (`v05/parser.ts`) が持つ表をそのまま引く。
- *
- * 記法は値が全て文字列で届くため読み替えが要るが、JSON は型のまま届く。 ここでは
- * 「知らない種類」 「知らない欄」 「足りない必須の欄」 「欄の型違い」 の 4 つを見る。
+ * **判定と知らせが同じ集合を読む**。 別々に並べていた間、判定に項目を足しても
+ * 知らせは古い一覧を教え続ける形だった。
  */
+const 選択肢の項目 = ["value", "label"] as const;
+
 /**
  * 選択肢の並び (`["green", { "value": "red", "label": "失敗" }]`) を要素ごとに検査する (#1920)。
  *
@@ -1240,13 +1336,21 @@ function 選択肢の並びを検査する(値: unknown, path: string, errors: J
     }
     const 組 = x as Record<string, unknown>;
     for (const k of Object.keys(組)) {
-      if (k === "value" || k === "label") continue;
-      errors.push({ path: `${here}.${k}`, message: `unknown key "${k}"`, hint: "使える項目 = value, label" });
+      if ((選択肢の項目 as readonly string[]).includes(k)) continue;
+      errors.push({
+        path: `${here}.${k}`,
+        message: `unknown key "${k}"`,
+        hint: `使える項目 = ${選択肢の項目.join(", ")}`,
+      });
     }
-    for (const k of ["value", "label"] as const) {
+    for (const k of 選択肢の項目) {
       const v = 組[k];
       if (v === undefined) {
-        errors.push({ path: `${here}.${k}`, message: `${k} is required`, hint: "必須の項目 = value, label" });
+        errors.push({
+          path: `${here}.${k}`,
+          message: `${k} is required`,
+          hint: `必須の項目 = ${選択肢の項目.join(", ")}`,
+        });
       } else if (typeof v !== "string") {
         errors.push({ path: `${here}.${k}`, message: `${k} must be 文字列`, hint: `got ${v === null ? "null" : typeof v}` });
       } else if (v === "") {
@@ -1260,6 +1364,14 @@ function 選択肢の並びを検査する(値: unknown, path: string, errors: J
   });
 }
 
+/**
+ * 図形と部品の中身を、記法と **同じ表** で検査する (#1374)。
+ *
+ * 表を 2 つ持つと片方だけ直してずれる。 記法側 (`v05/parser.ts`) が持つ表をそのまま引く。
+ *
+ * 記法は値が全て文字列で届くため読み替えが要るが、JSON は型のまま届く。 ここでは
+ * 「知らない種類」 「知らない欄」 「足りない必須の欄」 「欄の型違い」 の 4 つを見る。
+ */
 function 表で中身を検査する(
   o: Record<string, unknown>,
   表: Record<string, 図形の定義>,
@@ -1344,18 +1456,30 @@ function 表で中身を検査する(
   }
 }
 
+/** 帯に書く相手の項目。 値が文字列で、他の 2 つと型が違う */
+const 帯の相手の項目 = ["actor"] as const;
+/** 帯に書く段の項目。 値が 0 以上の整数 */
+const 帯の段の項目 = ["from", "to"] as const;
 /**
- * 値を見せる部品の並びを検査する (#1374)。
+ * 帯が受ける項目。 判定と知らせの両方がここから作る (#2258)。
  *
- * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
- * 委ねる作りなので (`checkFieldType` の `case "並び"`)、ここで見ないと `readouts: 1` が
- * 素通りする。
+ * 公開 schema の `$.bands` も同じ 3 語を閉じた集合として宣言しており、
+ * `closed-level-coverage.test.ts` が両者の一致を見る。
  */
+export const 帯の項目: readonly string[] = [...帯の相手の項目, ...帯の段の項目];
+
 /**
  * 順序図の帯の並びを検査する (#1466)。
  *
  * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
  * 委ねる作りなので、ここで見ないと `bands: 1` が素通りする。
+ *
+ * ## 知らない項目も見る (#2262)
+ *
+ * 書いてある 3 つの型だけを見て、**知らない項目があるかを確かめていなかった**。
+ * 公開 schema は `$.bands` を閉じた階層として宣言しているので、
+ * schema を信じて書いた入力がこちらでは通り、schema 検証器では落ちる状態だった。
+ * 公開 schema が閉じた階層のうち、素通りしていたのはここだけだった。
  */
 function validateBands(v: unknown, errors: JsonDslError[]): void {
   if (v === undefined) return;
@@ -1374,10 +1498,20 @@ function validateBands(v: unknown, errors: JsonDslError[]): void {
       return;
     }
     const o = b as Record<string, unknown>;
-    if (typeof o.actor !== "string" || o.actor === "") {
-      errors.push({ path: `${path}.actor`, message: "band.actor must be a non-empty string" });
+    for (const k of Object.keys(o)) {
+      if (帯の項目.includes(k)) continue;
+      errors.push({
+        path: `${path}.${k}`,
+        message: `unknown key "${k}"`,
+        hint: `使える項目 = ${帯の項目.join(", ")}`,
+      });
+    }
+    for (const k of 帯の相手の項目) {
+      if (typeof o[k] !== "string" || o[k] === "") {
+        errors.push({ path: `${path}.${k}`, message: `band.${k} must be a non-empty string` });
+      }
     }
-    for (const k of ["from", "to"] as const) {
+    for (const k of 帯の段の項目) {
       if (typeof o[k] !== "number" || !Number.isInteger(o[k]) || o[k] < 0) {
         errors.push({ path: `${path}.${k}`, message: `band.${k} must be a non-negative integer` });
       }
@@ -1385,6 +1519,13 @@ function validateBands(v: unknown, errors: JsonDslError[]): void {
   });
 }
 
+/**
+ * 値を見せる部品の並びを検査する (#1374)。
+ *
+ * **外側の形もここで見る**。 `欄の型表` は「並び」 とだけ宣言し、中身の検査は専用の検査に
+ * 委ねる作りなので (`checkFieldType` の `case "並び"`)、ここで見ないと `readouts: 1` が
+ * 素通りする。
+ */
 function validateReadouts(v: unknown, errors: JsonDslError[]): void {
   if (v === undefined) return;
   if (!Array.isArray(v)) {
@@ -1578,6 +1719,11 @@ function validateFormulas(v: unknown, inputs: unknown, errors: JsonDslError[]):
  */
 type 式の検査結果 = { readonly 読めた: true; readonly 値: unknown } | { readonly 読めた: false };
 
+/**
+ * 式の組が受ける項目 (#2258)。 判定と知らせが同じ集合を読む。
+ */
+const 式の組の項目 = ["expression", "label"] as const;
+
 /**
  * 式の値が組の形 (`{ expression, label }`) なら組を検査し、式の文字列を返す (#1916)。
  *
@@ -1589,12 +1735,12 @@ function 式の組を検査する(値: unknown, path: string, errors: JsonDslErr
   const 組 = 値 as Record<string, unknown>;
   let 読めた = true;
   for (const 鍵 of Object.keys(組)) {
-    if (鍵 === "expression" || 鍵 === "label") continue;
+    if ((式の組の項目 as readonly string[]).includes(鍵)) continue;
     読めた = false;
     errors.push({
       path: `${path}.${鍵}`,
       message: `unknown formula field: ${鍵}`,
-      hint: "使える項目 = expression, label",
+      hint: `使える項目 = ${式の組の項目.join(", ")}`,
     });
   }
   if (typeof 組.expression !== "string" || 組.expression.trim() === "") {
@@ -1632,7 +1778,11 @@ function validateEvents(v: unknown, errors: JsonDslError[]): void {
     });
     return;
   }
-  const 相手の鍵 = ["box", "lane", "arrow", "diagram"];
+  // 相手の指し方は記法の側が 1 か所で決める (#2256)。 同じ 4 語をここにも並べていた間、
+  // 1:1 を名乗りながら受ける項目が両側で別々に決まっていた。
+  // 必ず書く 2 つも同じ定数から取る (#2258) = 知らせが判定と別に並べる形をやめる
+  const 相手の鍵: readonly string[] = EVENT_TARGET_KEYS;
+  const 出来事の項目: readonly string[] = [...EVENT_REQUIRED_KEYS, ...EVENT_TARGET_KEYS];
   v.forEach((e, i) => {
     const path = `$.events[${i}]`;
     if (!e || typeof e !== "object" || Array.isArray(e)) {
@@ -1641,11 +1791,11 @@ function validateEvents(v: unknown, errors: JsonDslError[]): void {
     }
     const o = e as Record<string, unknown>;
     for (const k of Object.keys(o)) {
-      if (k === "on" || k === "handler" || 相手の鍵.includes(k)) continue;
+      if (出来事の項目.includes(k)) continue;
       errors.push({
         path: `${path}.${k}`,
         message: `unknown key "${k}"`,
-        hint: `使える項目 = on, handler, ${相手の鍵.join(", ")}`,
+        hint: `使える項目 = ${出来事の項目.join(", ")}`,
       });
     }
     if (typeof o.on !== "string" || !(EVENT_KINDS as readonly string[]).includes(o.on)) {
@@ -1700,6 +1850,16 @@ function validateEvents(v: unknown, errors: JsonDslError[]): void {
   });
 }
 
+/**
+ * 巻き上げに応じて進む値が受ける項目 (#2258)。
+ *
+ * **数を書く項目と文字を書く項目を分けて持つ** = 受け方が違うので判定が分かれるが、
+ * 知らせは 2 つを繋いで 1 つの一覧として出す。 別々に並べていた間、判定が 3 語で
+ * 知らせが 4 語という食い違いが同じ関数の中にあった。
+ */
+const 送りの数の項目 = ["start", "end", "scrub"] as const;
+const 送りの文の項目 = ["label"] as const;
+
 /**
  * 巻き上げに応じて進む値を検査する (#1393)。
  *
@@ -1749,17 +1909,17 @@ function validateScrolls(
       continue;
     }
     for (const [k, x] of Object.entries(spec as Record<string, unknown>)) {
-      if (k === "label") {
+      if ((送りの文の項目 as readonly string[]).includes(k)) {
         if (typeof x !== "string") {
-          errors.push({ path: `${path}.label`, message: "label must be a string" });
+          errors.push({ path: `${path}.${k}`, message: `${k} must be a string` });
         }
         continue;
       }
-      if (k !== "start" && k !== "end" && k !== "scrub") {
+      if (!(送りの数の項目 as readonly string[]).includes(k)) {
         errors.push({
           path: `${path}.${k}`,
           message: `unknown key "${k}"`,
-          hint: "使える項目 = start, end, scrub, label",
+          hint: `使える項目 = ${[...送りの数の項目, ...送りの文の項目].join(", ")}`,
         });
         continue;
       }
@@ -1794,6 +1954,15 @@ function validateActorShape(v: unknown, path: string, errors: JsonDslError[]): v
   表で中身を検査する(v as Record<string, unknown>, 図形の表, path, "shape", errors);
 }
 
+/**
+ * 鍵を利用者が決める入れ物 (縦列 / 群) を見る (#1304)。
+ *
+ * `lanes` / `groups` は id を鍵に持つため、鍵そのものは縛れない。 縛れるのは
+ * 「入れ物が plain object か」 と「各 id の中身の項目名と値の型」 の 2 つ。
+ *
+ * #1304 まで外側の形が違う入力 (`lanes: 5`) は走査ごと飛ばされ、誤りが 1 件も返らなかった。
+ * 形が違うものを黙って捨てると、書いた縦列が 1 つも効かない図が知らせなしで出る。
+ */
 function validateIdMap(
   v: unknown,
   欄: "lanes" | "groups",
@@ -2075,6 +2244,10 @@ export function 素のデータに写す(
   }
 }
 
+/**
+ * shape validation。 layer 1 = 必須 field + 型 check、 layer 2 は compile 側の validation に委譲。
+ * fail-fast ではなく全 error 収集して返す (LLM に一括で修正させるため)。
+ */
 function validateJson(
   json: unknown,
 ): { ok: true; data: DragonJson } | { ok: false; errors: JsonDslError[] } {
@@ -2150,6 +2323,7 @@ function validateJson(
       const 代わりに使う欄: Record<(typeof 見本にしか効かない欄)[number], string> = {
         state: "箱の見た目を変えるなら tone / color を使う",
         scale: "大きさを変えるなら posW / posH を使う",
+        phase: "普通の箱は自分の段を持たない。 動かす段は animation に書く",
       };
       if (!見本か) {
         for (const 欄 of 見本にしか効かない欄) {
@@ -2173,8 +2347,8 @@ function validateJson(
           });
         }
       }
-      // codex-review MAJOR fix = state override は plain object + 値は primitive (number / string / boolean) 限定、
-      // `{ v: {} }` 等 nested object や null が流入すると CdlState.initial に不正な型が入り compile 崩れる。
+      // 値の上書き (`state`) は素の object に限り、中の値も数 / 文字 / 真偽のいずれかに限る。
+      // `{ v: {} }` のような入れ子や null を通すと、値の初期値に扱えない型が入って組み立てが崩れる。
       if (ao.state !== undefined) {
         if (!ao.state || typeof ao.state !== "object" || Array.isArray(ao.state)) {
           errors.push({
@@ -2195,7 +2369,11 @@ function validateJson(
       }
       // CAR-1693 Phase 1: actor DSL 表面 pos の validation
       validateLayoutPos(ao.pos, `$.actors[${i}].pos`, errors);
+      // 相対で置く指定 (#2039)
+      validateRelativePos(ao.posRel, `$.actors[${i}].posRel`, errors);
     });
+    // 解けない相対の指定 (#2039)。 欄ごとの形を見た後に、図全体として解けるかを見る
+    validateRelativeAnchors(j.actors, errors);
   }
   if (!Array.isArray(j.flow)) {
     errors.push({ path: "$.flow", message: "flow must be an array" });
@@ -2375,12 +2553,6 @@ function validateValues(v: unknown, errors: JsonDslError[]): void {
   }
 }
 
-/**
- * JSON DSL → DslDocument (AST) 変換。 pos は JSON なので line 情報なし、 全て line 0。
- *
- * CAR-1693 Phase 1: DSL 表面 `pos: {x, y}` → 内部 AST `layoutPos:` の 2 層 mapping の実装 core。
- * test で mapping logic を実 execute するため export する (pos-field.test.ts の regression guard)。
- */
 /**
  * 図表の箱の上の小見出しを、 記法側と同じ形に整える (#1247)。
  *
@@ -2393,11 +2565,40 @@ function 整えた小見出し(v: string | undefined): string | undefined {
   return t.length > 0 ? t : undefined;
 }
 
-export function jsonToDoc(json: DragonJson): DslDocument {
-  const p0 = { line: 0 };
-  const actors: DslActor[] = json.actors.map((a) => {
+/**
+ * 見本の状態の上書きに、段を使うかどうか (`phase`) を混ぜる (#2125)。
+ *
+ * 組み立て側は段を外す指定を状態の上書きの中の `phase` として読む
+ * (`compile/parts.ts` の `段を外す`)。 記法は中括弧に書いた名前をすべて上書きへ入れるため
+ * `{ kind: wave-gauge, phase: false }` がそのまま届くが、JSON は欄ごとに型を宣言する形なので、
+ * 欄として受けたものを同じ場所へ入れ直す。
+ *
+ * **書かなかった時は欄を作らない**。 `{ phase: undefined }` を混ぜると、上書きの有無で
+ * 分岐する側から見て「書いた」 ことになる。
+ */
+function 段を含めた上書き(a: JsonActor): Record<string, number | string | boolean> | undefined {
+  if (a.phase === undefined) return a.state;
+  return { ...(a.state ?? {}), phase: a.phase };
+}
+
+/**
+ * JSON DSL → DslDocument (AST) 変換。
+ *
+ * 行番号は `行の表` を渡した時だけ入る (#2117)。 JSON そのものは書いた場所を持たないため、
+ * 本文の行が分かる入口 (編集画面の YAML 欄) が場所ごとの行を集めて渡す。 渡さない呼出は
+ * 全ての要素が 0 行になる = 「行が分からない」 ことを 0 で表す。
+ *
+ * CAR-1693 Phase 1: DSL 表面 `pos: {x, y}` → 内部 AST `layoutPos:` の 2 層 mapping の実装 core。
+ * test で mapping logic を実 execute するため export する (pos-field.test.ts の regression guard)。
+ */
+export function jsonToDoc(json: DragonJson, 行の表?: 書いた行の表): DslDocument {
+  // 書いた場所から行を引く。 引けない場所は 0 行 = 表を渡さない呼出と同じ状態になる
+  const 位置 = (...道: readonly (string | number)[]): { line: number } => ({
+    line: 行の表?.get(書いた場所の鍵(...道)) ?? 0,
+  });
+  const actors: DslActor[] = json.actors.map((a, i) => {
     if (typeof a === "string") {
-      return { name: a, kind: "actor" as NodeKind, kindWritten: false, pos: p0 };
+      return { name: a, kind: "actor" as NodeKind, kindWritten: false, pos: 位置("actors", i) };
     }
     // CAR-1657 = kind が既存 NodeKind に無い値なら parts identifier 候補、 partId に格納
     const kindStr = a.kind ?? "actor";
@@ -2457,10 +2658,12 @@ export function jsonToDoc(json: DragonJson): DslDocument {
       scale: isPart ? a.scale : undefined,
       scaleKeys: isPart && a.scale !== undefined ? ["scale"] : undefined,
       partId: isPart ? kindStr : undefined,
-      stateOverride: isPart ? a.state : undefined,
+      stateOverride: isPart ? 段を含めた上書き(a) : undefined,
       // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos の 2 層 mapping (naming collision 回避)
       layoutPos: a.pos,
-      pos: p0,
+      // 相対で置く指定 (#2039)。 欄の名前が内部と同じなのでそのまま渡す
+      posRel: a.posRel,
+      pos: 位置("actors", i),
     };
   });
   // 図の配色 (#1553)。 解くのは 1 度だけにする
@@ -2504,7 +2707,7 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     ...(s.toPartNode !== undefined ? { toPartNode: s.toPartNode } : {}),
     // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos
     layoutPos: s.pos,
-    pos: p0,
+    pos: 位置("flow", i),
   }));
   // 状態は段が無くても図に載る (#1162 で組み立ての出口が載せる)。 **段の有無で分けない** =
   // 分けると `states` だけを書いた JSON で値が 1 つも届かない (記法側で起きていた形、 #1181)
@@ -2517,7 +2720,7 @@ export function jsonToDoc(json: DragonJson): DslDocument {
    *
    * 相手は名前のまま持ち、識別子への読み替えは組み立てが行う = 2 つの入口で同じ経路を通る。
    */
-  const events: DslEventBinding[] | undefined = json.events?.map((e) => ({
+  const events: DslEventBinding[] | undefined = json.events?.map((e, i) => ({
     event: e.on as DslEventBinding["event"],
     target:
       e.diagram === true
@@ -2532,7 +2735,7 @@ export function jsonToDoc(json: DragonJson): DslDocument {
             ? ({ kind: "lane" as const, name: e.lane } as const)
             : ({ kind: "node" as const, name: e.box ?? "" } as const),
     handlerId: e.handler.trim(),
-    pos: p0,
+    pos: 位置("events", i),
   }));
   const scrolls: DslScrollTrigger[] | undefined = json.scrolls
     ? Object.entries(json.scrolls).map(([id, spec]) => ({ id, ...spec }))
@@ -2542,28 +2745,28 @@ export function jsonToDoc(json: DragonJson): DslDocument {
   const formulas: DslFormula[] | undefined = json.formulas
     ? Object.entries(json.formulas).map(([id, 値]) =>
         typeof 値 === "string"
-          ? { id, expression: 値, pos: p0 }
+          ? { id, expression: 値, pos: 位置("formulas", id) }
           : {
               id,
               expression: 値.expression,
               ...(値.label !== undefined ? { label: 値.label } : {}),
-              pos: p0,
+              pos: 位置("formulas", id),
             },
       )
     : undefined;
   const states: DslState[] = Object.entries(json.states ?? {}).map(([name, initial]) => ({
     name,
     initial,
-    pos: p0,
+    pos: 位置("states", name),
   }));
-  const phases: DslPhase[] = (json.animation ?? []).map((p) => ({
+  const phases: DslPhase[] = (json.animation ?? []).map((p, i) => ({
     name: p.step,
     durationMs: Math.round((p.duration ?? 1.4) * 1000),
     highlight: p.focus,
     body: p.body,
     badge: p.badge,
     // 書いた段だけが欄を持つ。 空文字を置くと「書いた」 と「書いていない」 が同じ形になる
-    ...(p.draw !== undefined ? { draw: p.draw, drawPos: p0 } : {}),
+    ...(p.draw !== undefined ? { draw: p.draw, drawPos: 位置("animation", i, "draw") } : {}),
     // 割合は `draw` がある段にだけ写す。 単独で書いても描く相手が決まらず何も起きないので、
     // 記法側 (同じ行に書かせる形) と同じ状態に揃える
     ...(p.draw !== undefined && p.drawRatio !== undefined ? { drawRatio: p.drawRatio } : {}),
@@ -2575,17 +2778,27 @@ export function jsonToDoc(json: DragonJson): DslDocument {
             state,
             from,
             to,
-            pos: p0,
+            pos: 位置("animation", i, "tween", state),
           })),
         }
       : {}),
     ...(p.set && Object.keys(p.set).length > 0
-      ? { sets: Object.entries(p.set).map(([state, value]) => ({ state, value, pos: p0 })) }
+      ? {
+          sets: Object.entries(p.set).map(([state, value]) => ({
+            state,
+            value,
+            pos: 位置("animation", i, "set", state),
+          })),
+        }
       : {}),
-    pos: p0,
+    pos: 位置("animation", i),
   }));
   const animate: DslAnimate | undefined =
-    states.length > 0 || phases.length > 0 ? { states, phases, pos: p0 } : undefined;
+    states.length > 0 || phases.length > 0
+      ? // 動きの塊そのものには書いた場所が無い。 段がある文書は `animation`、無い文書は
+        // `states` を指す = どちらも「動きを書き始めた場所」 になる
+        { states, phases, pos: phases.length > 0 ? 位置("animation") : 位置("states") }
+      : undefined;
   return {
     title: json.title,
     type: json.type,
@@ -2593,12 +2806,12 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     // 空かどうかを判定するため、 揃えないと **空白だけの値で入口ごとに図が変わる**
     // (記法は書かなかった扱い、 JSON は中身のない帯を描く。 Round 2 の指摘で実測)
     ...(整えた小見出し(json.eyebrow) !== undefined
-      ? { eyebrow: 整えた小見出し(json.eyebrow), eyebrowPos: p0 }
+      ? { eyebrow: 整えた小見出し(json.eyebrow), eyebrowPos: 位置("eyebrow") }
       : {}),
     // 2 軸で仕分ける図の軸の名前 (#1294)。 中身の無い形は「書かなかった」 と同じにする =
     // 空の軸を渡すと、書いていない側の名前が空文字で描かれる (記法側と同じ扱い)
     ...(json.axes && (json.axes.x !== undefined || json.axes.y !== undefined)
-      ? { axes: json.axes, axesPos: p0 }
+      ? { axes: json.axes, axesPos: 位置("axes") }
       : {}),
     actors,
     flow,
@@ -2606,16 +2819,20 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     // 他の値から決まる値 (#1181)。 書いた順に並べる = 解く順は参照から決まるので順序に
     // 意味は無いが、知らせの並びが書いた順になる
     values: json.values
-      ? Object.entries(json.values).map(([name, expression]) => ({ name, expression, pos: p0 }))
+      ? Object.entries(json.values).map(([name, expression]) => ({
+          name,
+          expression,
+          pos: 位置("values", name),
+        }))
       : undefined,
-    viewport: json.viewport ? { ...json.viewport, pos: p0 } : undefined,
+    viewport: json.viewport ? { ...json.viewport, pos: 位置("viewport") } : undefined,
     lanes: json.lanes
       ? Object.fromEntries(
           Object.entries(json.lanes).map(([id, l]) => {
             // CAR-1693 Phase 1: DSL 表面 pos → 内部 AST layoutPos の 2 層 mapping。
             // JSON input の { pos, x, width, ... } を分離し、 pos のみ layoutPos に rename する。
             const { pos: layoutPos, ...laneRest } = l;
-            return [id, { id, ...laneRest, layoutPos, pos: p0 }];
+            return [id, { id, ...laneRest, layoutPos, pos: 位置("lanes", id) }];
           }),
         )
       : undefined,
@@ -2623,7 +2840,7 @@ export function jsonToDoc(json: DragonJson): DslDocument {
       ? Object.fromEntries(
           Object.entries(json.groups).map(([id, g]) => [
             id,
-            { id, label: g.label, lanes: g.lanes, pos: p0 },
+            { id, label: g.label, lanes: g.lanes, pos: 位置("groups", id) },
           ]),
         )
       : undefined,
@@ -2638,12 +2855,18 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     reveal: json.reveal,
     // 箱に触れると関係する線だけを光らせるか (#1757)
     relations: json.relations,
-    // 図の並ぶ向き (#1494)。 JSON は英語で書くので、記法と同じ語に直してから渡す
-    ...(json.direction !== undefined ? { direction: json.direction === "horizontal" ? ("横" as const) : ("縦" as const) } : {}),
+    // 図の並ぶ向き (#1494)。 JSON は英語で書くので、記法と同じ語に直してから渡す。
+    // 書いた行も記法と同じく持つ = 持たないと、向きの知らせが文書の行 (1 行目) を指す
+    ...(json.direction !== undefined
+      ? {
+          direction: json.direction === "horizontal" ? ("横" as const) : ("縦" as const),
+          directionPos: 位置("direction"),
+        }
+      : {}),
     // 図の配色 (#1553)。 記法と同じ解決を通す = 別名 (`生成り` / `青磁`) の受け方がずれない。
     // 読めない語は渡さない = 上流の型検査が語を絞っているので、ここに来るのは書き間違いだけ
     ...(配色 !== null ? { palette: 配色 } : {}),
-    pos: p0,
+    pos: 位置(),
   };
 }
 
@@ -2673,7 +2896,17 @@ export function jsonToDiagram(
   // **`onNotice` も通す**。 記法経路だけに通知を付けていたため、 同じ型を受ける JSON / YAML
   // 経路では読めない値や捨てた矢印が利用者へ届かなかった (review 指摘)。 エディタの YAML タブは
   // ここを通る
-  opts?: { partsCatalog?: Record<string, CdlDiagram>; onNotice?: CompileToCdlOpts["onNotice"] },
+  opts?: {
+    partsCatalog?: Record<string, CdlDiagram>;
+    onNotice?: CompileToCdlOpts["onNotice"];
+    /**
+     * 本文の場所から書いた行を引く表 (#2117)。 渡すと知らせが書いた行を指す。
+     *
+     * JSON そのものは書いた場所を持たないため、本文の行が分かる入口 (編集画面の YAML 欄) が
+     * 集めて渡す。 渡さない呼出は今までどおり全ての知らせが 0 行になる。
+     */
+    行の表?: 書いた行の表;
+  },
 ): CdlDiagram {
   const v = validateJson(json);
   if (!v.ok) {
@@ -2682,7 +2915,7 @@ export function jsonToDiagram(
       .join("\n");
     throw new Error(`Dragon JSON DSL validation error:\n${msg}`);
   }
-  const doc = jsonToDoc(v.data);
+  const doc = jsonToDoc(v.data, opts?.行の表);
   return compileToCdl(doc, opts);
 }