@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.
- package/README.ja.md +12 -8
- package/README.md +13 -10
- package/dist/analysis/contracts.d.ts +217 -0
- package/dist/analysis/contracts.d.ts.map +1 -0
- package/dist/analysis/contracts.js +27 -0
- package/dist/analysis/contracts.js.map +1 -0
- package/dist/analysis/index.d.ts +5 -0
- package/dist/analysis/index.d.ts.map +1 -0
- package/dist/analysis/index.js +17 -0
- package/dist/analysis/index.js.map +1 -0
- package/dist/analysis/json.d.ts +21 -0
- package/dist/analysis/json.d.ts.map +1 -0
- package/dist/analysis/json.js +111 -0
- package/dist/analysis/json.js.map +1 -0
- package/dist/cli.js +106 -35
- package/dist/cli.js.map +1 -1
- package/dist/core/derive.d.ts +13 -8
- package/dist/core/derive.d.ts.map +1 -1
- package/dist/core/derive.js +19 -13
- package/dist/core/derive.js.map +1 -1
- package/dist/core/diagnose.d.ts +4 -3
- package/dist/core/diagnose.d.ts.map +1 -1
- package/dist/core/diagnose.js +46 -11
- package/dist/core/diagnose.js.map +1 -1
- package/dist/core/diff.d.ts +3 -2
- package/dist/core/diff.d.ts.map +1 -1
- package/dist/core/diff.js +8 -5
- package/dist/core/diff.js.map +1 -1
- package/dist/core/fabric.d.ts +1 -3
- package/dist/core/fabric.d.ts.map +1 -1
- package/dist/core/fabric.js +8 -8
- package/dist/core/fabric.js.map +1 -1
- package/dist/core/graph.d.ts +2 -2
- package/dist/core/graph.d.ts.map +1 -1
- package/dist/core/graph.js +12 -5
- package/dist/core/graph.js.map +1 -1
- package/dist/core/light.d.ts.map +1 -1
- package/dist/core/light.js +2 -2
- package/dist/core/light.js.map +1 -1
- package/dist/core/model.d.ts +59 -10
- package/dist/core/model.d.ts.map +1 -1
- package/dist/core/model.js +128 -26
- package/dist/core/model.js.map +1 -1
- package/dist/core/parse.d.ts.map +1 -1
- package/dist/core/parse.js +83 -82
- package/dist/core/parse.js.map +1 -1
- package/dist/core/poly.d.ts +0 -4
- package/dist/core/poly.d.ts.map +1 -1
- package/dist/core/poly.js +1 -5
- package/dist/core/poly.js.map +1 -1
- package/dist/core/site.d.ts +9 -0
- package/dist/core/site.d.ts.map +1 -1
- package/dist/core/site.js +8 -2
- package/dist/core/site.js.map +1 -1
- package/dist/core/tolerance.d.ts +1 -1
- package/dist/core/tolerance.js +2 -2
- package/dist/core/tolerance.js.map +1 -1
- package/dist/core/vertical.d.ts +9 -2
- package/dist/core/vertical.d.ts.map +1 -1
- package/dist/core/vertical.js +8 -1
- package/dist/core/vertical.js.map +1 -1
- package/dist/core/vocabulary.d.ts.map +1 -1
- package/dist/core/vocabulary.js +17 -5
- package/dist/core/vocabulary.js.map +1 -1
- package/dist/diagnostics.d.ts +2 -0
- package/dist/diagnostics.d.ts.map +1 -0
- package/dist/diagnostics.js +3 -0
- package/dist/diagnostics.js.map +1 -0
- package/dist/diff.d.ts +2 -0
- package/dist/diff.d.ts.map +1 -0
- package/dist/diff.js +3 -0
- package/dist/diff.js.map +1 -0
- package/dist/draw/index.js +1 -1
- package/dist/draw/index.js.map +1 -1
- package/dist/draw/plan.js +5 -5
- package/dist/draw/plan.js.map +1 -1
- package/dist/form.d.ts +5 -0
- package/dist/form.d.ts.map +1 -0
- package/dist/form.js +4 -0
- package/dist/form.js.map +1 -0
- package/dist/graph.d.ts +2 -0
- package/dist/graph.d.ts.map +1 -0
- package/dist/graph.js +3 -0
- package/dist/graph.js.map +1 -0
- package/dist/index.d.ts +2 -14
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +36 -45
- package/dist/index.js.map +1 -1
- package/dist/mcp.js +81 -30
- package/dist/mcp.js.map +1 -1
- package/dist/model.d.ts +3 -0
- package/dist/model.d.ts.map +1 -0
- package/dist/model.js +3 -0
- package/dist/model.js.map +1 -0
- package/dist/parse-file.d.ts.map +1 -1
- package/dist/parse-file.js +18 -3
- package/dist/parse-file.js.map +1 -1
- package/dist/validate/assessment.d.ts +8 -0
- package/dist/validate/assessment.d.ts.map +1 -0
- package/dist/validate/assessment.js +1738 -0
- package/dist/validate/assessment.js.map +1 -0
- package/dist/validate/builtin/access.d.ts +55 -0
- package/dist/validate/builtin/access.d.ts.map +1 -0
- package/dist/validate/builtin/access.js +494 -0
- package/dist/validate/builtin/access.js.map +1 -0
- package/dist/validate/builtin/daylight.d.ts +44 -0
- package/dist/validate/builtin/daylight.d.ts.map +1 -0
- package/dist/validate/builtin/daylight.js +233 -0
- package/dist/validate/builtin/daylight.js.map +1 -0
- package/dist/validate/builtin/door-column-collisions.d.ts +47 -0
- package/dist/validate/builtin/door-column-collisions.d.ts.map +1 -0
- package/dist/validate/builtin/door-column-collisions.js +189 -0
- package/dist/validate/builtin/door-column-collisions.js.map +1 -0
- package/dist/validate/builtin/envelope.d.ts +30 -0
- package/dist/validate/builtin/envelope.d.ts.map +1 -0
- package/dist/validate/builtin/envelope.js +169 -0
- package/dist/validate/builtin/envelope.js.map +1 -0
- package/dist/validate/builtin/freeze.d.ts +3 -0
- package/dist/validate/builtin/freeze.d.ts.map +1 -0
- package/dist/validate/builtin/freeze.js +21 -0
- package/dist/validate/builtin/freeze.js.map +1 -0
- package/dist/validate/builtin/index.d.ts +38 -0
- package/dist/validate/builtin/index.d.ts.map +1 -0
- package/dist/validate/builtin/index.js +106 -0
- package/dist/validate/builtin/index.js.map +1 -0
- package/dist/validate/builtin/site.d.ts +62 -0
- package/dist/validate/builtin/site.d.ts.map +1 -0
- package/dist/validate/builtin/site.js +333 -0
- package/dist/validate/builtin/site.js.map +1 -0
- package/dist/validate/builtin/vertical-runs.d.ts +53 -0
- package/dist/validate/builtin/vertical-runs.d.ts.map +1 -0
- package/dist/validate/builtin/vertical-runs.js +290 -0
- package/dist/validate/builtin/vertical-runs.js.map +1 -0
- package/dist/validate/contracts.d.ts +188 -0
- package/dist/validate/contracts.d.ts.map +1 -0
- package/dist/validate/contracts.js +28 -0
- package/dist/validate/contracts.js.map +1 -0
- package/dist/validate/index.d.ts +2 -59
- package/dist/validate/index.d.ts.map +1 -1
- package/dist/validate/index.js +22 -70
- package/dist/validate/index.js.map +1 -1
- package/dist/vocabulary.d.ts +2 -0
- package/dist/vocabulary.d.ts.map +1 -0
- package/dist/vocabulary.js +3 -0
- package/dist/vocabulary.js.map +1 -0
- package/editors/vscode/syntaxes/koyu.tmLanguage.json +2 -2
- package/examples/basement/main.muro +3 -3
- package/examples/complex/main.muro +1 -1
- package/examples/complex/podium.muro +1 -1
- package/examples/complex/site.muro +6 -6
- package/examples/house/L2.muro +1 -1
- package/examples/house/main.muro +1 -1
- package/examples/house/site.muro +4 -4
- package/examples/house.muro +6 -6
- package/examples/mansion.muro +2 -2
- package/examples/office.muro +3 -3
- package/examples/steps/04-exterior.muro +1 -1
- package/examples/steps/05-two-storeys.muro +1 -1
- package/examples/steps/06-finished.muro +2 -2
- package/examples/tower/L2.muro +1 -1
- package/examples/tower/main.muro +1 -1
- package/examples/tower/site.muro +4 -4
- package/examples/twin/main.muro +1 -1
- package/examples/twin/podium.muro +4 -4
- package/examples/twin/site.muro +8 -8
- package/examples/two-rooms.canonical.json +4 -4
- package/examples/two-rooms.muro +2 -2
- package/package.json +41 -9
- package/src/analysis/contracts.ts +234 -0
- package/src/analysis/index.ts +61 -0
- package/src/analysis/json.ts +117 -0
- package/src/cli.ts +116 -36
- package/src/core/derive.ts +32 -15
- package/src/core/diagnose.ts +63 -16
- package/src/core/diff.ts +10 -6
- package/src/core/fabric.ts +18 -9
- package/src/core/graph.ts +19 -5
- package/src/core/light.ts +2 -2
- package/src/core/model.ts +141 -31
- package/src/core/parse.ts +100 -85
- package/src/core/poly.ts +1 -8
- package/src/core/site.ts +19 -2
- package/src/core/tolerance.ts +2 -2
- package/src/core/vertical.ts +10 -3
- package/src/core/vocabulary.ts +18 -5
- package/src/diagnostics.ts +8 -0
- package/src/diff.ts +14 -0
- package/src/draw/index.ts +1 -1
- package/src/draw/plan.ts +5 -5
- package/src/form.ts +37 -0
- package/src/graph.ts +12 -0
- package/src/index.ts +40 -175
- package/src/mcp.ts +85 -35
- package/src/model.ts +43 -0
- package/src/parse-file.ts +17 -3
- package/src/validate/assessment.ts +1934 -0
- package/src/validate/builtin/access.ts +642 -0
- package/src/validate/builtin/daylight.ts +321 -0
- package/src/validate/builtin/door-column-collisions.ts +266 -0
- package/src/validate/builtin/envelope.ts +227 -0
- package/src/validate/builtin/freeze.ts +19 -0
- package/src/validate/builtin/index.ts +156 -0
- package/src/validate/builtin/site.ts +445 -0
- package/src/validate/builtin/vertical-runs.ts +390 -0
- package/src/validate/contracts.ts +240 -0
- package/src/validate/index.ts +45 -99
- package/src/vocabulary.ts +9 -0
- package/dist/validate/access.d.ts +0 -6
- package/dist/validate/access.d.ts.map +0 -1
- package/dist/validate/access.js +0 -238
- package/dist/validate/access.js.map +0 -1
- package/dist/validate/envelope.d.ts +0 -4
- package/dist/validate/envelope.d.ts.map +0 -1
- package/dist/validate/envelope.js +0 -55
- package/dist/validate/envelope.js.map +0 -1
- package/dist/validate/light.d.ts +0 -6
- package/dist/validate/light.d.ts.map +0 -1
- package/dist/validate/light.js +0 -28
- package/dist/validate/light.js.map +0 -1
- package/dist/validate/runs.d.ts +0 -16
- package/dist/validate/runs.d.ts.map +0 -1
- package/dist/validate/runs.js +0 -60
- package/dist/validate/runs.js.map +0 -1
- package/dist/validate/site.d.ts +0 -6
- package/dist/validate/site.d.ts.map +0 -1
- package/dist/validate/site.js +0 -63
- package/dist/validate/site.js.map +0 -1
- package/spec/README.md +0 -28
- package/spec/canonical-json.md +0 -98
- package/spec/composition.md +0 -121
- package/spec/derivation.md +0 -393
- package/spec/en/README.md +0 -30
- package/spec/en/canonical-json.md +0 -101
- package/spec/en/composition.md +0 -121
- package/spec/en/derivation.md +0 -393
- package/spec/en/language.md +0 -164
- package/spec/en/notation-v0.md +0 -145
- package/spec/en/scope.md +0 -229
- package/spec/en/semantics.md +0 -132
- package/spec/en/tools.md +0 -108
- package/spec/en/validation.md +0 -79
- package/spec/en/vocabulary.md +0 -103
- package/spec/language.md +0 -163
- package/spec/notation-v0.md +0 -184
- package/spec/scope.md +0 -229
- package/spec/semantics.md +0 -130
- package/spec/tools.md +0 -106
- package/spec/validation.md +0 -79
- package/spec/vocabulary.md +0 -114
- package/src/validate/access.ts +0 -279
- package/src/validate/envelope.ts +0 -59
- package/src/validate/light.ts +0 -43
- package/src/validate/runs.ts +0 -87
- package/src/validate/site.ts +0 -84
package/spec/en/language.md
DELETED
|
@@ -1,164 +0,0 @@
|
|
|
1
|
-
**English** · [日本語](../language.md)
|
|
2
|
-
|
|
3
|
-
# Language reference — .muro (the authored form)
|
|
4
|
-
|
|
5
|
-
The norm for the notation as of koyu v0.16.0. For semantics (derivation, checking, queries) see [semantics.md](semantics.md); for the attribute contract see [vocabulary.md](vocabulary.md).
|
|
6
|
-
|
|
7
|
-
> This is a reference. If you are learning koyu, start at [guide/en/start.md](../../guide/en/start.md).
|
|
8
|
-
|
|
9
|
-
## 1. Lexis
|
|
10
|
-
|
|
11
|
-
**One line is one statement.** Every line takes the form `keyword positional... key:value...`. Tokens are whitespace-separated. `#` begins a comment that runs to the end of the line. Wrap a value in `"..."` when it contains whitespace or `#` (quotes may appear anywhere in a token, and an unclosed quote is an error). An indented line (leading whitespace) **is subordinate to the parent line above it** — `door` / `window` / `seg` under `boundary`, `area` under `space`, `space` under `band` (§3, bands). Indentation is one level only; there is no nesting. Blank lines are ignored.
|
|
12
|
-
|
|
13
|
-
**Attributes are `key:value`.** The key is to the left of `:` and the value to the right (an empty value is an error). A value in numeric form (`-?\d+(\.\d+)?`) is held as a number; anything else is held as a string. A repeated key on the same line is an error — silently taking the last one hides typos and merge accidents (ADR-0013; an instance overriding an asset default (§6) is two sources, not a duplicate). Interpreted attributes (★) are contracted in the ledger in vocabulary.md; any other `k:v` may be written freely and is carried through untouched.
|
|
14
|
-
|
|
15
|
-
**Units and coordinate system.** Lengths are in mm. In plan, X is east-positive and Y is north-positive; height z is up-positive. A ratio position along a segment is 0..1. Areas are reported in m² (measured to wall centerlines).
|
|
16
|
-
|
|
17
|
-
## 2. Foundation declarations (the base layer holds these, once)
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
koyu 1.0 # version declaration (base layer only, once)
|
|
21
|
-
name 街角の複合ビル # building name (the rest of the line, whitespace allowed)
|
|
22
|
-
unit mm # v0 is mm only
|
|
23
|
-
grid X 0 6400 12800 19200 # X-axis grid-line coordinates (ascending, two or more). X1, X2, … are named automatically
|
|
24
|
-
grid Y 0 5600 7600 13200
|
|
25
|
-
level L1 0 h:3600 slab:600 # level: name z [h:ceiling height] [slab:slab thickness]
|
|
26
|
-
level L4..L10 11000 pitch:3000 h:2500 slab:450 # range declaration (arithmetic). pitch is required
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
`grid` is declared once per axis (in the base layer when composing). `name` is also declared once (it may be repeated only if identical). A `level` range declaration `L4..L10` is a prefix plus consecutive numbers, expanded to `z + pitch×k`. Duplicate level names are an error. Declaring a level that holds no space (a roof `R`, say) makes it the upper bound for the topmost floor's height check.
|
|
30
|
-
|
|
31
|
-
**The version norm (ADR-0017).** The language versions this tool accepts are `0.1, 0.2, 0.3, 0.4, 0.5, 1.0`; when the declaration is omitted the file is read with the semantics of the newest version, `1.0` (omission is *not* stable in meaning across tool versions — write the version in any file whose meaning you want pinned). Newer and older follow that listed order, not the lexical order of the spelling (`1.0` is newer than `0.5`). The version declaration is the two tokens `koyu <version>` (a missing version, or extra tokens, is an error), in the base layer (the entry) only, and only once (the same discipline as `grid` — re-declaring is an error even with an identical value, which forbids a silent override that depends on composition order). An older version is accepted **only when meaning is preserved** — the parser reads it, but a file whose meaning would change is made an error by check, which offers two ways out. For `0.1`, that is a file in which default boundaries (§4) would be derived (**VER01** — declare the boundaries, or raise the file to `koyu 0.2`). For `0.3` and earlier, which inferred the daylight scope from the type, it is a space of one of those types (`unit`, `room`, `ldk`, `bedroom`, `living`) carrying no `daylight` (**VER02** — write `daylight:1`/`daylight:0`, then raise the file to `koyu 0.4`; ADR-0020). For `0.4` and earlier, which know nothing of the vertical-circulation declarations (`stair:` `ramp:` `escalator:` `lift:`), drawn lines (`line`), columns (`column`) or basements (`underground:`), it is a file in which one of them is written (**VER03** — raise the file to `koyu 0.5`; ADR-0021/0022/0023). For `0.5` and earlier, which know nothing of the composition override (`over`), removal (`drop`) or the set edits directly under `over` (`+` `-` `=`), it is a file in which one of them is written (**VER04** — raise the file to `koyu 1.0`; ADR-0035/0038). A change that changes the language raises the version, and the migration is written in an ADR.
|
|
32
|
-
|
|
33
|
-
### Grid references and offsets
|
|
34
|
-
|
|
35
|
-
Coordinates are never written directly — position is always spoken in the language of grid lines: `X2`, `X2+600`, `Y3-150`. A range is written with a grid reference at each end, as in `X1..X2+3200`.
|
|
36
|
-
|
|
37
|
-
## 3. space — spaces
|
|
38
|
-
|
|
39
|
-
```
|
|
40
|
-
space /L5/A/ldk ldk X1+3200..X2+3200 Y1..Y1+4000 + X2+3200..X3 Y1..Y1+2400 name:LDK floor:オーク
|
|
41
|
-
space /out/road-s exterior name:南側道路 road:12000
|
|
42
|
-
area X1..X2 Y1-4600..Y1-2600 name:土間 floor:タイル # indented: an uncounted subdivision
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
- **The path is the identity.** A `/`-separated hierarchy. A path is first of all an aggregation hierarchy, and if its first segment is a level name the space belongs to that level. A grouping that spans levels (a maisonette, say) states it with the `level:` attribute.
|
|
46
|
-
- **The type is an open vocabulary** (second positional, required). The only two words interpreted structurally are `exterior` (may have no region; outside) and `void` (a void through the floor — excluded from floor area, not passable). **Being in scope for the daylight check is never inferred from the type** — `light` looks at the spaces that carry `daylight:1` (the default is out of scope; ADR-0020).
|
|
47
|
-
- **A region is a union of rectangles.** Write `X?..X? Y?..Y?` and join several with `+` (for an L shape, say). A space with no region (an `exterior`, say) is allowed. Overlapping regions — within one space or between spaces — are an error.
|
|
48
|
-
- **`area` (indented)** is an uncounted subdivision inside a room: a region plus overriding attributes only. It does not affect area, room counts, or the graph (the isolation rule). Spilling outside the parent region is a warning.
|
|
49
|
-
- **Span expansion**: if the **first segment** of the path has the form `L3..L10`, the line expands across the declared levels in z order (all paths on one line must carry the same span).
|
|
50
|
-
|
|
51
|
-
### band — dividing a run by dimension and order
|
|
52
|
-
|
|
53
|
-
```
|
|
54
|
-
band X X1+3200..X2+3200 Y1+4000..Y2 # the band: which extent, divided which way
|
|
55
|
-
space /L3..L10/A/wet wet w:4800 name:水回り # indented: a band member (a dimension instead of a region)
|
|
56
|
-
space /L3..L10/A/hall hall w:1600 name:玄関
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
**A band writes dimension and order rather than position** (ADR-0019). It is the horizontal extension of the vertical section stack-up (`level`): what is written is each room's dimension and its place in the run, and position is derived from those. It coexists with the region notation, and neither is forced.
|
|
60
|
-
|
|
61
|
-
- **`band <axis> <X?..X?> <Y?..Y?>`.** The first positional is the direction of division (`X` = west to east / `Y` = south to north), spelled the same way as `grid X 0 6400 …`. The other two are the extent of the band, with the same lexis as a `space` region and in either order (a `+` union may not be written). **No `key:value` may appear on this line** — the band does not survive into the model, so there is nowhere for an attribute to live. **Ranges must be ascending** — because the order of members carries meaning, a descending spelling is not normalized as it is for `space`.
|
|
62
|
-
- **A member is an indented `space` line** carrying a width `w:` in place of a region. In every other respect it is an ordinary `space` line (path, type, attributes, level span). `w` is the dimension along the band's direction, axis-relative in the same way that `door w:800` is a width along a segment. `level:` and `area` may not be written on a member. All members of one band must expand to the same level.
|
|
63
|
-
- **`w:rest` marks the member that absorbs the remainder**, at most one per band, in any position. **The default is a closed band, which uses no `rest`** — every member carries a dimension and the parser reconciles their sum against the width of the band. This is the same arithmetic as a dimension string on a drawing, where the partial dimensions must sum to the overall, and it is the only defense against a mistyped dimension. `rest` is reserved for the case where the remainder is not a design decision.
|
|
64
|
-
- **Over-determination (the sum exceeds the band) and under-determination (the sum falls short with no `w:rest`) are both errors.** There is no solver — only addition and a single subtraction, in declaration order, always from low coordinate to high. A broken band is **always a parse error** (if the band is broken, not one rectangle can be built — that is a question of form), surfacing in `check --json` as SYN01. No new diagnostic codes are minted.
|
|
65
|
-
- **A band is expanded into ordinary spaces at parse time and survives neither in the model nor in the canonical JSON** (the same discipline as import, spans, and stack). A plan written with bands and the same plan written with positions yield the same canonical JSON.
|
|
66
|
-
- **How derived cut positions are spelled (the floor rule).** The two ends of the band, and both ends across it, keep **the spelling that was written**; only the interior cuts are spelled by the tool. The rule is "the offset from the largest grid line at or below that coordinate": an offset of 0 gives the bare grid name, and a coordinate before the first grid line gives a negative offset (`8000` → `X2+1600`, `12800` → `X3`). **A spelling that subtracts from the grid line above (`Y2-1800`) never arises from derivation** — rewriting a region written that way as a band leaves the geometry identical but changes the spelling, which appears in a semantic diff.
|
|
67
|
-
- **`w:` may not be written on a `space` line** — a space written by width always sits indented under a band. This prevents a member that has lost its indentation from silently becoming a space with no region.
|
|
68
|
-
|
|
69
|
-
## 4. boundary — boundaries (a wall is a relation, not a thing)
|
|
70
|
-
|
|
71
|
-
```
|
|
72
|
-
boundary /L5/A/hall /L5/corridor t:180 spec:RC
|
|
73
|
-
door D1 at:X4 name:玄関 # indented: an opening
|
|
74
|
-
seg w:1800 at:X5 edge:S spec:受付ガラス # indented: an uncounted subdivision
|
|
75
|
-
boundary /L1/hall /L2/void type:void # a vertical exception
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
- A first-class relation joining two space paths. The wall centerline segment is not written — it is derived from the layout of the two spaces (semantics.md §2). A boundary between spaces that do not touch is an error. **A duplicate boundary on the same pair of spaces (identical down to the `edge` restriction) is also an error** — a wall/open contradiction must not pass silently (ADR-0013). A pair carrying a mix of edge-restricted and unrestricted boundaries is a warning (the segments overlap).
|
|
79
|
-
- **The default between touching spaces is a wall (ADR-0014).** Where two spaces with regions touch in plan on the same level and no boundary is declared for that pair, a `wall` default boundary is derived — symmetric with the vertical default of a floor, so that declaration is reserved for exceptions (open, railings) and for attributes and openings. A boundary with a space that has no region (an `exterior`, say) is still declared as before — naming *which* outside is the information. The edge of a void (`type:void`) also defaults to a wall; a railing (`air:1`) or an open is declared. Default boundaries do not appear in the canonical JSON.
|
|
80
|
-
- **type (kind) states topology only**: horizontally, `wall` (the default — there is something there; not passable without a door) or `open` (nothing there — always passable). Vertically, `stair` (passable), `shaft` (continuous but not passable), or `void` (the absence of a floor). Floors are not written — vertical adjacency is derived from overlap in plan and defaults to a floor. Writing a wall boundary between different levels is an error.
|
|
81
|
-
- **The name of the thing belongs to the `spec` vocabulary** (railing, RC, LGS, curtain wall…). Tools do not interpret it.
|
|
82
|
-
- **`air:1`** = there is something there, but it does not block outside air or light (railings, fences, balustrades). It affects the derivation of semi-outdoor, the daylight coefficient, and thin-line drawing.
|
|
83
|
-
- **`t`** = wall thickness in mm (split about the centerline; the drawing default when unspecified is 100). **`edge`** restricts the segment to one side — N/E/S/W as seen from the rectangle of the a-side (the space written first).
|
|
84
|
-
- **`stack <name> L1..L11 type:stair|shaft|void`** declares a vertical stack in one line: it draws vertical boundaries between consecutive level pairs `/Lk/<name> | /Lk+1/<name>`.
|
|
85
|
-
|
|
86
|
-
### Openings (door / window)
|
|
87
|
-
|
|
88
|
-
- `door` is for passage, `window` for daylight (it does not admit passage). **The width `w` is required** (it may come from the asset). `h` is optional (the daylight calculation counts only windows that carry `h`).
|
|
89
|
-
- **Asset reference**: the leading non-`key:value` token is an asset name (`door SD1 sill:800`). The asset's attributes become defaults, and the instance's attributes override them. A kind mismatch, or an undefined asset, is an error.
|
|
90
|
-
- **Position `at`**: either a ratio `0..1` (default 0.5 — clamped to keep the opening within the segment) or a grid reference `at:X2+450` (an absolute position — not clamped; overrunning the segment, or using the wrong axis (a horizontal segment takes X references, a vertical one takes Y), is an error). Openings overlapping on the same segment are an error.
|
|
91
|
-
- **`edge` selects the side when there are several segments**, and the swing is given by **`hinge`** (the hinge side: W/E on a horizontal segment, N/S on a vertical one; the default is the starting end) and **`swing`** (the side it opens toward, a/b; the default is a, the side that has a region). `style` (hinged/sliding/auto) changes how the door is drawn in plan.
|
|
92
|
-
- **`seg`** is an uncounted subdivision along a boundary: a position (at/w/edge — the same idiom as an opening) plus overriding attributes. It affects neither passage nor connection.
|
|
93
|
-
|
|
94
|
-
## 5. zone — counted aggregation
|
|
95
|
-
|
|
96
|
-
```
|
|
97
|
-
zone /L3..L10/A name:Aタイプ use:exclusive
|
|
98
|
-
zone /site name:敷地 site:1 area:1097.80
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
A zone has no geometry; it bundles the spaces beneath it by path prefix. Its area is the sum of those spaces, and `use` is inherited by them (a declaration on the space wins). `site:1` marks the site and makes it the subject of the `site` query, and `area:` (the surveyed value, in m²) is reconciled against the derived area. A duplicate path is an error; a zone with no spaces beneath it is a warning.
|
|
102
|
-
|
|
103
|
-
## 6. asset — door and window assets
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
asset SD1 door w:800 h:2000 style:sliding name:片引き戸
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
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. A duplicate name is an error (including across composition).
|
|
110
|
-
|
|
111
|
-
## 7. polygon — the site shape
|
|
112
|
-
|
|
113
|
-
```
|
|
114
|
-
polygon /site -2600,-7000 38000,-7000 38000,19600 2000,21000 -2600,15000
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
**This is the one place in the notation where a shape is *written* with free vertices that do not sit on the grid** (a space's region is also a written shape, but as a rectangle in grid references; an arbitrary vertex list is only `polygon`). A site's shape is surveyed input from the world rather than designed form, so it is admitted as an exception. Vertices are `x,y` in mm (the same coordinate system as the grid), three or more. Associate it with a `site:1` zone path (a missing association is a warning). The derived area, the containment check for the building, and the site boundary line on the plan all follow from it (semantics.md §5). The standard practice is to keep it in a quarantined layer (its own file, brought in by import). A duplicate is an error.
|
|
118
|
-
|
|
119
|
-
## 8. import / over / drop — composition
|
|
120
|
-
|
|
121
|
-
The normative rules live in [composition.md](composition.md). Only the spelling is given here.
|
|
122
|
-
|
|
123
|
-
```
|
|
124
|
-
import ./assets.muro # lay a layer on top. **The order is the declaration of strength** (later is stronger)
|
|
125
|
-
|
|
126
|
-
over /L5/A/ldk h:2600 spec:改修後 # override a space (one path; a zone if no space has it)
|
|
127
|
-
over /L5/A/hall /L5/corridor t:200 # override a boundary (two paths)
|
|
128
|
-
over level L3 h:2600 # override a level (h / slab / underground only)
|
|
129
|
-
over asset SD1 w:900 # override an asset
|
|
130
|
-
- door D2 # indented: remove from a set (named)
|
|
131
|
-
= door D1 w:1000 # replace in a set (only the attributes written)
|
|
132
|
-
+ window w:600 h:1200 name:W1 # add to a set (name: required)
|
|
133
|
-
|
|
134
|
-
drop /L5/A/store # remove a space (its boundaries go with it)
|
|
135
|
-
drop /L5/a /L5/b # remove a boundary
|
|
136
|
-
drop column C1 # remove a column declaration
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
- **`import`** takes a path relative to the file it is written in. The base layer (the entry) declares the foundation (`koyu`/`name`/`unit`/`grid`/`level`) once. The same layer is composed only once (a double import, or a cycle, is idempotent).
|
|
140
|
-
- **`space` / `boundary` / `zone` / `asset` / `polygon` are definitions**, and a duplicate is a build error naming the provenance of both. **`over` is an override**, and a missing target is an error.
|
|
141
|
-
- **Only `+` / `-` / `=` may be written under `over`.** Set members are pointed at by `name:` — an element without a name cannot be edited.
|
|
142
|
-
- The list of composition entry points is in the public API section of [tools.md](tools.md) (`parse` / `parseFile` / `parseFiles` / `parseFileWith` / `parseWith`).
|
|
143
|
-
- The canonical JSON is the single composed model; neither `import` nor `over` nor `drop` survives in it.
|
|
144
|
-
- **`over`, `drop` and the set edits are muro 1.0 words.** Written in a file that declares `0.5` or earlier, they are stopped with **VER04** (§2, the version norm).
|
|
145
|
-
|
|
146
|
-
## 9. column — an element with no written position
|
|
147
|
-
|
|
148
|
-
`column <size mm> <level range|level name> [d:depth] [x:grid,..] [y:grid,..] [free attributes]`
|
|
149
|
-
|
|
150
|
-
**No position is written anywhere.** Columns stand where grid lines cross and that level has floor (ADR-0023) — the same rule that makes walls appear where two spaces touch. "Has floor" means the point falls inside a space with a region that is neither `exterior` nor `void`. But **a floor that holds up nothing but sky carries no columns** (ADR-0030): a space that is semi-outdoor (touching the exterior through an open or air:1 boundary — ADR-0007) and has no floor of any level overlapping above it (the ADR-0009 derivation) is excluded from column sites. An open roof garden or setback terrace gets no columns; the underside of an overhanging balcony still does. `x:` / `y:` restrict which grid lines carry columns (comma-separated; all by default). Two columns never stand at the same intersection — the earlier declaration wins. Writing three declarations for three level ranges gives columns that slim down as the building rises. A column is neither a space nor a boundary, so it appears in no area total and in no graph.
|
|
151
|
-
|
|
152
|
-
## 10. The defaults, in one table
|
|
153
|
-
|
|
154
|
-
| Item | Default |
|
|
155
|
-
|---|---|
|
|
156
|
-
| boundary type | `wall` |
|
|
157
|
-
| boundary t | none (the derivation default is 100 mm — [derivation.md](derivation.md) §5) |
|
|
158
|
-
| boundary between touching spaces | `wall` — not written. Declare only the exceptions (open / air:1 / anything carrying attributes or openings — ADR-0014) |
|
|
159
|
-
| opening at | 0.5 (a ratio — clamped) |
|
|
160
|
-
| opening hinge / swing | the starting end of the segment / the a side (the one with a region) |
|
|
161
|
-
| space level | the first path segment (when it is a level name) |
|
|
162
|
-
| space h | the level's h |
|
|
163
|
-
| vertical adjacency | a floor (slab) — not written. Declare only the exceptions (stair/shaft/void) |
|
|
164
|
-
| area measurement | to wall centerlines |
|
package/spec/en/notation-v0.md
DELETED
|
@@ -1,145 +0,0 @@
|
|
|
1
|
-
**English** · [日本語](../notation-v0.md)
|
|
2
|
-
|
|
3
|
-
# koyu notation v0 — the record of how it came about (a historical document)
|
|
4
|
-
|
|
5
|
-
**The current specification is [language.md](language.md) / [semantics.md](semantics.md) / [canonical-json.md](canonical-json.md) / [tools.md](tools.md).** This document records the process by which the notation was born — the v0 comparison (DSL/YAML/JSON) and the addendum written for each version, preserved as they were written at the time. The reasons behind decisions are in docs/decisions/ (the ADRs); the argument is in docs/writing-architecture.md.
|
|
6
|
-
|
|
7
|
-
> **A note on this translation.** The Japanese original is a preserved record, kept in the words it was written in. The substantive sections below are translated in full. The per-version addenda (§v0.1 through §v0.7) are given here in condensed form, because each has since been superseded by an ADR that is the durable record of the same decision — the ADR is cited in each case. Where you need the text as written, read [the Japanese original](../notation-v0.md).
|
|
8
|
-
|
|
9
|
-
The design criterion is fixed to one thing. **Can an LLM read the whole thing in a single context and edit part of it correctly?** From that criterion follow being text-native, having references be human-readable hierarchical paths, keeping files small, and declaring units and the coordinate system once at the top.
|
|
10
|
-
|
|
11
|
-
## The model
|
|
12
|
-
|
|
13
|
-
The primary element is space. A `space` denotes a room, a zone, or an exterior region, and is named by a hierarchical path. A wall is not an independent thing; it is held as a relation between two spaces (a `boundary`). Performance attributes — thickness, specification, fire rating — ride on the boundary. An opening (`door` / `window`) is a connection cut into a boundary. The skeleton is given by the grid (`grid`) and levels (`level`). Types are an open vocabulary rather than a vast class hierarchy: free words may be added to a core vocabulary of `room`, `corridor`, `exterior`, and the like.
|
|
14
|
-
|
|
15
|
-
Form is not in this source. Wall segments are derived from the layout of spaces, and the plan is generated when it is needed. That several forms come from one composition is not a defect.
|
|
16
|
-
|
|
17
|
-
## The notation (the authored form: a bespoke DSL)
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
# 二室一扉 — 最初の一手
|
|
21
|
-
|
|
22
|
-
koyu 0.1
|
|
23
|
-
name 二室一扉
|
|
24
|
-
unit mm
|
|
25
|
-
|
|
26
|
-
grid X 0 3600 7200 # 通り芯 X1, X2, X3
|
|
27
|
-
grid Y 0 4500 # 通り芯 Y1, Y2
|
|
28
|
-
level L1 0 h:2400 # FL高さ 0、基準天井高 2400
|
|
29
|
-
|
|
30
|
-
space /L1/a room X1..X2 Y1..Y2 name:居室A
|
|
31
|
-
space /L1/b room X2..X3 Y1..Y2 name:居室B
|
|
32
|
-
space /out exterior name:外部
|
|
33
|
-
|
|
34
|
-
boundary /L1/a /L1/b t:120 spec:PW1
|
|
35
|
-
door w:780 h:2000
|
|
36
|
-
|
|
37
|
-
boundary /L1/a /out t:150 spec:EW1 fire:60
|
|
38
|
-
boundary /L1/b /out t:150 spec:EW1 fire:60
|
|
39
|
-
door w:900 h:2100 edge:S name:玄関
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
The grammar is as follows. One line is one statement, taking the form `keyword positional... key:value...`. `#` begins a comment; wrap a value containing whitespace in `"..."`. An indented line is an opening (`door` / `window`) belonging to the `boundary` above it.
|
|
43
|
-
|
|
44
|
-
`grid X 0 3600 7200` declares ascending coordinates in mm, and the grid names X1, X2, … are assigned automatically. `level <name> z [h:ceiling height]` declares a level. `space <path> <type> [X?..X? Y?..Y?] [attributes...]` declares a space, and if the first segment of the path is a level name it belongs to that level. In v0 a region is limited to a single rectangle bounded by grid lines. A space with no region, such as an `exterior`, may also be written.
|
|
45
|
-
|
|
46
|
-
`boundary <pathA> <pathB> [t:thickness type:wall|open attributes...]` declares a boundary. The wall centerline segment is not written — it is derived from the layout of the two spaces. A boundary between spaces that do not touch is an error. `type:open` is an open boundary with no head above it, passable without a door. A boundary with a space that has no region, such as the exterior, is what remains of the room's perimeter once the intervals shared with other rooms are removed; because that splits across several edges, placing an opening requires `edge:N/E/S/W`. An opening is placed along the segment with `at:0..1` (default 0.5).
|
|
47
|
-
|
|
48
|
-
Defaults: a boundary is `type:wall`, an opening position is `at:0.5`, and the drawing wall thickness when `t` is unspecified is 100 mm. Area is measured to wall centerlines.
|
|
49
|
-
|
|
50
|
-
## The comparison — the same two rooms and one door in three formats
|
|
51
|
-
|
|
52
|
-
To settle v0, the same scene was written three ways. The DSL above is the first.
|
|
53
|
-
|
|
54
|
-
Second, YAML:
|
|
55
|
-
|
|
56
|
-
```yaml
|
|
57
|
-
koyu: "0.1"
|
|
58
|
-
name: 二室一扉
|
|
59
|
-
unit: mm
|
|
60
|
-
grid:
|
|
61
|
-
X: [0, 3600, 7200]
|
|
62
|
-
Y: [0, 4500]
|
|
63
|
-
levels:
|
|
64
|
-
L1: {z: 0, h: 2400}
|
|
65
|
-
spaces:
|
|
66
|
-
/L1/a: {type: room, at: [X1, Y1, X2, Y2], name: 居室A}
|
|
67
|
-
/L1/b: {type: room, at: [X2, Y1, X3, Y2], name: 居室B}
|
|
68
|
-
/out: {type: exterior, name: 外部}
|
|
69
|
-
boundaries:
|
|
70
|
-
- between: [/L1/a, /L1/b]
|
|
71
|
-
t: 120
|
|
72
|
-
spec: PW1
|
|
73
|
-
openings:
|
|
74
|
-
- {kind: door, w: 780, h: 2000}
|
|
75
|
-
- between: [/L1/a, /out]
|
|
76
|
-
t: 150
|
|
77
|
-
spec: EW1
|
|
78
|
-
fire: 60
|
|
79
|
-
- between: [/L1/b, /out]
|
|
80
|
-
t: 150
|
|
81
|
-
spec: EW1
|
|
82
|
-
fire: 60
|
|
83
|
-
openings:
|
|
84
|
-
- {kind: door, w: 900, h: 2100, edge: S, name: 玄関}
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
Third, JSON. This is exactly the canonical form that `koyu json` emits; the whole file is in examples/two-rooms.canonical.json (111 lines). An excerpt:
|
|
88
|
-
|
|
89
|
-
```json
|
|
90
|
-
{
|
|
91
|
-
"koyu": "0.1",
|
|
92
|
-
"name": "二室一扉",
|
|
93
|
-
"unit": "mm",
|
|
94
|
-
"grid": { "X": [0, 3600, 7200], "Y": [0, 4500] },
|
|
95
|
-
"spaces": {
|
|
96
|
-
"/L1/a": { "type": "room", "at": ["X1", "Y1", "X2", "Y2"], "attrs": { "name": "居室A" } }
|
|
97
|
-
},
|
|
98
|
-
"boundaries": [
|
|
99
|
-
{ "between": ["/L1/a", "/L1/b"], "kind": "wall", "t": 120,
|
|
100
|
-
"openings": [{ "kind": "door", "w": 780, "h": 2000, "at": 0.5 }] }
|
|
101
|
-
]
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
| Aspect | DSL | YAML | JSON |
|
|
106
|
-
|---|---|---|---|
|
|
107
|
-
| Lines for the same scene | 14 (excluding comments) | about 30 | 111 |
|
|
108
|
-
| Human reading and writing | Closest to the density of a drawing | Readable enough | Clear in structure but verbose |
|
|
109
|
-
| Partial editing by an LLM | One line, one statement, so a replacement is local | Good | Good, but bracket matching gets involved |
|
|
110
|
-
| The language of a diff | "this room got bigger" comes out in one line | Good | Noisy |
|
|
111
|
-
| Parser | Bespoke (about 300 lines sufficed) | Off the shelf | Off the shelf |
|
|
112
|
-
| Layer composition | Not directly suited | In between | The most natural (the same ground as IFCX/USD) |
|
|
113
|
-
|
|
114
|
-
**Decision: the authored form is the DSL, the machine form is the canonical JSON.** The source that people (and LLMs) read and write is held as the DSL, and the canonical form emitted by `koyu json` is the footing for composition, diffs, and external connections. YAML sits between the two and offers nothing decisive, so it is set aside. The cost of the DSL is the absence of editor support and the burden of maintaining a grammar, held down by not growing that grammar beyond "one line, one statement + key:value + indentation".
|
|
115
|
-
|
|
116
|
-
## The shape of the canonical JSON (the machine form)
|
|
117
|
-
|
|
118
|
-
As written at the time, the canonical JSON emitted by `koyu json` carried: `koyu` (the version), `name`, `unit`, `grid` (coordinate arrays in mm per axis), `levels` (name → `{z, h?}`), `spaces` (path → `{type, at?, attrs?}`, where `at` is the 4-tuple of grid names `[XA, YA, XB, YB]`), and `boundaries` (an array whose elements are `{between, kind, t?, edge?, attrs?, openings?}`, `between` being the two paths in ascending order and each opening being `{kind, w, h?, at, edge?, attrs?}`).
|
|
119
|
-
|
|
120
|
-
The stability rules: every object key is sorted, `spaces` are in path order, and `boundaries` are in lexicographic order of `between`. Because the same composition always emits byte-identical JSON, it can serve as the footing for diffs, hashes, and layer composition. The present-tense schema is [canonical-json.md](canonical-json.md).
|
|
121
|
-
|
|
122
|
-
## The addenda, in brief (each superseded by its ADR)
|
|
123
|
-
|
|
124
|
-
| Version | What it added | The durable record |
|
|
125
|
-
|---|---|---|
|
|
126
|
-
| v0.1 | Grid offsets (`X2+600`); levels and heights (`z`/`h`/`slab`) with the invariant "ceiling height + the slab above ≤ the floor-to-floor height"; vertical boundaries (`stair`/`shaft`) with the floor left implicit; the schematic-design resolution; `use` aggregation in stats | ADR-0002 |
|
|
127
|
-
| v0.2 | Writing the typical floor once — arithmetic level ranges (`level L3..L9 … pitch:`), span expansion of paths (`/L2..L9/A`), and `stack` for vertical stacks | ADR-0004 |
|
|
128
|
-
| v0.2 | Uncounted subdivisions — `area` under a space, `seg` under a boundary, with the isolation rule that neither affects area, room counts, or the graph | ADR-0003 |
|
|
129
|
-
| v0.3 | L-shaped rooms (a region as a `+` union of rectangles); zones as counted aggregation, so subdividing a dwelling never loses the language of net area; mixed granularity | ADR-0005 |
|
|
130
|
-
| v0.3 | Voids (`type:void`) as a declarative exemption from the height invariant; the daylight query `light` (window area / floor area ≥ 1/7) | ADR-0006 |
|
|
131
|
-
| v0.4 | `air:1` and semi-outdoor derived rather than declared; the swing (`hinge`/`swing`); maisonettes via the `level:` attribute; partial voids controlled by a coverage ratio | ADR-0006, ADR-0007 |
|
|
132
|
-
| v0.4 | The vocabulary ledger as the contract for attributes | ADR-0008 |
|
|
133
|
-
| v0.5 | The outside is also space — `/out` split by direction and character, `road:` as the mark of a road, the site as `zone … site:1` with the declared area reconciled, and the `site` query deriving frontage, coverage ratio, and floor area ratio | ADR-0009 |
|
|
134
|
-
| v0.6 | Explicit opening positions (`at:Y2+1820`, not clamped); opening assets (`asset`) as Revit's Family and USD's Reference; composition by `import` with collisions as build errors carrying provenance | ADR-0010 |
|
|
135
|
-
| v0.7 | The site shape (`polygon`) as the one written shape, kept in a quarantined layer; the full-feature showcase examples/tower/ | ADR-0011 |
|
|
136
|
-
|
|
137
|
-
## What those few dozen lines settled
|
|
138
|
-
|
|
139
|
-
Just as the essay predicted, writing two rooms and one door put four design decisions into words. The identity of a space is given by a human-readable hierarchical path. A boundary belongs to neither space; it is a first-class relation joining two paths. A connection is an opening on a boundary, and a subdivision with no head above it is expressed as `type:open`. Paths are cut as `/level/space`, and the exterior, which belongs to no level, sits directly beneath the site. The reasons and the alternatives for each are recorded in ADR-0001.
|
|
140
|
-
|
|
141
|
-
## The open questions (as they stood then)
|
|
142
|
-
|
|
143
|
-
Voids and spaces that span levels; the subdivision of semi-outdoor and exterior space (`/out` cannot reasonably stay monolithic); the two-tier granularity of room and zone — these were to be met head-on when a whole floor was written (M1). On the notation side there remained: a region limited to one rectangle (no L-shaped rooms), the description of a door's swing (v0 fell back on a drawing convention, "it opens toward the space written first"), the granularity of the opening vocabulary, the distribution of wall thickness (v0 fixed it to the centerline), and the area convention (v0 fixed it to wall centerlines). Correspondence with IFC GUIDs would be appended later as a layer of `id:` attributes, at import time (M5).
|
|
144
|
-
|
|
145
|
-
*Every one of these questions has since been answered; see [language.md](language.md) and [semantics.md](semantics.md) for the present tense.*
|
package/spec/en/scope.md
DELETED
|
@@ -1,229 +0,0 @@
|
|
|
1
|
-
**English** · [日本語](../scope.md)
|
|
2
|
-
|
|
3
|
-
# Scope — the three domains, and the surfaces that freeze
|
|
4
|
-
|
|
5
|
-
As of koyu v0.16.0 / muro 1.0. **This document is the norm for what is promised and what is not.**
|
|
6
|
-
For the grammar see [language.md](language.md), for the semantics [semantics.md](semantics.md), for the ledger of verdicts [validation.md](validation.md).
|
|
7
|
-
|
|
8
|
-
The lines drawn here are stronger than those drawn in any other document. Where another page of the spec disagrees with this one, **this one is right**.
|
|
9
|
-
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
## 1. The three domains
|
|
13
|
-
|
|
14
|
-
koyu is made of three domains. **They are kept apart because the quality demanded of them differs.**
|
|
15
|
-
|
|
16
|
-
| Domain | Where | Size | Quality | Version |
|
|
17
|
-
|---|---|---|---|---|
|
|
18
|
-
| **core** | `src/core/` | small | **must be clean** | **freezes** |
|
|
19
|
-
| **validation** | `src/validate/` | grows | may be messy | does not freeze |
|
|
20
|
-
| **presentation and build** | `src/draw/` and [ugatsu](https://github.com/kensnzk/ugatsu) | grows | may be messy | does not freeze |
|
|
21
|
-
|
|
22
|
-
**The dependency runs one way.** Validation and presentation both depend on core; core depends on neither. core stands and runs by itself. This one-way rule is not held by a sentence but machine-checked by `test/domains.test.ts`.
|
|
23
|
-
|
|
24
|
-
Without the separation two things happen at once — **the mess seeps into core and freezes there, and core's caution stops validation and presentation from growing.** The separation itself is the condition under which validation and presentation are allowed to be messy. Mess in a domain that does not freeze is cheap, because it can be rewritten at any time. Mess in a domain that freezes stays forever.
|
|
25
|
-
|
|
26
|
-
> **koyu does not make coordinates. ugatsu does not make meaning.**
|
|
27
|
-
|
|
28
|
-
---
|
|
29
|
-
|
|
30
|
-
## 2. What core holds
|
|
31
|
-
|
|
32
|
-
The source language, its semantics, and the mouth it offers to machines.
|
|
33
|
-
|
|
34
|
-
- **the grammar and semantics of muro** — what may be written, and what what is written means
|
|
35
|
-
- **composition** — the strength order of layers, the resolution of single values, the editing of sets, provenance ([composition.md](composition.md))
|
|
36
|
-
- **identity** — uid and path, the identity of a relation ([§5](#5-identity))
|
|
37
|
-
- **derivation** — the rules that make **a unique form** from the authored composition, and their reference implementation ([§6](#6-the-contract-of-derivation))
|
|
38
|
-
- **the diagnostics of structural consistency** — the `Diagnostic[]` that `check` returns
|
|
39
|
-
- **the queries** — area, graph, route, opening area. **But they deliver no verdict** ([§4](#4-the-queries-deliver-no-verdict))
|
|
40
|
-
- **the machine format** — canonical JSON ([canonical-json.md](canonical-json.md))
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## 3. The extent of the guarantee — what "the check passed" means
|
|
45
|
-
|
|
46
|
-
**The meaning of a green `koyu check` is defined as follows.**
|
|
47
|
-
|
|
48
|
-
> **For the structural layer and the interpreted layer, the declared invariants hold. About the carrier layer it says nothing. About soundness as architecture it says nothing.**
|
|
49
|
-
|
|
50
|
-
This is not a verdict but **part of reading**, and it sits at the same layer as a JSON parser rejecting broken JSON.
|
|
51
|
-
|
|
52
|
-
### 3.1 What is guaranteed
|
|
53
|
-
|
|
54
|
-
| Guarantee | Diagnostic |
|
|
55
|
-
|---|---|
|
|
56
|
-
| the uniqueness of paths and identities | UID01-04 / ZON02 / the duplicate-path error raised during composition |
|
|
57
|
-
| the existence of what is referenced | REF01 / an undefined asset / the zone a polygon corresponds to (SIT04) |
|
|
58
|
-
| the definition of levels | LVL01 / VRT02 |
|
|
59
|
-
| overlapping regions (in plan) | GEO01 / GEO02 |
|
|
60
|
-
| overlapping regions (in section) | HGT01 / HGT02 |
|
|
61
|
-
| that composition resolves determinately | A composition error (`SourceError` — [composition.md](composition.md)) |
|
|
62
|
-
| **the sufficiency of the information a form needs** | SUF01-04 |
|
|
63
|
-
| the soundness of relations | BND01-06 / VRT01-06 |
|
|
64
|
-
| the uniqueness of derivation (the form of openings, segs, lines, columns, vertical circulation) | OPN01-08 / SEG01-08 / LIN01-03 / COL01-02 / RUN01-05 |
|
|
65
|
-
| the domain of values of interpreted attributes | ATT01-03 / DAY01 |
|
|
66
|
-
| the soundness of the given data | SIT01 / SIT02 |
|
|
67
|
-
|
|
68
|
-
**Overlap in section (HGT01/HGT02) is in core because it is the sectional counterpart of overlap in plan (GEO01/GEO02).** The ceiling below and the floor above occupying the same z is the same kind of contradiction as two spaces whose regions overlap, and no unique form can be made from it. Architectural judgements about height — floor-to-floor heights, eaves heights, diagonal setback envelopes — are not guaranteed; those are the validation surface.
|
|
69
|
-
|
|
70
|
-
### 3.2 What is not guaranteed
|
|
71
|
-
|
|
72
|
-
**Daylighting, coverage ratio, floor area ratio, continuity of the envelope, whether a stair is comfortable to climb, whether a door can actually be installed, means of egress, road frontage — and every other kind of soundness as architecture.** And **the meaning of the attributes of the carrier layer**.
|
|
73
|
-
|
|
74
|
-
These do not fail to exist; they are **on another surface**. [validation.md](validation.md) and `koyu validate` hold them.
|
|
75
|
-
|
|
76
|
-
### 3.3 Do not claim it "works" on the strength of green
|
|
77
|
-
|
|
78
|
-
Even when `check` is green the building need not be usable. Because the default between touching spaces is a wall ([ADR-0014](../../docs/decisions/0014-default-boundaries.md)), a two-storey building that declares not one door is **completely sealed while staying green**. Nor does an envelope grow by itself. Circulation is answered separately by `doors`, and verdicts by `validate`.
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
## 4. The queries deliver no verdict
|
|
83
|
-
|
|
84
|
-
core holds the queries of aggregation and of the graph. **But they deliver no verdict.**
|
|
85
|
-
|
|
86
|
-
| Query | What core returns | What validation says |
|
|
87
|
-
|---|---|---|
|
|
88
|
-
| daylighting | floor area and effective window area (`daylightInputs`) | whether 1/7 is met (`daylight.ratio`) |
|
|
89
|
-
| the site | site area, road frontage length, building footprint area, gross floor area, and their quotients (`siteReport`) | the 2 m frontage (`site.frontage`), escaping the site (`site.escape`) |
|
|
90
|
-
| vertical circulation | number of steps, riser, going, slope (`verticalRuns`) | crampedness (`stair.proportion`), slope (`run.slope`) |
|
|
91
|
-
| the envelope | the perimeter segments that face nothing (`envelopeGaps`) | whether that is a hole (`envelope.gap`) |
|
|
92
|
-
| circulation | the path of fewest doors and passability (`doorsBetween` / `passable`) | whether the outside can be reached (`access.unreachable` and the rest of `access.*`) |
|
|
93
|
-
| columns and openings | columns standing on the grid and openings placed on segments (`columnsFor` / `placeOpening`) | whether they overlap (`column.blocksdoor`) |
|
|
94
|
-
|
|
95
|
-
**The thresholds are on the architecture's side.** Neither 1/7 nor 2 m nor 240 mm is an invariant the authored composition must satisfy. Returning the number is core's work; drawing a line through the number is validation's.
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## 5. Identity
|
|
100
|
-
|
|
101
|
-
**Only spaces and aggregations (space / zone) carry a uid. And it is not required.**
|
|
102
|
-
|
|
103
|
-
- **a space with a uid written on it** is canonically that uid. It is the same thing even when its path changes
|
|
104
|
-
- **a space without one** corresponds by path. Rename it and the correspondence is cut
|
|
105
|
-
- **the identity of a relation (boundary) is derived from the spaces at its two ends.** A uid cannot be written on a relation — a relation always lies between two spaces, so fixing both ends fixes the relation. Writing a uid per relation would make relations outnumber spaces, which is to cut away, by one's own hand, the aim that "one building fits in the machine's field of view"
|
|
106
|
-
- **the identity of an opening or of an inclusion (a column) is derived from the object that contains it and a name unique within it**
|
|
107
|
-
|
|
108
|
-
It is not required so that **the author can choose the strength of the guarantee**. Write one only on the spaces that must be pointed at across time.
|
|
109
|
-
|
|
110
|
-
> **Be responsible for identity, not for content.**
|
|
111
|
-
|
|
112
|
-
### 5.1 The list of things that can carry a uid is closed
|
|
113
|
-
|
|
114
|
-
`uid` may be written on `space` and `zone`, and **that list is closed**. Those are the only two elements whose ledger entry ([vocabulary.md](vocabulary.md)) holds `uid`; writing it on any other element is ATT03 (a key not in the ledger), and writing it on `level` is a syntax error. **There is no path where it is silently ignored.**
|
|
115
|
-
|
|
116
|
-
It can be written with a namespace — `acme.uid:` — but that is the carried tier ([§7](#7-the-three-layers-of-attributes)), which core never looks at. **It does not amount to having given the thing an identity.**
|
|
117
|
-
|
|
118
|
-
### 5.2 The rule of generation, and the extent of non-collision
|
|
119
|
-
|
|
120
|
-
**A uid is never derived from the path, nor from anything else in the model.** Derive it and the token would change on a rename, which erases what a uid means (surviving a rename). When a machine makes one it is **random** — the prefix `u-` plus 16 characters of Crockford base32, 80 bits in all ([ADR-0039](../../docs/decisions/0039-identity-generation.md)).
|
|
121
|
-
|
|
122
|
-
```
|
|
123
|
-
u-7f3k9m2qx4b8dhtv
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
**The guarantee has two levels.**
|
|
127
|
-
|
|
128
|
-
| Against | Guarantee |
|
|
129
|
-
|---|---|
|
|
130
|
-
| the model already composed | **No collision.** The generator checks it, and UID03 under `check` proves it |
|
|
131
|
-
| layers not composed here, and other repositories | **Probabilistic only.** At 80 bits, a million tokens still collide with probability below 10⁻¹². When certainty is needed, compose them and run `check` |
|
|
132
|
-
|
|
133
|
-
**Assignment is an explicit act.** No tool writes a uid until the author writes one or calls `newUids` / the MCP tool `new_uids`. Not even `write_layer`.
|
|
134
|
-
|
|
135
|
-
### 5.3 A name has to point at exactly one thing
|
|
136
|
-
|
|
137
|
-
Since identity is "the containing subject plus a name unique within it", **one name pointing at two things is a break in identity** — the set edits of composition (`= window W1` / `- column C1`) cannot say which one they mean. This is checked (UID04), and refused on the composition side as well.
|
|
138
|
-
|
|
139
|
-
**A name inherited from an asset is not a claim of identity.** The `name` in `asset W1 window … name:掃き出し窓` is the type's name, and putting the same product twice on one wall is ordinary design. The claim is only the name written on that opening's own line.
|
|
140
|
-
|
|
141
|
-
---
|
|
142
|
-
|
|
143
|
-
## 6. The contract of derivation
|
|
144
|
-
|
|
145
|
-
Not making the form and not being able to make it are different things. **From this description a unique form must be derivable.**
|
|
146
|
-
|
|
147
|
-
The assurance is first of all structural — the given data supplies coordinates, a relation supplies a seat in the shape of a shared face, and substance sits on that seat. **Substance is born holding a seat.** Four further things are fixed.
|
|
148
|
-
|
|
149
|
-
1. **The rules of derivation belong to the specification**, not to the implementation. If the rules differ from consumer to consumer, different buildings come out of the same source. Then it is not a source. The rules are held by [derivation.md](derivation.md) (the account from the side of semantics is [semantics.md](semantics.md) §2-4)
|
|
150
|
-
2. **Sufficiency is checked.** Whether the information a form needs is present is part of structural consistency (SUF01-04). **It is a check of completeness, not a judgement of soundness**
|
|
151
|
-
3. **A reference implementation exists and is exercised by the tests.** `derive(model): Form` is the only entrance, and it **has no appearance** — it returns no color, no typeface, no line weight, no annotation string. `src/draw/` and ugatsu merely draw this `Form` ([derivation.md](derivation.md) §7)
|
|
152
|
-
4. **Uniqueness is a predicate a machine can hold.** "Unique" is not a promise made in prose; it is written as this implication ([ADR-0041](../../docs/decisions/0041-derivation-uniqueness.md)):
|
|
153
|
-
|
|
154
|
-
```
|
|
155
|
-
toCanonical(a) === toCanonical(b) ⟹ derive(a) ≡ derive(b)
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
**The form is a function of the canonical form.** The canonical form is the definition of "what counts as the same building" ([canonical-json.md](canonical-json.md)), so whatever it discards — the written order of a line's endpoints, the declaration order of boundaries, the order of lines in the file — must not move the form. If it does, either something discardable was not discarded, or something that had to be kept was thrown away
|
|
159
|
-
|
|
160
|
-
**"Several forms come out of one composition" is a defect.** What may be several is the **appearance**, not the form.
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
## 7. The three layers of attributes
|
|
165
|
-
|
|
166
|
-
| Layer | Examples | core's stance |
|
|
167
|
-
|---|---|---|
|
|
168
|
-
| **structural** | path, type, region, level, the other side of a relation, kind | **always read.** If it is broken, nothing is read |
|
|
169
|
-
| **interpreted** | `h` `w` `at` `daylight` `road` `site` `style` … | the ledger ([vocabulary.md](vocabulary.md)) defines the domain of values, and it **is read** |
|
|
170
|
-
| **carrier** | `acme.sensor` `bems.temp` `survey.measured` … | **not read.** Open, under a namespace |
|
|
171
|
-
|
|
172
|
-
**The carrier layer carries a namespace (dot separated).** It is written like `acme.sensor:23`. An unknown key without a namespace is **an error (ATT03)** — this keeps a one-letter slip such as `heigh:2400` from quietly having no effect, and it is the only shape in which "not looked at" can be told apart from "looked at and found sound".
|
|
173
|
-
|
|
174
|
-
Being open and being trustworthy are compatible as long as the boundary is declared. Without the declaration, **"not looked at" cannot be told apart from "looked at and found sound"**. "Nothing wrong" in that state means nothing. **Being able to carry something without judging it is a legitimate state, and saying so explicitly is the condition of that freedom.**
|
|
175
|
-
|
|
176
|
-
For the details see [vocabulary.md](vocabulary.md).
|
|
177
|
-
|
|
178
|
-
---
|
|
179
|
-
|
|
180
|
-
## 8. The eight surfaces that 1.0.0 freezes
|
|
181
|
-
|
|
182
|
-
**1.0.0 is not the completion of features. It is the fixing of the surfaces promised not to break.**
|
|
183
|
-
|
|
184
|
-
| Surface | What is promised |
|
|
185
|
-
|---|---|
|
|
186
|
-
| **the grammar and semantics of muro 1.0** | what this version could read will be read with the same meaning ever after |
|
|
187
|
-
| **the rules of composition** | the six in [composition.md](composition.md). The same input always yields the same result |
|
|
188
|
-
| **identity** | the rules of §5. Same uid, same thing |
|
|
189
|
-
| **the three layers of attributes and the namespace** | §7, including the promise that the carrier layer is not read |
|
|
190
|
-
| **the machine format** | **it names its format version** ([canonical-json.md](canonical-json.md)). The same input yields the same bytes — the collation and the normalization are settled as norms. It holds the result of composition and holds no form |
|
|
191
|
-
| **the rules of derivation** | §6. Written out as specification, with a reference implementation offered as API |
|
|
192
|
-
| **the diagnostics of structural consistency** | codes and severity. The meaning of green agrees with the definition in §3 |
|
|
193
|
-
| **the public API and the CLI** | parsing, composition, canonicalization, the queries, derivation. Commands, arguments, exit codes |
|
|
194
|
-
|
|
195
|
-
### What is not subject to the freeze
|
|
196
|
-
|
|
197
|
-
**These may exist; that they are not subject to the freeze is stated explicitly.**
|
|
198
|
-
|
|
199
|
-
- **the generation and drawing of form** — `svgPlan` / `svgAxo` / the CLI's `plan` and `axo` / MCP's `plan_svg`. The CLI's **surface** (subcommand names, arguments, exit codes) freezes, but **the contents of the SVG do not**. Drawing only draws the `Form`, so **what may not change is the `Form`, not the SVG** ([derivation.md §9](derivation.md))
|
|
200
|
-
- **architectural verdicts** — the body of rules in [validation.md](validation.md) and the output of `koyu validate`. It is a surface that grows
|
|
201
|
-
- **the MCP tools** — treated as a surface that grows by addition
|
|
202
|
-
- **round trips to and from external formats, and import**
|
|
203
|
-
- **the surfaces for people** — editor support and authoring. ugatsu holds them
|
|
204
|
-
- **the meaning of the attributes of the carrier layer**
|
|
205
|
-
|
|
206
|
-
---
|
|
207
|
-
|
|
208
|
-
## 9. How the versions are counted
|
|
209
|
-
|
|
210
|
-
There are two lines of version.
|
|
211
|
-
|
|
212
|
-
- **the version of muro** — the language, its semantics, and the rules of composition. The **meaning** the machine format carries follows this version (it is another spelling of the same semantics)
|
|
213
|
-
- **the version of koyu** — the implementation. It declares which muro it implements
|
|
214
|
-
|
|
215
|
-
**The machine format carries a version of its spelling, which is neither of these two** — the `format` key ([canonical-json.md](canonical-json.md)). muro holds the semantics, but the same semantics may be re-spelled with different keys, so the spelling is counted separately.
|
|
216
|
-
|
|
217
|
-
ugatsu versions independently and declares the version of muro it follows. The validation surface carries no version and grows by addition.
|
|
218
|
-
|
|
219
|
-
**The two are different promises, so they need not arrive together** ([ADR-0042](../../docs/decisions/0042-two-version-lines.md)). muro's version promises "a file written this way keeps meaning this"; koyu's version promises "this implementation's surface will not break". As it stands muro has reached 1.0 and koyu is still 0.x — **the language is settled, the implementation has promised no freeze yet.**
|
|
220
|
-
|
|
221
|
-
---
|
|
222
|
-
|
|
223
|
-
## 10. What is not held
|
|
224
|
-
|
|
225
|
-
- **geometry in the authored source** (the exception is given data — the `polygon` of the site shape)
|
|
226
|
-
- **a mechanism for placement** — inclusion supplies no seat. Columns and equipment carry only "which space contains them", and no form can be made from that
|
|
227
|
-
- **including architectural verdicts in the contract of the source**
|
|
228
|
-
- **the pursuit of professional-practice resolution.** Coverage is not a value — adding more takes the thing out of the machine's field of view and breaks the aim
|
|
229
|
-
- **round-trip compatibility.** An exit is built; a round trip is not
|