kilonova 0.1.0__tar.gz

kilonova-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run ruff check src tests examples tools
+      - run: uv run ruff format --check src tests examples tools || true
+
+  test:
+    name: tests + quasar conformance (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      # kilonova's oracle is quasar's own CI test-case suite: the conformance job
+      # serves every case and diffs the client-visible address space against the
+      # reference nodesets - the same gate quasar's C++ CI uses for its backends.
+      - name: Check out quasar (conformance oracle)
+        uses: actions/checkout@v4
+        with:
+          repository: quasar-team/quasar
+          path: quasar
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --dev
+      - name: Unit + UX tests
+        run: uv run pytest tests -q --ignore=tests/conformance
+      - name: Conformance vs quasar reference nodesets
+        env:
+          KILONOVA_QUASAR_ROOT: ${{ github.workspace }}/quasar
+        run: uv run pytest tests/conformance -v

kilonova-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

kilonova-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+uv.lock
+dump*.xml
+dist/

kilonova-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Paris Moschovakos
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

kilonova-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: kilonova
+Version: 0.1.0
+Summary: Pure-Python OPC UA servers from quasar Design files — the quasarnova family's no-codegen engine
+Project-URL: Homepage, https://github.com/quasarnova-team/kilonova
+Project-URL: Repository, https://github.com/quasarnova-team/kilonova
+Project-URL: Issues, https://github.com/quasarnova-team/kilonova/issues
+Author-email: Paris Moschovakos <paris@moschovakos.com>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: asyncua,cern,opc-ua,opcua,quasar,scada,server
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: asyncua>=2.0
+Requires-Dist: lxml>=5
+Description-Content-Type: text/markdown
+
+# kilonova
+
+[![CI](https://github.com/quasarnova-team/kilonova/actions/workflows/ci.yml/badge.svg)](https://github.com/quasarnova-team/kilonova/actions/workflows/ci.yml)
+
+What is this?
+-------------
+
+kilonova serves a quasar `Design.xml` + `config.xml` as a live OPC UA server in pure
+Python — no code generation, no C++. It produces the same address space as a
+[quasar](https://github.com/quasar-team/quasar)-generated server (same `ns=2` string NodeIds,
+same dotted `parent.child` addressing), so quasar ecosystem tools —
+[Cacophony](https://github.com/quasar-team/Cacophony)/WinCC OA,
+[UaoForQuasar](https://github.com/quasar-team/UaoForQuasar) clients, plain OPC UA clients —
+work against it unmodified.
+
+A *kilonova* is the luminous flash of a neutron-star merger — a lighter, faster transient
+in the nova family. This kilonova is the pure-Python engine of the
+[quasarnova](https://github.com/quasarnova-team) family: successor of
+[MilkyWay](https://github.com/quasar-team/MilkyWay) (Piotr Nikiel's 2021 prototype, and
+briefly named microquasar), rebuilt from scratch on
+[asyncua](https://github.com/FreeOpcUa/opcua-asyncio) 2.x.
+
+Basic usage mode
+----------------
+
+1. Install (Python ≥ 3.10): `pip install .` (from this repository, for now)
+1. Run your existing quasar server's design, unchanged:
+   `kilonova run --design Design/Design.xml --config bin/config.xml`
+1. Point any OPC UA client at `opc.tcp://host:4841` — the address space is quasar's.
+1. Dump a running server's address space (uasak_dump-style NodeSet2):
+   `kilonova dump --endpoint opc.tcp://127.0.0.1:4841 --output dump.xml`
+
+Device logic is plain Python (see [doc/DeviceLogic.md](doc/DeviceLogic.md)):
+
+```python
+from kilonova import Server
+
+server = Server("Design.xml", config_path="config.xml")
+
+@server.read("sca1.adc")                 # source variable: runs inside the client read
+async def read_adc(obj):
+    return await hardware.read_adc()
+
+@server.method("sca1.reset")             # method handler
+async def reset(obj):
+    await obj.setOnline(0)               # generated setter, quasar naming
+
+async with server:
+    ...
+```
+
+What works
+----------
+
+All 12 cases of quasar's own CI test suite pass against the reference nodesets
+(cache/source/calculated variables, methods incl. arguments, config entries and
+restrictions, singleVariableNode, design/config instantiation, StandardMetaData).
+Production designs (ATLAS ATCA, CAEN, CanOpen) were probed at structural parity against
+live C++ servers of both backends. Details: [doc/Parity.md](doc/Parity.md).
+
+Limitations
+-----------
+
+- Device logic is registered per address at runtime — there is no generated `D<Class>`
+  skeleton (that is the point).
+- Design-mandated children are instantiated unconditionally; C++ device logic may create
+  some conditionally.
+- No server-side security policies yet (NoSecurity endpoint only).
+- Values live in asyncua's address space; extreme write rates were not a design goal.
+
+Documentation
+-------------
+
+- [doc/Architecture.md](doc/Architecture.md) — modules and data flow
+- [doc/DeviceLogic.md](doc/DeviceLogic.md) — the user API
+- [doc/Parity.md](doc/Parity.md) — the parity contract and current status
+- [PLAN.md](PLAN.md) — milestone log and engineering notes
+
+Credits
+-------
+
+- Paris Moschovakos (paris@moschovakos.com) — kilonova
+- Piotr Nikiel — quasar concept and architecture; MilkyWay, the predecessor
+
+License: BSD-2-Clause.

kilonova-0.1.0/PLAN.md

@@ -0,0 +1,126 @@
+# kilonova — implementation plan
+
+One feature at a time; every step lands with tests, and every user-visible behaviour is tested
+**from the UX**: a real asyncua `Client` connects to the running server and reads the address
+space, exactly as WinCC OA, UaoForQuasar, or uasak_dump would.
+
+## The parity contract
+
+The oracle is quasar's own CI: `quasar/.CI/test_cases/manifest.json` declares ~12 cases, each
+with `Design.xml` + `config.xml` + `reference_ns2.xml`. The gate (same semantics as
+`NodeSetTools/nodeset_compare.py`):
+
+- every `UAObject` / `UAVariable` / `UAMethod` NodeId in the reference must exist exactly once
+  in our client-side dump;
+- every attribute present in the reference (`BrowseName`, `DataType`, `ValueRank`,
+  `AccessLevel`) must match exactly. Format rules learned from uasak_dump: NS0 ids as `i=N`,
+  quasar ids as `ns=2;s=path`, XSD-default attributes suppressed (DataType `i=24`,
+  ValueRank `-1`, AccessLevel `1`);
+- `StandardMetaData` is compared in full for the `default_design` case (its reference is
+  the meta oracle); for the other cases it is ignored exactly as quasar's own CI does —
+  their references carry stale, mutually contradictory meta snapshots (minThreads i=7 vs
+  i=12). kilonova's meta is live: log-level variables drive the Python loggers, and
+  `<StandardMetaData>` config sections set initial levels.
+
+## Milestones
+
+| # | Feature | UX test gate | Status |
+|---|---------|--------------|--------|
+| M0 | Scaffold: pyproject/uv, ruff, pytest, git | `uv run pytest` runs | done |
+| M1 | Design layer: typed `Design.xml` parser | parses all quasar CI test-case designs | done |
+| M2 | Server core on asyncua: boot, ns=2, ObjectTypes | Client connects, browses, finds types | done |
+| M3 | Config instantiation: recursive objects, dotted string NodeIds | Client resolves exact NodeIds from config tree | done |
+| M4 | Cache variables: DataType/ValueRank/AccessLevel/initialValue+Status | Client reads every attribute + value + status | done |
+| M5 | MilkyWay parity: `set_cv`, generated `setXxx` setters, live demo | Client subscribes, sees ticking value | done |
+| M6 | Conformance runner + dumper (uasak_dump equivalent) | parity table over quasar CI cases | done |
+| M7 | Methods: nodes + real async handlers (decorator API) | Client calls method, gets result | done |
+| M8 | Source variables + delegated-write callbacks | Client read/write triggers user coroutine | done |
+| M9 | CalculatedVariables (safe formula eval) | Client reads computed value | done |
+| M10 | StandardMetaData subtree | default_design case passes un-ignored | done |
+| M11 | Config restrictions + cardinality validation | invalid config rejected like C++ Configurator | done |
+| M12 | Ecosystem smoke: UaoForQuasar client + Cacophony against kilonova | generated client works unmodified | done (local legs) |
+| M13 | parity-night third backend column (production servers) | probe parity vs live C++ backends | done — ATCA/CAEN full structural parity; CanOpen surfaced 2 cross-backend quirks (see .parity-night/cells/*-kilonova/deps-note.txt) |
+
+## Current parity table (M6 gate, StandardMetaData ignored)
+
+Run `uv run pytest tests/conformance -v` with a quasar checkout next door.
+As of M6 (all verified by `pytest tests/conformance`, 2026-07-11):
+
+| quasar CI case | verdict |
+|----------------|---------|
+| default_design | PASS (full comparison incl. StandardMetaData) |
+| methods | PASS |
+| async_methods | PASS |
+| cache_variables | PASS |
+| config_entries | PASS |
+| recurrent_hasobjects | PASS |
+| single_variable_node | PASS |
+| instantiation_from_design | PASS |
+| config_restrictions | PASS |
+| defaulted_instance_name | PASS |
+| source_variables | PASS |
+| calculated_variables | PASS |
+
+Method *nodes* (incl. `.args`/`.return_values` argument properties) are at parity as part of
+M6; M7 added callable handlers via the `@server.method("sca1.scale")` decorator API.
+
+M8 (source variables): `@server.read("sca1.adc")` runs the device coroutine *inside* the
+client's read transaction (asyncua's awaited PreRead callback — true quasar synchronous-read
+semantics, impossible in the 2021 sync prototype); `@server.write(...)` intercepts client
+writes to source variables and `addressSpaceWrite="delegated"` cache variables before storage
+(raise `ua.UaStatusCodeError` to refuse with a real per-item status; unhandled delegated
+writes answer BadNotImplemented). AccessLevel encodes the design's read/write modes
+(read-only 1, write-only 2, read-write 3); until first device interaction source variables
+serve BadWaitingForInitialData. Server-side `set_cv` bypasses delegation by design.
+
+M9 (calculated variables): config-level `<FreeVariable>`, `<CalculatedVariable>` and
+`<CalculatedVariableGenericFormula>` are served; formulas compile to a whitelisted AST (no
+eval), inputs are dotted addresses, `$thisObjectAddress` and `$applyGenericFormula(...)`
+are substituted, and recalculation runs through server-side datachange callbacks — a
+dependent recomputes *inside* the write that changed its input, so the next read is fresh.
+Any null/bad input yields BadWaitingForInitialData. **All 12 quasar CI oracle cases now pass.**
+
+M12 (ecosystem smoke, local legs — 2026-07-11): Cacophony generates its WinCC OA CTRL
+artifacts cleanly from kilonova-served designs, and `tools/cacophony_crosscheck.py`
+verifies every periphery address the generated configParser.ctl would assign resolves on a
+live kilonova server: 8/8 on the SCA demo, **600/600 on the production ATCA design**.
+UaoForQuasar client classes generate cleanly for production classes (Manager/Board/FanTray)
+and their generated NodeId construction (`parentId + ".var"`, parent namespace) is exactly
+kilonova's addressing. Deferred: compiling/running the generated C++ client (needs UASDK
+— a docker parity-image job, natural follow-up in the parity-night campaign).
+
+## Design decisions (2026 rewrite, vs the 2021 MilkyWay prototype)
+
+- **asyncua 2.x** (python-opcua is deprecated); async-first, `asyncio.run` friendly.
+- **No copy-paste of quasar's DesignInspector** — a clean-room typed design layer
+  (`design.py`) exposing only what the server needs.
+- **Setters done right**: `set` + upper-first camelCase (`setMyVar`, not `.title()`), async.
+- **DataType always set from the Design** (the 2021 prototype derived it from values;
+  null-initialized variables then reported BaseDataType).
+- **Conformance from day one**: the dumper reads the address space through a real client
+  connection — testing "from the UX" is the default, not an afterthought.
+- The 2021 bugs are regression-tested: initialStatus actually applied, numeric initialValue
+  works, unsupported config elements raise instead of NameError-ing.
+
+## Parity rules learned the hard way (2026-07-11 adversarial review)
+
+A 38-agent review panel with live-repro verification found parity bugs the M6 gate is
+structurally blind to (the comparison is one-directional and value-less). All fixed and
+regression-tested in `tests/test_robustness.py`:
+
+- **DataType follows nullPolicy**: C++ quasar sets the concrete DataType only for
+  `nullForbidden` variables; `nullAllowed` ones serve BaseDataType (i=24) so null writes
+  stay legal. (asyncua's type heuristic refuses writes to BaseDataType nodes — instance-local
+  override in `Server._allow_writes_to_base_datatype_nodes`, worth upstreaming.)
+- **Arrays are `<value>` elements** in config.xml (quasar's generated Configuration.xsd);
+  text-content arrays are rejected loudly, as the C++ Configurator would.
+- **`defaultConfigInitializerValue`** is honoured when the config omits a value.
+- **singleVariableNode instances** take configuration values.
+- **Array config entries** are NOT published as properties (C++ skips them).
+- Robustness: unknown config attributes/children and out-of-range integers are rejected at
+  load; `set_cv` raises on refused writes and range violations; method calls validate
+  argument counts (BadArgumentsMissing/BadTooManyArguments).
+
+Known gate limitations (roadmap): the comparer checks only NodeId+attributes (like quasar's
+own CI) — values and references are dumped but not compared; strengthening it beyond the C++
+gate is future work alongside M11.

kilonova-0.1.0/README.md

@@ -0,0 +1,85 @@
+# kilonova
+
+[![CI](https://github.com/quasarnova-team/kilonova/actions/workflows/ci.yml/badge.svg)](https://github.com/quasarnova-team/kilonova/actions/workflows/ci.yml)
+
+What is this?
+-------------
+
+kilonova serves a quasar `Design.xml` + `config.xml` as a live OPC UA server in pure
+Python — no code generation, no C++. It produces the same address space as a
+[quasar](https://github.com/quasar-team/quasar)-generated server (same `ns=2` string NodeIds,
+same dotted `parent.child` addressing), so quasar ecosystem tools —
+[Cacophony](https://github.com/quasar-team/Cacophony)/WinCC OA,
+[UaoForQuasar](https://github.com/quasar-team/UaoForQuasar) clients, plain OPC UA clients —
+work against it unmodified.
+
+A *kilonova* is the luminous flash of a neutron-star merger — a lighter, faster transient
+in the nova family. This kilonova is the pure-Python engine of the
+[quasarnova](https://github.com/quasarnova-team) family: successor of
+[MilkyWay](https://github.com/quasar-team/MilkyWay) (Piotr Nikiel's 2021 prototype, and
+briefly named microquasar), rebuilt from scratch on
+[asyncua](https://github.com/FreeOpcUa/opcua-asyncio) 2.x.
+
+Basic usage mode
+----------------
+
+1. Install (Python ≥ 3.10): `pip install .` (from this repository, for now)
+1. Run your existing quasar server's design, unchanged:
+   `kilonova run --design Design/Design.xml --config bin/config.xml`
+1. Point any OPC UA client at `opc.tcp://host:4841` — the address space is quasar's.
+1. Dump a running server's address space (uasak_dump-style NodeSet2):
+   `kilonova dump --endpoint opc.tcp://127.0.0.1:4841 --output dump.xml`
+
+Device logic is plain Python (see [doc/DeviceLogic.md](doc/DeviceLogic.md)):
+
+```python
+from kilonova import Server
+
+server = Server("Design.xml", config_path="config.xml")
+
+@server.read("sca1.adc")                 # source variable: runs inside the client read
+async def read_adc(obj):
+    return await hardware.read_adc()
+
+@server.method("sca1.reset")             # method handler
+async def reset(obj):
+    await obj.setOnline(0)               # generated setter, quasar naming
+
+async with server:
+    ...
+```
+
+What works
+----------
+
+All 12 cases of quasar's own CI test suite pass against the reference nodesets
+(cache/source/calculated variables, methods incl. arguments, config entries and
+restrictions, singleVariableNode, design/config instantiation, StandardMetaData).
+Production designs (ATLAS ATCA, CAEN, CanOpen) were probed at structural parity against
+live C++ servers of both backends. Details: [doc/Parity.md](doc/Parity.md).
+
+Limitations
+-----------
+
+- Device logic is registered per address at runtime — there is no generated `D<Class>`
+  skeleton (that is the point).
+- Design-mandated children are instantiated unconditionally; C++ device logic may create
+  some conditionally.
+- No server-side security policies yet (NoSecurity endpoint only).
+- Values live in asyncua's address space; extreme write rates were not a design goal.
+
+Documentation
+-------------
+
+- [doc/Architecture.md](doc/Architecture.md) — modules and data flow
+- [doc/DeviceLogic.md](doc/DeviceLogic.md) — the user API
+- [doc/Parity.md](doc/Parity.md) — the parity contract and current status
+- [PLAN.md](PLAN.md) — milestone log and engineering notes
+
+Credits
+-------
+
+- Paris Moschovakos (paris@moschovakos.com) — kilonova
+- Piotr Nikiel — quasar concept and architecture; MilkyWay, the predecessor
+
+License: BSD-2-Clause.

kilonova-0.1.0/doc/Architecture.md

@@ -0,0 +1,53 @@
+# Architecture
+
+What is this?
+-------------
+
+How a Design file becomes a served address space. One page; the code is small
+(~1500 lines) and each module has one job.
+
+Data flow
+---------
+
+```
+Design.xml ──> design.py ──────┐
+                               ├──> address_space.py ──> asyncua Server (ns=2)
+config.xml ──> config.py ──────┘         │
+                                         ├── objects.py     QuasarObject handles, setters
+                                         ├── calculated.py  formulas + recalculation graph
+                                         └── meta.py        StandardMetaData subtree
+server.py orchestrates; dispatches methods / source reads / delegated writes
+dump.py    reads it all back through a real client (uasak_dump equivalent)
+```
+
+Modules
+-------
+
+| Module | Job |
+|--------|-----|
+| `design.py` | Typed, frozen model of Design.xml. Total over quasar's CI corpus; unknown constructs fail loudly at instantiation, not parsing. |
+| `config.py` | config.xml → instance tree. Validates like the C++ Configurator: unknown attributes/children, hasobjects, `<value>` arrays, restrictions input. |
+| `oracle.py` | quasar dataType ↔ OPC UA type maps, value parsing, integer ranges, configRestriction checks. (Named after quasar's own Oracle.) |
+| `address_space.py` | Builds ObjectTypes (`ns=2;i=1000+`) and instances (`ns=2;s=parent.child`). Owns the parity-critical attribute rules. |
+| `objects.py` | `QuasarObject`: `set_cv`, `get_cv`, generated `setXxx` async setters. |
+| `server.py` | Lifecycle + handler registries (`@server.method/read/write`), source-read PreRead hook, delegated-write interception. |
+| `calculated.py` | Config-level CalculatedVariables/FreeVariables: whitelisted-AST formulas (no `eval`), datachange-driven recalculation. |
+| `meta.py` | StandardMetaData, live: log-level nodes drive Python logging. |
+| `dump.py` | Client-side NodeSet2 dump + reference comparison (the conformance gate). |
+| `cli.py` | `kilonova run` / `kilonova dump`. |
+
+Design decisions
+----------------
+
+- **asyncua 2.x, async-first.** Reads of source variables await device coroutines *inside*
+  the read transaction (asyncua PreRead callback); calculated variables recompute inside the
+  write that changed an input. The 2021 sync prototype could do neither.
+- **No copy-paste of DesignInspector.** The design layer is clean-room and typed; drift
+  against quasar is caught by parsing quasar's whole CI corpus in the test suite.
+- **Parity rules live in one place** (`address_space.py`): DataType is concrete only for
+  `nullPolicy="nullForbidden"` (else BaseDataType), ValueRank −1/1/−3 (scalar/array/UaVariant),
+  AccessLevel from `addressSpaceWrite` or source read/write modes.
+- **Handlers are late-bound by address.** Registration works before or after `start()`;
+  unregistered methods/writes answer proper OPC UA status codes.
+- **One asyncua override**, documented in `server.py`: BaseDataType variables accept any
+  concrete value type (OPC UA Part 3 semantics; upstream FIXME).

kilonova-0.1.0/doc/DeviceLogic.md

@@ -0,0 +1,87 @@
+# Device logic
+
+What is this?
+-------------
+
+In C++ quasar you implement `D<Class>` methods. In kilonova there is no generated
+skeleton: you register plain async Python functions by dotted address. Everything below is
+the entire user API.
+
+Objects and cache variables
+---------------------------
+
+```python
+server = Server("Design.xml", config_path="config.xml")
+await server.start()                       # or: async with server:
+
+sca1 = server.objects["sca1"]              # dotted addresses, as in the address space
+await sca1.setOnline(42)                   # generated setter (quasar naming: setMyVar)
+await sca1.set_cv("online", 42)            # same thing, explicit
+await sca1.set_cv("online", 0, status=ua.StatusCodes.Bad)   # value + status
+value = await sca1.get_cv("online")        # None while status is bad
+```
+
+`set_cv` raises on refused writes (type mismatch, null into `nullForbidden`) and on
+integer range violations — no silent drops.
+
+Methods
+-------
+
+```python
+@server.method("sca1.scale")
+async def scale(obj, factor):              # obj is the owning QuasarObject
+    return factor * 2.0                    # mapped to the Design's return values
+```
+
+- Argument counts are validated (`BadArgumentsMissing` / `BadTooManyArguments`).
+- Unregistered methods answer `BadNotImplemented`.
+- Multiple return values: return a tuple. A single array return value is never unpacked.
+
+Source variables
+----------------
+
+```python
+@server.read("sca1.adc")                   # addressSpaceRead: runs INSIDE the client read
+async def read_adc(obj):
+    return await hw.read()                 # value
+    # or: return value, ua.StatusCodes.Good
+    # or: return ua.DataValue(...)
+
+@server.write("sca1.dac")                  # addressSpaceWrite
+async def write_dac(obj, value):
+    if not 0 <= value <= 10:
+        raise ua.UaStatusCodeError(ua.StatusCodes.BadOutOfRange)   # client gets this
+    await hw.write(value)
+```
+
+Until the first interaction a source variable serves `BadWaitingForInitialData`.
+
+Delegated cache variables
+-------------------------
+
+`addressSpaceWrite="delegated"` cache variables use the same `@server.write` decorator: the
+handler runs before the value is stored, its exception status is returned to the client,
+and an unregistered delegated write answers `BadNotImplemented`. Server-side `set_cv` never
+triggers the handler (it *is* device logic).
+
+Calculated variables and free variables
+---------------------------------------
+
+Config-level, exactly as in C++ quasar:
+
+```xml
+<FreeVariable name="fv" type="Double" initialValue="5"/>
+<CalculatedVariable name="sum" value="$thisObjectAddress.fv + 7"/>
+<CalculatedVariableGenericFormula name="Doubled" formula="$thisObjectAddress.fv * 2"/>
+```
+
+Formulas are compiled to a whitelisted AST (numbers, addresses, `+ - * / % ^`) — never
+`eval`. Dependents recompute inside the write that changed an input; null/bad inputs
+propagate `BadWaitingForInitialData`.
+
+Logging
+-------
+
+Standard Python `logging`, loggers `kilonova.*`. The StandardMetaData log-level nodes
+(`TRC/DBG/INF/WRN/ERR`) set those loggers at runtime, like LogIt on a C++ server; a config
+`<StandardMetaData>` section sets initial levels.

kilonova-0.1.0/doc/Parity.md

@@ -0,0 +1,62 @@
+# Parity
+
+What is this?
+-------------
+
+kilonova's definition of done: serve the address space the C++ quasar framework would,
+verified — never claimed. Two gates exist; both read the server through a real OPC UA
+client connection.
+
+Gate 1: quasar's own CI oracle
+------------------------------
+
+`tests/conformance` loads `quasar/.CI/test_cases/manifest.json`, serves each case's
+Design + config in-process, dumps the address space (uasak_dump-compatible NodeSet2) and
+compares it against the case's `reference_ns2.xml`:
+
+1. Have a quasar checkout next door (or set `KILONOVA_QUASAR_ROOT`).
+1. `uv run pytest tests/conformance -v`
+
+Comparison semantics (same as quasar's NodeSetTools): every `UAObject`/`UAVariable`/
+`UAMethod` NodeId in the reference must exist exactly once in the dump, with every
+reference attribute (`BrowseName`, `DataType`, `ValueRank`, `AccessLevel`) equal.
+`StandardMetaData` is ignored except for the `default_design` case, whose reference *is*
+the meta oracle (quasar's own CI ignores it everywhere; the checked-in references carry
+mutually contradictory meta snapshots).
+
+Current status: **12/12 cases PASS.**
+
+Gate 2: live production servers
+-------------------------------
+
+The `.parity-night` campaign compares probes of real servers. kilonova runs as a third
+backend column, no docker/build:
+
+```
+bash .parity-night/scripts/run_kilonova_cell.sh <cell> <server-src> <config.xml> <port>
+python3 .parity-night/scripts/compare.py cells/<a>/probe.json cells/<b>/probe.json
+```
+
+Results (2026-07-11): ATCA and CAEN at full structural parity vs both live C++ backends;
+CanOpen surfaced two genuine cross-backend deltas (method-argument AccessLevel: kilonova
+agrees with UASDK; FreeVariable writability: kilonova agrees with open62541).
+
+Expected, accepted differences
+------------------------------
+
+- Source variables report `err:BadWaitingForInitialData` where C++ device logic answers —
+  a kilonova cell has no device logic.
+- LogIt components in StandardMetaData reflect each build (`mule`, `ThreadPool`,
+  `open62541` on C++; kilonova serves its own subsystems).
+- Design-mandated children are instantiated unconditionally (C++ device logic may skip
+  some at runtime).
+
+Ecosystem cross-checks
+----------------------
+
+- Cacophony: `tools/cacophony_crosscheck.py` verifies every periphery address the
+  generated `configParser.ctl` would assign resolves on a live kilonova —
+  600/600 on the production ATCA design.
+- UaoForQuasar: client classes generate cleanly from production designs; the generated
+  NodeId construction is exactly kilonova's addressing. Compile/run of the C++ client
+  needs UASDK (docker) — pending.