@kensnzk/koyu 0.14.0 → 0.16.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 (212) hide show
  1. package/README.ja.md +4 -2
  2. package/README.md +5 -3
  3. package/dist/cli.js +156 -81
  4. package/dist/cli.js.map +1 -1
  5. package/dist/core/derive.d.ts +259 -0
  6. package/dist/core/derive.d.ts.map +1 -0
  7. package/dist/core/derive.js +570 -0
  8. package/dist/core/derive.js.map +1 -0
  9. package/dist/{check.d.ts → core/diagnose.d.ts} +11 -12
  10. package/dist/core/diagnose.d.ts.map +1 -0
  11. package/dist/{check.js → core/diagnose.js} +232 -221
  12. package/dist/core/diagnose.js.map +1 -0
  13. package/dist/core/diff.d.ts.map +1 -0
  14. package/dist/{diff.js → core/diff.js} +84 -41
  15. package/dist/core/diff.js.map +1 -0
  16. package/dist/{fabric.d.ts → core/fabric.d.ts} +4 -0
  17. package/dist/core/fabric.d.ts.map +1 -0
  18. package/dist/{fabric.js → core/fabric.js} +4 -3
  19. package/dist/core/fabric.js.map +1 -0
  20. package/dist/{graph.d.ts → core/graph.d.ts} +1 -3
  21. package/dist/core/graph.d.ts.map +1 -0
  22. package/dist/{graph.js → core/graph.js} +43 -51
  23. package/dist/core/graph.js.map +1 -0
  24. package/dist/core/light.d.ts +24 -0
  25. package/dist/core/light.d.ts.map +1 -0
  26. package/dist/{light.js → core/light.js} +15 -10
  27. package/dist/core/light.js.map +1 -0
  28. package/dist/{model.d.ts → core/model.d.ts} +124 -13
  29. package/dist/core/model.d.ts.map +1 -0
  30. package/dist/{model.js → core/model.js} +193 -50
  31. package/dist/core/model.js.map +1 -0
  32. package/dist/core/parse.d.ts.map +1 -0
  33. package/dist/{parse.js → core/parse.js} +528 -116
  34. package/dist/core/parse.js.map +1 -0
  35. package/dist/{poly.d.ts → core/poly.d.ts} +3 -2
  36. package/dist/core/poly.d.ts.map +1 -0
  37. package/dist/{poly.js → core/poly.js} +8 -9
  38. package/dist/core/poly.js.map +1 -0
  39. package/dist/core/site.d.ts.map +1 -0
  40. package/dist/core/site.js.map +1 -0
  41. package/dist/core/tolerance.d.ts +26 -0
  42. package/dist/core/tolerance.d.ts.map +1 -0
  43. package/dist/core/tolerance.js +48 -0
  44. package/dist/core/tolerance.js.map +1 -0
  45. package/dist/{vertical.d.ts → core/vertical.d.ts} +41 -12
  46. package/dist/core/vertical.d.ts.map +1 -0
  47. package/dist/{vertical.js → core/vertical.js} +45 -104
  48. package/dist/core/vertical.js.map +1 -0
  49. package/dist/core/vocabulary.d.ts +40 -0
  50. package/dist/core/vocabulary.d.ts.map +1 -0
  51. package/dist/core/vocabulary.js +164 -0
  52. package/dist/core/vocabulary.js.map +1 -0
  53. package/dist/{axo.d.ts → draw/axo.d.ts} +1 -1
  54. package/dist/draw/axo.d.ts.map +1 -0
  55. package/dist/{axo.js → draw/axo.js} +53 -81
  56. package/dist/draw/axo.js.map +1 -0
  57. package/dist/draw/index.d.ts +3 -0
  58. package/dist/draw/index.d.ts.map +1 -0
  59. package/dist/draw/index.js +11 -0
  60. package/dist/draw/index.js.map +1 -0
  61. package/dist/draw/plan.d.ts +10 -0
  62. package/dist/draw/plan.d.ts.map +1 -0
  63. package/dist/draw/plan.js +284 -0
  64. package/dist/draw/plan.js.map +1 -0
  65. package/dist/index.d.ts +15 -11
  66. package/dist/index.d.ts.map +1 -1
  67. package/dist/index.js +49 -12
  68. package/dist/index.js.map +1 -1
  69. package/dist/mcp.js +71 -40
  70. package/dist/mcp.js.map +1 -1
  71. package/dist/parse-file.d.ts +1 -1
  72. package/dist/parse-file.d.ts.map +1 -1
  73. package/dist/parse-file.js +1 -1
  74. package/dist/parse-file.js.map +1 -1
  75. package/dist/validate/access.d.ts +6 -0
  76. package/dist/validate/access.d.ts.map +1 -0
  77. package/dist/validate/access.js +238 -0
  78. package/dist/validate/access.js.map +1 -0
  79. package/dist/validate/envelope.d.ts +4 -0
  80. package/dist/validate/envelope.d.ts.map +1 -0
  81. package/dist/validate/envelope.js +55 -0
  82. package/dist/validate/envelope.js.map +1 -0
  83. package/dist/validate/index.d.ts +60 -0
  84. package/dist/validate/index.d.ts.map +1 -0
  85. package/dist/validate/index.js +77 -0
  86. package/dist/validate/index.js.map +1 -0
  87. package/dist/validate/light.d.ts +6 -0
  88. package/dist/validate/light.d.ts.map +1 -0
  89. package/dist/validate/light.js +28 -0
  90. package/dist/validate/light.js.map +1 -0
  91. package/dist/validate/runs.d.ts +16 -0
  92. package/dist/validate/runs.d.ts.map +1 -0
  93. package/dist/validate/runs.js +60 -0
  94. package/dist/validate/runs.js.map +1 -0
  95. package/dist/validate/site.d.ts +6 -0
  96. package/dist/validate/site.d.ts.map +1 -0
  97. package/dist/validate/site.js +63 -0
  98. package/dist/validate/site.js.map +1 -0
  99. package/editors/vscode/.vscodeignore +2 -0
  100. package/editors/vscode/README.md +28 -0
  101. package/editors/vscode/extension.js +150 -0
  102. package/editors/vscode/language-configuration.json +19 -0
  103. package/editors/vscode/package.json +57 -0
  104. package/editors/vscode/syntaxes/koyu.tmLanguage.json +226 -0
  105. package/examples/basement/main.muro +1 -1
  106. package/examples/complex/main.muro +1 -1
  107. package/examples/house/main.muro +2 -2
  108. package/examples/house.muro +2 -2
  109. package/examples/mansion.muro +2 -2
  110. package/examples/office.muro +2 -2
  111. package/examples/steps/01-one-room.muro +1 -1
  112. package/examples/steps/02-two-rooms.muro +1 -1
  113. package/examples/steps/03-door.muro +1 -1
  114. package/examples/steps/04-exterior.muro +1 -1
  115. package/examples/steps/05-two-storeys.muro +1 -1
  116. package/examples/steps/06-finished.muro +2 -2
  117. package/examples/tower/main.muro +1 -1
  118. package/examples/twin/L1.muro +136 -119
  119. package/examples/twin/L5.muro +85 -123
  120. package/examples/twin/assets.muro +10 -8
  121. package/examples/twin/basement.muro +43 -34
  122. package/examples/twin/core.muro +148 -65
  123. package/examples/twin/hotel.muro +66 -107
  124. package/examples/twin/main.muro +73 -67
  125. package/examples/twin/office.muro +87 -88
  126. package/examples/twin/podium.muro +309 -97
  127. package/examples/twin/residence.muro +61 -116
  128. package/examples/twin/site.muro +16 -13
  129. package/examples/two-rooms.canonical.json +4 -2
  130. package/examples/two-rooms.muro +2 -2
  131. package/package.json +16 -1
  132. package/spec/README.md +28 -0
  133. package/spec/canonical-json.md +98 -0
  134. package/spec/composition.md +121 -0
  135. package/spec/derivation.md +393 -0
  136. package/spec/en/README.md +30 -0
  137. package/spec/en/canonical-json.md +101 -0
  138. package/spec/en/composition.md +121 -0
  139. package/spec/en/derivation.md +393 -0
  140. package/spec/en/language.md +164 -0
  141. package/spec/en/notation-v0.md +145 -0
  142. package/spec/en/scope.md +229 -0
  143. package/spec/en/semantics.md +132 -0
  144. package/spec/en/tools.md +108 -0
  145. package/spec/en/validation.md +79 -0
  146. package/spec/en/vocabulary.md +103 -0
  147. package/spec/language.md +163 -0
  148. package/spec/notation-v0.md +184 -0
  149. package/spec/scope.md +229 -0
  150. package/spec/semantics.md +130 -0
  151. package/spec/tools.md +106 -0
  152. package/spec/validation.md +79 -0
  153. package/spec/vocabulary.md +114 -0
  154. package/src/cli.ts +165 -80
  155. package/src/core/derive.ts +852 -0
  156. package/src/{check.ts → core/diagnose.ts} +260 -229
  157. package/src/{diff.ts → core/diff.ts} +84 -40
  158. package/src/{fabric.ts → core/fabric.ts} +4 -3
  159. package/src/{graph.ts → core/graph.ts} +47 -60
  160. package/src/core/light.ts +69 -0
  161. package/src/{model.ts → core/model.ts} +236 -52
  162. package/src/{parse.ts → core/parse.ts} +584 -116
  163. package/src/{poly.ts → core/poly.ts} +8 -9
  164. package/src/core/tolerance.ts +55 -0
  165. package/src/{vertical.ts → core/vertical.ts} +65 -115
  166. package/src/core/vocabulary.ts +197 -0
  167. package/src/{axo.ts → draw/axo.ts} +51 -94
  168. package/src/draw/index.ts +11 -0
  169. package/src/draw/plan.ts +344 -0
  170. package/src/index.ts +181 -35
  171. package/src/mcp.ts +76 -40
  172. package/src/parse-file.ts +2 -2
  173. package/src/validate/access.ts +279 -0
  174. package/src/validate/envelope.ts +59 -0
  175. package/src/validate/index.ts +107 -0
  176. package/src/validate/light.ts +43 -0
  177. package/src/validate/runs.ts +87 -0
  178. package/src/validate/site.ts +84 -0
  179. package/dist/axo.d.ts.map +0 -1
  180. package/dist/axo.js.map +0 -1
  181. package/dist/check.d.ts.map +0 -1
  182. package/dist/check.js.map +0 -1
  183. package/dist/diff.d.ts.map +0 -1
  184. package/dist/diff.js.map +0 -1
  185. package/dist/fabric.d.ts.map +0 -1
  186. package/dist/fabric.js.map +0 -1
  187. package/dist/graph.d.ts.map +0 -1
  188. package/dist/graph.js.map +0 -1
  189. package/dist/light.d.ts +0 -15
  190. package/dist/light.d.ts.map +0 -1
  191. package/dist/light.js.map +0 -1
  192. package/dist/model.d.ts.map +0 -1
  193. package/dist/model.js.map +0 -1
  194. package/dist/parse.d.ts.map +0 -1
  195. package/dist/parse.js.map +0 -1
  196. package/dist/plan.d.ts +0 -10
  197. package/dist/plan.d.ts.map +0 -1
  198. package/dist/plan.js +0 -354
  199. package/dist/plan.js.map +0 -1
  200. package/dist/poly.d.ts.map +0 -1
  201. package/dist/poly.js.map +0 -1
  202. package/dist/site.d.ts.map +0 -1
  203. package/dist/site.js.map +0 -1
  204. package/dist/vertical.d.ts.map +0 -1
  205. package/dist/vertical.js.map +0 -1
  206. package/src/light.ts +0 -63
  207. package/src/plan.ts +0 -472
  208. /package/dist/{diff.d.ts → core/diff.d.ts} +0 -0
  209. /package/dist/{parse.d.ts → core/parse.d.ts} +0 -0
  210. /package/dist/{site.d.ts → core/site.d.ts} +0 -0
  211. /package/dist/{site.js → core/site.js} +0 -0
  212. /package/src/{site.ts → core/site.ts} +0 -0
