Metadata-Version: 2.4
Name: kir-building
Version: 0.6.0
Summary: KIR — typed, verifiable IR for buildings. A building is a program.
Author: Dima
License: Apache-2.0
Project-URL: Homepage, https://github.com/5vbkgsghhh-hash/kir
Project-URL: Source, https://github.com/5vbkgsghhh-hash/kir
Keywords: revit,bim,compiler,ir,buildings,cad,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: shapely<3.0,>=2.0
Requires-Dist: networkx<4.0,>=3.0
Requires-Dist: pydantic<3.0,>=2.7.0
Requires-Dist: httpx<1.0,>=0.27.0
Provides-Extra: bridge
Requires-Dist: fastapi<1.0,>=0.115.0; extra == "bridge"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: jsonschema<5.0,>=4.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp<3.0,>=2.1; extra == "mcp"
Dynamic: license-file


<p align="center">
  <img src="assets/logo.png" width="256" alt="KIR building graph logo"/>
</p>

<h1 align="center">KIR</h1>

<p align="center">
  <b>A building is a program.</b><br/>
  Write buildings in Python. KIR type-checks them and compiles them to Revit C# —
  offline, for six Revit versions at once.
</p>

<p align="center">
  <img alt="pip install kir-building" src="https://img.shields.io/badge/install-pip%20install%20kir--building-blue">
  <img alt="Revit 2021-2026" src="https://img.shields.io/badge/targets-Revit%202021%E2%80%932026-005386">
  <img alt="Runs offline" src="https://img.shields.io/badge/to%20try%20it-no%20Revit%2C%20no%20licence-success">
  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-blue">
  <img alt="License Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue">
</p>

<p align="center">
  <a href="#build-a-building-in-60-seconds">Build one now</a> ·
  <a href="#be-wrong-on-purpose">Be wrong on purpose</a> ·
  <a href="#can-a-person-live-in-it-ask-before-revit">Design verdict</a> ·
  <a href="#what-you-actually-get">What you get</a> ·
  <a href="#hand-it-to-a-model-the-mcp-server">MCP server</a> ·
  <a href="#why-this-exists">Why</a> ·
  <a href="#how-it-works">How it works</a> ·
  <a href="#measured-not-promised">Measured numbers</a> ·
  <a href="#working-on-kir-itself">Contribute</a>
</p>

---

## Build a building in 60 seconds

```bash
pip install kir-building
```

Four direct dependencies, fifteen packages in a clean venv, no `sudo`. **Nothing on this
page needs Revit, a licence, a running service or a network** — Python 3.12 or newer is
the whole requirement.

Save this as `room.py`:

```python
from kir import compile_program
from kir.dsl import envelope, create_level, create_wall, build

envelope(intent="a room, 6 x 4 m")
level = create_level(elev_mm=0, name="Level 1")
corners = [(0, 0), (6000, 0), (6000, 4000), (0, 4000)]
for a, b in zip(corners, corners[1:] + corners[:1]):
    create_wall(p0_mm=a, p1_mm=b, level=level, height_mm=3000)

program = build()
out = compile_program(program, revit_version="2026", snapshot=None, bulk=True)
print(out.ok, "|", len(out.csharp), "characters of Revit C#")

versions = ["2021", "2022", "2023", "2024", "2025", "2026"]
ok = sum(compile_program(program, revit_version=v, snapshot=None, bulk=True).ok
         for v in versions)
print(f"compiled for {ok} of {len(versions)} Revit versions")
```

```console
$ python room.py
True | 20252 characters of Revit C#
compiled for 6 of 6 Revit versions
```

That is nine lines of building. `out.csharp` is finished Revit add-in code: transactions
opened and closed, millimetres converted to feet, API members chosen for that exact Revit
release, and every element read back after creation to check it is what you asked for.
You did not write any of that, and you cannot get it wrong.

Note what you also did not write. `create_level` returned a **handle**, and passing it as
`level=` is the whole of reference management — the language filled in
`{"by": "ref", "value": "level1"}`, the element ids, and the operation ids itself. There is
no `xyz` on a door, no feet anywhere, and no way to say "a window floating in the air":
that is not a case KIR validates, it is a sentence the language cannot form.

*(Run verbatim on 2026-09-04 against `kir-building` 0.5.0 installed from PyPI into a
`python3.12 -m venv` created from scratch. The character count includes your `intent`
string, so it moves if you change the text.)*

### Or one command

