refdef 0.1.0__tar.gz

refdef-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

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

@@ -0,0 +1,31 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.13.5"
+      - run: uv sync
+      - run: uv python install 3.14
+      - run: uvx --from rust-just==1.59.0 just ci
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        if: github.event.repository.private == false
+        with:
+          repository: OleJBondahl/refdef
+          path: sibling
+      - run: uv run python scripts/family_compare.py sibling
+        if: github.event.repository.private == false

refdef-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: docs
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.13.5"
+      - run: uv run python scripts/build_site.py
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: .site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

refdef-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.13.5"
+      - name: The tag matches the package version
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing: no token secret
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          attestations: true

refdef-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.superpowers/
+claude-tools/
+dist/
+.site-src/
+.site/
+.refdef/

refdef-0.1.0/.python-version

@@ -0,0 +1 @@
+3.15.0

refdef-0.1.0/AGENTS.md

@@ -0,0 +1,12 @@
+# Agent guide
+
+- Docs site: https://olejbondahl.github.io/refdef/
+- Surface: `python -m refdef api`, snapshot in `docs/api-snapshot.txt`
+- Guide: `docs/guide/`
+- Design: `DESIGN.md`
+- Rules: `RULES.md`
+- A change follows RULES.md.
+- Design-review paths: `DESIGN.md`, `RULES.md`, `docs/api-snapshot.txt`, `src/refdef/tables/`, `tests/corpus/`.
+  A commit touching them needs a `Design-review: <ID>` trailer.
+- A need the surface does not meet is a reviewed design change, never a workaround.
+- Use `uv` only, with exact pins.

refdef-0.1.0/CLAUDE.md

@@ -0,0 +1,48 @@
+# refdef: agent guide
+
+refdef is a library of reference designations: strict, typed, immutable Python values for the tags
+that name things in a plant, with no runtime dependency. A sibling library follows the same family rules.
+Docs: <https://olejbondahl.github.io/refdef/>. Surface: `python -m refdef api`.
+
+## Read first
+
+Read `DESIGN.md`, then `RULES.md`. They bind: a change follows RULES.md, and code that disagrees
+with them is wrong. Family rules F1-F17 are shared with the sibling library; R1-R12 are ours.
+
+## Gate
+
+`just ci` runs locally (no hosted gate beyond one CI job): ruff, ty, vulture, pytest with a 95 %
+coverage floor, the tests on Python 3.14, the two guards, and the strict site build. Its last
+stdout line is `site built: .site`. Each shared test guards one family rule:
+
+- `test_deps` (F1): no runtime dependency, stdlib and the package only.
+- `test_pure` (F2), `test_check` and `test_malformed` (F3): frozen values, no I/O, issues as values.
+- `test_vocab` (F4): a closed vocabulary is never a bare `str`.
+- `test_boundary` (F5, F6, F13): no boundary names, no application default, no sibling import.
+- `test_wording` (F7 and the em-dash rule): no standard cited by number, clause or year.
+- `test_surface` (F8, F15): the snapshot equals `python -m refdef api`; no operators on surface classes.
+- `test_docs` (F9) and `test_site`: every name has a docstring and a runnable guide block.
+- `test_lean` (F10): no nested def, 300 code lines, short docstrings, every noqa with a reason.
+- `test_release_guard` (F11) and `test_design_guard` (F12): the guard scripts can fail.
+- `test_licence` (F14), `test_agents` (F16), `test_standalone` (F17), `test_family_rules`, `test_pyproject_pins`.
+
+## Process
+
+- F12: a commit that touches a review path (`DESIGN.md`, `RULES.md`, `docs/api-snapshot.txt`,
+  `src/refdef/tables/`, `tests/corpus/`) carries a trailer `Design-review: <ID>`. The maintainer approves the
+  contract; the design reviewer approves surface and table changes.
+- F13: a missing need is a reviewed extension of the surface, never a workaround or a private import.
+- F17: name no application anywhere, in a tracked or an untracked file, or in a commit message.
+- One source of truth for the surface: `docs/api-snapshot.txt`, regenerated with `just api-write`,
+  never edited by hand. A new surface name adds its door to `[tool.family].doors` and `_api.DOORS`
+  together, a docstring, a runnable guide block, a CHANGELOG line and its `docs/llms.txt` lines.
+- The identical test set listed in `scripts/family_files.txt` is copied byte for byte between the
+  sibling repositories; `scripts/family_compare.py` checks it. Edit it in both or in neither.
+
+## Style
+
+- `uv` only; no bare `python` or `pip`. Dependencies are exact pins (`name==X.Y.Z`).
+- No em-dashes in any text file.
+- Lean limits (F10): 15 statements, 12 branches, complexity 8, no nested `def`, 300 code lines per
+  module, docstrings of one summary line plus at most two of why, `# noqa: CODE - reason`.
+- Stage named paths with git; never `git add -A`.

refdef-0.1.0/DESIGN.md

