knobly 1.1.0__tar.gz

knobly-1.1.0/.gitignore

@@ -0,0 +1,7 @@
+# Generated by tools/gen.sh py during build and test; never committed (owner, 2026-10-23).
+src/knobly/_gen/
+src/knobly/_api/
+dist/
+.venv/
+conformance/shapes.py
+tests/api_contract.py

knobly-1.1.0/.python-version

@@ -0,0 +1 @@
+3.13

knobly-1.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: knobly
+Version: 1.1.0
+Summary: A configuration language defined by one formal grammar, with a lossless syntax tree
+Project-URL: Repository, https://github.com/mcurcio/knobly
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: antlr4-python3-runtime==4.13.2

knobly-1.1.0/README.md

@@ -0,0 +1,169 @@
+# knobly (Python)
+
+The Python package for the knobly configuration language. Its parser is generated by ANTLR4
+from [`grammar/Knobly.g4`](../grammar/Knobly.g4), the language's one specification. It
+needs Python 3.11 or later and has one dependency, `antlr4-python3-runtime` 4.13.2 (the same
+version as the generator).
+
+It is not on PyPI. Releases attach the wheel and sdist to the GitHub Release (see the
+[root README](../README.md#releases)).
+
+## What it has
+
+It has the same parts as the TypeScript package ([`ts/README.md`](../ts/README.md)), in Python's
+own style: `Processor` for `knobly()`, `walk()` as a generator, `match` on one class per kind,
+`snake_case` names. The core does no input or output. The concepts and their names come from
+[`spec/`](../spec/README.md); each binding only changes the casing.
+
+Every public signature is generated from [`spec/schema/api.json`](../spec/schema/api.json) into
+`src/knobly/_api/` (spec/codegen.md): the records (`SourceSpan`, `Token`, `Copy`, `Expansion`,
+`SliceValue`, `Added` ... as frozen dataclasses), the kind lists (`StrEnum`s), the diagnostic codes, the error
+tree, the rules module (`MAX_NESTING`, `RESERVED`, `VARIABLE_NAME` ...) and a `Protocol` for every handle, which
+each hand-written class here subclasses, so mypy checks each member against the schema. Every generated annotation
+names the public classes (`knobly.LocatedDiagnostic`, `rendered.Directive`, `written.Statement` ...), so a
+program annotates with what it imports: `def key(d: rendered.Directive) -> str | None` is a `rendered.KeyRule`.
+`_api` is private; nothing outside `src/` imports it but the generated contract's type checker's block. Each
+module's `__all__` equals the generated `PUBLIC_NAMES` and each public union holds the generated `UNIONS` variant
+classes (tests/test_api_names.py); mypy checks each module against its generated `<Module>Functions` Protocol, each
+constructed class against its `<Class>Constructor` and each hand class against its generated Protocol, all from the
+generated `tests/api_contract.py`. Every public doc is the schema's: each public module gives its hand-written
+classes, members and functions their generated docstrings at import (spec/codegen.md section 3). Inside the
+package a `kind`, `reason` or `code` is compared with an enum member, never a string (tests/test_kind_lint.py runs `tools/lint/kind_lint.py`).
+
+One namespace per layer (binding guide rule 9):
+
+| Import | What it has |
+|---|---|
+| `knobly` | The shared and io layers: `ConfigText`, `quote`, `text`, positions, places, origins and steps, `Diagnostic`, `LocatedDiagnostic`, `Diagnostics`, `DiagnosticCode`, `Severity`, the error classes, `PROGRAM_CODE`, the document source and writer ports, `memory_source`, `memory_writer`, `check_lost_updates` |
+| `knobly.syntax` | The syntax tree: `parse`, `Syntax`, `Token`, `Node`, `TokenRange`, `span_of`, `text_of`, `TokenKind`, `NodeKind`, `MAX_NESTING` |
+| `knobly.written` | The low level: `Processor`, `DocumentGraph`, the written types, the expansion and its expanded values (`ExpandedWord` ... `ExpandedIndex`), the extension port (`Extension`, `ExtensionUse`), its kind lists and limits, `format_diagnostic`, and the written values `Word`, `String`, `List`, `Slice`, `Index` and `Reference` (import the module, `from knobly import written`, so `written.List` never replaces `typing.List`). It never imports the rendered layer |
+| `knobly.rendered` | The rendered layer: `render`, `Rendered`, `RenderedBlock`, `Directive`, addresses, `KeyRule` and the change classes. It reaches the low level only through `knobly.written`'s public names |
+| `knobly.include` | `include()`: the include extension |
+| `knobly.files` | `file_source()` and `file_writer()`: files on disk |
+
+Every block has one shape (spec 2.11): a written block (statements), an expansion block (directive expansions) and
+a rendered block (directives) are each a `Sequence` (iterate, `len`, `block[i]`, `IndexError` out of range) with
+`directives(name)` and `walk(descend=...)`, a generator over every item at any depth.
+
+- **The syntax tree.** `parse(text)` returns a `Syntax` with `tokens`, `root` and `diagnostics`. It never
+  raises. The tree is lossless: `text_of(syntax, syntax.root)` gives the text back.
+- **The low level: the files as written.** `Processor(source=..., extensions=[...])` is made once, and loading
+  is all it does: `processor.load(path, overrides=...)` reads the root file and every file it includes and
+  returns a `DocumentGraph`: the documents, their statements and values (one class per kind, each with a `kind`
+  from its generated `StrEnum` and `__match_args__`, for `match`: `case SetLine(variable, values):`,
+  `case Slice(Word("leds"), start, end):`), the include copies, the variables (`SetVariable`, `Parameter`,
+  `OverrideVariable`) and what each `$name` reads at each place.
+  A statement headed by a word is a directive whatever the word (`use epoll;` is a directive); the language
+  statements are `@set`, `@snippet` and `@use`, and `@include` is the include extension's line.
+  An operation exists only where it can succeed: `rename` on a written directive and on set variables and
+  parameters, `set` on statements with values, on set variables and on every written value; an include line is an
+  `ExtensionLine`, with no `rename`. An override is a value the program passes in, as config text
+  (`overrides={"host": quote(host)}`; change it later with `graph.set_override(name, text)`); which `@set` lines it
+  wins over, and what an included file sees, is [spec/expansion.md](../spec/expansion.md). Named edits change the
+  text and keep comments and layout. They take config text, `ConfigText` (a `NewType` of `str`), made only by
+  `quote()` from a program string or `text()` from a text already written as knobly text: mypy refuses a plain
+  `str` there, and at run time anything but a `str` raises `TypeError`. Write a number with `text(str(n))`.
+
+  ```python
+  from knobly import memory_source, quote, text
+  from knobly.written import Processor
+
+  graph = Processor(source=memory_source({"main.conf": "host a;\nport 80;\n"})).load("main.conf")
+  host, port = graph.root.block
+  host.set(quote("10.0.60.31"))  # set replaces a statement's values (not the language's `@set` line)
+  port.set(text(str(8080)))
+  assert graph.root.text == 'host "10.0.60.31";\nport 8080;\n'
+  ```
+
+  `set(text)`, `replace_with_text(text)`, `insert_before(text)`, `insert_after(text)`,
+  `insert_statements(index, text)`, `add_statements(text)` and `rename(name)` are the edits. Every statement ends
+  with `;` or a block, and a line break is whitespace, so a values text may hold line breaks
+  (`port.set(text("1\n2"))` writes `port 1\n2;`). A given text is checked with the grammar's entry rule for it
+  (spec 2.8): a values text that holds a `;` or a block, or ends in a comment (which would swallow the `;`), raises
+  `BadTextError` (E2001, its message built from its diagnostics); a statement's `set` takes the empty text to clear
+  its values and refuses any other text that holds no value. An edit that would make its file nest blocks and lists
+  past the nesting [limit](https://mcurcio.github.io/knobly/language/#limits) raises `BadTextError` too: E2010 at the bracket of the given text, or at 0:0 when the file
+  was already too deep (a document's `replace_with_text` is never refused). A written value's `set(text)` takes exactly one value
+  and keeps the handle: the same object, now of the new value's kind (its class becomes `Word`, `List`, ...). A bad name in `rename`, `set_override` or an override is a program bug,
+  `ValueError`. `graph.read()` reads files an edit added, through the graph's own source; until then an include
+  copy not read renders as an unreadable with reason `unread` (E3007). `graph.save(writer)` hands the changed
+  files to a writer in one batch (`memory_writer(files)` writes into the same map a `memory_source(files)` reads;
+  `file_writer()` to disk); every writer refuses a file changed since it was read with `LostUpdateError` (a
+  `SaveError`, `paths` the conflicting files) through the one check `check_lost_updates`, which a program's own
+  writer calls too. `graph.expand()` gives every copy as read, which the rendered layer builds on, and
+  `graph.diagnostics` is the one list a render shows. A variable's `references()` are
+  lexical: the `$name`s in its own file that it declares. A use in an included file is resolved per copy, so it is
+  only in `wins()` and `shadowed_at()`. Guide: [Editing and saving](https://mcurcio.github.io/knobly/editing/).
+- **The rendered tree.** `render(graph)` builds on the low level: it expands variables, snippets and included
+  files into directives (`block`, `tree.block.walk()`). A directive's values are the low level's expanded values,
+  the same objects its directive expansion holds, one class per kind (`ExpandedWord`, `ExpandedString`,
+  `ExpandedList` with its `items`, `ExpandedSlice`, `ExpandedIndex`; the union `ExpandedValue`), equal when their
+  canonical texts are (`==`, `hash`), with its readers (`word()`, `string()`, `number()`, `integer()`, `boolean()`,
+  `list()`, `slice()`: a word stays untyped until the program reads it as one of these), its
+  origin, and `written` (the value on the same line), `definition` (where it is written) and `chain` (each `$name`
+  it went through) leading back to the low level. `tree.addresses(key=...)` names each directive under a key rule,
+  and `before.diff(after, key=...)` lists what changed, as `Added`, `Removed`, `Changed` and `Unknown`. Matching a
+  `ExpandedString` by position gives its canonical `text`, quotes included; read `string()` for the decoded text.
+  A file included twice renders as two copies that share one written line, so an edit loop over the render meets
+  the same `written` handle twice; a value's `set` keeps its handle, so setting it through each copy just writes
+  the line again.
+
+  ```python
+  from knobly import rendered, text
+
+  for d in rendered.render(graph).block.walk():
+      match d:
+          case rendered.Directive("max_count", [value]):
+              value.written.set(text("2400"))
+  ```
+
+  Guide: [Getting started](https://mcurcio.github.io/knobly/getting-started/).
+
+There is no fetch source and no fetch writer in Python. The user guide, with every sample in TypeScript, Python and
+C++, is [https://mcurcio.github.io/knobly/](https://mcurcio.github.io/knobly/) (source: [`docs/site/pages/`](../docs/site/pages/)); every sample is a file `pytest` runs
+(`examples/`). The language is [the language reference](https://mcurcio.github.io/knobly/language/).
+
+Diagnostic codes are the same as in TypeScript. Each diagnostic has a `severity`, `Severity.ERROR` or
+`Severity.WARNING`: the one warning, W3005, is an `@include` glob that matches no file. Nothing raises a warning or
+acts on one; a program that stops on problems reads the sink's `errors` (`Diagnostics(tree.diagnostics).errors`). Offsets and columns count code points, Python's own string unit
+([spec/contract.md](../spec/contract.md) 1), so `text[span.start.offset:span.end.offset]` is a span's text
+(TypeScript counts UTF-16 code units; the two differ after a character outside the Basic Multilingual Plane). A
+place prints as `main.conf:4:5` (`str(place)`, counting from 1), as do diagnostics and steps. Every expected
+outcome (a diagnostic, read, bad text, save or lost update error) is under `KnoblyError`, and no program bug
+is: a detached handle raises `DetachedError` (a `ReferenceError`), misuse `ValueError`, a wrong argument type
+`TypeError`, an index out of range `IndexError` (spec 2.8). The shared cases in `conformance/` stay in UTF-16 units; one shared
+driver ([spec/conformance.md](../spec/conformance.md)) runs every corpus against this package through its adapter,
+`conformance/adapter.py`, converts positions, and compares (the adapter's own failing source and `throws` extension
+give the faults of spec/conformance.md 4.5). The Python package claims level L3 (syntax, low level,
+rendered tree, extensions) and passes every case, as the TypeScript package does.
+
+## Build and test
+
+From `py/`, with [uv](https://docs.astral.sh/uv/) (`.python-version` picks 3.13):
+
+```bash
+uv run pytest                 # also builds the wheel and sdist once (tests/test_build.py)
+uv run ruff check
+uv run ruff format --check
+uv run mypy
+uv run --python 3.11 pytest   # the oldest supported Python
+python3 ../conformance/driver/run.py -- uv run --locked python conformance/adapter.py   # the shared cases
+```
+
+`pytest` runs this package's own unit tests; the shared cases run only through the driver (after `pytest` or
+`bash ../tools/gen.sh py` has generated the parser). The driver prints TAP and ends with the count per level and
+whether the claimed level holds.
+
+`tests/conftest.py` first runs `bash ../tools/gen.sh py`, which regenerates the parser into
+`src/knobly/_gen/` and the API declarations (records, Protocols, kind lists, codes, errors, rules, from
+`spec/schema/`) into `src/knobly/_api/`, the adapter's message shapes and error groups into
+`conformance/shapes.py`, and the names, match fields, unions and module Protocols the tests check against into
+`tests/api_contract.py` (all ignored by git, never committed). That needs Java 11+; the ANTLR jar is
+cached in `$ANTLR_JAR_DIR` (default `~/.cache/antlr`). A build needs no step first: `hatch_build.py` runs `gen.sh` when it builds from a checkout that has no generated files (after a grammar or
+schema change, run `gen.sh` or the tests first: the hook does not refresh files that exist), and `pyproject.toml`
+forces the ignored `_gen/` and `_api/` files into the wheel and sdist. So another project can depend on a commit
+before any release (it needs bash, Java 11+, `curl` and `uv` when it installs):
+
+```toml
+dependencies = ["knobly @ git+https://github.com/mcurcio/knobly@<commit>#subdirectory=py"]
+```

knobly-1.1.0/conformance/adapter.py

@@ -0,0 +1,483 @@
+"""The Python binding's conformance adapter (spec/conformance.md): the shared driver runs every corpus through it.
+From py/:
+
+    python3 ../conformance/driver/run.py -- uv run --locked python conformance/adapter.py
+
+It speaks the adapter protocol on standard input and output: one JSON request per line, one JSON response per line.
+Every object it dumps gets an id; a later request names the object by that id. It finds no target and compares
+nothing: the driver does both. Its dumps are typed by the generated message shapes (``shapes.py``, from
+spec/schema/protocol.json), members are spelled through the generated ``SPELLING`` and error groups named through the
+generated ``ERROR_GROUP_OF_CLASS``. Parameters are typed with the binding's public classes, the types the generated
+records' fields carry."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from shapes import (
+    ERROR_GROUP_OF_CLASS,
+    PROTOCOL,
+    SPELLING,
+    AddressDump,
+    BlockDump,
+    ChangeDump,
+    CopyDump,
+    DirectiveDump,
+    EditedDump,
+    ExpandedValueDump,
+    GraphDump,
+    HelloResultDump,
+    KeyRuleDump,
+    LoadedDump,
+    LocatedDiagnosticDump,
+    OriginDump,
+    OverrideDump,
+    PlaceDump,
+    Position,
+    ReaderResultDump,
+    RenderDump,
+    ResolutionDump,
+    SavedDump,
+    StatementDump,
+    StepDump,
+    SyntaxDiagnosticDump,
+    SyntaxDump,
+    UnreadableDump,
+    VariableReferenceDump,
+    WrittenValueDump,
+)
+
+import knobly as vl
+from knobly import rendered, syntax, written
+from knobly.include import include
+
+handles: list[object] = []
+
+
+def ref(obj: object) -> str:
+    handles.append(obj)
+    return str(len(handles) - 1)
+
+
+def get(id_: str) -> Any:
+    return handles[int(id_)]
+
+
+def pos(p: vl.SourcePosition) -> Position:
+    return (p.line, p.column, p.offset)
+
+
+def file_place(p: vl.Place) -> PlaceDump:
+    return {"id": ref(p), "path": p.resolved_path, "start": pos(p.span.start), "end": pos(p.span.end)}
+
+
+def place(p: vl.Place | vl.Override) -> PlaceDump | OverrideDump:
+    if p.kind is vl.PlaceKind.OVERRIDE:
+        return {"id": ref(p), "override": p.variable}
+    return file_place(p)
+
+
+def steps(via: Sequence[vl.Step]) -> list[StepDump]:
+    return [{"id": ref(s), "kind": str(s.kind), "name": s.name, "place": file_place(s.place)} for s in via]
+
+
+def origin(o: vl.Origin | vl.DirectiveOrigin) -> OriginDump:
+    return {"place": place(o.place), "via": steps(o.via)}
+
+
+def diagnostic(d: vl.Diagnostic) -> SyntaxDiagnosticDump:
+    return {
+        "id": ref(d),
+        "code": str(d.code),
+        "severity": str(d.severity),
+        "message": d.message,
+        "start": pos(d.span.start),
+        "end": pos(d.span.end),
+    }
+
+
+def located(d: vl.LocatedDiagnostic) -> LocatedDiagnosticDump:
+    return {
+        "id": ref(d),
+        "code": str(d.code),
+        "severity": str(d.severity),
+        "message": d.message,
+        "place": file_place(d.place),
+        "via": steps(d.via),
+    }
+
+
+def syntax_dump(s: syntax.Syntax) -> SyntaxDump:
+    def node(n: syntax.Node) -> Any:
+        return (str(n.kind), n.start, n.end, [node(c) for c in n.children])
+
+    return {
+        "tokens": [(str(t.kind), t.text, pos(t.span.start), pos(t.span.end)) for t in s.tokens],
+        "root": node(s.root),
+        "diagnostics": [diagnostic(d) for d in s.diagnostics],
+    }
+
+
+def variable(v: written.Variable) -> VariableReferenceDump:
+    where = None if v.kind is written.VariableKind.OVERRIDE else file_place(v.place)
+    return {"id": ref(v), "name": v.name, "kind": str(v.kind), "place": where}
+
+
+def resolution(r: written.ReferenceResolution) -> ResolutionDump:
+    return {
+        "reference": {"id": ref(r.reference), "place": file_place(r.reference.place)},
+        "via": steps(r.copy.via),
+        "winner": None if r.winner is None else variable(r.winner),
+        "shadowed": [variable(v) for v in r.shadowed],
+    }
+
+
+def value(v: written.WrittenValue) -> WrittenValueDump:
+    """The dump of one value: a discriminated union on the wire's kind, so each kind's own fields are checked."""
+    i, at, text = ref(v), file_place(v.place), v.text
+    match v:
+        case written.List():
+            return {"id": i, "kind": "list", "place": at, "text": text, "items": [value(x) for x in v.items]}
+        case written.Slice():
+            start = None if v.start is None else value(v.start)
+            end = None if v.end is None else value(v.end)
+            return {
+                "id": i,
+                "kind": "slice",
+                "place": at,
+                "text": text,
+                "name": value(v.name),
+                "start": start,
+                "end": end,
+            }
+        case written.Index():
+            return {"id": i, "kind": "index", "place": at, "text": text, "name": value(v.name), "index": value(v.index)}
+        case written.Reference():
+            declaration = None if v.declaration is None else variable(v.declaration)
+            resolutions = [resolution(r) for r in v.resolutions()]
+            return {
+                "id": i,
+                "kind": "reference",
+                "place": at,
+                "text": text,
+                "declaration": declaration,
+                "resolutions": resolutions,
+            }
+        case written.Word():
+            return {"id": i, "kind": "word", "place": at, "text": text}
+        case _:
+            return {"id": i, "kind": "string", "place": at, "text": text}
+
+
+def statement(s: written.Statement) -> StatementDump:
+    """The dump of one statement, one alternative per kind (as value above)."""
+    i, at, text = ref(s), file_place(s.place), s.text
+
+    def inner(b: written.WrittenBlock | None) -> BlockDump | None:
+        return None if b is None else block(b)
+
+    match s:
+        case written.WrittenDirective():
+            return {
+                "id": i,
+                "kind": "directive",
+                "place": at,
+                "text": text,
+                "values": [value(v) for v in s.values],
+                "block": inner(s.block),
+            }
+        case written.ExtensionLine():
+            return {
+                "id": i,
+                "kind": "extension",
+                "place": at,
+                "text": text,
+                "values": [value(v) for v in s.values],
+                "block": inner(s.block),
+            }
+        case written.SetLine():
+            return {"id": i, "kind": "set", "place": at, "text": text, "values": [value(v) for v in s.values]}
+        case written.UseLine():
+            return {"id": i, "kind": "use", "place": at, "text": text, "values": [value(v) for v in s.values]}
+        case written.SnippetLine():
+            return {"id": i, "kind": "snippet", "place": at, "text": text, "block": inner(s.block)}
+        case _:
+            return {"id": i, "kind": "unreadable", "place": at, "text": text}
+
+
+def block(b: written.WrittenBlock) -> BlockDump:
+    return {"id": ref(b), "statements": [statement(s) for s in b]}
+
+
+def copy(c: written.Copy) -> CopyDump:
+    return {"place": file_place(c.statement.place), "via": steps(c.via)}
+
+
+def graph_dump(g: written.DocumentGraph) -> GraphDump:
+    return {
+        "id": ref(g),
+        "documents": [
+            {
+                "id": ref(d),
+                "path": d.resolved_path,
+                "text": d.text,
+                "savedText": d.saved_text,
+                "syntax": syntax_dump(d.syntax),
+                "block": block(d.block),
+                "includedBy": [copy(e.copy) for e in d.included_by()],
+            }
+            for d in g.documents.values()
+        ],
+        "edges": [{"copy": copy(e.copy), "specs": list(e.specs), "targets": list(e.targets)} for e in g.edges()],
+        "variables": [
+            {
+                **variable(v),
+                "wins": [resolution(r) for r in v.wins()],
+                "shadowedAt": [resolution(r) for r in v.shadowed_at()],
+            }
+            for v in g.variables()
+        ],
+        "diagnostics": [located(d) for d in g.diagnostics],
+    }
+
+
+def key_rule(rules: Sequence[KeyRuleDump] | None) -> rendered.KeyRule | None:
+    """A key rule from its data (spec/conformance.md section 3)."""
+    if rules is None:
+        return None
+
+    def key(d: rendered.Directive) -> str | None:
+        for rule in rules:
+            parent = rule.get("parent")
+            if rule["directive"] == d.name and (parent is None or (d.parent is not None and d.parent.name == parent)):
+                how, arg = rule["key"]
+                if how == "value":
+                    return d.values[int(arg)].text if len(d.values) > int(arg) else None
+                return str(arg).join(a.text for a in d.values)
+        return None
+
+    return key
+
+
+def address(a: rendered.Address) -> AddressDump:
+    return {"text": a.text, "people": str(a)}
+
+
+def render_dump(r: rendered.Rendered, rules: Sequence[KeyRuleDump] | None) -> RenderDump:
+    addresses = r.addresses(key=key_rule(rules))
+
+    def unreadable(u: written.UnreadableExpansion) -> UnreadableDump:
+        return {"reason": str(u.reason), "origin": origin(u.origin)}
+
+    def expanded(a: written.ExpandedValue) -> ExpandedValueDump:
+        return {
+            "id": ref(a),
+            "kind": str(a.kind),
+            "text": a.text,
+            "origin": origin(a.origin),
+            "definition": None if a.definition is None else file_place(a.definition.place),
+            "chain": [resolution(x) for x in a.chain],
+        }
+
+    def directive(d: rendered.Directive) -> DirectiveDump:
+        return {
+            "id": ref(d),
+            "name": d.name,
+            "address": address(addresses[d]),
+            "origin": origin(d.origin),
+            "values": [expanded(a) for a in d.values],
+            "block": None if d.block is None else [directive(x) for x in d.block],
+            "unreadable": [unreadable(u) for u in d.unreadable],
+        }
+
+    return {
+        "id": ref(r),
+        "block": [directive(d) for d in r.block],
+        "unreadable": [unreadable(u) for u in r.unreadable],
+        "diagnostics": [located(d) for d in r.diagnostics],
+    }
+
+
+def result(x: Any) -> ReaderResultDump:
+    """A reader's result, neutral (spec/conformance.md, ``read``)."""
+    if isinstance(x, bool):
+        return {"boolean": x}
+    if isinstance(x, str):
+        return {"text": x}
+    if isinstance(x, int | float):
+        return {"number": "-0" if x == 0 and str(x).startswith("-") else x}
+    if isinstance(x, written.SliceValue):
+        return {"slice": (x.name, x.start, x.end)}
+    if isinstance(x, written.IndexValue):
+        return {"index": (x.name, x.index)}
+    if isinstance(x, tuple):  # the list reader's items
+        return {"list": [{"value": item.text} for item in x]}
+    raise TypeError(f"not a reader result: {x!r}")
+
+
+# Where each edit takes config text (the driver's OPS parameters): the adapter wraps the text the driver sends with
+# text(), as a program does with a text already written as knobly text (spec 6.9). Names stay plain text.
+TEXT_AT = {
+    "set": 0,
+    "replace with text": 0,
+    "insert statements": 1,
+    "add statements": 0,
+    "insert before": 0,
+    "insert after": 0,
+    "set override": 1,
+}
+
+
+def config_text(given: Any) -> Any:
+    """``text(given)`` for a str; anything else as given (a case may pass a non-str to see the argument type error)."""
+    return vl.text(given) if isinstance(given, str) else given
+
+
+def edit(target: str, member: str, args: list[Any]) -> EditedDump:
+    at = TEXT_AT.get(member)
+    if at is not None and at < len(args):
+        args = [config_text(a) if i == at else a for i, a in enumerate(args)]
+    out = getattr(get(target), SPELLING[member])(*args)
+    return {"handles": [{"id": ref(h), "text": h.text} for h in out]} if isinstance(out, tuple) else {}
+
+
+class Recorder:
+    def __init__(self) -> None:
+        self.batches: list[list[tuple[str, str]]] = []
+
+    def write(self, files: Sequence[vl.FileWrite], /) -> None:
+        self.batches.append([(f.resolved_path, f.text) for f in files])
+
+
+def save(graph: str, disk: dict[str, str] | None = None) -> SavedDump:
+    """Without ``disk``, what a recording writer got; with it, a memory writer over a new map holding ``disk`` (so a
+    file whose text there differs from its saved text is a lost update), then the map after, sorted by path."""
+    if disk is None:
+        recorder = Recorder()
+        get(graph).save(recorder)
+        return {"batches": recorder.batches}
+    files = dict(disk)
+    get(graph).save(vl.memory_writer(files))
+    return {"files": sorted(files.items())}
+
+
+class FailingReads:
+    """The test source of spec/conformance.md 4.5: the memory source, but ``read`` of a path named fails."""
+
+    def __init__(self, source: vl.DocumentSource, failing: Sequence[str]) -> None:
+        self.source, self.failing = source, frozenset(failing)
+
+    def resolve(self, spec: str, context: vl.LoadContext, /) -> tuple[str, ...]:
+        return self.source.resolve(spec, context)
+
+    def read(self, resolved_path: str, /) -> str:
+        if resolved_path in self.failing:
+            raise RuntimeError(f"failReads: {resolved_path}")
+        return self.source.read(resolved_path)
+
+
+class Throws:
+    """The test extension ``throws`` of spec/conformance.md 4.5: its ``specs`` raises a diagnostic error of the code
+    its first value names when that value is a word, else an error of no spec 2.8 group."""
+
+    @property
+    def directive(self) -> str:
+        return "throws"
+
+    def specs(self, use: written.ExtensionUse, /) -> tuple[str, ...]:
+        first = use.values[0] if use.values else None
+        if not isinstance(first, written.ExpandedWord):
+            raise RuntimeError("the throws extension")
+        code = vl.DiagnosticCode(first.text)
+        message = f"the throws extension: {code}"
+        raise vl.DiagnosticError(vl.LocatedDiagnostic(code, message, use.origin.place, use.origin.via))
+
+
+EXTENSIONS: dict[str, Callable[[], written.Extension]] = {"include": include, "throws": Throws}
+
+
+def load(
+    files: dict[str, str],
+    root: str,
+    extensions: list[str],
+    overrides: dict[str, Any] | None = None,
+    failReads: list[str] | None = None,  # the wire's own spelling
+) -> LoadedDump:
+    source = vl.memory_source(files)
+    if failReads is not None:
+        source = FailingReads(source, failReads)
+    processor = written.Processor(source=source, extensions=[EXTENSIONS[name]() for name in extensions])
+    given = None if overrides is None else {name: config_text(text) for name, text in overrides.items()}
+    return {"graph": ref(processor.load(root, overrides=given))}
+
+
+def hello(protocol: int) -> HelloResultDump:
+    return {"protocol": PROTOCOL, "binding": "python", "unit": "code point", "level": 3}
+
+
+def diff(before: str, after: str, key: Sequence[KeyRuleDump] | None = None) -> list[ChangeDump]:
+    changes = get(before).diff(get(after), key=key_rule(key))
+    return [{"kind": str(c.kind), "address": address(c.address)} for c in changes]
+
+
+OPS: dict[str, Callable[..., Any]] = {
+    "hello": hello,
+    "parse": lambda text: syntax_dump(syntax.parse(text)),
+    "load": load,
+    "graph": lambda graph: graph_dump(get(graph)),
+    "render": lambda graph, key=None: render_dump(rendered.render(get(graph)), key),
+    "diff": diff,
+    "edit": edit,
+    "save": save,
+    "quote": lambda text: vl.quote(text),
+    "read": lambda value, reader: result(getattr(get(value), SPELLING[reader])()),
+    "print": lambda target: str(get(target)),
+    "format": lambda diagnostic, graph=None: written.format_diagnostic(
+        get(diagnostic), None if graph is None else get(graph)
+    ),
+    "cut": lambda text, start, end: text[start:end],
+}
+
+
+def group_of(error: Exception) -> str | None:
+    """The spec 2.8 group of an error: the first class of its ``__mro__`` that ``ERROR_GROUP_OF_CLASS`` names, so the
+    most specific (a ``LostUpdateError`` before its ``SaveError``; the language's own ``TypeError``, ``ValueError``
+    and ``IndexError`` for the program-bug groups)."""
+    names = (cls.__name__ for cls in type(error).__mro__)
+    return next((ERROR_GROUP_OF_CLASS[name] for name in names if name in ERROR_GROUP_OF_CLASS), None)
+
+
+def thrown(error: Exception) -> dict[str, Any] | None:
+    """The thrown response's body: the group, with its code, diagnostics or paths; None for anything else (a fault)."""
+    name = group_of(error)
+    if name is None:
+        return None
+    out: dict[str, Any] = {"group": name}
+    if isinstance(error, vl.DiagnosticError):
+        out["code"] = str(error.diagnostic.code)
+    if isinstance(error, vl.BadTextError):
+        out["diagnostics"] = [diagnostic(d) for d in error.diagnostics]
+    if isinstance(error, vl.ReadError | vl.SaveError):
+        out["paths"] = list(error.paths)
+    return out
+
+
+def main() -> None:
+    for line in sys.stdin:
+        request = json.loads(line)
+        id_, op = request.pop("id"), request.pop("op")
+        try:
+            response = {"id": id_, "ok": OPS[op](**request)}
+        except Exception as error:
+            body = thrown(error)
+            fault = f"{type(error).__name__}: {error}"
+            response = {"id": id_, "thrown": body} if body is not None else {"id": id_, "fault": fault}
+        sys.stdout.write(json.dumps(response) + "\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()