@@ -1,29 +1,32 @@
1
1
  # 敷地と外構 — 隔離レイヤー (ADR-0011)
2
2
  #
3
- # 敷地の形はこの記法で**唯一「書かれる形」**である。他はすべて生成物だが、
4
- # 敷地は測量に由来する所与で、設計の結果ではない。だから別ファイルに隔離する。
5
- #
6
- # 14頂点の不整形。三方が道路で、北西が隣地。建蔽率62%の残り38%が公開空地になる —
7
- # この規模の容積を積むには総合設計の上乗せが要るので、広場は制度の裏づけでもある。
3
+ # 14頂点の不整形、23,167㎡。基壇は敷地の南半分に寄せ、**北半分は広場と緑地**にする —
4
+ # この規模の容積を積む再開発は、公開空地が制度の裏づけになる (総合設計・都市再生特区)。
5
+ # 基壇の四隅の斜めは、この敷地の辺の振れをそのまま建物に写した隅切りである。
8
6
 
9
- # 外部そのもの — 領域を持たない。地下の土圧壁や機械階のルーバーが面する先である
10
7
  space /out exterior name:外部
11
8
 
12
9
  zone /site name:敷地 site:1 area:23167.40
13
10
 
14
11
  polygon /site 0,24000 14000,6000 46000,0 92000,3000 126000,0 158000,9000 168000,38000 164000,80000 168000,118000 152000,144000 104000,151200 58000,149000 16000,142000 0,100000
