quire-grammar 0.2.0__tar.gz

quire_grammar-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roger Cooper
+
+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.

quire_grammar-0.2.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: quire-grammar
+Version: 0.2.0
+Summary: An offline English grammar and style checker — a writer's aid, not a proofreading service.
+Author: Roger Cooper
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: model
+Requires-Dist: quire-grammar-model>=0.2; extra == "model"
+Requires-Dist: onnxruntime>=1.17; extra == "model"
+Requires-Dist: tokenizers>=0.15; extra == "model"
+Provides-Extra: ml
+Requires-Dist: quire-grammar-model>=0.2; extra == "ml"
+Requires-Dist: onnxruntime>=1.17; extra == "ml"
+Requires-Dist: tokenizers>=0.15; extra == "ml"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: onnxruntime>=1.17; extra == "dev"
+Requires-Dist: tokenizers>=0.15; extra == "dev"
+Requires-Dist: numpy>=1.26; extra == "dev"
+Dynamic: license-file
+
+# quire-grammar
+
+A **standalone, offline English grammar and style checker** — a writer's aid,
+not a proofreading service, and a library other writing tools can license
+rather than build their own. It runs fully offline and is permissively
+licensed end to end.
+
+[Quire Desktop](https://github.com/jutreuter/quire-desktop) is the first
+consumer — the rules layer is a hard dependency (the always-on checker) and
+the model is the opt-in `[model]` extra, *off if missing* the way WordNet and
+SCOWL spell-check are. The dependency runs one way and the `check()` API is
+designed to stand on its own.
+
+## Use it
+
+```python
+from quire_grammar import check
+
+for c in check("Its been a long day and and the sky is is grey."):
+    print(c.rule_id, repr(c.original), "->", c.suggestions, f"({c.confidence})")
+```
+
+```
+$ quire-grammar "She had a apple. This went better then that."
+1:9   [mechanics/a-vs-an]     “a” before “apple” — “an” matches the sound.  →  'an'
+1:35  [confusable/then-vs-than]  “then” here reads as “than”.  →  'than'
+```
+
+`check()` returns a sorted `list[Correction]` — a stable dataclass of
+`start, end, original, category, rule_id, message, suggestions, confidence`.
+That signature does not change whether or not the model is installed.
+
+## Install
+
+```
+pip install quire-grammar            # rules layer — pure Python, zero deps
+pip install quire-grammar[model]     # + the phase-2 model (onnxruntime, tokenizers, ~40 MB weights)
+```
+
+Without the `[model]` extra, `check()` runs rules-only and the model
+contributes nothing — the same "off if missing" behaviour Quire gives WordNet
+and spell-check.
+
+## How it works
+
+**Phase 1 — a deterministic rules layer (this repo, now).** Pure-Python,
+**zero runtime dependencies**. Each rule is a narrow, high-precision pattern
+for a mistake a *native writer* actually makes. The guard rail is precision:
+a checker that cries wolf gets switched off, so the test suite weighs "must
+not flag" cases as heavily as "must flag".
+
+| category | rules |
+|---|---|
+| **mechanics** | doubled word · `a`/`an` · space before punctuation · missing space after a sentence · capitalisation after `.` |
+| **confusable** | its/it's · there/their/they're · your/you're · then/than · affect/effect · lose/loose · lead/led · breath/breathe · to/too · whose/who's · passed/past · weather/whether · "should of" → "should have" |
+| **agreement** | pronoun subject–verb (`he don't`, `they was`, `I are`) · within-sentence past → present tense drift |
+| **punctuation** | comma splice · broken-off subordinate-clause fragment · straight-vs-curly quotes/apostrophes/dashes *(opt-in)* |
+| **style** | filter verb · `said angrily` · overlong sentence · dangling modifier · weak intensifier *(opt-in)* · passive voice *(opt-in)* |
+
+`enable` / `disable` take rule ids or whole categories. Opt-in rules are off
+until you ask for them.
+
+**Phase 2 — a small local model behind the same `check()` API.** A
+GECToR-style edit tagger (DistilBERT-base-cased, 66 MB int8 ONNX, ~40 MB in
+the wheel) run on CPU via `onnxruntime` — no GPU is assumed, for training or
+inference. It catches homophone and agreement slips the deliberately-narrow
+rules miss, gated at a 0.9 confidence floor (tuned so it flags ~1% of
+genuinely clean sentences), merged with the rule hits so a rule wins on any
+span overlap. Trained **synthetic-first** — `corrupt.py` errors over
+public-domain prose, because the usual GEC learner corpora are
+research/non-commercial licensed. It ships as the separate
+[`quire-grammar-model`](packages/quire-grammar-model/) distribution
+(`quire-grammar[model]`); training code and data pipeline live in `train/`
+and are **not** shipped.
+
+See [CLAUDE.md](CLAUDE.md) for the design contract and the phase-2 plan.
+
+## Develop
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]" -e ./packages/quire-grammar-model
+.venv/bin/python -m pytest -q
+.venv/bin/ruff check src train tests packages
+.venv/bin/mypy
+```
+
+The phase-2 training scripts in `train/` need the heavier ML stack —
+`.venv/bin/pip install -r train/requirements.txt` (CPU-only, all permissive).
+It is **not** a dependency of the shipped package.
+
+`quire-grammar` is MIT; `quire-grammar-model` is Apache-2.0 (it carries a
+`distilbert-base-cased` lineage). Everything either depends on — now and
+planned — is MIT / BSD / Apache. No GPL, no AGPL, so a licensee can
+redistribute the whole thing.

quire_grammar-0.2.0/README.md

@@ -0,0 +1,95 @@
+# quire-grammar
+
+A **standalone, offline English grammar and style checker** — a writer's aid,
+not a proofreading service, and a library other writing tools can license
+rather than build their own. It runs fully offline and is permissively
+licensed end to end.
+
+[Quire Desktop](https://github.com/jutreuter/quire-desktop) is the first
+consumer — the rules layer is a hard dependency (the always-on checker) and
+the model is the opt-in `[model]` extra, *off if missing* the way WordNet and
+SCOWL spell-check are. The dependency runs one way and the `check()` API is
+designed to stand on its own.
+
+## Use it
+
+```python
+from quire_grammar import check
+
+for c in check("Its been a long day and and the sky is is grey."):
+    print(c.rule_id, repr(c.original), "->", c.suggestions, f"({c.confidence})")
+```
+
+```
+$ quire-grammar "She had a apple. This went better then that."
+1:9   [mechanics/a-vs-an]     “a” before “apple” — “an” matches the sound.  →  'an'
+1:35  [confusable/then-vs-than]  “then” here reads as “than”.  →  'than'
+```
+
+`check()` returns a sorted `list[Correction]` — a stable dataclass of
+`start, end, original, category, rule_id, message, suggestions, confidence`.
+That signature does not change whether or not the model is installed.
+
+## Install
+
+```
+pip install quire-grammar            # rules layer — pure Python, zero deps
+pip install quire-grammar[model]     # + the phase-2 model (onnxruntime, tokenizers, ~40 MB weights)
+```
+
+Without the `[model]` extra, `check()` runs rules-only and the model
+contributes nothing — the same "off if missing" behaviour Quire gives WordNet
+and spell-check.
+
+## How it works
+
+**Phase 1 — a deterministic rules layer (this repo, now).** Pure-Python,
+**zero runtime dependencies**. Each rule is a narrow, high-precision pattern
+for a mistake a *native writer* actually makes. The guard rail is precision:
+a checker that cries wolf gets switched off, so the test suite weighs "must
+not flag" cases as heavily as "must flag".
+
+| category | rules |
+|---|---|
+| **mechanics** | doubled word · `a`/`an` · space before punctuation · missing space after a sentence · capitalisation after `.` |
+| **confusable** | its/it's · there/their/they're · your/you're · then/than · affect/effect · lose/loose · lead/led · breath/breathe · to/too · whose/who's · passed/past · weather/whether · "should of" → "should have" |
+| **agreement** | pronoun subject–verb (`he don't`, `they was`, `I are`) · within-sentence past → present tense drift |
+| **punctuation** | comma splice · broken-off subordinate-clause fragment · straight-vs-curly quotes/apostrophes/dashes *(opt-in)* |
+| **style** | filter verb · `said angrily` · overlong sentence · dangling modifier · weak intensifier *(opt-in)* · passive voice *(opt-in)* |
+
+`enable` / `disable` take rule ids or whole categories. Opt-in rules are off
+until you ask for them.
+
+**Phase 2 — a small local model behind the same `check()` API.** A
+GECToR-style edit tagger (DistilBERT-base-cased, 66 MB int8 ONNX, ~40 MB in
+the wheel) run on CPU via `onnxruntime` — no GPU is assumed, for training or
+inference. It catches homophone and agreement slips the deliberately-narrow
+rules miss, gated at a 0.9 confidence floor (tuned so it flags ~1% of
+genuinely clean sentences), merged with the rule hits so a rule wins on any
+span overlap. Trained **synthetic-first** — `corrupt.py` errors over
+public-domain prose, because the usual GEC learner corpora are
+research/non-commercial licensed. It ships as the separate
+[`quire-grammar-model`](packages/quire-grammar-model/) distribution
+(`quire-grammar[model]`); training code and data pipeline live in `train/`
+and are **not** shipped.
+
+See [CLAUDE.md](CLAUDE.md) for the design contract and the phase-2 plan.
+
+## Develop
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]" -e ./packages/quire-grammar-model
+.venv/bin/python -m pytest -q
+.venv/bin/ruff check src train tests packages
+.venv/bin/mypy
+```
+
+The phase-2 training scripts in `train/` need the heavier ML stack —
+`.venv/bin/pip install -r train/requirements.txt` (CPU-only, all permissive).
+It is **not** a dependency of the shipped package.
+
+`quire-grammar` is MIT; `quire-grammar-model` is Apache-2.0 (it carries a
+`distilbert-base-cased` lineage). Everything either depends on — now and
+planned — is MIT / BSD / Apache. No GPL, no AGPL, so a licensee can
+redistribute the whole thing.

quire_grammar-0.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quire-grammar"
+version = "0.2.0"
+description = "An offline English grammar and style checker — a writer's aid, not a proofreading service."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Roger Cooper" }]
+# The rules layer has ZERO runtime dependencies. Keep it that way.
+dependencies = []
+
+[project.optional-dependencies]
+# Phase 2 — the small local model behind the same check() API. `model` pulls
+# the ONNX weights (the separate quire-grammar-model dist) plus the runtime.
+model = ["quire-grammar-model>=0.2", "onnxruntime>=1.17", "tokenizers>=0.15"]
+ml = ["quire-grammar-model>=0.2", "onnxruntime>=1.17", "tokenizers>=0.15"]  # deprecated alias for `model`
+# dev pulls the model runtime too (onnxruntime/tokenizers/numpy) so the full
+# test suite — including the ONNX integration tests — runs after
+#   pip install -e ".[dev]" -e ./packages/quire-grammar-model
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.8",
+       "onnxruntime>=1.17", "tokenizers>=0.15", "numpy>=1.26"]
+
+[project.scripts]
+quire-grammar = "quire_grammar.__main__:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# py.typed marks the package as typed; models/* is the optional local-build
+# fallback (the real model ships as the separate quire-grammar-model dist)
+quire_grammar = ["py.typed", "models/*"]
+
+[tool.pytest.ini_options]
+# "src" for the package, "packages/.../src" so the model dist is importable
+# without installing it, "." for the unshipped train/ package
+pythonpath = ["src", "packages/quire-grammar-model/src", "."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "RUF"]
+ignore = ["RUF001"]   # curly quotes / “ ” are deliberate in message text
+
+[tool.mypy]
+files = ["src/quire_grammar", "train", "packages/quire-grammar-model/src"]
+mypy_path = "packages/quire-grammar-model/src"
+
+# train/train.py and train/export.py are workbench-only and import the heavy
+# ML stack from train/requirements.txt, which isn't installed for lint/CI.
+[[tool.mypy.overrides]]
+module = ["torch.*", "transformers.*", "datasets.*", "numpy.*", "onnx.*",
+          "onnxruntime.*", "tokenizers.*"]
+ignore_missing_imports = true

quire_grammar-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quire_grammar-0.2.0/src/quire_grammar/__init__.py

@@ -0,0 +1,17 @@
+"""quire-grammar — an offline English grammar and style checker.
+
+Public surface (stable):
+
+    check(text, *, enable=None, disable=None, min_confidence=0.0) -> list[Correction]
+
+Everything else is an implementation detail. The phase-2 local model plugs in
+behind ``check`` without changing this signature.
+"""
+
+from __future__ import annotations
+
+from .check import check
+from .types import CATEGORIES, Correction
+
+__version__ = "0.0.1"
+__all__ = ["CATEGORIES", "Correction", "__version__", "check"]

quire_grammar-0.2.0/src/quire_grammar/__main__.py

@@ -0,0 +1,57 @@
+"""quire-grammar CLI:
+
+    quire-grammar "Its a nice day and and the the sky is is blue."
+    echo "text" | quire-grammar -
+    quire-grammar --json chapter-3.txt
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__, check
+
+
+def _line_col(text: str, pos: int) -> tuple[int, int]:
+    head = text[:pos]
+    return head.count("\n") + 1, pos - (head.rfind("\n") + 1) + 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="quire-grammar", description=__doc__)
+    ap.add_argument("source", help='text, a file path, or "-" for stdin')
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    ap.add_argument("--min-confidence", type=float, default=0.0)
+    ap.add_argument("--disable", default="", help="comma-separated rule ids / categories")
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    args = ap.parse_args(argv)
+
+    if args.source == "-":
+        text = sys.stdin.read()
+    else:
+        try:
+            with open(args.source, encoding="utf-8") as f:
+                text = f.read()
+        except OSError:
+            text = args.source
+
+    hits = check(text, disable=[s for s in args.disable.split(",") if s],
+                 min_confidence=args.min_confidence)
+
+    if args.json:
+        print(json.dumps([vars(h) | {"meta": h.meta} for h in hits], indent=2))
+        return 1 if hits else 0
+
+    for h in hits:
+        line, col = _line_col(text, h.start)
+        fix = f"  →  {h.suggestions[0]!r}" if h.suggestions else ""
+        print(f"{line}:{col}  [{h.category}/{h.rule_id}]  {h.message}{fix}")
+    if not hits:
+        print("no issues found")
+    return 1 if hits else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

quire_grammar-0.2.0/src/quire_grammar/check.py

@@ -0,0 +1,56 @@
+"""The one call the rest of the world makes.
+
+    from quire_grammar import check
+    for c in check("Its a nice day and and the the sky is is blue."):
+        print(c.rule_id, c.original, "->", c.suggestions)
+
+``enable`` / ``disable`` accept rule ids *or* category names, so a UI can
+switch off "style" wholesale or turn on a single opt-in rule.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+
+from . import rules as _rules  # noqa: F401 — importing registers every rule
+from .registry import all_rules
+from .types import Correction
+
+# Phase 2: when the optional model is installed, its predictions are merged
+# in here (same Correction shape, category "agreement" etc.), de-duplicated
+# against the rule hits, and gated by a confidence threshold.
+_model_predict: Callable[[str], list[Correction]] | None
+try:  # pragma: no cover
+    from .model import predict as _model_predict
+except Exception:  # pragma: no cover
+    _model_predict = None
+
+
+def check(
+    text: str,
+    *,
+    enable: Iterable[str] | None = None,
+    disable: Iterable[str] | None = None,
+    min_confidence: float = 0.0,
+) -> list[Correction]:
+    on = set(enable or ())
+    off = set(disable or ())
+
+    out: list[Correction] = []
+    for r in all_rules():
+        keys = {r.id, r.category}
+        active = bool(keys & on) or (r.enabled_by_default and not (keys & off))
+        if active:
+            out.extend(r.fn(text))
+
+    if _model_predict is not None and "model" not in off:  # pragma: no cover
+        rule_spans = [(c.start, c.end) for c in out]
+        for c in _model_predict(text):
+            # a rule hit wins on any span overlap — it's the higher-precision
+            # signal; the model only adds what the rules missed
+            if not any(c.start < re_ and rs < c.end for rs, re_ in rule_spans):
+                out.append(c)
+
+    out = [c for c in out if c.confidence >= min_confidence]
+    out.sort(key=lambda c: (c.start, c.end, c.rule_id))
+    return out

quire_grammar-0.2.0/src/quire_grammar/edits.py

@@ -0,0 +1,241 @@
+"""The GECToR-style edit-tag scheme — shared by the phase-2 model's training
+pipeline and its runtime decoder, so it lives in the shipped package.
+
+The model reads a sentence, splits it into word tokens, and predicts one
+**edit tag** per token. Applying the tags and re-joining rebuilds the
+corrected sentence.
+
+    $KEEP                 leave the token alone
+    $DELETE               drop the token
+    $REPLACE_{t}          swap the token for t
+    $APPEND_{t}           insert t (one or more words) after the token
+    $CASE_CAPITAL         Titlecase the token
+    $CASE_LOWER           lowercase the token
+    $CASE_UPPER           UPPERCASE the token
+
+Kept small on purpose — precision over coverage. Multi-edit tokens (GECToR
+uses iterative rounds) are rare in native-writer text; ``$APPEND_{t}`` carries
+the whole inserted run so one pass covers them. Anything the scheme cannot
+express round-trips wrong, and :func:`encode`'s caller drops the pair.
+
+Zero dependencies — part of the rules-layer contract.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+KEEP = "$KEEP"
+DELETE = "$DELETE"
+_REPLACE = "$REPLACE_"
+_APPEND = "$APPEND_"
+CASE_CAPITAL = "$CASE_CAPITAL"
+CASE_LOWER = "$CASE_LOWER"
+CASE_UPPER = "$CASE_UPPER"
+
+_CASE_TAGS = (CASE_CAPITAL, CASE_LOWER, CASE_UPPER)
+
+#: the tags that are always in the vocabulary, at fixed indices
+BASE_TAGS: tuple[str, ...] = (KEEP, DELETE, *_CASE_TAGS)
+
+
+def replace_tag(token: str) -> str:
+    return _REPLACE + token
+
+
+def append_tag(run: str) -> str:
+    return _APPEND + run
+
+
+def is_replace(tag: str) -> bool:
+    return tag.startswith(_REPLACE)
+
+
+def is_append(tag: str) -> bool:
+    return tag.startswith(_APPEND)
+
+
+def tag_value(tag: str) -> str:
+    """The payload of a ``$REPLACE_`` / ``$APPEND_`` tag."""
+    return tag.split("_", 1)[1]
+
+
+# --------------------------------------------------------------------------
+# tokenisation — word tokens with punctuation split off, plus a deterministic
+# detokeniser. Not exact for pathological spacing; callers verify and drop.
+# --------------------------------------------------------------------------
+
+_TOKEN_RE = re.compile(
+    r"""
+      \d[\d,]*(?:\.\d+)?          # 12  1,000  3.5
+    | [A-Za-z]+(?:['’][A-Za-z]+)* # word, with internal apostrophes
+    | \.\.\.|[.!?]+               # sentence punctuation, runs kept together
+    | --+|[-–—]                   # dashes / hyphen
+    | [^\s\w]                     # any other single punctuation mark
+    """,
+    re.VERBOSE,
+)
+
+# marks that hug the previous token (no space before)
+_CLOSE = set(".,;:!?)]}%…") | {"...", "n't", "'s", "'re", "'ve", "'ll", "'m", "'d"}
+# marks that hug the next token (no space after)
+_OPEN = set("([{$")
+_CONTRACTION = re.compile(r"^['’](s|re|ve|ll|m|d)$|^n['’]t$", re.I)
+
+
+def tokenize(text: str) -> list[str]:
+    return _TOKEN_RE.findall(text)
+
+
+def tokenize_spans(text: str) -> list[tuple[str, int, int]]:
+    """``(token, start, end)`` — same tokens as :func:`tokenize`, with their
+    character offsets in ``text`` (the runtime decoder needs them to place
+    ``Correction`` spans)."""
+    return [(m.group(0), m.start(), m.end()) for m in _TOKEN_RE.finditer(text)]
+
+
+def detokenize(tokens: list[str]) -> str:
+    """Join word tokens back into a sentence. Deterministic; assumes the
+    tokens describe ordinary prose."""
+    out: list[str] = []
+    quote_open = False
+    for tok in tokens:
+        if not out:
+            out.append(tok)
+            continue
+        prev = out[-1]
+        glue = (
+            tok in _CLOSE
+            or _CONTRACTION.match(tok)
+            or prev in _OPEN
+            or prev[-1:] in _OPEN
+            or (tok == '"' and quote_open)
+            or (prev == '"' and not quote_open)
+            or (tok in "-–—")
+            or (prev in "-–—")
+            or (tok in "'’" and quote_open)
+        )
+        out.append(tok if glue else " " + tok)
+        if tok == '"':
+            quote_open = not quote_open
+    return "".join(out)
+
+
+# --------------------------------------------------------------------------
+# alignment — token-level Levenshtein, then read off the edit tags
+# --------------------------------------------------------------------------
+
+
+def _case_transform(src: str, dst: str) -> str | None:
+    if src == dst or src.lower() != dst.lower():
+        return None
+    if dst == src.capitalize():
+        return CASE_CAPITAL
+    if dst == src.lower():
+        return CASE_LOWER
+    if dst == src.upper():
+        return CASE_UPPER
+    return None
+
+
+def _flush_append(tags: list[str], src_pos: int, pending: list[str]) -> None:
+    if pending:
+        tags[src_pos - 1] = append_tag(" ".join(pending))
+        pending.clear()
+
+
+def _tags_from_alignment(src: list[str], tgt: list[str]) -> list[str] | None:
+    n, m = len(src), len(tgt)
+    d = [[0] * (m + 1) for _ in range(n + 1)]
+    for i in range(1, n + 1):
+        d[i][0] = i
+    for j in range(1, m + 1):
+        d[0][j] = j
+    for i in range(1, n + 1):
+        for j in range(1, m + 1):
+            cost = 0 if src[i - 1] == tgt[j - 1] else 1
+            d[i][j] = min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost)
+
+    tags: list[str] = [KEEP] * n
+    pending_append: list[str] = []
+    i, j = n, m
+    lead_insert: list[str] = []
+    while i > 0 or j > 0:
+        if i > 0 and j > 0 and src[i - 1] == tgt[j - 1] and d[i][j] == d[i - 1][j - 1]:
+            _flush_append(tags, i, pending_append)
+            i, j = i - 1, j - 1
+        elif i > 0 and j > 0 and d[i][j] == d[i - 1][j - 1] + 1:
+            ct = _case_transform(src[i - 1], tgt[j - 1])
+            if pending_append:
+                tags[i - 1] = replace_tag(" ".join([tgt[j - 1], *pending_append]))
+                pending_append.clear()
+            else:
+                tags[i - 1] = ct or replace_tag(tgt[j - 1])
+            i, j = i - 1, j - 1
+        elif j > 0 and d[i][j] == d[i][j - 1] + 1:
+            pending_append.insert(0, tgt[j - 1])
+            j -= 1
+            if i == 0:
+                lead_insert = list(pending_append)
+        else:
+            tags[i - 1] = DELETE
+            _flush_append(tags, i, pending_append)
+            i -= 1
+    if lead_insert:
+        return None
+    return tags
+
+
+# --------------------------------------------------------------------------
+# public: encode / apply / verify
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Tagged:
+    tokens: tuple[str, ...]
+    tags: tuple[str, ...]
+
+
+def encode(corrupt: str, clean: str) -> Tagged | None:
+    """``(corrupt, clean)`` → token tags, or ``None`` if the scheme can't
+    represent the edit or the result won't round-trip."""
+    src, tgt = tokenize(corrupt), tokenize(clean)
+    if not src:
+        return None
+    tags = _tags_from_alignment(src, tgt)
+    if tags is None:
+        return None
+    tagged = Tagged(tuple(src), tuple(tags))
+    if apply(tagged.tokens, tagged.tags) != detokenize(tgt):
+        return None
+    return tagged
+
+
+def apply(tokens: tuple[str, ...] | list[str],
+          tags: tuple[str, ...] | list[str]) -> str:
+    out: list[str] = []
+    for tok, tag in zip(tokens, tags, strict=True):
+        if tag == KEEP:
+            out.append(tok)
+        elif tag == DELETE:
+            continue
+        elif tag == CASE_CAPITAL:
+            out.append(tok.capitalize())
+        elif tag == CASE_LOWER:
+            out.append(tok.lower())
+        elif tag == CASE_UPPER:
+            out.append(tok.upper())
+        elif is_replace(tag):
+            out.extend(tokenize(tag_value(tag)))
+        elif is_append(tag):
+            out.append(tok)
+            out.extend(tokenize(tag_value(tag)))
+        else:  # unknown tag → treat as KEEP (a miss, never a crash)
+            out.append(tok)
+    return detokenize(out)
+
+
+def verify(corrupt: str, clean: str, tagged: Tagged) -> bool:
+    return apply(tagged.tokens, tagged.tags) == detokenize(tokenize(clean))