@@ -0,0 +1,69 @@
+# refdef: design
+
+refdef is a small Python library for reference designations: the tags that name the things in a plant, a machine or a cabinet (`=M1+ER-K2`, `-X1:3`, `-KE1:DI03`). It is compatible with IEC practice. This file is the current truth of the design; `RULES.md` holds the rules every change must keep, and the two change only through the process in the last section.
+
+## Purpose
+
+A designation names an occurrence of a thing by its place in one or more trees: what it does (function, `=`), what it is (product, `-`) and where it sits (location, `+`). Every electrical engineer who scripts, generates or checks drawings, lists and PLC configurations in Python meets these tags, and every tool passes them around as strings and then re-splits, re-sorts and re-checks them in slightly different ways. refdef gives the tag one structured value, one strict way to print it, one lenient way to read it, and the operations a tool needs on top: relative paths, common prefixes, free-number allocation, natural sort, a class-code table and a check that reports issues. It has no runtime dependency, does no I/O and holds no global state.
+
+## The family
+
+Three libraries share the work, and each fact has one home:
+
+- `symdef` draws: symbols, frames, markers, their geometry and styles.
+- `elecdef` says what a thing is: kinds of devices, their properties, terminal markings and internal links.
+- `refdef` says what a thing is called: designations, their structure, printing, reading, numbering and order.
+
+symdef draws a thing, elecdef says what it is, refdef says what it is called; an application connects and lays out. The three are basic building blocks for electrical work in Python, written for every electrical engineer who works there, and each stands alone. A fact never has two homes; what a terminal number means is an `elecdef` fact, how it prints after the colon is a `refdef` fact. None of the three imports another, and none names an application that uses it.
+
+## The core model
+
+**Aspect.** An enum whose value is the sign: `FUNCTION "="`, `PRODUCT "-"`, `LOCATION "+"`, `TYPE "%"`, `OTHER "#"`, `ASSIGNMENT "=="`, `SITE "++"`. The first three are on in the shipped scheme; the other four parse always and are off until a project turns them on.
+
+**Level.** One step in a tree: an aspect with class letters and a number (`-K2`), a number alone (`+3`), or a verbatim label (`+ER`, `-PE_BAR`). A string has exactly one value: letters need a number, so letters alone are a label; a number is an `int` from 1 to 999,999,999 with no padding and no meaning; a label is stripped, non-empty, holds no sign or separator character (`= - + % # : ; & < > .`) and is never shaped like a code (ASCII letters then digits worth 1 to 999,999,999, so `K1` and `7` are refused as labels while `K0` is one), so what it prints reads back to itself. Code letters are upper case. Whether the letters form a known class is not a construction rule, so a designation from any era can be built.
+
+**Designation.** A frozen tuple of levels and an optional top node (printed `<...>`). The empty designation is the root. Level order is kept as given; nothing re-sorts aspects. The builder is the constructor taking levels and `child(aspect, code, number, label)`, and nothing else: two designations are joined through their levels, `Designation(tag.levels + d.levels)`, and no operator builds a value. It is viewed with `only(*aspects)`, `parent(aspect)` and `last`. A top node, when given, is stripped, non-empty and holds none of `> : ; &`.
+
+**Scheme.** A frozen value passed to every check: the aspects that are on, a `LetterRule` (letter count, letters that never appear) and a `ClassTable`. `STANDARD` is the shipped scheme. `scheme.extend(*entries, aspects=...)` returns a new scheme with project classes overlaid and further aspects on; a project that uses `J` for its board connectors adds `ClassEntry("J", "board connector")` this way.
+
+**Parse and render.** `str(d)` prints strictly: every level with its sign, no padding, no separators. `render(d, pad=, dotted=, bare=)` adds the dialects a caller may want: `pad={"W": 4}` prints `-W0001`; `dotted=(Aspect.PRODUCT,)` prints a number-only sub-level as `-W25.1`; `bare=True` drops the first sign. `parse(text, bare=)` reads leniently and returns `Parsed(value, issues)`: lower-case code letters are raised, leading zeros dropped, a dot read as a sub-level, text before the first sign taken as the aspect the caller names in `bare` (a required keyword: which aspect a signless tag means is the caller's convention), anything that is not letters and a number kept verbatim as a label, each with a named issue. Nothing is coerced to a default letter or number, and nothing raises for content. `parse` knows shape only; `check(designations, scheme)` holds every scheme rule: an aspect that is off, a letter count, a letter that never appears, an unknown class, a duplicate. An `Issue` is a code from a closed enum of 21 (16 from `parse` and `parse_address`, 5 from `check`, listed in R6), a subject and a message; the caller decides what is fatal. A digit run of zero or over nine digits reads as a label with an issue.
+
+**Tree arithmetic.** Every operation works per aspect. `d.within(root)` holds when, for each aspect both share, the root's levels are a head of `d`'s; an aspect missing from either side constrains nothing; a root with a top node matches only that top. `d.relative_to(root)` drops the matched heads and keeps the rest in order, so `=U1=P1+ER+C1-K1` relative to the unit root `=U1+ER` is `=P1+C1-K1`, and a cable `=U1-W1` with no location prints `-W1` inside that unit. `Designation.common(*ds)` is the longest shared head per aspect, ordered as the first argument; every argument is within it. Units as atoms is this: a unit's own document prints each tag relative to the unit's root.
+
+**Numbering.** `allocate(aspect, code, taken, reserved, first=1)` returns the lowest free number: the first `n` from `first` whose level is in neither collection. Gaps refill unless the caller lists them as reserved. `number_group(aspect, codes, taken, reserved)` numbers a sequence of codes in one go and feeds each result back into `taken`. refdef owns no store of retired numbers; what forms a sibling group and what stays reserved are the caller's facts.
+
+**Sorting.** `natural_key(text, case_sensitive=True)` orders digit runs by value and text runs as text, numbers first, with the raw text as the last tie-break (`X01` before `X1`). `sort_key(d, aspects=, case_sensitive=True)` is one pair per level, aspect rank then the natural key of the level text; `aspects` is a required keyword, since the order of aspects is the caller's convention, and an unlisted aspect ranks after the listed ones.
+
+**Terminals and signals.** `Terminal(of, pins)` prints `-K1:13`, `-X1:L1:1`, `-A2:J7:3`, `-X1:OUT1-`; a pin is stripped, non-empty text without `:` (so `+`, `-`, `;`, `<` and inner spaces are allowed, and every pin reads back), kept verbatim, and its meaning is an `elecdef` fact. `Signal(of, name)` prints `;NAME` or `-K1;NAME`; the name is stripped, non-empty, free text, and `of` is `None` or a designation with a level or a top (an empty designation is refused). Both have `relative_to`. refdef never reads inside a pin or a name. Wires and cables need no type of their own: `-W25`, `=FIRE-W25`, a core as a sub-level.
+
+**PLC.** `refdef.plc` holds the direct-address form common to PLC programming languages: `Address(memory, size, path)` for `%IX0.0`, `%QW4`, `%M10.3` and the incomplete `%I*`, with `as_bit()` normalising `%Q7.5` to `%QX7.5`, and `parse_address(text)`. A channel tag such as `-KE1:DI03` is a `Terminal`; `ChannelTag(terminal, address)` pairs it with an optional address (named so it does not collide with `elecdef`'s channel). Vendor address dialects are separate modules, added when an application needs one.
+
+## The class table
+
+`refdef.tables.standard` is a generated Python module holding `ClassTable(name="standard", version="1", depth=2, entries=(...))`: the single letters that name the main classes and the two-letter codes beneath them, as electrical practice uses them, each with a short title in our own words. A title names the typical device of the class (owner 2026-10-22); a device's own facts are `elecdef`'s knowledge. `depth=2` means `check` tests a code by its first two letters, so a three-letter code passes when its two-letter parent exists. The code index is built once per table.
+
+The table has its own version line, independent of the library version. A moved, added or removed code bumps `version`, ships as a new entry tuple under the same `STANDARD` name, and is named in the changelog. A project pins the library version and gets the table that version carries; a second table, for another code set or a translation keyed by code, is a further module and a further scheme constant.
+
+## The public surface
+
+`refdef.__all__`: `Aspect`, `Level`, `Designation`, `Terminal`, `Signal`, `Scheme`, `ClassEntry`, `STANDARD`, `parse`, `Parsed`, `render`, `check`, `Issue`, `IssueCode`, `allocate`, `number_group`, `natural_key`, `sort_key`. `refdef.plc.__all__`: `Memory`, `Size`, `Address`, `ChannelTag`, `parse_address`. `ClassTable` and `LetterRule` are reached through `Scheme`. An application imports these names and nothing below them. Every surface name has a docstring of one summary line and at most two lines of why, an entry in the generated API reference and a runnable example in the guide (family rule F9). No surface class overloads an operator; one spelling builds, one reads, one prints (F15). `python -m refdef api` prints the two `__all__` tuples with every surface signature; `docs/api-snapshot.txt` holds that output byte for byte, and a change to it is a reviewed design change (family rules F8 and F12).
+
+## Docs and agents
+
+The docs site is GitHub Pages, built with Zensical from `docs/`, with the API reference generated from the docstrings. It ships with the first public release and has four parts: a guide (build, print, read, check, number, sort) in which every surface name has a runnable example, the API reference, `DESIGN.md` and `RULES.md` rendered as they are, and a changelog that names every moved class code.
+
+Two files are written for agents (family rule F16). `llms.txt` at the docs site root lists, in plain text, what refdef is, the URL of each docs page, the surface names with one line each, and the rules in one line each. `AGENTS.md` in the repository root names the docs site, the surface command (`python -m refdef api`) and snapshot (`docs/api-snapshot.txt`), the guide, `DESIGN.md` and `RULES.md`; it says which files change only with a design review (`DESIGN.md`, `RULES.md`, `docs/api-snapshot.txt`, `src/refdef/tables/`, `tests/corpus/`) and that a need the surface does not meet is a reviewed design change and never a workaround. The docs build is a gate: a surface name without an example, or an example that does not run, fails it (F9).
+
+## Out of scope
+
+refdef does not hold: the meaning of a pin or terminal number, a device's recommended class code, a drawing of anything, a store of retired numbers or a numbering file, document designations and their kind codes, signal-name rules, wire-number rules, vendor PLC dialects, the three-letter class level, other code sets, translations. Each is either another library's fact or a later, reviewed addition.
+
+## How it changes
+
+`DESIGN.md` and `RULES.md` are the contract. A pull request that edits either, changes `docs/api-snapshot.txt`, changes `src/refdef/tables/` or moves a golden under `tests/corpus/` carries a `Design-review:` trailer naming an approved review; `scripts/design_guard.py` fails the merge otherwise (family rule F12, refdef rule R3). An application whose need the surface does not meet opens a design review rather than a workaround on either side; a change that breaks a rule in `RULES.md` is not merged. Versions follow family rule F11; a changed printed form of an unchanged value moves the render golden (R3) and carries its changelog line, and a table change bumps the table's own version (R10).
+
+Who approves is family rule F12: the maintainer approves the contract, and the design reviewer approves surface and table changes.
+
+## Licence
+
+refdef is MIT licensed, code and shipped class table alike (family rule F14). Open sources used are credited in one block in `README.md` (F7); no share-alike or non-commercial source is used.

refdef-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ole Johan Bondahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

refdef-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: refdef
+Version: 0.1.0
+Summary: Reference designations as strict, typed, immutable Python values: parse, check, print, number and order
+Project-URL: Repository, https://github.com/OleJBondahl/refdef
+Author: Ole Johan Bondahl
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# refdef
+
+Reference designations (the tags that name things in a plant, a machine or a cabinet) as strict, typed, immutable Python values.
+The library has no runtime dependencies and does no file, network, clock or random access.
+Every value is a frozen dataclass or an enum.
+
+Status: pre-release, version 0.1.0. The package is an empty scaffold.
+
+## Install
+
+```text
+uv add refdef
+```
+
+Compatible with IEC conventions.
+
+Documentation: <https://olejbondahl.github.io/refdef/>
+
+Licence: MIT.
+
+<!-- credit:start -->
+Credits: none yet.
+<!-- credit:end -->

refdef-0.1.0/README.md

@@ -0,0 +1,23 @@
+# refdef
+
+Reference designations (the tags that name things in a plant, a machine or a cabinet) as strict, typed, immutable Python values.
+The library has no runtime dependencies and does no file, network, clock or random access.
+Every value is a frozen dataclass or an enum.
+
+Status: pre-release, version 0.1.0. The package is an empty scaffold.
+
+## Install
+
+```text
+uv add refdef
+```
+
+Compatible with IEC conventions.
+
+Documentation: <https://olejbondahl.github.io/refdef/>
+
+Licence: MIT.
+
+<!-- credit:start -->
+Credits: none yet.
+<!-- credit:end -->

refdef-0.1.0/RULES.md

@@ -0,0 +1,119 @@
+# refdef: rules
+
+These rules bind every implementation and every later change of refdef. The family rules F1-F17 are shared with elecdef and carried verbatim; the refdef rules R1-R12 add what is refdef's own and repeat no family rule. Each rule is one sentence and its GATE: the mechanical check that fails a breach, or "review" only where no mechanism can work, with the reason. A change to this file, to `DESIGN.md`, to `docs/api-snapshot.txt`, to `src/refdef/tables/` or to `tests/corpus/` needs a `Design-review:` trailer (F12, R3).
+
+## refdef rules
+
+- **R1. One value per string.** For every designation, terminal or signal value `v`, `parse(str(v), bare=a).value == v` for any aspect `a`, and for every string `s` that parses without an issue, `str(parse(s, bare=a).value) == s`. GATE: `tests/test_roundtrip.py`, a property test whose stdlib generator draws levels, labels, tops, pins and signal names from the full alphabets R2 allows (pins and names including `; & < > + - .` and inner spaces), plus `tests/corpus/strings.txt` of strings seen in real projects.
+- **R2. The shapes that construct.** A `Level` has upper-case letters with a number, a number alone, or a stripped non-empty label without `= - + % # : ; & < > .`; a number is an `int` from 1 to 999_999_999; a label is never shaped like a code (ASCII letters, then digits worth 1 to 999_999_999, such as `K1`, `k01` or `7`), because `-K1` must read back as a coded level (`K0` and `K1234567890` are labels); a `Designation.top` is empty or stripped, non-empty and without `> : ; &`; a `Terminal` has at least one pin, each stripped, non-empty and without `:`; a `Signal.name` is stripped and non-empty, and a `Signal.of` is `None` or a designation with at least one level or a top (an empty `Signal.of` is refused, because `;N` must read back to the same value); any other shape is malformed and raises `TypeError` at construction (F3). GATE: `tests/test_malformed.py` holds one fixture per clause (the labels `K1`, `k01` and `7`, the numbers 0 and 1_000_000_000, and an empty `Signal.of` among them) and asserts `TypeError`; `tests/test_level.py` asserts every value that constructs prints and parses back to itself (R1).
+- **R3. Strict render.** `str()` prints every level with its sign and never pads, dots or drops a sign; every dialect (`pad`, `dotted`, `bare`) is an explicit `render` option, and a change to any printed form moves the golden. GATE: `tests/test_render.py` asserts `str(v) == render(v)` over the round-trip corpus, compares `render` of `tests/corpus/strings.txt` under each option to `tests/corpus/render.txt` line by line, and asserts each option changes only the documented characters; `scripts/design_guard.py` watches `tests/corpus/` (F12).
+- **R4. Lenient parse with issues.** `parse` and `parse_address` return a value and an issue tuple for any string, every lenient repair (case, leading zero, dot, missing sign, free label, unsupported suffix) is matched by an issue with its code, and no default letter or number is ever substituted; a digit run that is zero or longer than nine digits (the bound of R2) reads as a label with an issue. GATE: `tests/test_parse.py` feeds a fuzz corpus (random text, every sign alone, empty, whitespace) and asserts no exception, and asserts one issue per repair against a table of input, value and codes.
+- **R5. Shape in parse, scheme in check.** `parse` takes no scheme, every rule that needs one (aspect on, letter count, never-letters, unknown class by `code[:depth]`, duplicate) lives in `check`, and no function reads a scheme or table other than through its argument. GATE: `tests/test_parse.py` asserts `parse`'s signature has no `scheme` parameter; `tests/test_check.py` has one case per check-family `IssueCode`, asserts `parse` never emits them, and an AST test in it fails the name `STANDARD` or an import from `refdef.tables` anywhere under `src/refdef` outside `scheme.py` and `__init__.py`.
+- **R6. An issue is a code, a subject and a message.** `Issue` has exactly these three fields, no severity, and `IssueCode` is a closed enum of exactly 21 codes that every emitted issue uses: the parse family (16) `EMPTY`, `NO_SIGN`, `EMPTY_LEVEL`, `EMPTY_TOP`, `WHITESPACE`, `LOWER_CASE`, `LEADING_ZERO`, `ZERO_NUMBER`, `NUMBER_TOO_LARGE`, `FREE_LABEL`, `BAD_LABEL`, `DOT_LEVEL`, `EMPTY_PIN`, `EMPTY_NAME`, `UNSUPPORTED_SUFFIX`, `NOT_ADDRESS` (the last only from `parse_address`), and the check family (5) `ASPECT_OFF`, `LETTER_COUNT`, `NEVER_LETTER`, `UNKNOWN_CLASS`, `DUPLICATE`; the values are the lower-case names. GATE: `tests/test_check.py` asserts the field names of `Issue`, that the `IssueCode` names equal these 21, and that every issue any test produces has a code in `IssueCode`.
+- **R7. Per-aspect tree arithmetic.** `within`, `relative_to` (on `Designation`, `Terminal` and `Signal`) and `common` follow the rule in `DESIGN.md` exactly, and every argument is within `common(*ds)`. GATE: `tests/test_tree.py` holds the unit-root, cable, mixed-order and top-node cases for all three types, and a property test asserting `a.within(common(a, b))`, `len(b.relative_to(common(a, b)).levels) == len(b.levels) - len(common(a, b).levels)` and `Terminal(d, p).relative_to(r).of == d.relative_to(r)` for random values.
+- **R8. Numbering is pure.** `allocate` returns the lowest free number from `first` given `taken` and `reserved`, `number_group` equals `allocate` applied in sequence with each result added to `taken`, and refdef holds no numbering store. GATE: `tests/test_numbering.py` asserts `allocate` against a brute-force search and `number_group` against the sequential fold, for random inputs.
+- **R9. One natural order.** `natural_key` orders digit runs by value and text runs as text, numbers before text, with the raw text as the last tie-break; `sort_key` is one `(aspect rank, natural_key(level.text))` pair per level, with the aspect order a required keyword and an unlisted aspect ranked after the listed ones in enum order. GATE: `tests/test_order.py` asserts the fixed cases (`-W2 < -W10`, `X01 < X1`, numbers before text), a property test that `sorted` by `sort_key` is a total order consistent with `natural_key` on single-level designations, and that `sort_key` has no default for `aspects`.
+- **R10. The class table is versioned.** `ClassTable.version` is refdef's own line, bumps whenever the entry tuple changes, and the changelog names each moved code. GATE: `tests/test_table_version.py` hashes the entry tuple and compares it with the hash stored beside `version`, failing when the entries change and the version does not; the changelog line is review.
+- **R11. One PLC grammar in the core.** `refdef.plc` holds only the direct-address form (`%` + memory area + optional size + dotted path, `*` for incomplete), with `as_bit` the one normalisation, and every vendor dialect is its own module behind its own type. GATE: `tests/test_plc.py` round-trips `tests/corpus/addresses.txt` through `parse_address` and `str`, asserts `as_bit` changes only a size-less dotted address, and `tests/test_boundary.py` fails a vendor name (`siemens`, `rockwell`, `omron`, `mitsubishi`, `beckhoff`) in `plc.py`.
+- **R12. Pins and signal names are opaque.** refdef never reads inside a pin or a signal name: the only operations on them are the `:` split in `parse`, the `:` join in `render` and `natural_key`. GATE: an AST test in `tests/test_boundary.py` fails any attribute call, subscript or comparison on `pins`, a pin element or `Signal.name` under `src/refdef` outside those three sites; the F5 name list below catches a field that would hold their meaning.
+
+## refdef's lists for the family gates
+
+- F4 allowlist of `str` fields, by design: `Level.code` (class letters), `Level.label` (verbatim text), `Designation.top`, `Terminal.pins` (`tuple[str, ...]`, opaque by R12), `Signal.name` (opaque by R12), `ClassEntry.code`, `ClassEntry.title`, `ClassTable.name`, `ClassTable.version`, `Scheme.name`, `Issue.subject`, `Issue.message`. Every other closed set is an enum: `Aspect`, `IssueCode`, `plc.Memory`, `plc.Size`.
+- F5 boundary names for refdef: F5's six (`rating`, `voltage`, `svg`, `x`, `y`, `page`) plus `marking`, `role`, `kind`, `potential`.
+- F6 caller conventions refdef takes only as arguments: `bare` (which aspect a signless tag means, required), `aspects` (the sort order of aspects, required), `pad`, `dotted`, `first`, `case_sensitive`.
+- F15 numeric types: none; no refdef surface class defines an arithmetic or bitwise dunder, and `Designation` is built by its constructor and `child()` only.
+
+## Family rules
+
+These rules bind elecdef and refdef alike, and symdef where it can (symdef has one runtime dependency, so F1 does not bind it). Both repositories carry this text verbatim in `RULES.md`,
+and `tests/test_family_rules.py` in each compares it to the other's last release.
+
+- **F1.** The library declares no runtime dependency and imports only the standard library and
+  itself; libraries of the family never import each other.
+  GATE: `tests/test_deps.py` asserts `dependencies = []` in `pyproject.toml` and walks every
+  module's imports with `ast`, allowing only `sys.stdlib_module_names` and the package.
+- **F2.** Every value is a frozen dataclass or an enum; the library performs no file, network,
+  clock or random access.
+  GATE: `tests/test_pure.py` fails a `@dataclass` without `frozen=True` and any import or name
+  from `os`, `pathlib`, `io`, `socket`, `time`, `datetime`, `random`, `secrets`, `uuid` or a
+  call to `open` under `src/`.
+- **F3.** Validation returns issues as values and never raises for content; only a malformed
+  call (a wrong type, a wrong kind of argument, or a shape the library's `RULES.md` names as
+  malformed) raises `TypeError`.
+  GATE: `tests/test_check.py` runs `check` over every malformed fixture in `tests/fixtures/`
+  and asserts a non-empty issue tuple and no exception; `tests/test_malformed.py` asserts
+  `TypeError` for each malformed-call fixture.
+- **F4.** A closed vocabulary is an enum or a typed constant, never a string.
+  GATE: `tests/test_vocab.py` fails any dataclass field annotated `str` that is not in the
+  allowlist that the test names and `RULES.md` lists for that library.
+- **F5.** A fact has one home across the family: `symdef` draws, `elecdef` says what a thing is,
+  `refdef` says what it is called, a consumer connects and lays out.
+  GATE: `tests/test_boundary.py` fails a field or function named for another home, from a list each
+  library keeps in the test (for elecdef: `designation`, `tag`, `svg`, `x`, `y`, `page`; for refdef:
+  `rating`, `voltage`, `svg`, `x`, `y`, `page`); the rest is review, because a
+  duplicated meaning under a new name is invisible to a test.
+- **F6.** A caller's convention (a padding, an ordering, a default, a project class) arrives as an
+  argument or a value; no general function carries a caller's default. A fact the library itself
+  defines (a block's default terminal markings, the shipped scheme's signs) is not a convention.
+  GATE: the tests of every option-taking function pass the option explicitly, and
+  `tests/test_boundary.py` fails a module-level default that names a consumer; what counts as a
+  convention is review, because a test cannot tell a convention from a fact.
+- **F7.** No paid standard is cited and no standard's wording is used; open sources are used
+  only with the credit block in `README.md`.
+  GATE: `tests/test_wording.py` fails a standards-body abbreviation followed by digits, an
+  edition year beside a table or scheme name, or a clause reference (the pattern list lives in
+  the test) anywhere under `src/`, `docs/`, `README.md` or
+  `CHANGELOG.md` outside the README credit block, and asserts the credit block names every
+  open source a `tables/` module header declares.
+- **F8.** The public surface is the names in `__all__` of the top level and of each door, read
+  by `python -m <library> api`, and it changes only with the snapshot.
+  GATE: `tests/test_surface.py` compares `python -m <library> api` to `docs/api-snapshot.txt`
+  byte for byte, and fails an import of a non-surface name in `docs/` and `tests/guide/`.
+- **F9.** Every surface name has a docstring and a runnable example on the docs site.
+  GATE: `tests/test_docs.py` asserts a non-empty docstring for every surface name, one fenced
+  Python block naming it under `docs/guide/`, and runs every fenced block; the strict
+  Zensical docs build runs in CI.
+- **F10.** Code stays lean: a function has at most 15 statements, complexity 8 and 12 branches,
+  no `def` inside a `def`; a module has at most 300 code lines; a docstring is one summary line
+  plus at most two lines of why.
+  GATE: ruff `PLR0915=15`, `C901=8`, `PLR0912=12` in `pyproject.toml`; `tests/test_lean.py` for
+  nested defs, module lines and docstring shape; every `noqa` and `ty: ignore` names its reason
+  on its line, checked by the same test.
+- **F11.** Versions are semantic and every surface change carries a changelog line.
+  GATE: `scripts/release_guard.py` in CI fails when `docs/api-snapshot.txt` differs from the
+  last tag's copy and `CHANGELOG.md` has no line under the unreleased heading, and when a name
+  disappeared without a major bump (minor before 1.0).
+- **F12.** A pull request that edits `DESIGN.md` or `RULES.md`, or changes
+  `docs/api-snapshot.txt`, or changes a shipped table under `src/<library>/tables/`, carries a
+  `Design-review:` trailer naming an approved review. The maintainer approves a change to
+  `DESIGN.md` or `RULES.md`; the design reviewer approves a surface or table change, and the
+  maintainer sees it at the next review.
+  GATE: `scripts/design_guard.py` in CI inspects every commit in the range touching those
+  paths and fails one without the trailer; branch protection requires the job.
+- **F13.** A consumer's missing need is met by a reviewed surface extension, never by a
+  workaround in the consumer, a private import, a copy of the rule or a consumer-specific
+  default in the library.
+  GATE: `tests/test_boundary.py` fails an import or a name of another family library under `src/`, and
+  `tests/test_standalone.py` (F17) fails an application's name; the consumer side is review, because the library cannot see the
+  consumer's tree.
+- **F14.** The library is MIT licensed, and the licence covers its code and its shipped tables.
+  GATE: `tests/test_licence.py` asserts `LICENSE` holds the MIT text and `pyproject.toml`
+  declares `license = "MIT"`, and fails a `tables/` module header that declares an open source
+  whose licence is share-alike or non-commercial.
+- **F15.** One public spelling per task: a second way to build, read or print the same value is
+  not added, and no operator is overloaded to build a value; arithmetic belongs only to the
+  numeric value types the library's `RULES.md` names.
+  GATE: `tests/test_surface.py` fails an arithmetic or bitwise dunder (`__add__`, `__or__`,
+  `__truediv__` and their kin) on a surface class that `RULES.md` does not name as numeric;
+  a second spelling under a new name is review, because a test cannot see that two names do one
+  task.
+- **F16.** An agent finds everything from one place: `AGENTS.md` in the repository and `llms.txt`
+  at the docs site root name the docs site, the surface command (`python -m <library> api`),
+  the guide, `DESIGN.md` and `RULES.md`, and say that a change follows `RULES.md`.
+  GATE: `tests/test_agents.py` asserts both files exist, name each of those five targets, and
+  that every link in them resolves in the built site (the strict Zensical docs build).
+- **F17.** The library stands alone: no file in the repository names an application that uses it.
+  It is written for every electrical engineer, and its examples are general.
+  GATE: `tests/test_standalone.py` lowercases every word in the tracked files and fails one whose
+  SHA-256 is in the test's list of application-name hashes, so the test spells no name itself.

refdef-0.1.0/docs/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+This file holds one section per release of refdef, newest first.
+Every change to the public surface gets a line under Unreleased until the release is cut.
+
+## Unreleased
+
+## 0.1.0 (2026-10-22)
+
+- Add `Aspect`, `Level`, `Designation`, `Terminal`, `Signal`, `Issue`, `IssueCode`, `Parsed` and `render`.
+- Add `parse`.
+- Add `within`, `relative_to` and `common` on `Designation`, and `relative_to` on `Terminal` and `Signal`.
+- Add `allocate`, `number_group`, `natural_key` and `sort_key`.
+- Add the door `refdef.plc`: `Memory`, `Size`, `Address`, `ChannelTag` and `parse_address`.
+- Add `Scheme`, `ClassEntry`, `STANDARD` and `check`.
+- Add class table version 1: 17 main letters and 166 two-letter codes (first version, no moved code).
+- First release: the package scaffold with the family rule gates, standard library only.

refdef-0.1.0/docs/api-snapshot.txt

@@ -0,0 +1,98 @@
+## refdef
+class Aspect
+    The tree a level belongs to; the value is its sign.
+
+    The first three are on in the shipped scheme; declaration order is the rank tie-break.
+
+class ClassEntry(code: 'str', title: 'str') -> 'None'
+    One class code with its title, the typical device of the class.
+
+class Designation(levels: 'tuple[Level, ...]' = (), top: 'str' = '') -> 'None'
+    A tuple of levels and an optional top node, built by the constructor and `child` only.
+
+    Join two through their levels; the empty designation is the root.
+
+class Issue(code: 'IssueCode', subject: 'str', message: 'str') -> 'None'
+    One finding about a string or a designation: a code, the offending text, a short sentence.
+
+class IssueCode
+    The 21 issue codes: the first 16 come from the readers, the last 5 from check.
+
+class Level(aspect: 'Aspect', code: 'str' = '', number: 'int | None' = None, label: 'str' = '') -> 'None'
+    One step in a tree: letters and a number (`-K2`), a number alone (`+3`) or a label (`+ER`).
+
+    Letters are upper case and need a number; a label is never code-shaped. Else TypeError.
+
+class Parsed(value: 'T', issues: 'tuple[Issue, ...]') -> 'None'
+    A value read from text together with the issues the reader found.
+
+STANDARD: Scheme
+    What `check` tests against: aspects on, a letter rule and a class table.
+
+    `STANDARD` is the shipped scheme: `= - +` on, 1-3 letters without I and O, a versioned table.
+
+class Scheme(name: 'str', aspects: 'frozenset[Aspect]', letters: 'LetterRule', classes: 'ClassTable') -> 'None'
+    What `check` tests against: aspects on, a letter rule and a class table.
+
+    `STANDARD` is the shipped scheme: `= - +` on, 1-3 letters without I and O, a versioned table.
+
+class Signal(of: 'Designation | None', name: 'str') -> 'None'
+    A signal name on a designation, printed `of;name`; `of` is None for a bare name.
+
+    The name is stripped and non-empty and may hold `: ; &`. It is opaque text.
+
+class Terminal(of: 'Designation', pins: 'tuple[str, ...]') -> 'None'
+    A designation and the pins on it, printed `of:pin:pin`.
+
+    At least one pin; each is stripped, non-empty and without `:`. Pins are opaque text.
+
+allocate(aspect: 'Aspect', code: 'str', taken: 'Collection[Level]', reserved: 'Collection[Level]' = (), *, first: 'int' = 1) -> 'int'
+    The smallest number from `first` for which `Level(aspect, code, n)` is in neither collection.
+
+    `first` below 1 is a TypeError. Nothing is stored: the caller passes what is taken.
+
+check(designations: 'Iterable[Designation]', scheme: 'Scheme') -> 'tuple[Issue, ...]'
+    Issues of the designations against `scheme`, in order; duplicates first for each one.
+
+    Terminals and signals are not checked: pass their `of`.
+
+natural_key(text: 'str', *, case_sensitive: 'bool' = True) -> 'tuple[Any, ...]'
+    A sort key: digit runs by value, text runs as text, numbers first, then the raw text.
+
+number_group(aspect: 'Aspect', codes: 'Sequence[str]', taken: 'Collection[Level]' = (), reserved: 'Collection[Level]' = ()) -> 'tuple[Level, ...]'
+    One level per code, each numbered after the earlier ones; `taken` is not changed.
+
+parse(text: 'str', *, bare: 'Aspect') -> 'Parsed[Designation | Terminal | Signal]'
+    Read text as a designation, terminal or signal, with an issue for each repair.
+
+    `bare` is the aspect of text before the first sign. Never raises for content.
+
+render(d: 'Designation', *, pad: 'Mapping[str, int] | None' = None, dotted: 'Collection[Aspect]' = (), bare: 'bool' = False) -> 'str'
+    Print a designation; `pad`, `dotted` and `bare` are the explicit dialects, none is `str(d)`.
+
+    `pad={"W": 4}` gives `-W0001`; `dotted=(P,)` gives `-W25.1`; `bare=True` omits the first sign.
+
+sort_key(d: 'Designation', *, aspects: 'Sequence[Aspect]', case_sensitive: 'bool' = True) -> 'tuple[Any, ...]'
+    A sort key: per level the rank of its aspect in `aspects` and its natural key.
+
+    Aspects not listed rank after the listed ones, in enum order. The top is not in the key.
+
+## refdef.plc
+class Address(memory: 'Memory', size: 'Size', path: 'tuple[int, ...]') -> 'None'
+    A direct address printed `%` memory size path; an empty path is the incomplete `%I*`.
+
+    A path index is an int from 0 to 999_999_999; any other shape raises TypeError.
+
+class ChannelTag(terminal: 'Terminal', address: 'Address | None' = None) -> 'None'
+    A terminal with an optional address, printed as the terminal alone (`-KE1:DI03`).
+
+class Memory
+    The memory area of an address: input, output or marker; the value is the letter.
+
+class Size
+    The access size of an address: none, bit, byte, word, double word or long word.
+
+parse_address(text: 'str') -> 'Parsed[Address | None]'
+    Read a direct address; repairs (outer whitespace, leading zeros) are issues.
+
+    Text that is not an address gives `None` and a NOT_ADDRESS issue.

refdef-0.1.0/docs/guide/build.md

@@ -0,0 +1,37 @@
+# Build
+
+A designation is a tuple of levels, built by the constructor and `child`, never by an operator.
+
+```python
+from refdef import Aspect, Designation, Level
+F, P, L = Aspect.FUNCTION, Aspect.PRODUCT, Aspect.LOCATION
+u1 = Designation().child(P, "U", 1)
+k1 = u1.child(P, "U", 2).child(P, "K", 3)
+print(k1)                                                  # -U1-U2-K3
+print(Designation((Level(L, label="ER"),) + k1.levels))    # +ER-U1-U2-K3
+print(Level(P, "K", 3).text)                               # K3
+print(k1.parent())                                         # -U1-U2
+print(Designation((Level(L, label="ER"),) + k1.levels).only(P))   # -U1-U2-K3
+```
+
+A level is upper-case letters with a number, a number alone, or a label. A label is never shaped
+like a code, so `K1` and `7` cannot be labels (`K0` can). A malformed call raises `TypeError`.
+
+```python
+from refdef import Aspect, Level
+try:
+    Level(Aspect.PRODUCT, label="K1")
+except TypeError:
+    print("refused")                                       # refused
+```
+
+## Findings
+
+A reader or a checker reports an `Issue` with an `IssueCode`, and a reader returns its value in `Parsed`.
+
+```python
+from refdef import Designation, Issue, IssueCode, Parsed
+issue = Issue(IssueCode.EMPTY, "", "the text is empty")
+parsed = Parsed(Designation(), (issue,))
+print(parsed.issues[0].code.value)                         # empty
+```