@kensnzk/koyu 0.16.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (254) hide show
  1. package/README.ja.md +12 -8
  2. package/README.md +13 -10
  3. package/dist/analysis/contracts.d.ts +217 -0
  4. package/dist/analysis/contracts.d.ts.map +1 -0
  5. package/dist/analysis/contracts.js +27 -0
  6. package/dist/analysis/contracts.js.map +1 -0
  7. package/dist/analysis/index.d.ts +5 -0
  8. package/dist/analysis/index.d.ts.map +1 -0
  9. package/dist/analysis/index.js +17 -0
  10. package/dist/analysis/index.js.map +1 -0
  11. package/dist/analysis/json.d.ts +21 -0
  12. package/dist/analysis/json.d.ts.map +1 -0
  13. package/dist/analysis/json.js +111 -0
  14. package/dist/analysis/json.js.map +1 -0
  15. package/dist/cli.js +106 -35
  16. package/dist/cli.js.map +1 -1
  17. package/dist/core/derive.d.ts +13 -8
  18. package/dist/core/derive.d.ts.map +1 -1
  19. package/dist/core/derive.js +19 -13
  20. package/dist/core/derive.js.map +1 -1
  21. package/dist/core/diagnose.d.ts +4 -3
  22. package/dist/core/diagnose.d.ts.map +1 -1
  23. package/dist/core/diagnose.js +46 -11
  24. package/dist/core/diagnose.js.map +1 -1
  25. package/dist/core/diff.d.ts +3 -2
  26. package/dist/core/diff.d.ts.map +1 -1
  27. package/dist/core/diff.js +8 -5
  28. package/dist/core/diff.js.map +1 -1
  29. package/dist/core/fabric.d.ts +1 -3
  30. package/dist/core/fabric.d.ts.map +1 -1
  31. package/dist/core/fabric.js +8 -8
  32. package/dist/core/fabric.js.map +1 -1
  33. package/dist/core/graph.d.ts +2 -2
  34. package/dist/core/graph.d.ts.map +1 -1
  35. package/dist/core/graph.js +12 -5
  36. package/dist/core/graph.js.map +1 -1
  37. package/dist/core/light.d.ts.map +1 -1
  38. package/dist/core/light.js +2 -2
  39. package/dist/core/light.js.map +1 -1
  40. package/dist/core/model.d.ts +59 -10
  41. package/dist/core/model.d.ts.map +1 -1
  42. package/dist/core/model.js +128 -26
  43. package/dist/core/model.js.map +1 -1
  44. package/dist/core/parse.d.ts.map +1 -1
  45. package/dist/core/parse.js +83 -82
  46. package/dist/core/parse.js.map +1 -1
  47. package/dist/core/poly.d.ts +0 -4
  48. package/dist/core/poly.d.ts.map +1 -1
  49. package/dist/core/poly.js +1 -5
  50. package/dist/core/poly.js.map +1 -1
  51. package/dist/core/site.d.ts +9 -0
  52. package/dist/core/site.d.ts.map +1 -1
  53. package/dist/core/site.js +8 -2
  54. package/dist/core/site.js.map +1 -1
  55. package/dist/core/tolerance.d.ts +1 -1
  56. package/dist/core/tolerance.js +2 -2
  57. package/dist/core/tolerance.js.map +1 -1
  58. package/dist/core/vertical.d.ts +9 -2
  59. package/dist/core/vertical.d.ts.map +1 -1
  60. package/dist/core/vertical.js +8 -1
  61. package/dist/core/vertical.js.map +1 -1
  62. package/dist/core/vocabulary.d.ts.map +1 -1
  63. package/dist/core/vocabulary.js +17 -5
  64. package/dist/core/vocabulary.js.map +1 -1
  65. package/dist/diagnostics.d.ts +2 -0
  66. package/dist/diagnostics.d.ts.map +1 -0
  67. package/dist/diagnostics.js +3 -0
  68. package/dist/diagnostics.js.map +1 -0
  69. package/dist/diff.d.ts +2 -0
  70. package/dist/diff.d.ts.map +1 -0
  71. package/dist/diff.js +3 -0
  72. package/dist/diff.js.map +1 -0
  73. package/dist/draw/index.js +1 -1
  74. package/dist/draw/index.js.map +1 -1
  75. package/dist/draw/plan.js +5 -5
  76. package/dist/draw/plan.js.map +1 -1
  77. package/dist/form.d.ts +5 -0
  78. package/dist/form.d.ts.map +1 -0
  79. package/dist/form.js +4 -0
  80. package/dist/form.js.map +1 -0
  81. package/dist/graph.d.ts +2 -0
  82. package/dist/graph.d.ts.map +1 -0
  83. package/dist/graph.js +3 -0
  84. package/dist/graph.js.map +1 -0
  85. package/dist/index.d.ts +2 -14
  86. package/dist/index.d.ts.map +1 -1
  87. package/dist/index.js +36 -45
  88. package/dist/index.js.map +1 -1
  89. package/dist/mcp.js +81 -30
  90. package/dist/mcp.js.map +1 -1
  91. package/dist/model.d.ts +3 -0
  92. package/dist/model.d.ts.map +1 -0
  93. package/dist/model.js +3 -0
  94. package/dist/model.js.map +1 -0
  95. package/dist/parse-file.d.ts.map +1 -1
  96. package/dist/parse-file.js +18 -3
  97. package/dist/parse-file.js.map +1 -1
  98. package/dist/validate/assessment.d.ts +8 -0
  99. package/dist/validate/assessment.d.ts.map +1 -0
  100. package/dist/validate/assessment.js +1738 -0
  101. package/dist/validate/assessment.js.map +1 -0
  102. package/dist/validate/builtin/access.d.ts +55 -0
  103. package/dist/validate/builtin/access.d.ts.map +1 -0
  104. package/dist/validate/builtin/access.js +494 -0
  105. package/dist/validate/builtin/access.js.map +1 -0
  106. package/dist/validate/builtin/daylight.d.ts +44 -0
  107. package/dist/validate/builtin/daylight.d.ts.map +1 -0
  108. package/dist/validate/builtin/daylight.js +233 -0
  109. package/dist/validate/builtin/daylight.js.map +1 -0
  110. package/dist/validate/builtin/door-column-collisions.d.ts +47 -0
  111. package/dist/validate/builtin/door-column-collisions.d.ts.map +1 -0
  112. package/dist/validate/builtin/door-column-collisions.js +189 -0
  113. package/dist/validate/builtin/door-column-collisions.js.map +1 -0
  114. package/dist/validate/builtin/envelope.d.ts +30 -0
  115. package/dist/validate/builtin/envelope.d.ts.map +1 -0
  116. package/dist/validate/builtin/envelope.js +169 -0
  117. package/dist/validate/builtin/envelope.js.map +1 -0
  118. package/dist/validate/builtin/freeze.d.ts +3 -0
  119. package/dist/validate/builtin/freeze.d.ts.map +1 -0
  120. package/dist/validate/builtin/freeze.js +21 -0
  121. package/dist/validate/builtin/freeze.js.map +1 -0
  122. package/dist/validate/builtin/index.d.ts +38 -0
  123. package/dist/validate/builtin/index.d.ts.map +1 -0
  124. package/dist/validate/builtin/index.js +106 -0
  125. package/dist/validate/builtin/index.js.map +1 -0
  126. package/dist/validate/builtin/site.d.ts +62 -0
  127. package/dist/validate/builtin/site.d.ts.map +1 -0
  128. package/dist/validate/builtin/site.js +333 -0
  129. package/dist/validate/builtin/site.js.map +1 -0
  130. package/dist/validate/builtin/vertical-runs.d.ts +53 -0
  131. package/dist/validate/builtin/vertical-runs.d.ts.map +1 -0
  132. package/dist/validate/builtin/vertical-runs.js +290 -0
  133. package/dist/validate/builtin/vertical-runs.js.map +1 -0
  134. package/dist/validate/contracts.d.ts +188 -0
  135. package/dist/validate/contracts.d.ts.map +1 -0
  136. package/dist/validate/contracts.js +28 -0
  137. package/dist/validate/contracts.js.map +1 -0
  138. package/dist/validate/index.d.ts +2 -59
  139. package/dist/validate/index.d.ts.map +1 -1
  140. package/dist/validate/index.js +22 -70
  141. package/dist/validate/index.js.map +1 -1
  142. package/dist/vocabulary.d.ts +2 -0
  143. package/dist/vocabulary.d.ts.map +1 -0
  144. package/dist/vocabulary.js +3 -0
  145. package/dist/vocabulary.js.map +1 -0
  146. package/editors/vscode/syntaxes/koyu.tmLanguage.json +2 -2
  147. package/examples/basement/main.muro +3 -3
  148. package/examples/complex/main.muro +1 -1
  149. package/examples/complex/podium.muro +1 -1
  150. package/examples/complex/site.muro +6 -6
  151. package/examples/house/L2.muro +1 -1
  152. package/examples/house/main.muro +1 -1
  153. package/examples/house/site.muro +4 -4
  154. package/examples/house.muro +6 -6
  155. package/examples/mansion.muro +2 -2
  156. package/examples/office.muro +3 -3
  157. package/examples/steps/04-exterior.muro +1 -1
  158. package/examples/steps/05-two-storeys.muro +1 -1
  159. package/examples/steps/06-finished.muro +2 -2
  160. package/examples/tower/L2.muro +1 -1
  161. package/examples/tower/main.muro +1 -1
  162. package/examples/tower/site.muro +4 -4
  163. package/examples/twin/main.muro +1 -1
  164. package/examples/twin/podium.muro +4 -4
  165. package/examples/twin/site.muro +8 -8
  166. package/examples/two-rooms.canonical.json +4 -4
  167. package/examples/two-rooms.muro +2 -2
  168. package/package.json +41 -9
  169. package/src/analysis/contracts.ts +234 -0
  170. package/src/analysis/index.ts +61 -0
  171. package/src/analysis/json.ts +117 -0
  172. package/src/cli.ts +116 -36
  173. package/src/core/derive.ts +32 -15
  174. package/src/core/diagnose.ts +63 -16
  175. package/src/core/diff.ts +10 -6
  176. package/src/core/fabric.ts +18 -9
  177. package/src/core/graph.ts +19 -5
  178. package/src/core/light.ts +2 -2
  179. package/src/core/model.ts +141 -31
  180. package/src/core/parse.ts +100 -85
  181. package/src/core/poly.ts +1 -8
  182. package/src/core/site.ts +19 -2
  183. package/src/core/tolerance.ts +2 -2
  184. package/src/core/vertical.ts +10 -3
  185. package/src/core/vocabulary.ts +18 -5
  186. package/src/diagnostics.ts +8 -0
  187. package/src/diff.ts +14 -0
  188. package/src/draw/index.ts +1 -1
  189. package/src/draw/plan.ts +5 -5
  190. package/src/form.ts +37 -0
  191. package/src/graph.ts +12 -0
  192. package/src/index.ts +40 -175
  193. package/src/mcp.ts +85 -35
  194. package/src/model.ts +43 -0
  195. package/src/parse-file.ts +17 -3
  196. package/src/validate/assessment.ts +1934 -0
  197. package/src/validate/builtin/access.ts +642 -0
  198. package/src/validate/builtin/daylight.ts +321 -0
  199. package/src/validate/builtin/door-column-collisions.ts +266 -0
  200. package/src/validate/builtin/envelope.ts +227 -0
  201. package/src/validate/builtin/freeze.ts +19 -0
  202. package/src/validate/builtin/index.ts +156 -0
  203. package/src/validate/builtin/site.ts +445 -0
  204. package/src/validate/builtin/vertical-runs.ts +390 -0
  205. package/src/validate/contracts.ts +240 -0
  206. package/src/validate/index.ts +45 -99
  207. package/src/vocabulary.ts +9 -0
  208. package/dist/validate/access.d.ts +0 -6
  209. package/dist/validate/access.d.ts.map +0 -1
  210. package/dist/validate/access.js +0 -238
  211. package/dist/validate/access.js.map +0 -1
  212. package/dist/validate/envelope.d.ts +0 -4
  213. package/dist/validate/envelope.d.ts.map +0 -1
  214. package/dist/validate/envelope.js +0 -55
  215. package/dist/validate/envelope.js.map +0 -1
  216. package/dist/validate/light.d.ts +0 -6
  217. package/dist/validate/light.d.ts.map +0 -1
  218. package/dist/validate/light.js +0 -28
  219. package/dist/validate/light.js.map +0 -1
  220. package/dist/validate/runs.d.ts +0 -16
  221. package/dist/validate/runs.d.ts.map +0 -1
  222. package/dist/validate/runs.js +0 -60
  223. package/dist/validate/runs.js.map +0 -1
  224. package/dist/validate/site.d.ts +0 -6
  225. package/dist/validate/site.d.ts.map +0 -1
  226. package/dist/validate/site.js +0 -63
  227. package/dist/validate/site.js.map +0 -1
  228. package/spec/README.md +0 -28
  229. package/spec/canonical-json.md +0 -98
  230. package/spec/composition.md +0 -121
  231. package/spec/derivation.md +0 -393
  232. package/spec/en/README.md +0 -30
  233. package/spec/en/canonical-json.md +0 -101
  234. package/spec/en/composition.md +0 -121
  235. package/spec/en/derivation.md +0 -393
  236. package/spec/en/language.md +0 -164
  237. package/spec/en/notation-v0.md +0 -145
  238. package/spec/en/scope.md +0 -229
  239. package/spec/en/semantics.md +0 -132
  240. package/spec/en/tools.md +0 -108
  241. package/spec/en/validation.md +0 -79
  242. package/spec/en/vocabulary.md +0 -103
  243. package/spec/language.md +0 -163
  244. package/spec/notation-v0.md +0 -184
  245. package/spec/scope.md +0 -229
  246. package/spec/semantics.md +0 -130
  247. package/spec/tools.md +0 -106
  248. package/spec/validation.md +0 -79
  249. package/spec/vocabulary.md +0 -114
  250. package/src/validate/access.ts +0 -279
  251. package/src/validate/envelope.ts +0 -59
  252. package/src/validate/light.ts +0 -43
  253. package/src/validate/runs.ts +0 -87
  254. package/src/validate/site.ts +0 -84