The repository ships a `kir` command that does all of the above and more in one line — it
prints the source of a small house, builds it, compiles it for six Revit versions, lists the
defaults the compiler chose for you, and judges whether a person could live in it:

```bash
git clone https://github.com/5vbkgsghhh-hash/kir && cd kir
pip install .
kir demo
```

```text
KIR: ЗДАНИЕ — ЭТО ПРОГРАММА. Вот весь исходник этого дома:
    ...
ВЫШЛО 7 операций — слоты, которых ты не назвал, язык заполнил САМ:
   0  create_level   id «level1»
   1  create_floor   id «floor1», level {"by": "ref", "value": "level1"}
   2  create_wall    id «wall1», level {"by": "ref", "value": "level1"}
   ...
КОМПИЛЯЦИЯ, 6/6 версий Revit, без Revit и без сети:
  2021     31506 знаков C#
  2022     31597 знаков C#
  ...
КВИТАНЦИЯ НАЗВАННОГО УМОЛЧАНИЯ, записей 5: выборы, которые сделал КОМПИЛЯТОР, а не автор.
  floor1.type — правило «doc_default»: решит revit, прочтётся обратно из result.floor1.type_name
  ...
═══ ВЕРДИКТ О ЗАМЫСЛЕ: НЕПРИГОДЕН ═══
  HAB030: Помещение 'Гостиная' (жилая) не имеет наружного окна — жить/готовить без
          естественного света нельзя.
```

*(Excerpted from 68 lines of output, run 2026-09-04 from a clone installed into a fresh venv.
`kir ops`, `kir skill`, `kir course`, `kir doctor` and `kir build FILE.json` are the rest of
the surface. **The `kir` command is newer than the current PyPI release (0.5.0)** — from
`pip install kir-building` today you get the library, and the `room.py` above; the command
arrives with the next release.)*

Two more one-liners, offline, and true of the published package today:

```bash
python -c "from kir import spec, sdk; print(len(spec.OPS), len(sdk.builders()))"
python -c "from kir.course import course; course()"
```

The first prints `82 82` — 82 operations in the registry, and one generated Python builder
per operation, so a signature cannot drift from the spec. The second prints the sixteen
lessons of the authoring course that ships inside the package.

> **Language, named rather than glossed.** KIR's refusals, the shipped examples and the
> authoring course an LLM reads are written in **Russian today**; diagnostic codes
> (`KIR-G101`, `HAB030`), operation names and the whole Python API are language-neutral.
> English text is not shipped yet.

## Be wrong on purpose

The point of a typed IR is what happens when you are wrong. Add a door to `room.py`:

```python
from kir import compile_program
from kir.dsl import envelope, create_level, create_wall, create_door, build

envelope(intent="a room with a door")
level = create_level(elev_mm=0, name="Level 1")
corners = [(0, 0), (6000, 0), (6000, 4000), (0, 4000)]
walls = [create_wall(p0_mm=a, p1_mm=b, level=level, height_mm=3000)
         for a, b in zip(corners, corners[1:] + corners[:1])]
create_door(host=walls[0], offset_mm=3000, symbol="0915 x 2134mm")

program = build()
out = compile_program(program, revit_version="2026", snapshot=None, bulk=True)
print("ok:", out.ok)
for d in out.diagnostics:
    print(d.code, "|", d.message_ru.splitlines()[0])
```

```console
ok: False
KIR-G103 | программа требует снапшот модели (census) для ground-стадии (резолв по имени/
default). Снимка требуют: create_door#door1.symbol. Без снимка эти слоты адресуются
только формой {"by": "element_id", "value": <id>}
```

A wall is geometry, so KIR can build it from numbers alone. A door is a *family symbol* that
must already exist in the document, and offline there is no document to ask. So the compiler
stops before emitting anything and names the exact slot — `create_door#door1.symbol`. Hand
it the one catalogue it needs and the same program compiles:

```python
snapshot = {"door_symbols": [{"id": 700, "name": "0915 x 2134mm"}]}
out = compile_program(program, revit_version="2026", snapshot=snapshot, bulk=True)
print("ok:", out.ok, "|", len(out.csharp), "characters of Revit C#")
```

```console
ok: True | 23031 characters of Revit C#
```

Now misspell the symbol — `symbol="Big Door"` — and keep the same snapshot:

```console
ok: False
KIR-G101 | door_symbols: «Big Door» не найден
candidates: [{'id': 700, 'name': '0915 x 2134mm'}]
```