15
12
 
16
- # 道路 (接道は導出される — 幅員は road: が言う)
17
13
  space /road-s exterior X1..X21 Y1-22000..Y1 level:L1 name:南側道路 road:25000
18
14
  space /road-e exterior X21..X21+18000 Y1..Y19 level:L1 name:東側道路 road:18000
19
15
  space /road-n exterior X1..X21 Y19..Y19+16000 level:L1 name:北側道路 road:16000
20
16
 
21
- # 外構 — 敷地に載る屋外の床。建物の周りの公開空地である
22
- space /site/plazaS exterior X3..X19 Y1..Y3 level:L1 name:南側広場
23
- space /site/plazaE exterior X19..X21 Y3..Y17 level:L1 name:東側広場
24
- space /site/plazaN exterior X3..X19 Y17..Y19 level:L1 name:北側広場
25
- space /site/plazaW exterior X1..X3 Y3..Y17 level:L1 name:西側広場
17
+ # 外構。北の大きな広場が公開空地の主体
18
+ space /site/plazaS exterior X2..X19 Y1..Y4 level:L1 name:南側広場
19
+ space /site/plazaE exterior X19..X21 Y1..Y12 level:L1 name:東側広場
20
+ space /site/plazaW exterior X1..X2 Y1..Y12 level:L1 name:西側広場
21
+ space /site/green exterior X1..X21 Y12..Y19 level:L1 name:北側広場・緑地
26
22
 