@@ -1,393 +0,0 @@
1
- [English](en/derivation.md) · **日本語**
2
-
3
- # 導出の規範 — 書かれた構成から、一意な形へ
4
-
5
- koyu v0.16.0 / muro 1.0 現在。**この文書が、書かれた構成からどんな形が出るかの規範である。**
6
-
7
- 原本に形は無い ([policy.md](../docs/policy.md) §2)。平面図も面積も動線も、書かれるのではなく導かれる。導出の規則が消費者ごとに違えば、同じ原本から違う建物が出る — **それは原本ではない** ([scope.md §6](scope.md))。だからここが規則を持ち、実装は参照実装として従う。
8
-
9
- 参照実装は `derive(model): Form` である ([tools.md](tools.md))。`Form` は**見た目を一つも持たない** — 色も書体も線幅も注記文字列も記号も縮尺も紙面の余白も返さない。返すのは座標・厚み・z 範囲・向き・そして対象の同一性だけである。`src/draw/` と ugatsu はこの `Form` を描くだけであり、複数あってよいのは**見た目**であって形ではない。
10
-
11
- 範囲の規範は [scope.md](scope.md)、意味論は [semantics.md](semantics.md)、属性の値域は [vocabulary.md](vocabulary.md)。
12
-
13
- ---
14
-
15
- ## 0. 四つの約束
16
-
17
- **1. 形は正準形の関数である。**
18
-
19
- ```
20
- toCanonical(a) === toCanonical(b) ⟹ derive(a) ≡ derive(b)
21
- ```
22
-
23
- 正準形は「同じ建物とは何か」の定義である ([canonical-json.md](canonical-json.md))。したがって**正準形が捨てる情報は、形を変えてはならない** — 線の端点の書き順も、境界の宣言順も、行の並びも、形に効かない。これは §6 の一意性の約束を機械が縛れる形に言い直したものである ([scope.md §6](scope.md))。
24
-
25
- この約束から二つの規則が出る。**描かれた線は向きを持たない** (§1.5)。**切り分けは正準の境界順に効く** (§1.1)。
26
-
27
- **2. 形を読む入口は一つである。**空間の形は `pieces`(導出された凸片)であって `rects`(書かれた割付)ではない。割付はセルの綴りであり、形ではない。面積・共有辺・外周・被覆・柱の立地・投影 — 形を読むすべての導出がこの一つの入口を通る。
28
-
29
- **3. 既定値を捏造しない。**必要な値が書かれていなければ、既定を勝手に置くのではなく**その要素を作らない**。充足性 (SUF01-04) が「作れない」ことを言葉にする。ただし本書の §5 に列挙した導出の既定は例外で、これは仕様が定めた規則であって捏造ではない。
30
-
31
- **4. 凸片は反時計回りである。**`Form` が返す輪郭はすべて反時計回り (符号つき面積が正) であり、辺の方位 (N/E/S/W) の読みはこの向きを前提とする。
32
-
33
- ---
34
-
35
- ## 1. 領域 — 空間の形
36
-
37
- ### 1.1 割付から凸片へ
38
-
39
- 空間の領域は矩形の合併として書かれる。導出はまず各矩形を反時計回りの四頂点 `[(x1,y1),(x2,y1),(x2,y2),(x1,y2)]` へ写し、次に境界に**描かれた線** (`line`) があればその半平面で切り直す。
40
-
41
- ```
42
- pieces = rects # 線が無ければ割付の写し
43
- pieces = outside(window) + halfplane(inside) # 線があれば窓の中だけを切り直す
44
- ```
45
-
46
- 切り直しは `parse` の出口で**一度だけ**、**正準の境界順**に効く。冪等ではない — 先に効いた線が縮めた領域が、後の線の窓を縮める。
47
-
48
- **順序は宣言順ではない。**正準JSONは境界の宣言順を捨てるので ([canonical-json.md](canonical-json.md))、宣言順に切ると同じ正準形から違う面積が出る (§0 の約束1 に反する)。並びの規則は `toCanonical` と同じ — `between` の辞書順、同じ `between` は直列化順である。合成で境界が挟まっても並びは動かない。
49
-
50
- ### 1.2 線の及ぶ窓
51
-
52
- 線は無限直線ではない。**線に沿っては限られた区間を、線を横切っては相手を含む範囲を**切る。この非対称が要である — 無限直線として扱うと離れた翼を巻き込んで室が消え、線分の外接矩形として扱うと軸平行の線で退化して何も切れない。
53
-
54
- 線の向きは `|Δy| >= |Δx|` なら**縦向き**である (ちょうど 45 度と退化した点も縦向きに数える)。縦向きなら「沿う」軸が y、「横切る」軸が x で、横向きならその逆になる。
55
-
56
- | 場合 | 沿う軸 | 横切る軸 |
57
- |---|---|---|
58
- | 二空間を分け直す (両側が領域を持つ) | 二つの領域の外接矩形の**積** | 二つの外接矩形の**和** |
59
- | 外皮を切る (片側が領域を持たない) | **線分自身の区間** | 領域を持つ側の外接矩形**全体** |
60
-
61
- 窓は二辺とも許容 (§6 の `EPS`) を超えていなければ実体を持たず、その線は何も切らない (LIN01)。
62
-
63
- ### 1.3 残す側
64
-
65
- 線のどちら側を残すかは、**窓に触れる凸片を丸ごと測って**決める。窓に触れるかは外接矩形どうしの重なりで見る。各片を線で二分し、左の面積の合計と右の面積の合計を比べ、差が許容 (§6 の `AREA_EPS`) 未満なら「偏りなし」とする。
66
-
67
- **切るのは窓の中だけ、決めるのは片の全体である。**全ての凸片を測ると線が届かない翼が符号を支配して室が消え、窓の中だけを測ると隅から隅への線が「二等分」に見える。
68
-
69
- - **外皮を切る場合**: 領域を持つ側の偏りが、そのまま残す側である。偏りなしなら切らない (LIN01)
70
- - **二空間の場合**: 両側の偏りを取り、片方だけが 0 なら他方の反対を当てる。両方 0 でも、同じ側でも切らない (LIN01)
71
-
72
- **`a`/`b` のどちらを先に書いたかは、残す側に効かない。**`boundary /L1/room /out` と `boundary /out /L1/room` は同じ関係の二つの綴りであり、残す側は**領域を持つ側そのもの**が決める。a/b の向きが意味を持つのは `edge` と `swing` — 「どちらから見た関係か」を必要とする二つ — だけである。
73
-
74
- ### 1.4 分け直しの操作
75
-
76
- 窓の内と外へ割り、**窓の中の割付を合併してから線の両側へ分け直す**。したがって二空間の分け直しでは合計面積が保存される (一方が失う三角形を他方が得る)。外皮を切る場合は領域を持つ側だけが減り、相手は面積を得ない。
77
-
78
- 半平面で切った結果が三頂点未満か、面積が許容以下なら、その片は無かったことにする。この閾値が無ければ、隅切りの端に髪の毛のような破片が残り、それが辺として読まれて幽霊の壁を生む。
79
-
80
- ### 1.5 線の向き
81
-
82
- **線分は向きを持たない。**同じ二点を結ぶ線は、どちらの端から書いても同じ線である。導出は切り分けの前に、各線の端点を**解決座標の (x, then y) 昇順**へ揃える — 正準JSONが端点の対に使う規則と同じものである。綴り (通り参照) も一緒に入れ替わるので、診断が引用する綴りは書かれたとおりのまま順だけが入れ替わる。
83
-
84
- **この正準の始端が、線に載る開口の `at:` の起点である** (§3.2)。揃えなければ、正準JSONがバイト同一のまま扉が別の位置に出る — §0 の約束1 に反する。
85
-
86
- ---
87
-
88
- ## 2. 境界 — 壁の位置
89
-
90
- ### 2.1 辺の方位
91
-
92
- 凸片の反時計回りの頂点列を一周し、軸に平行な辺だけを読む。+x へ進む辺が **S**、−x が **N**、+y が **E**、−y が **W** の面である。したがって N=+Y、S=−Y、E=+X、W=−X の面を指す。斜めの辺は方位を持たない。
93
-
94
- 二つの辺が「向かい合う」とは、方位が互いに逆 (N↔S / E↔W) であり、かつ固定座標の差が許容以下であることをいう。
95
-
96
- ### 2.2 線分の導出
97
-
98
- 境界の線分は次の順で決まる。**順序が意味を持つ。**
99
-
100
- 1. 両端のどちらかの空間が存在しなければ、線分は無い
101
- 2. `kind` が `stair` / `shaft` / `void` なら線分は無い (垂直の境界は壁を持たない)
102
- 3. **描かれた線があれば、それが境界の実現である** (§2.4)。共線マージも `edge:` の絞り込みも掛からない
103
- 4. 両側が領域を持つなら**共有辺**。レベルが違えば線分は無い (異なるレベル間に壁は立たない)
104
- 5. 片側だけが領域を持つなら**外周**。相手は「同じレベルの、この二空間以外のすべての空間の領域」である
105
- 6. どちらも領域を持たなければ線分は無い
106
-
107
- 4 と 5 の結果には共線マージ (§2.3) を掛け、最後に `edge:` があれば「a 側から見た辺」で絞る。
108
-
109
- **共有辺** — A の各凸片の軸平行な辺と B の各凸片の辺のうち、向かい合っていて重なる区間を持つものを取る。重なりが許容以下なら共有辺にならない (点接触は接触ではない)。線分は座標の昇順に向き、`a` 側から見た方位を持つ。
110
-
111
- **外周** — 各凸片の各辺から、向かい合う相手の辺が覆う区間を引いた残り。**同じ空間の他の凸片も相手に数える**ので、L 字を二矩形で書いても内部の継ぎ目に壁は立たない。相手を引く順序は結果に影響しない。
112
-
113
- ### 2.3 共線マージ
114
-
115
- 同じ直線上に並ぶ線分を一本にまとめる。まとめる単位は (向き・固定座標・a 側から見た方位) の三つ組で、**固定座標は厳密に一致していなければならない**。同じ組の中で座標の昇順に並べ、隙間が許容以下なら伸ばし、超えたら切る。
116
-
117
- 背中合わせの辺 (同じ直線上の N の辺と S の辺) は方位が違うので併合されない。
118
-
119
- ### 2.4 描かれた線が実現する区間
120
-
121
- **一本の設計線は複数の境界に共有される。**貫通通路の壁は、その前を通る区画の数だけ境界を持つ。各境界が線の全長を実現すると、平面には同じ壁が何本も重なる。
122
-
123
- 線を両空間の凸片の辺で切り、各区間の中点から法線方向へ探り距離 (§6 の `PROBE`) だけ離れた二点を取って、左右がちょうど a と b になっている区間だけを残す。片側が領域を持たない相手なら、持つ側が片側だけに居ることで境界になる。この判定は a と b について対称である。
124
-
125
- 出力の線分は**正準の端点の順** (§1.5 — 解決座標の昇順) を保ち、`a` 側から見た方位を持たない。したがって `line` を持つ境界に `edge:` を書いても効かない。
126
-
127
- ---
128
-
129
- ## 3. 実体 — 壁・開口・柱・面
130
-
131
- ### 3.1 壁の厚みと z 範囲
132
-
133
- 境界が立つレベルは「a が領域を持てば a、でなければ b」の空間のレベルである。壁の下端はそのレベルの FL。
134
-
135
- | | 厚み | 上端 |
136
- |---|---|---|
137
- | 壁 (`kind:wall`) | `t:` があればその値、無ければ既定 (§5) | FL + 階高 |
138
- | 遮蔽しない境界 (`air:1`) | `t:` があればその値、ただし上限で頭打ち | FL + 境界の `h:`、無ければ既定 |
139
-
140
- **階高**は「上のレベルがあればその差、無ければその階の最大天井高 + 屋根版の厚さ」である。上が無いときに屋根の頂点へ揃えるのは、`slabs()` の屋根が同じ式で架かるからで、揃えなければ壁が屋根を突き抜けるか下に隙間が空く。天井高が一つも決まらなければ階高も決まらず、**そのレベルには壁も柱も立たない** (SUF01 が既に error として言う)。
141
-
142
- 厚みは芯線に対して両側へ半分ずつ振り分ける。斜めの線分でも同じで、単位法線へ ±t/2 だけ振った四辺形になる。
143
-
144
- ### 3.2 帯 (開口・seg) の位置
145
-
146
- 開口も `seg` も「境界線分上の区間」であり、同じ規則で置かれる。**順序が意味を持つ。**
147
-
148
- 1. 境界の線分を取る (`edge:` は既に適用済み)。帯にも `edge:` があればさらに絞る
149
- 2. 線分が一つも無ければ置けない (OPN04 / SEG04)
150
- 3. 線分が二つ以上あれば辺を選ばなければ置けない (OPN05 / SEG05)
151
- 4. 帯の幅が線分の長さを超えれば置けない (OPN06 / SEG06)。等しい場合は置ける
152
- 5. **通り参照** (`at:X2+450`) なら、斜めの線分には置けず (OPN07 / SEG07)、水平の線分は X 系・垂直の線分は Y 系でなければならず (OPN07 / SEG07)、はみ出せば置けない (OPN08 / SEG08)
153
- 6. **比率** (`at:0.2`、既定 0.5) なら、両端で中心が納まる範囲へ**クランプされる** (診断は出ない)
154
-
155
- 中心の座標は、線分の始点から終点へのパラメータで取る — 軸平行でも斜めでも同じ一つの式である。**したがって線分の向きが変われば同じ `at:` が別の場所を指す。**線分は導出されたものも描かれた線のものも**常に座標の昇順に向く** (§1.5) ので、`a`/`b` の書き順にも線の端点の書き順にも依らない。
156
-
157
- ### 3.3 開口の z 範囲と、壁が割られること
158
-
159
- **開口の頭はまぐさ高に揃う。**扉は床から立ち上がってまぐさ高に達し、それ以外の開口はまぐさ高から高さのぶん下がる。高さは開口の `h:`、無ければ §5 の既定である。
160
-
161
- ```
162
- door : z0 = FL ; z1 = FL + (h ?? OPENING_HEAD)
163
- opening: z0 = FL + OPENING_HEAD - (h ?? OPENING_H) ; z1 = FL + OPENING_HEAD
164
- ```
165
-
166
- 窓台 (`sill`) は**運搬層**なので core は見ない ([scope.md §7](scope.md))。窓台の高さは頭を揃えた結果として決まる。
167
-
168
- 壁は**開口で割られた区間の列**として現れる。線分に載る開口を始点からの距離の順に並べ、開口の間には全高の区間を、開口の位置には腰壁 (床から開口の下端まで) と垂れ壁 (開口の上端から天端まで) を残す。長さか高さが許容以下の区間は作らない。
169
-
170
- **「壁の黒帯を紙の色で塗り潰して穴に見せる」という操作は、この規則があれば存在しない。**平面でも立体でも、壁は最初から穴の空いた区間の列である。
171
-
172
- ### 3.4 扉の開く先と軌跡
173
-
174
- 開く先は `swing:a/b`、書かれていなければ「a が領域を持てば a、でなければ b」。開く向きは、**開く先の導出された形**のうち開口に最も近い凸片の外接矩形の中心へ向かう成分で決める (割付ではなく形を読む — 描かれた線で切られた空間では、最も近い割付の中心が線の反対側に落ちうる)。
175
-
176
- 吊元は、水平の線分なら `hinge:E` で東端・でなければ西端、垂直の線分なら `hinge:N` で北端・でなければ南端。**斜めの線分では吊元を始端側に固定する** — `hinge` の N/E/S/W は軸の言葉なので斜めには当たらない。
177
-
178
- 軌跡は吊元を中心とする半径 = 開口の幅の 1/4 円で、葉の先端 (吊元から開く側へ幅のぶん) から開口の反対の側柱 (吊元から線分に沿って幅のぶん) へ回る。掃く向きは、この二点と吊元の外積の符号が決める。
179
-
180
- `style:sliding` / `style:auto` の開口は軌跡を持たない — 吊元の側へ引き込まれる。
181
-
182
- ### 3.5 柱
183
-
184
- 柱の位置はどこにも書かれない。**通り芯の交点と床の交わりから現れる。**
185
-
186
- 母集団の床は「そのレベルにあり、外部でも吹抜けでもなく、領域を持ち、**空しか支えない半屋外ではない**」空間である ([ADR-0030](../docs/decisions/0030-columns-hold-something.md))。宣言が通りを名指していればその通りだけを、していなければすべての通りを見る。走査は X が外側、Y が内側。交点が床のいずれかの凸片の内側 (辺の上も内側に数える) にあれば、そこに柱が立つ。
187
-
188
- 同じ交点に二本は立たない — **先に書かれた宣言が勝つ** ([ADR-0029](../docs/decisions/0029-order-as-meaning.md))。柱の z 範囲は、そのレベルの FL から FL + 階高 (§3.1) までである。
189
-
190
- ### 3.6 面 (床・天井・屋根)
191
-
192
- 母集団はレベルを z の昇順に、その中で空間を宣言順に、一空間の中で床 → 天井 → 屋根の順に走査する。輪郭はすべて導出された凸片である。
193
-
194
- | 面 | 生成の条件 | z 範囲 |
195
- |---|---|---|
196
- | **床** | 吹抜けでも外部でもなく、レベルに `slab` がある | FL − slab … FL |
197
- | **天井** | `ceiling:0` でなく、吹抜け・外部・半屋外・縦動線のいずれでもなく、天井高が決まる | FL + h − 天井厚 … FL + h |
198
- | **屋根** | 外部でも半屋外でもない。**上に空間が重なっていない範囲だけ** | 頂点 − 厚さ … 頂点 |
199
-
200
- **床の不在は屋根の不在ではない** — 吹抜けにも屋根は架かる。逆に**覆っている側には吹抜けも半屋外も数える**。覆いは直上のレベルだけでなく**上のすべてのレベル**から取り、導出された形で引く。
201
-
202
- 屋根の頂点と厚さは上のレベルの有無で式が切り替わる。
203
-
204
- ```
205
- upper level : top = upper.z ; t = upper.slab ?? ROOF_T
206
- no upper level : top = FL + h + ROOF_T ; t = ROOF_T
207
- ```
208
-
209
- 上のレベルがあるときは**天井高を読まない**。したがって天井高が決まらなくても屋根は生成される。上が無く天井高も決まらなければ形は痩せるが、その状態は SUF01 が error として塞いでいる。
210
-
211
- 引いた残りの面積が許容以下のタイルは屋根にしない。
212
-
213
- ---
214
-
215
- ## 4. 縦動線
216
-
217
- 段数も踏面も勾配も書かれない。**領域と階高と「上る向き」の宣言だけから導かれる。**
218
-
219
- ### 4.1 局所座標と、形が生成されない条件
220
-
221
- 走りの局所座標は t (進む向きに 0 から) と s (**進行方向の左**から) で測る。`turn:` は `L` と書かれたときだけ L で、未記入も不正値も R である。
222
-
223
- 次のいずれかに当たると**形は一つも生成されない** — check が RUN01-05 / SUF04 として言葉にする。
224
-
225
- 宣言が 0 個か 2 個以上 / 領域が単一矩形でない / レベルが特定できない / 昇降機以外で値が N/E/S/W でない / 昇降機で値が 1 でない / `form:` が straight・return 以外 / 階段と斜路以外に `form:return` / 上のレベルが無い (昇降機を除く) / 乗り込みが全長を食う / 折返しの走り長が残らない。
226
-
227
- **昇降機は上のレベルが無くても形を持つ** — かごは同じレベルで閉じる。
228
-
229
- ### 4.2 乗り込みと段割り
230
-
231
- 走りは領域の縁からは始まらない。近端に**乗り込みの帯**が残り、そこが扉の開く場所になる。直階段では遠端にも残る。
232
-
233
- ```
234
- usable = length - entry # form:return
235
- usable = length - entry * 2 # form:straight
236
- risers = max(2, ceil(rise / (riser ?? DEFAULT_RISER_MAX)))
237
- riser = rise / risers
238
- tread = usable / max(1, risers - 1)
239
- ```
240
-
241
- ### 4.3 折返し
242
-
243
- 幅を二分し、遠端に中間踊り場を置く。`turn:R` なら第一の走りが進行方向の左、`turn:L` なら右。二本の走りは同じ t の区間を占め、s だけが違う。
244
-
245
- 段の分割は `k = min(段数−1, max(1, round(段数÷2)))` で、踊り場の高さは FL + k×蹴上げ。**round は半数を切り上げるので、奇数段では下の走りが一段多い。**二本目は幾何としても逆向きで、t が小さい側が高い。斜路の折返しは踊り場を高さのちょうど半分に置く。
246
-
247
- **中間踊り場の奥行は残余として決まる。**走り長・踏面・踊り場は一つの式で結ばれていて、書けるのは高々二つである。設計者が握りたいのは踏面の快適さなので、既定では残余を踊り場へ寄せる ([ADR-0021](../docs/decisions/0021-vertical-circulation.md))。`landing:` を書けば踏面が残余になる。導出値も書かれた値も、最小奥行を下回れば最小奥行まで引き上げられる。
248
-
249
- ### 4.4 並列 (エスカレーター)
250
-
251
- 一台の呼び幅は `lane:`、無ければ既定。台数は `floor(幅 ÷ 呼び幅)` で最低一台、一台の幅は呼び幅と 幅÷台数 の小さい方、余りは両端に等分される。**台ごとに走る向きが交互になる** — 上りの隣は上から降りてくる一台である。`lane:` は階段・斜路・昇降機では効かない (台数は常に一である)。
252
-
253
- ### 4.5 集約値
254
-
255
- 走りの水平長の合計は**一台目だけ**を数える (折返しの二本はどちらも数える)。踏面は**最も窮屈な走り**が、勾配は**最も急な走り**が代表する。この非対称は検証 (RUN06/RUN07) の前提である。
256
-
257
- ### 4.6 立体
258
-
259
- | 部品 | 形 |
260
- |---|---|
261
- | 踊り場 | 版。上端が踊り場の高さ、厚さは版厚 |
262
- | 階段の走り | 蹴上げ k 段に対して段板は **k−1 枚** (最上段は上階の床が受ける)。i 段目の上端は 下端 + i×蹴上げ、厚みは蹴上げ + 見付け厚 |
263
- | 斜路・エスカレーター | 傾いた版一枚。**傾きは z の大小が決める** — 人の進む向きでは決めない |
264
- | エスカレーターの欄干 | 一台に二枚。段板面から持ち上げた傾いた薄板 |
265
- | 昇降機のかご | 四方から内へ寄せた箱。**階高に依らず一定の高さ**で、下端はそのレベルの FL から |
266
-
267
- ### 4.7 平面 — 切断
268
-
269
- 平面は「そのレベルで切った断面」である。切断面の高さは **FL からの切断高さ**で、これは `derive` の**入力**であって導出の中身ではない (既定は §5)。
270
-
271
- **上る走り**は部品ごとに、その z の範囲と切断面を比べて可視区間を決める。切断面が部品の上端以上なら丸ごと見え、下端以下なら丸ごと見えず、跨ぐなら跨いだ位置で切れる。判定は幾何だけで行い、部品の番号では決めない — 並列の台は同じ高さで切られるので、こう書いてはじめて二台目に窓が出る。
272
-
273
- **下りる走り**は、同じ枠を共有する双子の上る走りが**隠した残り**に現れる。双子であるには、矩形の四座標が許容内で一致し、向き・形式・装置・部品数がすべて一致していなければならない。位置だけで照合すると鏡像が出る。双子が無ければ下りる走りは丸ごと見える。
274
-
275
- 段鼻は部品の t0 を起点に踏面の刻みで並べ、可視区間の外は落とす。エスカレーターの段の刻みは**可視区間の始点**を起点に一定のピッチで並べる。
276
-
277
- 矢印は、エスカレーターなら台ごとに、階段と斜路なら出発する走り (上りの面) / 到着する走り (下りの面) に一本。向きは人の進む向きだけから決まり、**エスカレーターはどちらの面でも同じ向きを指し、階段と斜路は下りの面で反転する** (機械の向きは固定、人の向きは面で変わる)。可視区間が短すぎれば矢印は出ない。
278
-
279
- 切断線は、走りが切断面を跨いだ位置を**走りの幅いっぱいに横切る一本の線分**である。作図慣習の平行な二本の斜線は見た目であり、描画側が引く。
280
-
281
- ---
282
-
283
- ## 5. 導出の定数
284
-
285
- **台帳の既定ではない。**[vocabulary.md](vocabulary.md) が定めるのは「何を書いてよいか」であり、ここが定めるのは「書かれなかったときに何を導くか」である。書けば必ず書いた値が勝つ。
286
-
287
- <!-- derivation-constants -->
288
-
289
- | 定数 | 値 | 単位 | 何を決めるか |
290
- |---|---|---|---|
291
- | `WALL_T` | 100 | mm | 壁厚の既定 (`t:` で上書き)。芯線に対して両側へ半分ずつ |
292
- | `RAIL_T` | 60 | mm | 遮蔽しない境界 (`air:1`) の厚みの既定 (`t:` で上書き) |
293
- | `RAIL_T_MAX` | 80 | mm | 遮蔽しない境界の厚みの上限。`t:` に何を書いてもここで頭打ち |
294
- | `RAIL_H` | 1100 | mm | 遮蔽しない境界の天端高の既定 (境界の `h:` で上書き) |
295
- | `OPENING_HEAD` | 2000 | mm | 開口のまぐさ高。扉はここまで立ち上がり、それ以外はここから下がる |
296
- | `OPENING_H` | 1200 | mm | 扉以外の開口の高さの既定 (開口の `h:` で上書き) |
297
- | `CEILING_T` | 30 | mm | 天井面の見付け厚 |
298
- | `ROOF_T` | 200 | mm | 屋根版の厚さの既定と、最上階で天井高の上へ載せる量 |
299
- | `CUT_HEIGHT` | 1200 | mm | 平面の切断面の FL からの高さ (`derive` の入力の既定) |
300
- | `DEFAULT_RISER_MAX` | 180 | mm | 蹴上げの上限 (`riser:` で上書き)。段数を決める |
301
- | `TREAD_TARGET` | 300 | mm | 折返しの踊り場を残余として決めるときの目標踏面 (`tread:` で上書き) |
302
- | `LANDING_MIN` | 1100 | mm | 中間踊り場の最小奥行。書かれた `landing:` もここまで引き上げる |
303
- | `ENTRY_LANDING` | 1100 | mm | 乗り込みの床の奥行の既定 (`entry:` で上書き) |
304
- | `LANE_ESCALATOR` | 1200 | mm | エスカレーター一台の呼び幅の既定 (`lane:` で上書き)。台数を決める |
305
- | `TREAD_SOLID` | 200 | mm | 段板の見付け厚 (立体) |
306
- | `SLAB_T` | 200 | mm | 踊り場の版と、斜路・エスカレーターの傾いた版の厚さ |
307
- | `STEP_MARK` | 400 | mm | 平面のエスカレーターの段の刻みのピッチ |
308
-
309
- 昇降機のかごは四方から `min(300, 辺÷6)` だけ内へ寄せ、FL+60 から FL+2400 に立つ。エスカレーターの欄干は幅 `min(140, 台の幅÷8)`・厚さ 100 で、段板面から 900mm 持ち上がる。
310
-
311
- ---
312
-
313
- ## 6. 許容値
314
-
315
- **同じ問いに二つの許容値があってはならない。**座標は mm の整数が基本なので、長さの許容は整数の刻みの半分に置かれている。
316
-
317
- <!-- tolerances -->
318
-
319
- | 許容値 | 値 | 単位 | 何の許容か |
320
- |---|---|---|---|
321
- | `EPS` | 0.5 | mm | 辺の軸平行・向かい合わせ・区間の一致・共線マージの隙間・通り参照のはみ出し・開口の重なり |
322
- | `AREA_EPS` | 1 | mm² | 切った残りが消えるか。左右の面積差が「偏りなし」か。屋根タイルが残るか |
323
- | `PROBE` | 5 | mm | 描かれた線の左右を探る距離。**形の解像度の下限である** |
324
- | `SPAN_EPS` | 1 | mm | 切断面と部品の z の比較・可視区間の長さの下限・双子の枠の一致・外皮の穴の長さの下限・壁の区間の下限 |
325
- | `CROSS_EPS` | 1e-6 | — | 半平面で切るときの符号 (外積 = 面積の二倍) の許容 |
326
- | `PARALLEL_EPS` | 1e-9 | — | 無限直線と線分の平行判定・線分側パラメータの範囲 |
327
- | `POINT_EPS` | 1 | mm | 点が多角形の辺の上にあるとみなす幅 (境界上は内側扱い)。柱の立地もこれで見る |
328
-
329
- ---
330
-
331
- ## 7. 形と見た目の線引き
332
-
333
- `Form` が持つのはこれである。
334
-
335
- **座標** (領域の凸片・境界線分・開口の中心・柱の断面・段板の矩形)・**厚み** (壁・手すり・面)・**z 範囲** (壁・開口・柱・面・立体)・**向き** (辺の方位・上る向き・扉の吊元と開く側・矢印が上るか)・**対象の同一性** (どの空間の、どの境界の、どの開口の形か)・**平面の分類** (切断された断面 / 切断面より下の見えがかり / 切断面より上の投影 / 動きの軌跡 / 記号を置く座)。
336
-
337
- `Form` が持たないのはこれである。
338
-
339
- **色・書体・文字寸・線幅・線種 (破線のパターン)・注記の言葉** (`UP` も `12段 蹴上175/踏面300` も) **・作図の記号** (吹抜けの対角線・切断線の二本の斜線・通り芯の丸・矢印の頭・昇降機の対角線)・**縮尺と紙面の余白と viewBox**・**描く順序と重ね順と陰影**・**何を描き何を省くか**の判断。
340
-
341
- **「同じ構成から複数の形が出る」ことは欠陥である。**複数あってよいのは見た目であって、形ではない ([scope.md §6](scope.md))。
342
-
343
- ### 7.1 実体の構成子
344
-
345
- `Form` が持つのは芯線と厚みと z である。**そこから実体を起こす規則も導出の一部であり、実装は一つでなければならない。**消費者がそれぞれ書き直せば、部品を共有していても組み立ての規則は共有されず、同じ `Form` から違う形が出る余地がまた開く。
346
-
347
- | 構成子 | 何を起こすか |
348
- |---|---|
349
- | `thicken(x1, y1, x2, y2, t)` | 芯線を厚みのある四辺形へ (§3.1)。斜めの線分でも同じ一つの式 |
350
- | `bandLine(seg, cx, cy, w)` | 帯 (開口・seg) が線分上で占める区間 (§3.2) |
351
- | `band(seg, cx, cy, w, t)` | その区間を厚みのある四辺形へ — `bandLine` を `thicken` したもの |
352
- | `columnRect(c)` | 柱の断面 (§3.5) |
353
- | `runPrism(s)` | 縦動線の立体を角柱 (底面の輪郭と頂点ごとの上端/下端 z) へ。傾いた版の四隅は §4.6 の規則で振る |
354
-
355
- **四辺形の頂点は 始点+n → 終点+n → 終点−n → 始点−n の順である**ので、向かい合う二辺の中点を結べば芯線に戻る。平面のエンティティは区間の**足あと (四辺形) と芯線の両方**を持つ — 厚みを持つものとして描くか一本の線として描くか (遮蔽しない手すり・柵) は見た目の判断なので、消費者が足あとから芯線を復元しなくて済むようにする。
356
-
357
- ---
358
-
359
- ## 8. 平面は純粋な断面ではない
360
-
361
- 立体を切っただけでは平面図にならない。次の四つは、どれだけ正確に切っても出てこない。
362
-
363
- - **扉の軌跡** — 動きの記号であって、そこに物は無い
364
- - **上部吹抜けの投影** — 切断面より上のものが下階の平面に落ちる
365
- - **切断線** — 切れたことそのものの位置
366
- - **下りる走り** — 切断面より下の見えがかり
367
-
368
- だから `Form` は平面を**分類つきの2Dエンティティ集合**として持つ。各要素が (幾何・分類・対象の同一性) を持ち、分類は `cut` (切断された断面) / `below` (切断面より下の見えがかり) / `above` (切断面より上の投影) / `swing` (動きの軌跡) / `anchor` (記号を置く座) に割れる。
369
-
370
- 消費者に「立体から切れ」と言えば、この四つを各自が発明することになる。上部吹抜けの投影は実際にそうして落ちた — 同梱例に 11 件あるものが、ビュアーの平面から一つも出ていなかった。
371
-
372
- 上部吹抜けの投影に落とすのは**導出された形**である。割付で落とすと、描かれた線で切られた吹抜けが切られる前の姿で出る。
373
-
374
- ---
375
-
376
- ## 9. 実装と検査
377
-
378
- 参照実装は `derive(model, {cut?})` で、`Form` を返す ([tools.md](tools.md) の公開面の表)。定数の台帳は `DERIVATION_CONSTANTS`、許容値の台帳は `TOLERANCES` で、**§5 と §6 の表はその写しである** — `test/derive.test.ts` が表と実装の一致を縛る。
379
-
380
- **§0 の約束1 (形は正準形の関数である) を機械が縛る** (`test/uniqueness.test.ts`)。正準形が等しいことを**前提として確かめてから**形の一致を主張するので、前提が崩れれば「この組は何も証明していない」と落ちる。線の端点の書き順・境界の宣言順・a/b の向きの各々に節がある。
381
-
382
- **`Form` が境界を並べる順は正準順である** (§1.1 と同じ規則)。`FormSeg.boundary` のような索引はこの並びを指すので、消費者は `model.boundaries[i]` (宣言順) を当ててはならない。並びを得る関数 `canonicalBoundaryOrder(model)` が公開面にある ([tools.md](tools.md))。
383
-
384
- `Form` が見た目を持たないことも機械が縛る — 同梱例の `Form` を JSON にして、色の綴りも日本語も `UP`/`DN` も一つも現れないことを検査する。
385
-
386
- `src/draw/` (`svgPlan` / `svgAxo`) は `Form` を描くだけであり、**凍結の対象ではない** ([scope.md §8](scope.md))。SVG の中身はいつ変わってもよい。変わってはならないのは `Form` である。
387
-
388
- **「描くだけ」であることも機械が縛る** (`test/draw.test.ts`)。
389
-
390
- - `src/draw/` の import を実際に読み、**形を組み立てる部品** (`segmentsFor` `placeOpening` `placeBand` `slabs` `runSolids` `verticalRuns` `runDrawsForLevel` `columnsFor` `regionOf` `heff` `levelsSorted` ほか) を一つも引いていないこと
391
- - §5 の定数が `src/draw/` に綴られていないこと
392
- - 平面に出た黒帯が、`Form` の「切られた区間」そのものであること — 紙と世界を結ぶ相似変換を外接枠から解き、四辺形の集合として突き合わせる
393
- - 足あとを持つ区間は必ず芯線も持ち、その芯線が足あとの軸であること (§7.1)
package/spec/en/README.md DELETED
@@ -1,30 +0,0 @@
1
- **English** · [日本語](../README.md)
2
-
3
- # spec/ — the koyu specification (present tense)
4
-
5
- > **This is a reference. If you are learning koyu, start at [guide/en/start.md](../../guide/en/start.md).** It is written to be consulted, not to be read through and absorbed.
6
-
7
- This folder is the normative reference for **how koyu behaves right now**. It does not record how things came to be, or why — that is the job of [docs/decisions/](../../docs/decisions/) (the ADRs) and [docs/log/](../../docs/log/), and the spec keeps only **the present tense of the conclusions** once the decisions have settled. Where the two disagree, the implementation and its tests are the norm, and the spec is corrected.
8
-
9
- ## The map of the documents
10
-
11
- | Document | Contents | Reader |
12
- |---|---|---|
13
- | [language.md](language.md) | **Language reference** — lexis, the grammar of every declaration, composition (import), defaults, and how position is written | People who write .muro; people who touch the parser |
14
- | [semantics.md](semantics.md) | **Semantics reference** — the model; derivation (wall segments, vertical adjacency, semi-outdoor, height); the list of checks; the definitions of the queries (doors/stats/light/site) | People who touch derivation or check; people interpreting results |
15
- | [derivation.md](derivation.md) | **The norm for derivation** — from a written composition to a single shape: regions, boundaries, substance, vertical circulation, the constants of derivation, tolerances, and where shape ends and appearance begins | Consumers that build shape; people writing a viewer |
16
- | [vocabulary.md](vocabulary.md) | **The vocabulary ledger** — the contract for attributes (which words the tools interpret) and the rule for how an open vocabulary is opened | People adding attributes; everyone |
17
- | [canonical-json.md](canonical-json.md) | **The machine format** — the schema of the canonical JSON and its stability rules | People building external connections, diffs, or composition |
18
- | [tools.md](tools.md) | **Tool reference** — the CLI, the MCP server, the public API | Programs and agents that use koyu |
19
- | [notation-v0.md](notation-v0.md) | **The record of how the notation came about** — the v0 comparison (DSL/YAML/JSON) and the addenda for each version. A historical document; language.md is the present tense | People who want the background |
20
- | [../../guide/en/](../../guide/en/README.md) | **The companion book, for learning** — tutorial, the six concepts, how-to guides, the causes and fixes for every diagnostic, worked examples. It holds no norms and links here instead | People learning koyu; people looking things up by task |
21
-
22
- ## How this folder is updated
23
-
24
- A change to behavior lands as three parts together: **an ADR (why) + a test (the guarantee) + the spec (the present tense)**. A change that writes an ADR without updating the spec is unfinished. The spec never accumulates dates or "addenda" — the body is rewritten in place, and git holds the versions. Adding to the vocabulary (an interpreted attribute) means putting it in the table in vocabulary.md; that listing is the contract, and an interpretation that is not listed must not be implemented (ADR-0008).
25
-
26
- Translations follow the same discipline. Japanese is the default locale and `spec/en/` is its translation; the terminology contract is [docs/terminology.md](../../docs/terminology.md). A change to a normative statement is made in both locales in the same commit — `test/i18n.test.ts` fails if a page loses its counterpart, if the code in an example drifts apart, or if the heading structure diverges.
27
-
28
- ## The version this describes
29
-
30
- This set of documents describes koyu v0.16.0. If it diverges from the package version, fix whatever diverged.
@@ -1,101 +0,0 @@
1
- **English** · [日本語](../canonical-json.md)
2
-
3
- # Machine-format reference — the canonical JSON
4
-
5
- As of koyu v0.16.0. Emitted by `koyu json <entry>` / `toCanonical(model)`.
6
-
7
- **What is this for?** It is **the definition of what makes two buildings the same, written down.**
8
- The authored form (.muro) is free in line order and spelling, so whether two files are the same
9
- building is not decided by their text. The canonical form gives that question a single answer —
10
- the same composition always yields the same bytes, and a different composition always yields different bytes.
11
-
12
- That narrows its uses to two: **the yardstick that shows the semantic diff (`koyu diff`) is right**
13
- (asking the diff itself proves nothing, so an independent judgement is needed — the tests are written
14
- against this), and **an exit for programs that have no .muro parser** (Ugatsu's export, MCP's `canonical_json`).
15
-
16
- **It is not a substrate.** `semanticDiff` takes Models and never goes through the canonical JSON.
17
- Layer composition happens in `parse-file.ts`, over .muro layers, before canonicalisation.
18
- There is no reader (`fromCanonical`); the only way into the system is `parse` — one authored source is enough.
19
-
20
- > This is a reference. If you are learning koyu, start at [guide/en/start.md](../../guide/en/start.md).
21
-
22
- ## Two versions — the format's and the language's
23
-
24
- What the document names first is **the version of this format itself**. `koyu` comes next and is the language version, not the format version.
25
-
26
- | Key | Version of what | When it rises |
27
- |---|---|---|
28
- | `format` | **the spelling of the canonical JSON** — the set of keys, their order, the collation, the normalization, the spelling of numbers. Currently `koyu-canonical/1.0` | the minor when a key is added (the bytes of a document that does not carry it are unchanged), the major when an existing spelling changes (the bytes of existing documents change) |
29
- | `koyu` | **the language version of the source** ([language.md](language.md) §2), passed through. **It is absent when nothing was declared** | when the semantics of the language change (ADR-0017) |
30
-
31
- They are two because **the same semantics may be re-spelled with different keys**. Adding the boundary's direction (the `a` key) changed the spelling without changing a single word of the language. Conversely the language version may rise while the spelling stays put.
32
-
33
- **A source with no version declaration is not stamped with one.** The default language version is "the newest this tool knows" (language.md §2), so stamping it would make the document claim a version its author never wrote — and **the bytes of the same input would change** on the day the tool's default moves. Determinism is a promise this format makes; it is not left to a tool's default. A source that wants its meaning pinned writes `koyu 1.0`.
34
-
35
- ## The stability rules (why this format exists)
36
-
37
- 1. **The same composition always emits byte-identical JSON.** The keys of a record shape (the top level, levels, spaces, boundaries, openings, segs, columns) are in **the fixed order this schema defines**, and the keys that come from the source (level names, paths, asset names, attribute keys) are in **collation order**. `spaces` are in path order, `boundaries` in lexicographic order of `between` (and, within an identical `between`, in canonical order of content), and `zones`, `assets`, and `polygons` in key order. **Arrays whose declaration order carries no meaning (openings, segs, areas, the rectangles of a region union, a column's `x`/`y` grid names, the endpoints of a drawn line) are also placed in canonical order of content** — writing the same composition with the lines in a different order yields the same bytes (ADR-0013).
38
-
39
- **`columns` is the exception — a column declaration's order is meaning, so it is never sorted** (ADR-0029). No two columns stand on the same grid intersection and the earlier declaration wins (ADR-0023), so swapping two lines changes which columns actually stand. Sorting them would make two different buildings emit identical bytes, and this format's whole reason for existing would be lost for columns. **When order carries meaning, the canonical order is the declared order.**
40
- 2. **It is the authored composition, after composing.** import, spans, stack, and **bands** are already expanded and do not survive. Default boundaries (derived — ADR-0014) do not appear: the canonical JSON holds only the authored composition, and the meaning (default walls included) lives in the Model after derivation. A consumer applies `deriveDefaultBoundaries` before reading meaning from it.
41
- 3. **It preserves the spelling that was written.** A position stays a grid reference (`"at": "Y2+1820"`), a region is a 4-tuple of grid names, and **the direction of a boundary is the `a` key** (the space written first — `edge`/`swing` are read from that side; added in ADR-0013 because without it the swing cannot be recovered from the JSON alone). The canonical form does not re-say things. The only exceptions are spellings that carry no meaning: a descending region (`X2..X1`) is normalized to ascending coordinates. A polygon's vertex list is geometry (a cycle) and is not reordered. The interior cut positions derived by a band (language.md §3) have no written spelling, so they are spelled by the **floor rule**: the offset from the largest grid line at or below that coordinate (the bare grid name when the offset is 0). The two ends of a band, and both ends across it, keep the spelling that was written.
42
-
43
- ## The norms for the bytes (collation, normalization, numbers)
44
-
45
- "Byte-identical" in rule 1 means something only once the following four are settled as norms. **An implementation written in another language emits the same bytes by following them.**
46
-
47
- 1. **The encoding is UTF-8, the newline is LF, the indent is two spaces, and one newline ends the document.** Non-ASCII is emitted raw, never escaped (`"name": "居室"`). What is escaped is what JSON demands (`"`, `\`, control characters) and nothing else.
48
- 2. **The collation is ascending code point order, which is the ascending order of the emitted UTF-8 bytes.** Locale collation (anything like `localeCompare`) is not used. **JavaScript's `<` and its default `sort` cannot be used here** — those are UTF-16 code-unit order, which does not agree with code point order: 𠮟 (U+20B9F) is a surrogate pair, so under `<` it is smaller than 﨑 (U+FA11), while in UTF-8 `EF A8 91` (﨑) comes before `F0 A0 AE 9F` (𠮟). Both are characters in actual Japanese use, so the difference is not theoretical. The norm sits on "the bytes of this format itself" because that is the side an implementation in another language agrees with when written plainly. The implementation is `compareCanonical` (`src/core/model.ts`).
49
- 3. **Text is NFC.** The source is normalized to NFC as it is read, and **identity (paths, uids, names) is decided there** — a space whose name is spelled "か + dakuten" is the same space as one spelled with the composed `が`, and writing both is a duplicate-path error. Without normalization the document would carry two keys nothing can tell apart. **NFKC is not used** — it would rewrite `㎡` into `m2` and `①` into `1`, and that contradicts preserving the spelling that was written (rule 3).
50
- 4. **Numbers are spelled in their shortest round-trip form.** `0.30` is emitted as `0.3`. Nothing is rounded, padded, or converted. Magnitudes that need an exponent (`1e+23`, `1e-7`) come out in exponent form.
51
-
52
- ## The schema
53
-
54
- ```jsonc
55
- {
56
- "format": "koyu-canonical/1.0", // the format version (the version of this document's own spelling)
57
- "koyu": "1.0", // the language version (the declaration passed through; absent when the source omitted it)
58
- "name": "…", // optional
59
- "unit": "mm",
60
- "grid": { "X": [0, 6400, …], "Y": [0, 5600, …] }, // coordinate arrays (grid names X1.. are implicit)
61
- "levels": { "L1": { "z": 0, "h": 3600, "slab": 600 },
62
- "B1": { "z": -4200, "h": 3600, "slab": 600, "underground": 1 }, … }, // underground is declared, never inferred from a negative z (ADR-0022)
63
- "assets": { "SD1": { "kind": "door", "attrs": { "w": 800, "style": "sliding", … } }, … }, // optional
64
- "polygons": { "/site": [[-2600, -7000], [38000, -7000], …] }, // optional
65
- "columns": [ // optional (ADR-0023). **In declared order** — the first-wins rule makes order meaning
66
- { "size": 900, "d": 1200, "levels": ["B2","B1","L1"], "x": ["X2","X3"], "y": ["Y2"], "attrs": { "spec": "SRC" } }, …
67
- ],
68
- "zones": { "/L3/A": { "attrs": { "name": "Aタイプ", "use": "exclusive" } }, … }, // optional
69
- "spaces": {
70
- "/L5/A/ldk": {
71
- "type": "ldk",
72
- "level": "L5", // only when level: was explicit (a membership differing from the path head — a maisonette). The default (the path head) is omitted
73
- "at": [["X1+3200","Y1","X2+3200","Y1+4000"], ["X2+3200","Y1","X3","Y1+2400"]], // a flat 4-tuple when there is a single rectangle
74
- "attrs": { "name": "LDK", "floor": "オーク" },
75
- "areas": [{ "at": ["X1","Y1-4600","X2","Y1-2600"], "attrs": { … } }] // optional
76
- }, …
77
- },
78
- "boundaries": [
79
- {
80
- "between": ["/L5/A/hall", "/L5/corridor"], // two paths, ascending
81
- "a": "/L5/A/hall", // the direction as written — edge/swing are read from the a side
82
- "kind": "wall", // wall|open|stair|shaft|void
83
- "t": 180, "air": true, "edge": "S", // each optional
84
- "attrs": { "spec": "RC" }, // optional
85
- "line": ["X3,Y1", "X3+600,Y2-900"], // optional (ADR-0022). The endpoints of a drawn line — the grid-word spelling as written.
86
- // A segment has no direction, so the pair is canonicalised into ascending resolved coordinates
87
- "openings": [{ "kind": "door", "ref": "D1", "w": 900, "h": 2100,
88
- "at": "X4", // a number for a ratio, a string for a grid reference
89
- "edge": "S", "hinge": "E", "swing": "b", // optional
90
- "attrs": { "name": "玄関", "style": "hinged" } }],
91
- "segs": [{ "w": 1800, "at": "X5", "edge": "S", "attrs": { "spec": "受付ガラス" } }]
92
- }, …
93
- ]
94
- }
95
- ```
96
-
97
- Omission rules: a key with no value (koyu, h, slab, t, edge, attrs, line, and so on) is not emitted. An empty block (assets/polygons/columns/zones/areas/openings/segs) is not emitted either. An attribute value in numeric form is a number; anything else is a string. `underground` is emitted as `1` only when true.
98
-
99
- ## The implementation is the norm
100
-
101
- `toCanonical()` in `src/core/model.ts` is the norm, and this document is a copy of it. If the two diverge, decide on the spot which one to change, and bring the spec into line.