Nothing was emitted, nothing was half-built, and the refusal names the pool it looked in and
what *is* in that pool. This is the single rule the project is built on: a call ends in
exactly one of two typed outcomes — an `ok` carrying a read-back proof, or a machine-readable
`refused` with candidates and a route. A silently-wrong answer is the forbidden state.

## Can a person live in it? Ask before Revit

KIR also judges the *building*, not just the syntax — habitability rules run over the numbers
your program already contains. Save this as `verdict.py`:

```python
from kir.course import design_check
from kir.dsl import envelope, create_level, create_wall, create_room, build

envelope(intent="is this a place a person can live?")
level = create_level(elev_mm=0, name="Level 1")
corners = [(0, 0), (6000, 0), (6000, 4000), (0, 4000)]
for a, b in zip(corners, corners[1:] + corners[:1]):
    create_wall(p0_mm=a, p1_mm=b, level=level, height_mm=2400)
create_room(xy=(3000, 2000), level=level, name="Living room", function="жилая")

design_check(build()["ops"])
```

```console
$ python verdict.py
═══ ВЕРДИКТ О ЗАМЫСЛЕ: НЕПРИГОДЕН ═══
источник: САМОПРОВЕРКА — судится ЗАЯВЛЕННОЕ программой, а не построенное
прочитано: doors 0, levels 1, rooms 1, stairs 0, walls 4, windows 0
полигон помещения получили 1 из 1 (100%), высота известна у 0
БЛОКИРУЮЩИЕ 1: HAB030×1
  HAB030: Помещение 'Living room' (жилая) не имеет наружного окна — жить/готовить без
          естественного света нельзя.
НЕ ОЦЕНЕНО правил 13 из 20: HAB061, HAB001, HAB002, HAB003, HAB004, HAB010, HAB011,
                            HAB012, HAB022, HAB031, HAB041, HAB042, HAB050
```

*Unfit: a living room with no exterior window.* No Revit was involved. And look at the last
line — the verdict names the **thirteen rules it could not evaluate and why** (no stairs in
the program, no known ceiling height), instead of reporting a clean pass it never measured.
Coverage you did not have is never rendered as a zero.

## What you actually get

| | |
|---|---|
| **A building fits in a context window** | The 60-storey tower below is **3 394 685 characters** as emitted Revit C# and **13 210 characters** as the KIR program a model edits — **257× less**, roughly 1M tokens against 4k. That is the difference between a model that can re-plan a floor and one that cannot read the building it was asked to change. |
| **One program, six Revit versions** | The same intent compiles differently against Revit 2021 and 2026. You write it once; version choice is the compiler's job, and the six-version compile runs offline before any Revit is opened. |
| **Refusals instead of broken models** | Every operation carries declared post-conditions that are read back off the live element after it is created. A violated post-condition rolls the transaction back and returns a typed refusal — never an `ok` wrapping an error. |
| **Retries are safe** | Operation ids are stamped into the model inside the same transaction, so re-running a program skips what is already stamped. Resume-from-op-K is simply "skip what carries a stamp". |
| **It reads buildings too** | The reverse pipeline lifts an existing model back into a typed program, and anything it cannot express becomes a typed atom *with a reason code*, never a silent drop. That is what turns "we can build" into "we can edit what already exists". |
| **82 operations, not 35 516 API members** | Walls, floors, roofs, stairs, railings, curtain systems, ducts, pipes, rebar, rooms, tags, families, booleans, sweeps — a closed registry with kinds, bounds and tolerances, replacing an encyclopaedic API a human learns over years. |

Writing into a **live** model additionally needs a Revit 2021–2026 installation, its API
reference assemblies, the .NET Roslyn compile service and a separately running bridge — none
of which are part of this repository. Everything above runs without them.

## Hand it to a model: the MCP server