27
23
  boundary /site/plazaS /road-s type:open
28
24
  boundary /site/plazaE /road-e type:open
29
- boundary /site/plazaN /road-n type:open
25
+ boundary /site/green /road-n type:open
26
+ boundary /site/green /road-e type:open
27
+ boundary /site/plazaE /road-s type:open
28
+ boundary /site/plazaW /road-s type:open
29
+ boundary /site/plazaS /site/plazaE type:open
30
+ boundary /site/plazaS /site/plazaW type:open
31
+ boundary /site/green /site/plazaE type:open
32
+ boundary /site/green /site/plazaW type:open
@@ -1,5 +1,6 @@
1
1
  {
2
- "koyu": "0.5",
2
+ "format": "koyu-canonical/1.0",
3
+ "koyu": "1.0",
3
4
  "name": "二室",
4
5
  "unit": "mm",
5
6
  "grid": {
@@ -16,7 +17,8 @@
16
17
  "levels": {
17
18
  "L1": {
18
19
  "z": 0,
19
- "h": 2400
20
+ "h": 2400,
21
+ "slab": 150
20
22
  }
21
23
  },
22
24
  "spaces": {
@@ -4,13 +4,13 @@
4
4
  # 書いてあるのは、扉を吊るために宣言した境界と、外皮の境界だけ。
5
5
  # 両室に daylight:1 を書いたので、窓が要る — `koyu light` が 1/7 を確かめる (ADR-0020)。
6
6
 
7
- koyu 0.5
7
+ koyu 1.0
8
8
  name 二室
9
9
  unit mm
10
10
 
11
11
  grid X 0 3600 7200
12
12
  grid Y 0 4500
13
- level L1 0 h:2400
13
+ level L1 0 h:2400 slab:150
14
14
 
15
15
  space /L1/a room X1..X2 Y1..Y2 name:居室A daylight:1
16
16
  space /L1/b room X2..X3 Y1..Y2 name:居室B daylight:1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kensnzk/koyu",
3
- "version": "0.14.0",
3
+ "version": "0.16.0",
4
4
  "description": "空間を一次要素とするテキストネイティブ建築記述の探求 — writing architecture, not buildings",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -10,7 +10,17 @@
10
10
  "types": "./dist/index.d.ts",
11
11
  "default": "./dist/index.js"
12
12
  },
13
+ "./validate": {
14
+ "types": "./dist/validate/index.d.ts",
15
+ "default": "./dist/validate/index.js"
16
+ },
17
+ "./draw": {
18
+ "types": "./dist/draw/index.d.ts",
19
+ "default": "./dist/draw/index.js"
20
+ },
13
21
  "./examples/*": "./examples/*",
22
+ "./spec/*": "./spec/*",
23
+ "./syntax": "./editors/vscode/syntaxes/koyu.tmLanguage.json",
14
24
  "./package.json": "./package.json",
15
25
  "./node": {
16
26
  "types": "./dist/parse-file.d.ts",
@@ -24,9 +34,14 @@
24
34
  "files": [
25
35
  "dist",
26
36
  "src",
37
+ "spec",
27
38
  "examples",
39
+ "editors",
28
40
  "NOTICE"
29
41
  ],
42
+ "engines": {
43
+ "node": ">=22"
44
+ },
30
45
  "scripts": {
31
46
  "koyu": "tsx src/cli.ts",
32
47
  "build": "tsc -p tsconfig.build.json",
package/spec/README.md ADDED
@@ -0,0 +1,28 @@
1
+ [English](en/README.md) · **日本語**
2
+
3
+ # spec/ — koyuの仕様 (現在形)
4
+
5
+ > **これはリファレンスである。koyuをこれから学ぶなら [guide/start.md](../guide/start.md) から始めること。**引くための文書であって、通して読んで身につく作りにはしていない。
6
+
7
+ このフォルダは**いまのkoyuがどう振る舞うか**の規範文書 (normative reference) である。経緯や理由は書かない — それは [docs/decisions/](../docs/decisions/) (ADR) と [docs/log/](../docs/log/) の仕事で、specは決定が積もった後の**結論の現在形**だけを保つ。両者が食い違ったら、実装とテストが正であり、specを直す。
8
+
9
+ ## 文書の地図
10
+
11
+ | 文書 | 内容 | 読者 |
12
+ |---|---|---|
13
+ | [language.md](language.md) | **言語リファレンス** — 字句・全宣言の文法・合成 (import)・既定値・位置指定 | .muroを書く人・パーサを触る人 |
14
+ | [semantics.md](semantics.md) | **意味論リファレンス** — モデル・導出 (壁線分/垂直隣接/半屋外/高さ)・検査の一覧・問い (doors/stats/light/site) の定義 | 導出やcheckを触る人・結果を解釈する人 |
15
+ | [derivation.md](derivation.md) | **導出の規範** — 書かれた構成から一意な形へ。領域・境界・実体・縦動線・導出の定数・許容値、そして形と見た目の線引き | 形を作る消費者・ビュアーを書く人 |
16
+ | [vocabulary.md](vocabulary.md) | **語彙の台帳** — 属性の契約 (どの語をツールが解釈するか)・開かれた語彙の開き方の規則 | 属性を足す人・全員 |
17
+ | [canonical-json.md](canonical-json.md) | **機械形式** — 正準JSONのスキーマと安定性の規則 | 外部接続・diff・合成を作る人 |
18
+ | [tools.md](tools.md) | **ツールリファレンス** — CLI・MCPサーバー・公開API | koyuを使うプログラム・エージェント |
19
+ | [notation-v0.md](notation-v0.md) | 記法の**成立記録** — v0の書き比べ (DSL/YAML/JSON) と各版の追補。歴史文書であり現在形はlanguage.mdが正 | 経緯を知りたい人 |
20
+ | [../guide/](../guide/README.md) | **学ぶための対の本** — チュートリアル・六つの考え・how-to・診断の原因と直し方・実例集。規範は持たず、ここへリンクする | koyuを学ぶ人・使い方から引きたい人 |
21
+
22
+ ## 更新の作法
23
+
24
+ 機能の変更は三点セットで着地する: **ADR (なぜ) + テスト (保証) + spec (現在形)**。ADRを書いてspecを更新しない変更は未完了である。specには日付や「追補」を積まない — 本文をその場で書き換え、版はgitが持つ。語彙 (解釈される属性) の追加は vocabulary.md の表に載せることが契約であり、載っていない解釈は実装してはならない (ADR-0008)。
25
+
26
+ ## 対象の版
27
+
28
+ この文書群は koyu v0.16.0 の記述である。パッケージの版と乖離したら、乖離した箇所を直す。
@@ -0,0 +1,98 @@
1
+ [English](en/canonical-json.md) · **日本語**
2
+
3
+ # 機械形式リファレンス — 正準JSON
4
+
5
+ koyu v0.16.0 現在。`koyu json <entry>` / `toCanonical(model)` が出力する。
6
+
7
+ **これは何のためにあるか。****「同じ建物とは何か」の定義を書き下したもの**である。
8
+ 原本 (.muro) は行順も綴りも自由なので、二つのファイルが同じ建物かどうかはテキストでは決まらない。
9
+ 正準形はその問いに一意な答えを与える — 同じ構成なら常に同じバイト列、違う構成なら必ず違うバイト列。
10
+
11
+ だから使い道は二つに絞られる。**意味差分 (`koyu diff`) が正しいことを確かめる物差し**
12
+ (diff 自身に聞いても意味が無いので、独立した判定が要る — テストがこれで書かれている) と、
13
+ **`.muro` のパーサを持たないプログラムへの出口** (穿つのエクスポート、MCP の `canonical_json`) である。
14
+
15
+ **土台ではない。**`semanticDiff` は Model を受け取り、正準JSONを経由しない。
16
+ レイヤー合成は `parse-file.ts` が `.muro` の層に対して行い、正準化はその後である。
17
+ 読み込む側 (`fromCanonical`) は無く、系への入口は `parse` だけ — 原本は一つでよい、という選択である。
18
+
19
+ ## 二つの版 — 形式の版と言語の版
20
+
21
+ 文書が最初に名乗るのは**この形式自身の版**である。`koyu` はその次に来る言語版であって、形式版ではない。
22
+
23
+ | キー | 何の版か | 上がるとき |
24
+ |---|---|---|
25
+ | `format` | **正準JSONの綴り** — キーの集合・並び・照合順・正規化・数の綴り。現在は `koyu-canonical/1.0` | minorはキーが増えたとき (増えたキーを持たない文書のバイトは変わらない)、majorは既存の綴りが変わったとき (既存の文書のバイトが変わる) |
26
+ | `koyu` | **原本の言語版** ([language.md](language.md) §2) の素通し。**書かれていなければ出ない** | 言語の意味論が変わったとき (ADR-0017) |
27
+
28
+ 二つが別なのは、**同じ意味論を別のキーで綴り直すことがありうる**からである。境界の向き (`a` キー) の追加は言語を一語も変えずに綴りを変えた。逆に、言語版が上がっても綴りが変わらないことはある。
29
+
30
+ **版宣言の無い原本には版を刻まない。**言語版の既定は「そのツールの最新版」なので (language.md §2)、刻めば著者の書いていない版を名乗ることになり、しかもツールの既定が動いた日に**同じ入力のバイトが変わる**。決定性はこの形式の側の約束であって、ツールの既定に預けるものではない。意味を固定したい原本は `koyu 1.0` と書く。
31
+
32
+ ## 安定性の規則 (この形式の存在理由)
33
+
34
+ 1. **同じ構成からは常にバイト同一のJSONが出る。** 記録の形のキー (最上位・レベル・空間・境界・開口・seg・柱) は**このスキーマが定める固定順**で、原本に由来するキー (レベル名・パス・アセット名・属性キー) は**照合順**に並ぶ。`spaces` はパス順、`boundaries` は `between` の辞書順 (同一 `between` は内容の正準順)、`zones`・`assets`・`polygons` はキー順に並ぶ。**宣言順に意味の無い配列 (openings・segs・areas・領域合併・柱の通り名 `x`/`y`・描かれた線の端点) も内容の正準順に並ぶ** — 同じ構成を別の行順で書いても同じバイト列になる (ADR-0013)。
35
+
36
+ **例外は `columns` である — 柱の宣言順は意味だから並べ替えない** (ADR-0029)。同じ通りの交点に二本は立たず先の宣言が勝つ (ADR-0023) ので、二行を入れ替えると実際に立つ柱が変わる。並べ替えると別の建物が同一のバイト列になり、この形式の存在理由が柱について失われる。**順序が意味を持つ配列の正準順は、宣言順そのものである。**
37
+ 2. **合成後の、書かれた構成である。** import・スパン・stack・**帯 (band)** は展開済みで残らない。既定境界 (derived — ADR-0014) は出ない — 正準JSONは書かれた構成のみで、意味 (既定壁を含む) は導出後のModelが持つ。消費者は `deriveDefaultBoundaries` を適用してから意味を読むこと。
38
+ 3. **書かれた表記を保存する。** 位置は通り参照のまま (`"at": "Y2+1820"`)、領域は通り名4つ組、**境界の向きは `a` キー** (先に書いた空間 — `edge`/`swing` はこの側から読む。ADR-0013で追加: これが無いとJSONだけでは開き勝手を復元できない) — 正準形は語り直さない。例外は意味を持たない綴りだけ: 領域の逆順表記 (`X2..X1`) は座標昇順に正規化される。polygonの頂点列は幾何 (巡回) なので並べ替えない。帯 (band — language.md §3) が導出する内側の切り位置は、書かれた綴りが存在しないため**床規則**で綴られる: その座標以下で最も大きい通り芯からのオフセット (オフセット0なら通り名だけ)。帯の両端と直交方向の両端は書かれた綴りのままである。
39
+
40
+ ## バイトの規範 (照合順・正規化・数)
41
+
42
+ 規則1の「バイト同一」は、次の四つが規範として定まっていて初めて意味を持つ。**別の言語で書かれた実装も、これに従えば同じバイト列を出す。**
43
+
44
+ 1. **符号化は UTF-8、改行は LF、字下げは空白2つ、文書の末尾に改行が一つ。**非ASCIIはエスケープせず生のまま出る (`"name": "居室"`)。エスケープするのはJSONが要求するもの (`"` `\` 制御文字) だけである。
45
+ 2. **照合順は符号位置の昇順であり、これは出力されるUTF-8バイトの昇順に等しい。**ロケールの照合 (`localeCompare` の類) は使わない。**JavaScriptの `<` と既定の `sort` はここでは使えない** — あれはUTF-16コード単位順で、符号位置順と一致しない: 𠮟 (U+20B9F) は代用対なので `<` では 﨑 (U+FA11) より小さいが、UTF-8では `EF A8 91` (﨑) が `F0 A0 AE 9F` (𠮟) より前である。どちらも日本語の実在の字であり、差は理論上のものではない。規範を「この形式自身のバイト」に置くのは、素直に書かれた他言語の実装と一致する側だからである。実装は `compareCanonical` (`src/core/model.ts`)。
46
+ 3. **文字は NFC である。**原本は読み込みのときにNFCへ正規化され、**同一性 (パス・uid・名) もそこで決まる** — `が` を「か + 濁点」と綴った空間は、合成済みの `が` と綴った空間と同じ空間であり、両方書けばパスの重複エラーになる。正規化しなければ、見分けのつかない二つのキーが並ぶ文書が出る。**NFKCは採らない** — `㎡` を `m2` に、`①` を `1` に書き換えてしまい、それは書かれた表記の保存 (規則3) に反する。
47
+ 4. **数は最短往復表記で綴る。**`0.30` は `0.3` として出る。丸めも桁揃えも単位変換もしない。指数が要る大きさ (`1e+23`・`1e-7`) は指数表記になる。
48
+
49
+ ## スキーマ
50
+
51
+ ```jsonc
52
+ {
53
+ "format": "koyu-canonical/1.0", // 形式版 (この文書自身の綴りの版)
54
+ "koyu": "1.0", // 言語版 (書かれた版宣言の素通し。省略された原本では出ない)
55
+ "name": "…", // 任意
56
+ "unit": "mm",
57
+ "grid": { "X": [0, 6400, …], "Y": [0, 5600, …] }, // 座標配列 (通り名は X1.. が暗黙)
58
+ "levels": { "L1": { "z": 0, "h": 3600, "slab": 600 },
59
+ "B1": { "z": -4200, "h": 3600, "slab": 600, "underground": 1 }, … }, // underground は宣言のみ (zの負値から推定しない — ADR-0022)
60
+ "assets": { "SD1": { "kind": "door", "attrs": { "w": 800, "style": "sliding", … } }, … }, // 任意
61
+ "polygons": { "/site": [[-2600, -7000], [38000, -7000], …] }, // 任意
62
+ "columns": [ // 任意 (ADR-0023)。**宣言順のまま** — 先勝ちの規則を持つため
63
+ { "size": 900, "d": 1200, "levels": ["B2","B1","L1"], "x": ["X2","X3"], "y": ["Y2"], "attrs": { "spec": "SRC" } }, …
64
+ ],
65
+ "zones": { "/L3/A": { "attrs": { "name": "Aタイプ", "use": "exclusive" } }, … }, // 任意
66
+ "spaces": {
67
+ "/L5/A/ldk": {
68
+ "type": "ldk",
69
+ "level": "L5", // 明示の level: (パス先頭と異なる所属 — メゾネット等) のみ。既定 (パス先頭) は省略
70
+ "at": [["X1+3200","Y1","X2+3200","Y1+4000"], ["X2+3200","Y1","X3","Y1+2400"]], // 矩形1つなら平坦な4つ組
71
+ "attrs": { "name": "LDK", "floor": "オーク" },
72
+ "areas": [{ "at": ["X1","Y1-4600","X2","Y1-2600"], "attrs": { … } }] // 任意
73
+ }, …
74
+ },
75
+ "boundaries": [
76
+ {
77
+ "between": ["/L5/A/hall", "/L5/corridor"], // 昇順の2パス
78
+ "a": "/L5/A/hall", // 書かれた向き — edge/swingはa側から読む
79
+ "kind": "wall", // wall|open|stair|shaft|void
80
+ "t": 180, "air": true, "edge": "S", // それぞれ任意
81
+ "attrs": { "spec": "RC" }, // 任意
82
+ "line": ["X3,Y1", "X3+600,Y2-900"], // 任意 (ADR-0022)。描かれた線の端点 — 通り語の綴りのまま。
83
+ // 線分は向きを持たないので、対は解決座標の昇順に正準化される
84
+ "openings": [{ "kind": "door", "ref": "D1", "w": 900, "h": 2100,
85
+ "at": "X4", // 比率なら数値、通り参照なら文字列
86
+ "edge": "S", "hinge": "E", "swing": "b", // 任意
87
+ "attrs": { "name": "玄関", "style": "hinged" } }],
88
+ "segs": [{ "w": 1800, "at": "X5", "edge": "S", "attrs": { "spec": "受付ガラス" } }]
89
+ }, …
90
+ ]
91
+ }
92
+ ```
93
+
94
+ 省略規則: 値の無いキー (koyu・h・slab・t・edge・attrs・line等) は出力されない。空のブロック (assets/polygons/columns/zones/areas/openings/segs) も出力されない。属性値は数値の形なら数値、それ以外は文字列。`underground` は真のときだけ `1` として出る。
95
+
96
+ ## 実装の正
97
+
98
+ `src/core/model.ts` の `toCanonical()` が正であり、本書はその写しである。乖離したらどちらを直すかをその場で決め、specを合わせる。
@@ -0,0 +1,121 @@
1
+ [English](en/composition.md) · **日本語**
2
+
3
+ # 合成の規則
4
+
5
+ koyu v0.16.0 / muro 1.0 現在。文法は [language.md](language.md) §8、範囲の規範は [scope.md](scope.md)。
6
+
7
+ **合成は時間と分担のためにあり、大きさのためではない。**分担して書く、例外を差分として書く、計画の上に as-built を重ねる — これらが合成の用途である。一棟が大きいから分けるのではない。
8
+
9
+ USD に倣って六つの規則を定める。**この六つが揃ってはじめて合成が使える。**揃っていないことの帰結は「同じ入力から違う結果が出る」であって、それは原本ではない。
10
+
11
+ ---
12
+
13
+ ## 規則1 — 層は明示された強度順序を持つ
14
+
15
+ **`import` 行の並びが強度の宣言である。**深さ優先で平坦化した列が層の順序であり、**後の層ほど強い**。entry は添字0で最も弱い。同じ層が二度 import されれば、最初の位置を保つ (合成は一度だけ)。
16
+
17
+ ```muro-part
18
+ koyu 1.0
19
+ grid X 0 6400 12800
20
+ level L1 0 h:3600 slab:600
21
+ import ./plan.muro # 層1
22
+ import ./as-built.muro # 層2 — こちらが強い
23
+ ```
24
+
25
+ **強度は走査の順ではない。**entry の行が `import` より後ろにあっても、entry は添字0のままである。順序で決めていたら、`import` 行を上下に動かしただけで結果が変わってしまう。
26
+
27
+ ```sh
28
+ koyu layers <entry.muro> # 層を強度順に印字する
29
+ ```
30
+
31
+ ## 規則2 — 単一の値は、最も強い層の意見が勝つ
32
+
33
+ 厚みも仕様も用途も階高も、上書きは一つの規則で説明される。
34
+
35
+ ```muro-part
36
+ over /L5/A/ldk h:2600 spec:改修後
37
+ over /L5/A/hall /L5/corridor t:200 type:open
38
+ over level L3 h:2600
39
+ over asset SD1 w:900
40
+ ```
41
+
42
+ `over` は空間・ゾーン・境界・レベル・アセットを対象にとる。書き方から対象の種別が決まる — パス1つなら空間 (無ければゾーン)、パス2つなら境界、`level` / `asset` に続けて名を書けばそれぞれ。
43
+
44
+ **同じ層が同じ属性に二度意見を持つのはエラーである。**どちらが勝つかが決まらないからで、これは「暗黙の解決を残さない」の直接の帰結である。
45
+
46
+ ## 規則3 — 集合は、明示された編集で合成する
47
+
48
+ **暗黙のマージをしない。**同じ座に複数の意見がありうるもの — 開口・seg・area・柱 — はすべてこの規則に属す。
49
+
50
+ ```muro-part
51
+ over /L5/A/hall /L5/corridor
52
+ - door D2 # 削除
53
+ = door D1 w:1000 # 置換 (書いた属性だけを差し替える)
54
+ + window w:600 h:1200 at:0.9 name:W1 # 追加
55
+ drop /L5/A/store # 空間 (その関係も一緒に消える)
56
+ drop /L5/a /L5/b # 境界
57
+ drop column C1 # 柱の宣言
58
+ ```
59
+
60
+ **同一性は「含む対象 + その中で一意な名」である** ([scope.md §5](scope.md#5-同一性))。`name:` を持たない要素は編集の対象にできない — 指す言葉が無いからである。`+` で足す要素には `name:` が要り、同じ対象の中で重複すればエラーである。
61
+
62
+ **規則3が、これまで特殊扱いされてきたものを普通にする。**同じ場所に複数の層が意見を持ちうるものは、暗黙の勝ち負けではなく明示された編集で解決される。**特殊なのは値の種類であって、規則ではない。**専用構文を作らない。
63
+
64
+ ## 規則4 — 定義と上書きを区別する
65
+
66
+ | | 文 | 対象が既にあるとき | 対象が無いとき |
67
+ |---|---|---|---|
68
+ | **定義** | `space` `boundary` `zone` `asset` `level` `polygon` | **エラー** (重複) | 定義する |
69
+ | **上書き** | `over` | 上書きする | **エラー** |
70
+
71
+ 二つは別の文であって、書き方から区別がつく。存在しないものに意見だけを足すのは、たいてい綴り違いか、層の順序の思い違いである。
72
+
73
+ ## 規則5 — 同じ入力からは常に同じ結果が出る
74
+
75
+ 入力には**層とその順序の宣言**を含む。同じ entry からは常に同じ層の列が出て、同じ層の列からは常に同じモデルが出る。
76
+
77
+ **上書きの跡は機械形式に残らない。**`over` で `h:2400` にした模型と、最初から `h:2400` と書いた模型は、同じ正準JSONを与える。正準形が答えるのは「同じ建物か」であって「どう書かれたか」ではない。
78
+
79
+ ## 規則6 — 出所が追える
80
+
81
+ 最終的な値を、どの層が与えたかを示せる。
82
+
83
+ ```sh
84
+ koyu layers <entry.muro> --attrs
85
+ ```
86
+
87
+ ```text
88
+ Layers (weakest first — later layers are stronger):
89
+ 0 main.muro
90
+ 1 plan.muro
91
+ 2 as-built.muro
92
+
93
+ Attribute provenance:
94
+ boundary:/L1/a|/L1/b:t ← 2 as-built.muro
95
+ space:/L1/a:h ← 2 as-built.muro
96
+ space:/L1/a:spec ← 2 as-built.muro
97
+ ```
98
+
99
+ API では `model.attrSrc` (キーは `<種別>:<対象>:<属性キー>`、値は `model.layers` の添字)。
100
+
101
+ ---
102
+
103
+ ## 衝突とエラー
104
+
105
+ 合成の解決が定まらない状態は、**モデルが組み上がる前に止まる** (構文・合成エラー = `SourceError`。`check --json` では SYN01 に写る)。壊れた JSON を JSON パーサが弾くのと同じ層にあり、診断として後から報告するものではない。
106
+
107
+ | 状態 | 扱い |
108
+ |---|---|
109
+ | 空間パス・ゾーンパス・アセット名・敷地形状の重複 | エラー (両者の出所つき) |
110
+ | `grid` / `name` / `koyu` の再宣言 | エラー (同値でも) |
111
+ | `over` の対象が無い / `drop` の対象が無い | エラー |
112
+ | 同じ層が同じ属性に二度意見を持つ | エラー |
113
+ | 集合の編集で名が無い / 一意でない / 重複する | エラー |
114
+ | 同じファイルの二重 import・循環 | 冪等 (一度だけ合成される) |
115
+
116
+ ## 何を合成しないか
117
+
118
+ - **バリアント (USD の variant)** — 案の分岐は持たない。分岐は git が持つ
119
+ - **アセットの入れ子参照** — アセットはアセットを参照しない
120
+ - **層ごとの名前空間接頭辞** — パスの階層がすでに名前空間である
121
+ - **層の部分的な読み込み** — 層は丸ごと合成される