@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,132 +0,0 @@
1
- **English** · [日本語](../semantics.md)
2
-
3
- # Semantics reference — derivation, checking, queries
4
-
5
- As of koyu v0.16.0. For the grammar see [language.md](language.md). What is written here is what is derived from what was authored, what is checked, and what the queries answer — form, quantity, and the inside/outside distinction are all absent from the authored source, and all defined here as derivations.
6
-
7
- > This is a reference. If you are learning koyu, start at [guide/en/start.md](../../guide/en/start.md).
8
-
9
- ## 1. The model
10
-
11
- The composed model consists of: `spaces` (path → space: type, level, rectangle union, areas, attributes, provenance), `boundaries` (a list of relations: a/b paths, kind, t/air/edge, openings, segs, provenance), `zones` (path → aggregation), `assets` (name → opening type), `polygons` (path → site shape), `columns` (column declarations, in declared order — ADR-0023/0029), `grid`, and `levels`. The provenance (`file`) is **the key the loader gave**, used in the position prefix of errors and warnings (`file:line`). The CLI and MCP read files, so what lands there is **a resolved absolute path** (when `parseFiles` is handed a dictionary of strings, it is that key).
12
-
13
- ## 2. Derivation in plan
14
-
15
- **Shared edges.** The wall centerline segment between two spaces is derived as the shared edge of their rectangle unions — the interval where they overlap on the same line. Collinear intervals are merged into one, so an opening can be placed on a single segment even when it spans several rectangles.
16
-
17
- **Exterior boundaries.** A boundary with a space that has no region (an `exterior`, say) is what remains of the room's perimeter once the intervals shared with other spaces are removed. Because that remainder is split across several edges, placing an opening requires selecting one with `edge:`. The compass direction of `edge` is read from the rectangle of the a side (the space written first).
18
-
19
- **Default boundaries (ADR-0014).** Where two spaces with regions touch in plan on the same level (including two spaces whose level is undetermined) and not one boundary is declared for that pair, a `wall` default boundary is derived after composition (`derived`). This is the horizontal "default is a wall", symmetric with the vertical "default is a floor" — an undeclared contact means "wall", not "undefined". A default wall carries no door and so is not passable, and it is drawn identically to a bare declared wall. If even one boundary is declared for that pair (including an edge-restricted one), nothing is derived. Contact with an `exterior` that has a region also derives one (and counts toward road frontage). Default boundaries do not appear in the canonical JSON — the canonical JSON is the authored composition, and the meaning, after derivation, lives in the Model.
20
-
21
- **Placing openings.** A ratio `at` is the center position along the segment, clamped so that the opening stays within it. An explicit grid-reference position is not clamped — if center ± w/2 leaves the segment it is an error (within a tolerance), as is using a Y reference on a horizontal segment or an X reference on a vertical one. Openings on the same segment must satisfy center-to-center distance ≥ (w₁+w₂)/2.
22
-
23
- ## 3. Vertical derivation and the height invariant
24
-
25
- **Vertical adjacency is not declared.** Spaces on consecutive levels are vertically adjacent where they overlap in plan. The default reading is "there is a floor". Only the exceptions are declared as boundaries: `stair` (passable), `shaft` (continuous but not passable), or `void` (the absence of a floor).
26
-
27
- **The height invariant (the floor-height check).** For each space, `ceiling height (heff) + the slab above ≤ the floor-to-floor height (to the next level's z)` is checked, and exceeding it is a collision error. `levels` displays this stack-up as a textual section. **Void exemption**: a lower space joined by a void boundary is declaratively exempted from the invariant. Only at a coverage ratio ≥99% (a full-height void) may a ceiling height that spans levels be declared — under a partial void the lower ceiling height stays within its own floor. The space above a void is expected to be `type:void` (otherwise a warning — the implementation and its tests are the norm here, and the spec was brought into line with them; ADR-0013).
28
-
29
- **The surface elements (floor, ceiling, roof).** Only a level's `slab` (the floor-construction thickness) gives a floor — leave it out and not one floor is generated on that storey (SUF03). The ceiling is given by the effective ceiling height `heff` (the space's `h`, then its level's `h`) — if that is undetermined, no ceiling is generated (SUF01). A void (`type:void`) has neither floor nor ceiling; the exterior and semi-outdoor spaces have neither ceiling nor roof. A roof is laid over the range that no space above covers, and **where a level sits above, the ceiling height is not read** — that level gives both the apex and the thickness (ADR-0024; the formula is in [derivation.md](derivation.md) §3.6). **The rules are deterministic** — where a value is missing, no default is invented and no element is made. So the same composition always yields the same shape, but **that the shape has come out thin must be told.** That is why the sufficiency checks (SUF01-04) exist.
30
-
31
- ## 4. Derived properties
32
-
33
- **Semi-outdoor (isSemiOutdoor).** Derived rather than declared: a space that has a region and carries an `open` or `air:1` boundary with the outside (`type:exterior`). Balconies, terraces, exterior stairs, and gardens become this. It is reported separately in the area table (not counted as interior floor area), given a coefficient in the daylight check, and drawn in a paler tone with thinner lines in plan.
34
-
35
- **Covered above (isCoveredAbove).** Whether a space is overlapped from above by a space on any level. Even the presence of a roof is derived rather than declared — the semi-outdoor coefficient in the daylight check (below) reads it.
36
-
37
- **Passability (passable).** A wall is passable only when it carries a door. `open` and `stair` are always passable. `shaft` and `void` are never passable. `air:1` is about shielding, not about passage (a railing wall cannot be walked through).
38
-
39
- ## 5. The checks (check), in one table
40
-
41
- The primary form of `check` is a structured diagnostic (`checkDiagnostics` — ADR-0016): `code` (the ledger below, which is the implementation's `DIAGNOSTIC_CODES`; a test machine-checks that the two agree), `severity` (an invariant property of the code — to change the weight, mint a new code), `message` (the Japanese body — no position prefix), provenance (`line`/`file`), the subject path (`path` — for a boundary, both paths), and a related position (`related` — the earlier of a duplicate pair, and so on). `check` also returns a compatible string form (`file:N行目: body`), with the same items in the same order. An error says the composition does not stand up; a warning says something is suspect.
42
-
43
- Diagnostic messages are emitted in Japanese by the implementation. The English gloss in the table is a description, not the message text.
44
-
45
- | Code | Severity | Summary |
46
- |---|---|---|
47
- | REF01 | error | A boundary references an undefined space path |
48
- | BND01 | error | A boundary between a space and itself |
49
- | BND02 | error | A duplicate boundary on the same pair of spaces (identical down to the edge restriction — this covers a wall/open contradiction. ADR-0013; related = the earlier one) |
50
- | BND03 | error | A wall boundary to a space on a different level (vertical takes type:stair/shaft/void) |
51
- | BND04 | error | A boundary between spaces that do not touch (no segment can be derived) |
52
- | LVL01 | error | Duplicate level z |
53
- | GEO01 | error | Overlapping regions within one space (the rectangles of the union) |
54
- | GEO02 | error | Overlapping regions between spaces on the same level (related = the later one) |
55
- | VRT01 | error | The premise of a vertical boundary (stair/shaft/void) — it may only join spaces that have both a region and a level |
56
- | VRT02 | error | A vertical boundary between non-adjacent levels |
57
- | VRT03 | error | A vertical boundary between spaces that do not overlap in plan |
58
- | OPN01 | error | Wrong axis for hinge (W/E on a horizontal segment, N/S on a vertical one) |
59
- | OPN02 | error | Openings overlapping on the same segment (center to center < (w₁+w₂)/2) |
60
- | OPN04 | error | There is no boundary segment on which to place the opening |
61
- | OPN05 | error | Several boundary segments — ambiguous (select a side with edge:) |
62
- | OPN06 | error | The opening is wider than the boundary segment |
63
- | OPN07 | error | Wrong axis for an explicit opening position (a Y reference on a horizontal segment, an X reference on a vertical one) |
64
- | OPN08 | error | An explicit opening position overruns the segment (grid references are not clamped — within a tolerance) |
65
- | SEG01 | error | An area on a space that has no region |
66
- | SEG04 | error | There is no boundary segment on which to place the seg (the seg counterpart of OPN04) |
67
- | SEG05 | error | Several boundary segments for the seg — ambiguous (the seg counterpart of OPN05) |
68
- | SEG06 | error | The seg is wider than the boundary segment (the seg counterpart of OPN06) |
69
- | SEG07 | error | Wrong axis for an explicit seg position (the seg counterpart of OPN07) |
70
- | SEG08 | error | An explicit seg position overruns the segment (the seg counterpart of OPN08) |
71
- | HGT01 | error | Height invariant violated — collision into the floor above (ceiling height + the slab above > the floor-to-floor height) |
72
- | HGT02 | error | Insufficient coverage for a partial void (below 99% coverage a ceiling height spanning levels may not be declared) |
73
- | SUF01 | error | The ceiling height cannot be determined — neither the space's `h` nor the level's. There is no height to extrude, so no ceiling and no roof can be generated (voids, the exterior and semi-outdoor spaces are excluded — ADR-0034) |
74
- | SUF02 | error | A space with a region whose level cannot be determined — z is undetermined, so not one solid can be generated |
75
- | SIT01 | error | Duplicate vertex in the site shape |
76
- | SIT02 | error | The site shape is self-intersecting |
77
- | UID01 | error | A uid made only of digits (the parser's numeric coercion would lose the distinction between tokens — ADR-0015) |
78
- | UID02 | error | A uid containing whitespace |
79
- | ATT01 | error | An interpreted attribute's value is not a positive number (`h` `riser` `tread` `entry` `landing` `lane` `slope` `road` `area` — a value that does not match the ledger's type never quietly falls back to the default. ADR-0028) |
80
- | ATT02 | error | An interpreted attribute's value is not in the ledger's vocabulary (`ceiling` 0/1, `turn` R/L, `site` 0/1, `style` hinged/sliding/auto — ADR-0028) |
81
- | ATT03 | error | An attribute key that is not in the ledger and carries no namespace (dot-separated, e.g. `acme.sensor`) — ADR-0033 |
82
- | UID03 | error | A duplicate uid (unique across the whole model, spanning space and zone) |
83
- | UID04 | error | A duplicate `name` within the containing subject (openings and segs within a boundary, areas within a space, columns within the model). A name an opening inherits from an asset is the type's name and does not count — ADR-0039 |
84
- | DAY01 | error | The value of daylight is neither 0 nor 1 (being in scope is a binary declaration — ADR-0020) |
85
- | VER01 | error | A default boundary would be derived in a koyu 0.1 file (an older version is accepted only when meaning is preserved — ADR-0017) |
86
- | VER02 | error | In a koyu 0.3-or-earlier file, a space of a type that used to be inferred in scope (unit/room/ldk/bedroom/living) carries no daylight (in 0.4 it falls out of scope, so the meaning changes — ADR-0020) |
87
- | VER03 | error | A koyu 0.4-or-earlier file uses a 0.5 word (a vertical-circulation declaration, a drawn line, a column, underground) — the older processor does not know the word, so the form is silently never generated (ADR-0017/0021/0022/0023) |
88
- | VER04 | error | A koyu 0.5-or-earlier file uses a 1.0 word (the override `over`, the removal `drop`, or a set edit `+` `-` `=` directly under `over`) — the older processor does not know the word, so neither the override nor the removal happens and it silently becomes a different building (ADR-0017/0035/0038) |
89
- | SYN01 | error | A syntax or composition error (a copy of SourceError — `check --json` only; check does not turn thrown exceptions into diagnostics, the parser throws them) |
90
- | BND05 | warning | A pair of spaces carrying a mix of edge-restricted and unrestricted boundaries (the segments overlap) |
91
- | BND06 | warning | The boundary segment is of zero length (no edge remains on the perimeter) |
92
- | VRT04 | warning | The space above a void boundary is not type:void |
93
- | VRT05 | warning | An opening on a vertical boundary (not interpreted) |
94
- | VRT06 | warning | A seg on a vertical boundary (not interpreted) |
95
- | OPN03 | warning | An opening on an open boundary (it has no effect on passage — it is always passable) |
96
- | SEG02 | warning | An area spills outside its parent region |
97
- | SEG03 | warning | A seg on an open boundary (no wall — not interpreted) |
98
- | ZON01 | warning | An empty zone (no spaces beneath it) |
99
- | ZON02 | warning | A zone sharing a path with a space |
100
- | SUF03 | warning | The level has no `slab`, so not one floor is generated on that storey (the height invariant cannot be formulated either; the shape is settled, hence a warning — ADR-0034) |
101
- | SIT04 | warning | A polygon with no corresponding zone |
102
- | RUN01 | error | More than one vertical-circulation declaration on one space (stair/ramp/escalator/lift — one per space. ADR-0021) |
103
- | RUN02 | error | The value of a vertical-circulation declaration is not an ascending direction (N/E/S/W; for lift it is 1) |
104
- | RUN03 | error | The region of a vertical circulation is not a single rectangle, or its level cannot be determined (a union gives no step division) |
105
- | RUN05 | error | `form` is not straight/return, or a device that cannot fold declares one, or the flight length comes out at zero or less |
106
- | LIN01 | error | A drawn line does not separate the two spaces (both allocations must fall on opposite sides), or neither space has a region |
107
- | LIN02 | error | A line is drawn on a vertical boundary (drawing a line is an act of dividing a plan) |
108
- | LIN03 | warning | A drawn line cuts nothing (one side comes out empty) |
109
- | COL01 | warning | Not one column stands for a column declaration (the grid intersections have no floor — ADR-0023) |
110
- | COL02 | warning | A column declaration stands nowhere because an earlier declaration took the same intersections (the earlier one wins) |
111
- | SUF04 | warning | A vertical circulation is declared but not one shape is generated (there is no level above — a stair on the top floor and the like) |
112
- | BND07 | — | Retired — the "these touch but no boundary is declared" warning was abolished by ADR-0014 (an undeclared contact means the default wall) |
113
- | HGT03 | — | Retired — "no slab on the level above" merged into SUF03 (ADR-0034) |
114
- | HGT04 | — | Retired — "the ceiling height is unknown" merged into SUF01 and became an error (ADR-0034) |
115
- | HGT05 | — | Retired — "its level cannot be determined" merged into SUF02 and became an error (ADR-0034) |
116
- | RUN04 | — | Retired — "no level above, so no shape is generated" merged into SUF04 (ADR-0034) |
117
-
118
- ## 6. Queries — the same description, read differently
119
-
120
- **doors (egress and circulation).** The path of fewest doors over the space graph (edges are drawn by the passability of §4). `doorsBetween(from, to)` → the door count and the list of intermediate paths, or undefined if unreachable.
121
-
122
- **stats (area).** Interior floor area = the sum of the wall-centerline areas of spaces that have both a region and a level and are neither void, nor exterior, nor semi-outdoor. Subtotals by level; semi-outdoor reported separately; by zone (the sum over a path prefix — subdividing a dwelling into rooms never loses the language of the unit); by type; and by use (the effective use after zone→space inheritance).
123
-
124
- **light (daylighting).** Subjects: **only** the spaces with a region that carry `daylight:1` — being in scope is declared, never inferred from the type (the default is out of scope; ADR-0020). Where the denominator sits — a whole dwelling unit, or each room it is divided into — is chosen by the author, as the place `daylight:1` is written. Window area = the sum of w×h over the windows on that space's boundaries that carry `h`. Coefficient: 0.7 if the semi-outdoor space beyond the window **has a space above it** (under a balcony, under an eave), 1.0 if it is open above. Verdict: effective window area ≥ floor area / 7 (a coarse test, with no correction factors). The 1/7 ratio comes from the Japanese Building Standards Act.
125
-
126
- **site (the site).** Subject: zones marked `site:1`. Site area = the shoelace formula over the polygon if there is one, otherwise the union of the spaces on the site and the interior footprint — reconciled against the declaration (`area:`, the surveyed value) to ±0.05 m². A mismatch also becomes a warning in `check` (when a polygon is present — the same test in the CLI, the API, and MCP; ADR-0013). Road frontage = the total length of the boundary segments between spaces beneath the site zone and exteriors carrying `road:width` (the part where the building's own outer wall faces the road is not counted). Building footprint area = the union of the horizontal projections of the interior spaces (the inclusion rules are coarse). Building coverage ratio and floor area ratio are the quotients of these. These are terms of the Japanese Building Standards Act.
127
-
128
- **levels (the section stack-up).** Displays the levels in z order, as the stack-up of floor-to-floor height = ceiling height + slab + the remainder.
129
-
130
- ## 7. The conventions of drawing (plan)
131
-
132
- Form is a generated artifact — that several forms come from one composition is not a defect. The conventions of svgPlan: spaces are a pale fill (semi-outdoor paler still); walls are a black band along the derived segment (its weight from `t`); an open boundary is dashed; `air:1` is a thin solid line; a void is a dashed diagonal (with an "open above" projection on the level below); a door is its hinge and the quarter-circle of its swing (sliding/auto get a panel on the pocket side); a window is a centerline; a `seg` is a change of tone; an `area` is a pale fill with a dashed outline. Grid lines and their markers are drawn. The lowest level doubles as the site plan, drawing the site shape as a chain-dotted site boundary line (the polygon is included when reserving the sheet area).
package/spec/en/tools.md DELETED
@@ -1,108 +0,0 @@
1
- **English** · [日本語](../tools.md)
2
-
3
- # Tool reference — CLI, MCP, public API
4
-
5
- As of koyu v0.16.0. Every tool is a different entrance to the same derivations (semantics.md) — the CLI for hands, MCP for agents, the API for programs.
6
-
7
- > This is a reference. If you are learning koyu, start at [guide/en/start.md](../../guide/en/start.md); for the CLI worked through with real output, see [guide/en/cli.md](../../guide/en/cli.md).
8
-
9
- ## CLI (`koyu` / `npm run koyu --`)
10
-
11
- ```
12
- koyu <check|validate|layers|diff|plan|axo|doors|graph|stats|levels|runs|light|site|json> <file.muro> [引数...]
13
- ```
14
-
15
- | Command | Arguments | Output | Exit code |
16
- |---|---|---|---|
17
- | `check` | `--json` (emit Diagnostic[] as JSON — a syntax or composition error is copied into a single SYN01 so the JSON stays valid), `--strict` (exit 1 if there are warnings) | Whether the composition is structurally consistent; errors and warnings with provenance. The ledger of diagnostic codes is semantics.md §5. **It says nothing about architectural validity** (scope.md §3) | 0 = green / 1 = errors (with --strict, warnings too) |
18
- | `validate` | `--json` (emit Finding[] as JSON) | The architectural judgement (the ledger in validation.md). **This is not what check guarantees** — the type and the spelling of the codes both differ; only the exit-code convention is shared | 0 = no violation / 1 = violations |
19
- | `layers` | `--attrs` (the provenance of each attribute's final value) | The layers that took part in composition, weakest first. The face on which you can see with your own eyes that **there is no implicit resolution anywhere** (composition.md, rules 1 and 6) | 0 |
20
- | `diff` | `<b.muro>` (the target — the entry is the source), `--json` (emit ModelDiff as JSON) | The difference in the language of composition (ADR-0018): grid moves, renames (uid matches, path differs), field changes on spaces, boundaries, and openings. Line order, formatting, and the difference between a bare wall declaration and its omission (the default wall) are not differences | 0 = no difference / 1 = differences / 2 = the input is broken |
21
- | `plan` | `-l <level>` (default: the first level), `-o <out.svg>` (default: `<entry>-<level>.svg`) | Generates a plan as SVG | 0 / 2 (an undeclared level name — a question of how it was called. ADR-0028) |
22
- | `axo` | `-o <out.svg>` (default `out/axo.svg`), `-d NE\|NW\|SE\|SW` (default SE), `-l L1..L5` or `-l L1,L3`, `-s <scale>`, `--no-walls`, `--ceilings` | Generates an axonometric as SVG — floors, roofs, walls, columns and vertical circulation, projected (ADR-0026). It needs no runtime and no WebGL, so a solid can be checked with the same generate-and-look loop as a plan | 0 / 2 (an undeclared level name, an unreadable scale, an unknown direction — it never silently writes an empty SVG, nor one full of `NaN`. ADR-0028) |
23
- | `doors` | `/pathA /pathB` | The door count and the intermediate list; 1 if unreachable | 0/1/2 |
24
- | `graph` | — | The neighbors of each space (boundary kind, door count) | 0 |
25
- | `stats` | — | Area by level, semi-outdoor reported separately, by zone, by type, by use | 0 |
26
- | `levels` | — | The section stack-up as text (how the heights add up) | 0 / 1 |
27
- | `runs` | — | The vertical circulations — device, rise, whether it folds, and the derived slope and going length (ADR-0021). Riser counts and goings are checked by `check`'s RUN06 | 0 |
28
- | `light` | — | The 1/7 daylight verdict for **each room declared `daylight:1`** (scope is never inferred from the type — ADR-0020) | 0 = all pass / 1 / 1 = nothing in scope |
29
- | `site` | — | Site area (declared vs derived), road frontage, building coverage ratio, floor area ratio | 0 / 1 = no site |
30
- | `json` | — | The canonical JSON (canonical-json.md) | 0 |
31
-
32
- The entry is always a file path, and imports are composed automatically.
33
-
34
- ## The MCP server (`koyu-mcp` — ADR-0012)
35
-
36
- MCP over stdio (JSON-RPC 2.0, newline-delimited JSON). Zero dependencies and stateless (every tool takes `file` = the entry path and composes afresh each time). To register: `claude mcp add koyu -- npx -p @kensnzk/koyu koyu-mcp`.
37
-
38
- | Tool | Arguments | Returns |
39
- |---|---|---|
40
- | `model_summary` | file | Name, levels, layer composition, zones, assets, area, check counts — **call this first** |
41
- | `check` | file | ok; errors and warnings (with layer:line provenance); diagnostics (the structured form — ADR-0016; the same items in the same order as the strings) — **the gate; call it after every edit** |
42
- | `layers` | file | The {file, source} of every layer that took part in composition — to read the authored source |
43
- | `write_layer` | file, layer, content | Checks, then replaces wholesale (content that would not compose is never written — the source is left untouched; check errors are returned but saving an intermediate state is allowed). Writes are atomic. `.muro` only, and only beneath the entry's directory (verified on the relative path and on the symlink's real path; the content of files that do not take part in composition is not validated) |
44
- | `doors` | file, from, to | The path of fewest doors, or {unreachable} |
45
- | `validate` | file | The architectural verdicts (`findings` carry `rule`/`level`). **Not the check guarantee** — a surface that grows |
46
- | `spaces` | file, [level] | The list of spaces (path, type, area, semi-outdoor, provenance) |
47
- | `light` | file | The daylight verdict for each habitable room |
48
- | `site` | file | The site report (area reconciliation `areaMatch`, road frontage, coverage ratio, floor area ratio) |
49
- | `new_uids` | file, [count] | Mints persistent identity tokens (uid) that collide with nothing already composed into the model. **Nothing assigns one on its own**, so call it only when something has to be pointed at across renames |
50
- | `plan_svg` | file, level | The plan as an SVG string |
51
- | `canonical_json` | file | The canonical JSON |
52
-
53
- The standard agent loop: `model_summary` → `layers` → `write_layer` → (fix whatever check returns) → confirm the consequences with `doors`/`light`/`site`. History is git's job.
54
-
55
- ## The public API (`@kensnzk/koyu`)
56
-
57
- **The root entry is browser-safe** (it does not pull in node:fs). Only the entry points that use fs are split out into `@kensnzk/koyu/node`. The runtime it is declared to run on is Node 22 or newer (`engines`).
58
-
59
- | Entry | What is in it | Frozen |
60
- |---|---|---|
61
- | `@kensnzk/koyu` | everything listed below | the core part freezes (scope.md §8) |
62
- | `@kensnzk/koyu/node` | `parseFile(path)` / `parseFileWith(path, overlay)` — only the two that compose from fs | frozen |
63
- | `@kensnzk/koyu/validate` | the architectural judgement (validation.md) | **not frozen** — a face that grows |
64
- | `@kensnzk/koyu/draw` | SVG generation | **not frozen** — how it is called freezes, what is in the SVG does not |
65
- | `@kensnzk/koyu/examples/*` | the bundled buildings | — |
66
- | `@kensnzk/koyu/spec/*` | this specification itself (shipped in the package) | — |
67
-
68
- ```ts
69
- import { parse, check, doorsBetween, siteReport, svgPlan, toCanonical } from "@kensnzk/koyu";
70
- import { parseFile } from "@kensnzk/koyu/node";
71
- ```
72
-
73
- ### The face, written down
74
-
75
- **This table and the implementation's exports agree as sets** — if they disagree, a test fails (ADR-0037). `export *` is not used: the moment an export is added to a module, a promise nobody declared has been added to a face that freezes. **A face that freezes has to be written down.**
76
-
77
- <!-- api-surface -->
78
-
79
- | Face | Values | Types |
80
- |---|---|---|
81
- | Parsing and composition | `parse` `parseFiles` `parseWith` `tokenize` | `LayerLoader` |
82
- | The vocabulary of the model | — | `Model` `Space` `Zone` `Boundary` `Opening` `Seg` `Area` `Asset` `Level` `Rect` `Pt` `GridAxis` `GridRef` `SitePolygon` `Column` `ColumnDecl` `DrawnLine` `Edge` `BoundaryKind` `Attrs` `AttrValue` |
83
- | Queries, derivation, machine form | `areaM2` `zoneAreaM2` `unionAreaM2` `polygonAreaM2` `pointInPolygon` `polyBounds` `rectToPoly` `columnsFor` `displayName` `effectiveUse` `heff` `isIndoor` `isSemiOutdoor` `isCoveredAbove` `levelsSorted` `newUids` `toCanonical` `srcRef` `SourceError` `SUPPORTED_LANGUAGE_VERSIONS` `DEFAULT_LANGUAGE_VERSION` | — |
84
- | Structural diagnostics | `check` `checkDiagnostics` `DIAGNOSTIC_CODES` | `Diagnostic` `DiagnosticCode` `CheckResult` |
85
- | The spatial graph | `doorsBetween` `neighbors` `passable` `segmentsFor` `envelopeGaps` `deriveDefaultBoundaries` `placeOpening` `placeBand` | `Segment` `Route` `NeighborInfo` `Band` `PlacedBand` `BandError` `BandCode` |
86
- | The reference implementation of shape | `derive` `levelPitch` `DERIVATION_CONSTANTS` `TOLERANCES` `thicken` `bandLine` `band` `columnRect` `runPrism` `canonicalBoundaryOrder` | `Form` `FormInput` `FormLevel` `FormSpace` `FormBoundary` `FormPanel` `FormOpening` `FormSwing` `FormSeg` `FormColumn` `FormRun` `FormSite` `FormPlan` `FormPrism` `PlanEntity` `PlanClass` `PlanSubject` `PlanRole` `DeriveOptions` |
87
- | Floors, ceilings, roofs | `slabs` | `Slab` `SlabKind` |
88
- | Daylight | `daylightInputs` | `DaylightInput` |
89
- | Vertical circulation | `verticalRuns` `runSolids` `runDrawsForLevel` `slopeText` | `VerticalRun` `RunPart` `RunSolid` `RunDraw` `RunArrow` `RunDevice` `RunForm` `Seg2` |
90
- | The site | `siteReport` | `SiteReport` `RoadFrontage` |
91
- | Diffs | `semanticDiff` `renderDiff` | `ModelDiff` `FieldChange` `ChangedItem` `RenamedItem` `GridChange` `SpaceItem` `BoundaryItem` `BoundaryChange` `ColumnItem` |
92
- | Generation (not frozen) | `svgPlan` `svgAxo` | `PlanOptions` `AxoOptions` |
93
- | Validation (not frozen) | `validate` `VALIDATION_RULES` | `Finding` `ValidationRule` |
94
-
95
- ### What the face promises
96
-
97
- - **Composition entry points**: `parse(source)` (a single source — import is an error) / `parseFiles(files, entry)` (a set of virtual files — imports are resolved within that key space; for the browser) / `parseFile(path)` (fs) / `parseFileWith(path, overlay)` (fs plus a substitution — for the gate before writing) / `parseWith(loader, entry)` (your own loader). Every layer that took part is in `model.layers`, in composition order.
98
- - **Checking and queries**: `checkDiagnostics(model)` → `Diagnostic[]` (the primary form — code/severity/message/provenance/path/related. The ledger is `DIAGNOSTIC_CODES` and the code table is semantics.md §5. ADR-0016) / `check(model)` → {errors, warnings} (the compatible string form — the same items in the same order). The queries are `doorsBetween` / `daylightInputs` / `siteReport` / `zoneAreaM2` / `neighbors` / `passable` / `envelopeGaps` — **not one of them returns a verdict** (scope.md §4).
99
- - **The parts of derivation**: `segmentsFor` / `deriveDefaultBoundaries` (default boundaries — already applied by the parse family; use it when giving meaning to a model that came from canonical JSON) / `placeOpening` / `placeBand` (this "band" is an interval along a boundary segment — an opening or a seg — and is a different layer from the notation keyword `band` ⟨language.md §3⟩) / `columnsFor` / `heff` / `isSemiOutdoor` / `isCoveredAbove` / `levelsSorted`.
100
- - **The one entrance to shape**: `derive(model, {cut?})` → `Form` (ADR-0040). **The rules are held by [derivation.md](derivation.md), and this is its reference implementation.** `Form` carries no appearance at all — no colours, no typefaces, no line weights, no annotation strings, no symbols, no scale (scope.md §6). The ledger of constants is `DERIVATION_CONSTANTS` and the ledger of tolerances is `TOLERANCES`; the tables in derivation.md §5 and §6 are copies of them. `levelPitch(model, level)` answers the storey height (how far walls and columns rise) on its own.
101
- - **The canonical order of boundaries**: `canonicalBoundaryOrder(model)` — declaration order is information the canonical JSON discards, so **every derivation that reads boundaries in order uses this one** (ADR-0041). The boundary indices carried by the `Form` (`FormSeg.boundary` and the rest) index this order. Indexing the declaration array instead reads another boundary's annotation as soon as two lines are swapped.
102
- - **What is generated** (the parts `Form` assembles; each can also be called directly): `slabs(model)` (floors, ceilings and roofs — ADR-0024) / `verticalRuns(model)` (the shape of the vertical circulation — ADR-0021) / `runSolids(run)` (its solids) / `runDrawsForLevel(model, level)` (the drawing cut at that level). **None of them carries an appearance** — no colours, no line weights, no annotation strings. A viewer only maps them into geometry (scope.md §6).
103
- - **Drawing**: `svgPlan(model, {level, scale?})` / `svgAxo(model, {dir?, levels?, scale?, ceilings?, walls?})` / `toCanonical(model)`.
104
- - **Diffs**: `semanticDiff(a, b)` → `ModelDiff` (the difference in the language of composition — renames are detected by uid, and boundaries are compared as effective sets. Empty whenever `toCanonical` is identical. ADR-0018) / `renderDiff(d)` → lines of Japanese (an empty array means no difference).
105
- - **Identity**: `newUids(model, count?)` → a list of fresh uids (ADR-0039). **They collide with nothing already composed into that model**, while non-collision with layers not composed here is a probabilistic guarantee resting on 80 bits of randomness — only UID03 under `check` proves it ([scope.md §5](scope.md)). **Until it is called, no tool writes a uid.**
106
- - **Errors**: a syntax or composition error is a `SourceError` (line / raw / file — the message is `layer:line: body`). check never throws; it returns arrays.
107
-
108
- A worked consumer is the viewer ugatsu (github.com/kensnzk/ugatsu) — every derivation is a call into this API, and it holds no answers of its own.
@@ -1,79 +0,0 @@
1
- **English** · [日本語](../validation.md)
2
-
3
- # The ledger of verdicts — the validation surface
4
-
5
- As of koyu v0.16.0. **This surface does not freeze** ([scope.md §8](scope.md#8-the-eight-surfaces-that-100-freezes)).
6
-
7
- What `koyu check` says stops at "what is written is not self-contradictory as data" ([scope.md §3](scope.md#3-the-extent-of-the-guarantee--what-the-check-passed-means)). Whether it is sound as architecture is what this surface says. Causes and fixes are in [guide/en/validation.md](../../guide/en/validation.md).
8
-
9
- ## How it is kept apart from core
10
-
11
- So that the output of a verdict is never read as a guarantee about the source, **the types themselves are kept separate**.
12
-
13
- | | core's diagnostics | validation's verdicts |
14
- |---|---|---|
15
- | type | `Diagnostic` | `Finding` |
16
- | identifier | `code: "BND04"` | `rule: "daylight.ratio"` |
17
- | weight | `severity: "error" \| "warning"` | `level: "violation" \| "caution"` |
18
- | entrance | `checkDiagnostics(model)` / `koyu check` | `validate(model)` / `koyu validate` |
19
- | version | **freezes** | does not freeze — it grows, sharpens, and drops rules |
20
-
21
- Because the field names differ the two arrays cannot be mistaken for one another, and an attempt to concatenate them loses the type. **Making it impossible to speak of "core's green" and "the verdict's green" in the same words** is the purpose of this separation.
22
-
23
- `level` is an invariant property of the code — the same rule never comes out `violation` in one case and `caution` in another (the same discipline as core's severity). To change the weight, mint a new rule name.
24
-
25
- ## The ledger
26
-
27
- The implementation's `VALIDATION_RULES` (`src/validate/index.ts`) is the norm; this table is its copy. A test keeps the two sets identical.
28
-
29
- | Rule | level | Summary |
30
- |---|---|---|
31
- | `envelope.gap` | caution | A hole in the envelope — a stretch of the outline faces neither another space nor a declared boundary ([ADR-0025](../../docs/decisions/0025-envelope-gaps.md)). **Only a level on which at least one boundary to the outside is written** is checked (this is the consistency of "if you have started, finish", not a demand for completeness) |
32
- | `daylight.ratio` | violation | Effective window area < floor area / 7. The subjects are only the spaces that carry `daylight:1` ([ADR-0020](../../docs/decisions/0020-daylight-scope-is-declared.md)). A coarse test, with no correction factors applied |
33
- | `daylight.unknown` | caution | There is a window without `h`, so the window area could not be fully counted — the mark that distinguishes "it is enough" from "it was not counted" |
34
- | `stair.proportion` | caution | The derived steps are cramped (going < 240mm, or 2×riser + going outside 550-700mm). In a return stair the **tightest flight** stands for the whole |
35
- | `run.slope` | caution | The derived slope is steeper than the declared `slope:`, or it leaves the usual band for an escalator (about 1/1.7) |
36
- | `run.disconnected` | caution | The form of a vertical circulation is there, but no vertical boundary joins the levels (the shape exists, yet the graph cannot pass) |
37
- | `access.unreachable` | violation | A space with a region cannot reach an exterior space along passable boundaries. What is asked is **reachability, not the presence of a door**. Shafts (people cannot pass), voids (no floor) and exteriors are out of scope |
38
- | `access.voidonly` | violation | A space has passable boundaries, but every one of them leads to a `type:void` — the doors open onto a hole with no floor |
39
- | `access.throughtenant` | caution | Every route from a stair to the outside passes through a `use:rentable` space (an escape route that dies the moment the tenant locks up). Some designs do run a dedicated passage through, hence caution |
40
- | `access.parking` | violation | A car cannot get out of a `use:parking` space. A car passes only a `type:open` boundary, a door at least 2400mm wide, or a ramp (the vertical link of a space carrying `ramp:`) |
41
- | `access.backofhouse` | caution | A common space declaring a vertical run cannot be reached from a common corridor without passing through a `type:backyard`. Not asked at all in a building with no common corridor. Entry to the space itself must be **horizontal** (an approximation) |
42
- | `column.blocksdoor` | violation | A derived column overlaps a derived door ([ADR-0023](../../docs/decisions/0023-columns.md)). **Neither carries coordinates in the source**, so the collision only shows up in the derivation |
43
- | `site.escape` | violation | The building escapes the site shape. Beyond the containment of the four corners it looks at vertex intrusion and edge crossing, so it is correct on a concave site too. On the boundary counts as inside; tolerance 1mm. Exterior space tiles are not checked (an approximation) |
44
- | `site.area` | caution | The declaration of the site area (`area:`, the surveyed value) and the derivation from the polygon disagree by more than ±0.05 m² |
45
- | `site.frontage` | violation | The road frontage is under 2000mm (a coarse copy of Article 43 of the Japanese Building Standards Act). The part where the building's outer wall faces the road is not counted. **Not asked in a model with no `site:1` zone** — the 0 that would be derived means "not derivable", not "no frontage" |
46
-
47
- ## The thresholds
48
-
49
- A verdict's thresholds are **numbers on the architecture's side**, not invariants the authored composition must satisfy. They all sit in one place as constants of the implementation, and a section is added below this one when a second jurisdiction appears.
50
-
51
- | Constant | Value | Where it lives |
52
- |---|---|---|
53
- | `DAYLIGHT_DIVISOR` | 7 | `src/validate/light.ts` |
54
- | `TREAD_MIN` | 240mm | `src/validate/runs.ts` |
55
- | `STEP_RULE` | 550-700mm | same file |
56
- | `ESCALATOR_SLOPE` | 1/2.3 - 1/1.4 | same file |
57
- | `CAR_WIDTH_MIN` | 2400mm | `src/validate/access.ts` — the narrowest opening a car can pass (a 900mm door for people will not let a car out) |
58
- | `FRONTAGE_MIN` | 2000mm | `src/validate/site.ts` |
59
- | `COVERED_SEMI_FACTOR` | 0.7 | `src/core/light.ts` — this is **a coefficient, not a threshold**, so it lives in core (the derivation of what lies beyond the window) |
60
-
61
- ## The entrances
62
-
63
- ```sh
64
- koyu validate <file.muro> # for people. 0 = no violations / 1 = violations
65
- koyu validate <file.muro> --json # Finding[]
66
- ```
67
-
68
- ```ts
69
- import { validate, VALIDATION_RULES, type Finding } from "@kensnzk/koyu";
70
- ```
71
-
72
- In MCP it is the `validate` tool. **Every verdict can be called from MCP** — a verdict that cannot be called is, for a machine, as good as nonexistent.
73
-
74
- ## The discipline for adding one
75
-
76
- Adding a verdict is cheap. It grows one surface, and the language's version does not move. Only two things are to be kept.
77
-
78
- 1. **Put it in `VALIDATION_RULES`, and write a row in this table and a section in [guide/en/validation.md](../../guide/en/validation.md).** A test keeps the sets identical
79
- 2. **Do not touch core.** If you find yourself wanting to add an attribute or a diagnostic to core for the sake of a verdict, then it may not be a verdict but structural consistency — decide by holding it against [scope.md §3](scope.md#3-the-extent-of-the-guarantee--what-the-check-passed-means)
@@ -1,103 +0,0 @@
1
- **English** · [日本語](../vocabulary.md)
2
-
3
- # The vocabulary ledger
4
-
5
- This document puts the essay's position — "meaning is given by a vocabulary, not by a vast class hierarchy" — into practice. It is the contract for what may be attached to each element and which words the tools interpret, and it is the rule for *how* an open vocabulary is opened (ADR-0007 / ADR-0008).
6
-
7
- > This is a reference. If you are learning koyu, start at [guide/en/start.md](../../guide/en/start.md).
8
-
9
- ## Five rules
10
-
11
- **1. A kind states only the topology of a relation.** A boundary's type (wall/open/stair/shaft/void) is a word that the graph, the derivations, and the checks interpret structurally, and adding to that set is the last resort. This is the same stance IFC takes in letting a space boundary (IfcRelSpaceBoundary) say only Physical or Virtual. On a space, exactly two type words are interpreted structurally — `exterior` and `void` — and both correspond to a fact of composition (is it outside; does it count towards floor area). **The entrance to a verdict is never the type; it is an attribute, and each attribute names what the tool does** (`daylight` for the daylight check, `road` for street frontage width, `site` for site aggregation, `use` for the aggregation axis — ADR-0020).
12
-
13
- **2. The name of a thing belongs to the `spec` vocabulary.** Railing, RC, LGS, EW, glass partition… the value of `spec` is a free word, and tools do not interpret it (they only carry it). What IFC would make an element class (IfcRailing, IfcCurtainWall) is a value of `spec` here — the consequence of the turn by which a thing is an attribute of a relation.
14
-
15
- **3. An interpreted attribute goes in the ledger.** The attributes a tool reads (marked ★ below) are a contract; changing one means writing an ADR. Any other `k:v` is free, but so that one meaning does not acquire two words, a word whose meaning has settled is added to this ledger and grown there. There is one ledger.
16
-
17
- **4. Units and formats.** Lengths are in mm, a position along a segment is 0..1, and areas are reported in m². Attribute keys are lowercase Latin letters; values are free (Japanese is fine), while the values of core words are Latin.
18
-
19
- **5. Inheritance and overriding.** `use` is inherited from zone to space, and a declaration on the space wins. `floor` is overridden over an interval by space→area. `spec` is overridden over an interval by boundary→seg. An uncounted subdivision (area/seg) carries only overrides and does not affect the composition (ADR-0003).
20
-
21
- ## The ledger, by element
22
-
23
- ### space
24
- | Attribute | Interpreted | Meaning |
25
- |---|---|---|
26
- | type | ★ in part | An open vocabulary. The only two words interpreted structurally are `exterior` (outside — may split into several: /out/road etc.) and `void` (a void through the floor). Everything else is a free word, and whether the daylight check applies is in particular never inferred from the type (ADR-0020) |
27
- | road | ★ | The width in mm of an exterior space — the mark of a road. The site command derives road frontage from it (ADR-0009) |
28
- | region | ★ | `X?..X? Y?..Y?`, joined with `+` (for an L shape). Offsets such as `X2+600` are allowed |
29
- | level: | ★ | States the level explicitly. The default is the first path segment. Used for a grouping that spans levels (a maisonette) |
30
- | h | ★ | Ceiling height in mm (default: the level's h). The height invariant and `levels` read it |
31
- | use | ★ | An aggregation axis for stats (rentable/exclusive/common…). Inherited from the zone |
32
- | daylight | ★ | **Declares that the daylight check applies to this space** — `1` subjects it to `light`'s 1/7 test; `0` and absence leave it out (ADR-0020). Only 0 and 1 are accepted. It is not inherited (it differs room by room). The attribute names what the tool does, not a legal category (the habitable room of Article 2(iv)) — the scoping of Article 28(1) by building use, and the per-use ratios of Order Article 19(3), are not modelled, so what the 1/7 applies to is the author's call |
33
- | uid | ★ | An optional persistent identity token (ADR-0015). Opaque, unique across the whole model (spanning space and zone), and never derived from the path. Digits alone, or whitespace, is an error. It exists for external joins across renames (sensors, registers) — references inside the repository stay on paths. **space and zone are the only elements that can carry it, and that list is closed** (elsewhere it is ATT03). To have a machine make one, use `newUids` / the MCP tool `new_uids` (ADR-0039) |
34
- | w | ★ (band members only) | The dimension along the band's direction, in mm. `w:rest` marks the member that absorbs the remainder (at most one per band). It may not be written on a `space` outside a band |
35
- | name / floor / … | — | Free. `floor` may be overridden by an `area` |
36
-
37
- ### boundary
38
- | Attribute | Interpreted | Meaning |
39
- |---|---|---|
40
- | type | ★ | wall / open (horizontal); stair / shaft / void (vertical). The default is wall |
41
- | t | ★ | Wall thickness in mm (split about the centerline). Used in drawing; defaults to 100 there |
42
- | air | ★ | 1 = a thing that does not shield (a railing, a fence). It affects the derivation of semi-outdoor, thin-line drawing, and the 0.7 daylight coefficient |
43
- | edge | ★ | Restricts the segment to a particular side of the a-side rectangle (N/E/S/W) |
44
- | spec / fire / sound / h / … | — | Free (`spec` is the name of the thing; `fire`/`sound` are earmarked for interpretation by the M2 compartment query) |
45
-
46
- ### opening (indented under boundary)
47
- | Attribute | Interpreted | Meaning |
48
- |---|---|---|
49
- | kind | ★ | door (passage) / window (daylight; no passage) |
50
- | (leading token) | ★ | A reference to an opening asset (`door SD1 …` — a Reference). The asset's attributes become defaults and the instance overrides them (ADR-0010) |
51
- | w / h | ★ | Width and height in mm. A window's h is read by the daylight check |
52
- | at | ★ | Position. A ratio 0..1 (default 0.5, clamped within the segment) or a grid reference `at:X2+450` (absolute — not clamped; overrunning, the wrong axis, or overlapping another opening is an error) |
53
- | edge | ★ | Selects the side when there are several segments |
54
- | hinge | ★ | Swing: the hinge side (W/E on a horizontal segment, N/S on a vertical one; the default is the starting end) |
55
- | swing | ★ | Swing: the side it opens toward (a/b; the default is a, the side that has a region) |
56
- | style | ★ | The type of the door: hinged (the default) / sliding / auto. It changes how the door is drawn in plan |
57
- | sill / name / … | — | Free |
58
-
59
- ### band (ADR-0019)
60
- `band <axis> <X?..X?> <Y?..Y?>` plus indented `space` lines. It is the notation that writes dimension and order rather than position — the horizontal counterpart of the vertical section stack-up.
61
-
62
- | Positional | Interpreted | Meaning |
63
- |---|---|---|
64
- | axis | ★ | The direction of division: `X` (west to east) / `Y` (south to north). The first positional |
65
- | region | ★ | Two tokens, `X?..X? Y?..Y?`. Must be ascending (because the order of members carries meaning). A `+` union is not allowed |
66
-
67
- No `key:value` may be written — a band does not survive into the model, so there is nowhere for an attribute to live (attributes go on the member `space` lines). A band is expanded into ordinary spaces at parse time and does not survive in the canonical JSON either.
68
-
69
- ### asset (an opening asset — ADR-0010)
70
- `asset <name> door|window <attributes…>` — a bundle of defaults to be referenced (Revit's Family, USD's Reference). It is not a fourth element; it only puts the source of an opening's attributes in one place. The kind must match the opening that references it. A duplicate name is an error, including across composition.
71
-
72
- ### line (a drawn line — ADR-0022)
73
- `line <start> <end>`, indented under a boundary. Endpoints are pairs of grid words — `X3,Y1` / `X3+600,Y2-900` — and **neither raw coordinates nor angles can be written**. A drawn line gives the boundary its realisation as an act of design rather than as something derived from adjacency (★). It redistributes the union of the two spaces' declared cells across its two sides, so the area one loses the other gains. When one side has no region (the outside), it cuts the envelope instead: the side with a region is trimmed and nothing is gained. One line per boundary. On a diagonal segment an opening's `at:` can only be a 0..1 ratio, since a grid reference does not fix a unique position there.
74
-
75
- ### column (ADR-0023)
76
- `column <size mm> <level range|level name> [attrs...]` — **no position is written**. Columns stand where grid lines cross and that level has floor (inside a space with a region that is neither `exterior` nor `void`) (★). A semi-outdoor space with no floor above it (an open terrace or roof garden) is not a column site (ADR-0030).
77
-
78
- | Attribute | Read | Meaning |
79
- |---|---|---|
80
- | d | ★ | Depth in mm for a rectangular section (defaults to the size, i.e. square) |
81
- | x / y | ★ | Restrict which grid lines carry columns (comma-separated; all by default) |
82
- | spec / … | — | Free |
83
-
84
- Two columns never stand at the same intersection — the earlier declaration wins. A column is neither a space nor a boundary, so it appears in no area total and in no graph.
85
-
86
- ### polygon (the site shape — ADR-0011)
87
- `polygon /<zone path> x,y x,y x,y ...` — given geometry, from a survey. It is the one written shape in this notation, and it corresponds to a `site:1` zone (its absence is a warning). Tools interpret (★) the derived area (by the shoelace formula), the containment check for the building, and the site boundary line on the site plan. The standard practice is a quarantined layer of its own, brought in by import.
88
-
89
- ### import (composition — ADR-0010)
90
- `import ./L1.muro` — a path relative to the file it is written in. The base layer declares the foundation (koyu/name/unit/grid/level) once, and layers add spaces, boundaries, zones, and assets. A collision (a duplicate space path or asset name, a re-declared grid or name) is a build error with provenance. Importing the same file twice is idempotent.
91
-
92
- ### level
93
- `z` (positional), `h` (the base ceiling height), `slab` (slab thickness), `pitch` (range declarations only) — all ★.
94
-
95
- ### zone
96
- `name` (free), `use` (★, the source of inheritance), `site` (★ 1 = the site aggregation — the subject of the site command), `area` (★ the declared site area in m² — reconciled against the derived area), `uid` (★ a persistent identity token — the same uniqueness rule as space). A zone has no geometry.
97
-
98
- ### area / seg (uncounted subdivisions)
99
- A position (a region for `area`; at/w/edge for `seg` — ★; a seg's `at` may also be a grid reference) plus optional overriding attributes (—).
100
-
101
- ## Correspondence with IFC (informative)
102
-
103
- boundary wall/open ↔ IfcRelSpaceBoundary's PHYSICAL/VIRTUAL. The inside/outside distinction ↔ InternalOrExternalBoundary (here it is derived rather than declared). spec:railing ↔ IfcRailing (the element class becomes a value in the vocabulary). opening ↔ IfcOpeningElement + IfcDoor/IfcWindow. asset ↔ IfcDoorType/IfcWindowType (type and occurrence — Revit's Family), and style ↔ a coarse projection of IfcDoorTypeOperationEnum (SINGLE_SWING/SLIDING…). zone ↔ IfcZone. The vertical boundaries stair/shaft/void, and the default slab, have no direct counterpart in IFC because space is primary here. Composition by import has no counterpart in IFC4 (a single file is the rule) and corresponds instead to layer composition in IFCX/USD.