KIR ships an [MCP](https://modelcontextprotocol.io) server, so Claude Desktop, Claude Code or
any MCP host can author, compile and inspect buildings through it. **The server needs the
`mcp` extra** — without it `python -m kir.mcp` dies with a bare
`ModuleNotFoundError: No module named 'mcp'`, so install it explicitly:

```bash
pip install "kir-building[mcp]"
python -m kir.mcp            # stdio; --http --port 8765 for Streamable HTTP
```

```console
INFO kir.mcp: поверхность: kir_author, kir_spec, kir_compile, kir_rehearse, kir_open, kir_write, kir_preview
```

The extra costs 20 packages on top of the core fifteen. `kir.mcp` is not in the `import kir`
chain, so installing without it changes nothing else.

| tool | what it does | needs Revit |
|---|---|---|
| `kir_author` | Python that builds the program, run in a sandbox; returns typed IR ops | no |
| `kir_spec` | the registry contract for one op — call form, slots, bounds, witness tolerances | no |
| `kir_compile` | C# for every supported Revit version, inline or as files | no |
| `kir_rehearse` | which obligations will *not* be checked — before a single round-trip | no |
| `kir_preview` | a floor plan as deterministic SVG, plus a census of what is **not** on it | no |
| `kir_open` | ask the host which document is open and take a handle to it | **yes** |
| `kir_write` | write a program into that open document — the only door that changes anything | **yes** |

Five of the seven are fully offline: nothing is sent anywhere, every reply carries
`wrote_nothing: true`, and no model is touched. The two live doors are named separately on
purpose, and `kir_write` asks a human before it commits.

`kir_preview` also carries an [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)
UI (`ui://kir/floorplan.html`): hosts that negotiated the extension render the plan inline,
with zoom, per-level sheets and the census panel. Hosts that did not get the same SVG and
census as data — the extension adds handling, never content.

The author sandbox runs the script in a separate process with no reachable network (its own
namespace, probed on every run), an empty root, no writable filesystem and an import
allow-list; its only exit is the list of IR ops, which the compiler then type-checks in full.

To register the server with an MCP host, point it at **the interpreter of the venv you
installed into**, by absolute path. A bare `python` may not be on `PATH` at all, and where
it is it may be older than this package's floor — stock Ubuntu 22.04 ships Python 3.10:

```jsonc
// stdio server entry
{ "command": "/path/to/venv/bin/python", "args": ["-m", "kir.mcp"] }
```

*(Verified 2026-09-04 against `kir-building` 0.5.0 from PyPI in a fresh venv: the stdio door
completed the MCP handshake at protocol revision **2025-11-25**, listed the seven tools above,
and `kir_author` returned a four-wall program with `wrote_nothing`. `--http --port 8797`
answered `200` on `POST /mcp`. The client entry above is configuration, not a command, and was
not executed here.)*

## Why this exists

Language models write code well. They do not write buildings well, and the reason is
structural rather than a matter of training scale. A building does not fit in a context
window — one of the models we measure against holds **90 758 elements**. The work is
stateful: a wall must exist before a door can be hosted in it, and that state lives inside an
application, not in a file you can diff. It is re-entrant, because the same instruction issued
twice must not produce two doors. And it is versioned six ways: the same intent compiles
differently against Revit 2021 and Revit 2026.

So the practice today is to have the model write Revit C# directly, and the arithmetic of that
practice is available to us. Across **85 374 production compile errors** logged over seven
weeks, two codes account for **48.4%** — `CS1061` (32.3%) and `CS0117` (16.1%) — and both are
the same failure: *a member of the Revit API that does not exist*. Another ~10%
(`CS0104`/`CS0012`) are namespace and assembly-reference problems. Roughly **60% of all
production compile errors are spent fighting the surface of an API**, not describing a
building.

**KIR is an attempt to fix that**: the model concentrates on 3D, geometry and composition;
units, transactions, API versions, hosts, witnesses and rollbacks belong to a compiler.

<p align="center">
  <img src="assets/tower-side-by-side.png" alt="The same tower twice in Revit" width="720"/>
</p>

<p align="center"><sub>The same building, held two ways: as emitted C# no model can read, and
as the typed program a model actually edits. The render is a visual companion, not the
measurement.</sub></p>

## Python computes the form, KIR proves it

The division of labour is the whole design. Python owns loops, numpy, shapely, parameter
search and reusable functions; KIR owns units, versions, transactions and the proof. Clone the
repository — **the examples are not part of the installed package** — and run either
demonstration offline:

```bash
git clone https://github.com/5vbkgsghhh-hash/kir && cd kir
pip install .
python examples/tower_numpy.py
```

```text
100 строк питона → 6 опов написано → 840 после экспансии → 780 элементов (программ KIR: 3)
этажей 60, талия 30%, закрутка 120°
ломаная против синуса: 217 мм по радиусу
компиляция: 6/6 версий ['2021', '2022', '2023', '2024', '2025', '2026']
```

100 lines of Python become the 60-storey tower from
[`examples/tower_numpy.py`](examples/tower_numpy.py) — 6 authored operations, 840 after
expansion, 780 elements, compiled for all six Revit versions. That third line is the house
style: `stack.transform` interpolates linearly while the script asked for a sine, so the
example prints `piecewise vs. true sine: 217 mm` along the radius instead of pretending there
is none. An approximation you did not name is a silently wrong answer.

`examples/contour_shapely.py` does the mirror case: shapely computes an offset ribbon
(176 vertices simplified to 18 within a 220 mm tolerance) and KIR places the slab and walls the
perimeter. Both ship with their measured outputs in
[**examples/**](examples/README.md).

## Show me the program itself

A KIR program is data, not code. `build()` returns exactly this, and you can write it by hand:

```json
{
  "ir_version": "1.0",
  "intent": "one bay: wall + door + window",
  "ops": [
    {"op": "create_wall", "id": "wall1",
     "p0_mm": [0, 0], "p1_mm": [6000, 0],
     "level": {"by": "name", "value": "Level 1"}, "height_mm": 3300},
    {"op": "create_door", "id": "door1",
     "host": {"by": "ref", "value": "wall1"},
     "offset_mm": 1200, "sill_mm": -100,
     "symbol": {"by": "name", "value": "0915 x 2134mm"},
     "mirrored": false, "hand_flipped": false, "facing_flipped": false}
  ]
}
```

Hand that dict straight to `kir.compile_program(program, revit_version="2026", snapshot=...)`.
Everything above it is a front end over exactly this JSON, and no front end can express
anything the registry lacks or hide a refusal.

### Two front ends

`kir.dsl` — used everywhere on this page — accumulates implicitly: a call places its operation
in the current program and hands back a handle. `kir.sdk` is the explicit form, where a call
returns a dict you pass to `p.add(...)`; it adds macros such as `stack`, which is what the
tower example needs. Both are **generated from the registry at import time, one builder per
op**, so neither can drift from the spec:

```python
import numpy as np
from kir import sdk

p = sdk.program(intent="tower with a waist")
with p.stack(levels=20, h_mm=3600,
             transform=sdk.transform(scale_xy_top=[0.8, 0.8],
                                     twist_deg_total=24)) as floor:
    for a in np.linspace(0, 2 * np.pi, 12, endpoint=False):
        floor.add(sdk.create_column(xy=[20000 * np.cos(a), 20000 * np.sin(a)],
                                    level=sdk.BY_MACRO, symbol="К 300x300"))

p.stats()   # {'ops_written': 1, 'ops_expanded': 260, 'elements': 240}

snap = {"column_symbols_structural": [{"id": 6011, "name": "К 300x300"}]}
out = p.compile(version="2023", snapshot=snap)
out.ok, len(out.csharp)   # (True, 935314)
```

One authored op becomes 260 and 240 elements. Get the symbol name wrong and the refusal names
the pool it searched — `KIR-G101 column_symbols_structural: «К 300x300» не найден` — rather
than failing somewhere later.

## How it works

```mermaid
flowchart TB
    subgraph FWD["FORWARD — intent becomes a building"]
        direction LR
        SDK["Python front end<br/>kir.dsl · kir.sdk · numpy · shapely"]
        PROG["Typed program<br/>KIR JSON, ops + refs"]
        REG["Registry<br/>one source of truth:<br/>schema · grammar · docs · emitters"]
        GRND["ground<br/>symbolic selectors to ElementIds"]
        PLAN["typecheck + plan<br/>mm only · DAG · txn partitions"]
        EMIT["emit<br/>per-version C#"]
        GATE["Roslyn gate<br/>2021–2026"]
        RUN["live Revit<br/>one TransactionGroup"]
        SDK --> PROG --> REG --> GRND --> PLAN --> EMIT --> GATE --> RUN
    end

    RUN --> WIT["witness<br/>read the RESULT back, not the call"]
    WIT --> OUT{"exactly two<br/>typed outcomes"}
    OUT -->|ok| OKN["geometry_ok · semantic_ok · topology_ok"]
    OUT -->|refused| REFN["diagnostics + candidates + route<br/>KIR-G/T/L/E/C/X/W codes"]
    REFN -.->|"IR-level repair, max 3 rounds"| PROG

    subgraph REV["REVERSE — a building becomes a program"]
        direction LR
        DOC["live model"]
        L0["extract to L0<br/>48 categories · full-model census"]
        L1["lift to typed ops<br/>or a typed ATOM with a reason"]
        FOLD["fold to canon<br/>template-canon/4 · fidelity-canon/1"]
        MAT["materialize<br/>chunked programs, host-atomic"]
        DOC --> L0 --> L1 --> FOLD --> MAT
    end

    RUN -.-> DOC
    MAT -.->|"rebuild · edit · diff"| PROG
```

A stage-by-stage account of both pipelines lives in the language contracts under
[`kir/specs/`](kir/specs/) (`SPEC_V1.md`, the decompile spec) and the design specs under
[`docs/laws/`](docs/laws/). Shorter orientation: [`docs/KIR.md`](docs/KIR.md),
[`docs/RUNTIME.md`](docs/RUNTIME.md), [`docs/BUILDING_GRAPH.md`](docs/BUILDING_GRAPH.md),
[`docs/CLASH.md`](docs/CLASH.md).

### What happens to one op

```mermaid
sequenceDiagram
    autonumber
    participant M as Model — the LLM
    participant K as KIR compiler
    participant R as Revit — live document

    M->>K: create_wall — p0, p1, level by name, height 3300 mm
    K->>K: parse · typecheck · mm to feet · plan the DAG
    K->>R: snapshot query — resolve selectors
    R-->>K: level id, wall type pool

    alt selector missing or ambiguous
        K-->>M: refused KIR-G102 + candidates + route
    else grounded
        K->>K: emit C# for THIS Revit version
        K->>R: TransactionGroup — Wall.Create, op_id stamped
        R-->>K: new element id
        K->>R: read the element BACK
        R-->>K: LocationCurve, height param, level id
        alt postconditions hold
            K-->>M: ok + witness — geometry_ok, semantic_ok, topology_ok
        else violated
            K->>R: RollBack
            K-->>M: refused KIR-X004 + which axis failed
        end
    end
```

## A building has a history

A single write is not the whole story. A real project gets read, edited, and read again dozens
of times, and for most of this project's life nothing here remembered that revision N and
revision N+1 were the same building — every rebuild started from zero. Four modules close that
gap, and together they are exactly a version-control system, mapped onto concepts a reader
already knows:

| git concept | KIR module | what it actually is |
|---|---|---|
| content-addressed object store | `merkle` | a Merkle DAG over the folded building tree — a repeated floor is one node, not N |
| a history you can replay | `journal` | append-only per-building revision log; replaying it reconstructs any past revision exactly |
| applying a diff | `rebuild` | materializes only the delta between two revisions instead of the whole building |
| three-way merge | `merge3` | base / current document / target revision, with a real `conflicting` verdict — never a silent overwrite |

The merged state is deliberately identity-free — a canonical op carries no `ElementId` — which
is exactly what makes it mergeable; a program is still materialized from one concrete revision,
never from the merge itself. The routes that drive these four against an open Revit document
are part of a private product and are not in this open-core slice, but their offline half ships
and runs right here, no bridge and no Revit needed:

```text
pytest kir/decompile/tests/test_merkle.py kir/decompile/tests/test_rebuild.py \
       kir/decompile/tests/test_journal.py kir/decompile/tests/test_merge3.py
107 passed, 1 warning in 6.65s   -- run 2026-09-04, Python 3.12, this repository, no Revit
                                 -- the count is the claim; the seconds are this machine's
```

`pytest` is not pulled in by `pip install .` — it arrives with the `dev` extra; see
[Working on KIR itself](#working-on-kir-itself).

## Checked invariants

The reverse pipeline enforces five checked invariants: full document coverage, a reason
recorded for every element it cannot express, witnesses that match the data actually read,
contamination marking for partial reads, and neutral identifiers. Each invariant is backed by a
test or verification run; a violation stops the build or run.

```mermaid
flowchart LR
    subgraph LAWS["§18 — five invariants"]
        direction TB
        L1["1 · CENSUS<br/>lifted + atoms + not_read<br/>= the whole document"]
        L2["2 · RECEIPT<br/>every cut emits<br/>element_id + typed_reason"]
        L3["3 · WITNESS AXIS<br/>sign only the axis<br/>you actually read"]
        L4["4 · CONTAMINATION<br/>a partial read marks<br/>everything derived from it"]
        L5["5 · NEUTRALITY<br/>no device ids, install paths,<br/>or locale-only keys"]
    end

    subgraph CORE["what they enclose"]
        direction TB
        C1["compile"] --> C2["execute in Revit"] --> C3["read back"] --> C4["publish a number"]
    end

    L1 -->|"run-fatal identity check + CI fixture"| CORE
    L2 -->|"rows + failures contract on every side stage"| CORE
    L3 -->|"certificate lint: kind to legal reader"| CORE
    L4 -->|"header round-trip test + A5 gate on partial data"| CORE
    L5 -->|"CI pattern lint"| CORE

    CORE --> R1["built, with a witness"]
    CORE --> R2["typed refusal, with a route"]
    CORE -.->|forbidden by construction| R3["silently wrong"]
```

Full account: [`docs/laws/TYPED_HONESTY_SPEC.md`](docs/laws/TYPED_HONESTY_SPEC.md) — *Five
Conservation Laws of Honesty for an AI Agent in CAD*.

<a id="measured-not-promised"></a>
## Measured, not promised

<p align="center">
  <img alt="82 ops registered" src="https://img.shields.io/badge/registry-82%20ops%20(77%20writing)-success">
  <img alt="MCP 7 tools" src="https://img.shields.io/badge/MCP-7%20tools%2C%205%20offline-success">
</p>

Everything below is derived from an instrument on the date shown, not from memory. The
re-runnable rows are checked by a shipped instrument that reads this very table and recomputes
each number — `python3.12 tools/readme_numbers.py --check` returns 1 on any divergence. Rows
marked *historical* are older runs whose instrument or corpus is not shipped here; they carry
their date and cannot be re-run from this repository alone.

| Fact | Value | Date / how |
|---|---|---|
| Ops in the registry | **82** — 77 writing, 5 query | 2026-09-04, `len(spec.OPS)` |
| Generated SDK builders | **82 — one per op** | 2026-09-04, `len(sdk.builders()) == len(spec.OPS)` |
| Source size | **301 production modules**, **694 test files** | 2026-09-04, `python3.12 tools/readme_numbers.py --check` |
| Python syntax check | **1029 files parsed, 0 errors** | 2026-09-04, `ast.parse` over every `*.py` outside `build/` |
| Install into a clean venv | **PASS** — exit 0, 15 packages, no `sudo` | 2026-09-04, `pip install .` in a fresh `python3.12 -m venv` |
| Install from PyPI with the MCP extra | **PASS** — 35 packages, `kir-building` 0.5.0 | 2026-09-04, `pip install "kir-building[mcp]"` |
| The `room.py` above, from the PyPI package | **PASS** — 6/6 versions, 20 252 chars of C#, no snapshot | 2026-09-04, the block at the top of this page |
| Offline six-version compile of the shipped example | **PASS** — 3 programs, 840 ops, 780 elements, 6/6 versions | 2026-09-04, `python examples/tower_numpy.py` from a clone |
| MCP door | **PASS** — handshake at revision 2025-11-25, 7 tools listed, stdio and `--http` | 2026-09-04, `kir-building[mcp]` 0.5.0 from PyPI |
| Version-control half, offline | **107 passed**, under 10 s | 2026-09-04, `pytest kir/decompile/tests/test_{merkle,rebuild,journal,merge3}.py` |
| Emitted C# for the 60-storey tower, one version | **3 394 685 characters** against **13 210** for the KIR program — **257×** | 2026-09-04, Revit 2023, compact JSON, from a clone |
| Historical live baseline | **31 of 31 writing ops** had a witnessed run — of the 31 that existed then | 2026-07-28 local telemetry; telemetry is not shipped here |
| Historical six-version compile gate | **1 056 Roslyn compilations, PASS** | 2026-07-28 local gate run |
| Historical reverse-direction coverage | **48 categories; 92.83% on the 90 758-element R2026 model** | 2026-07-27/28 local runs |
| Historical production compile errors structurally inexpressible in KIR | **≈60%** of 85 374 over seven weeks | local report; completeness caveats apply |

## Repository layout

Everything here is the compiler and its instruments; the product that hosts them is a separate
repository. Revit is one target of several, and the package is agnostic about which one it
emits for.

- `kir/` — the forward compiler: registry, typecheck, plan, per-version emitters, typed
  diagnostics, witness/acceptance machinery;
- `kir/dsl.py`, `kir/sdk.py` — the two Python front ends, both generated from the registry;
- `kir/__main__.py` — the `kir` command: `demo`, `ops`, `skill`, `course`, `doctor`, `build`;
- `kir/decompile/` — the reverse pipeline: extract, lift, fold, materialize, and the
  version-control half (`merkle`, `journal`, `rebuild`, `merge3`);
- `kir/checker/`, `kir/clash/` — the judge and the clash pipeline;
- `kir/mcp/` — the MCP door: seven tools, five of them offline;
- `kir/instruments/` — instruments that run offline, without Revit: `compile_gate_offline`,
  `bounds_audit`, `unwired_census`, `scope_audit`, `snapshot_janitor`, `canon_state`, and others;
- `kir/course/`, `kir/skill.py` — the authoring course and the skill an LLM is handed;
- `kir/specs/` — the language contracts: `SPEC_V1.md`, the decompile spec;
- `kir/bridge/` — the client side of the bridge protocol, plus a mock server for offline runs;
- `kir/tests/` and `kir/*/tests/` — the unit, contract, golden and property tests;
- `examples/` — small SDK programs that compile offline. **Cloned only: `examples/` is not in
  the wheel**, so `pip install kir-building` does not give you these files;
- `docs/laws/` — the design specs behind the honesty, merkle and verified layers.

The Revit bridge itself, the .NET Roslyn compile service, the product's admin routes, runtime
data, credentials and logs are intentionally not part of this repository.

**The published source lags behind the published package, and by how much.** The wheel on PyPI
is built from an internal working tree; the public GitHub mirror is refreshed rarely and, as of
this release, is **425 commits behind** it (last public commit: 2026-09-01). So the `Source`
link on the PyPI page will show you code *older* than the package you just installed — the
`kir` command, this README and the 0.6.0 fixes are not there yet. We would rather say this than
let the two look identical. What you install is what the numbers on this page were measured
against; the mirror is what lags. If you need the exact source of a release, open an issue and
ask — the mirror is pushed on request, not on a schedule.

**What a bare install does *not* get you.** `kir.ports.supplied()` prints what the host
environment has handed the language; in a clean install it prints `()` — nothing. That is the
definition, not a fault: the language on its own has been given no environment. Everything on
this page works at `()`; live writing is what needs a host to register ports.

<a id="working-on-kir-itself"></a>
## Working on KIR itself

To work against the tree instead of an installed copy:

```bash
python3.12 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
PYTHONPATH="$PWD" python -m pytest \
    kir/decompile/tests/test_merkle.py kir/decompile/tests/test_rebuild.py \
    kir/decompile/tests/test_journal.py kir/decompile/tests/test_merge3.py -q
```

Three traps worth naming, all bought by measurement rather than reasoning:

- **Name the four files; do not point pytest at the directory.** `kir/decompile/tests` collects
  185 `test_*.py` files, and one of them allocates about 5 GB and takes the rest of the run down
  with it. The four named above are the ones the number in the table refers to.
- **`PYTHONPATH` must be absolute.** A bare `PYTHONPATH=.` is shadowed by any stray `kir.py`
  beside you, and the refusal then blames the wrong module.
- **Four direct dependencies, and `httpx` is one of them.** It looks like bridge-only machinery,
  but `compile_client.py` sits in the package import chain; dropping it into an extra made
  `import kir` fail in a clean venv. The dependency list is settled by a run, not by an argument.

**Machine-specific paths: measured, not asserted.** `python3.12 tools/host_path_census.py` sweeps
the shipped tests for absolute paths of the machine they were measured on: on 2026-09-04 it found
35 test files that know the host tree — 7 of them only through a declared constant, 21 through a
bare literal — and exactly **1** of those rides in the built wheel (`kir/tests/conftest.py`). No
credentials, keys or device identifiers were found anywhere in the wheel.

## For auditors

Beyond the compiler core in `kir/`:

- **Language contracts:** [`kir/specs/`](kir/specs/) — `SPEC_V1.md`, `KIR_DECOMPILE_SPEC.md`
- **Laws of honesty / verified / merkle:** [`docs/laws/`](docs/laws/)
- **LLM authoring skill + sandbox course:** `kir/skill.py` (14 774 characters, 2026-09-04) and
  [`kir/course/`](kir/course/) — `python -c "from kir.course import course; course()"` prints its
  sixteen lessons
- **README numbers, recomputed:** `python3.12 tools/readme_numbers.py --check`
- **CI evidence & secret boundary:** `.github/workflows/kir-evidence.yml`, `kir-security.yml`
- **Offline instruments, runnable with no Revit:** [`kir/instruments/`](kir/instruments/) — each one
  is expected to name what it could not read rather than report a zero it never measured

---

<p align="center">
  <sub>Apache License 2.0 — see <a href="LICENSE">LICENSE</a>.</sub>
</p>
