spintax-core 0.1.0__tar.gz

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

@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # The golden corpus is the cross-engine contract, shared with @spintax/core
+      # (TypeScript) and the PHP engine. It is checked out rather than vendored: a
+      # copy would drift, and a drifting contract is not a contract. Same pattern
+      # spintax-php already runs in production.
+      - name: Check out the golden corpus
+        uses: actions/checkout@v7
+        with:
+          repository: investblog/spintax-js
+          path: .corpus
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . pytest ruff mypy
+
+      - name: Golden corpus
+        env:
+          SPINTAX_FIXTURES: ${{ github.workspace }}/.corpus/packages/conformance/fixtures
+        run: pytest -q
+
+      # Gated, not merely runnable: the plan's definition of done names both, and a
+      # check nobody runs is a check that does not exist.
+      - name: Lint
+        run: ruff check .
+
+      - name: Types
+        run: mypy
+
+  # Everything above aims at the code. Nothing looked at the DISTRIBUTION, and that is
+  # where the last two publication blockers were hiding: a `Typing :: Typed` classifier
+  # with no marker behind it, and a licence declared twice. Neither shows up in ruff,
+  # mypy or pytest, and both would have reached PyPI.
+  #
+  # Its own job rather than a matrix step: a distribution does not vary by interpreter,
+  # so building it four times would only multiply the noise.
+  package:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine pyroma
+
+      - name: Build
+        run: python -m build
+
+      # Guards the PyPI project page: a README that stops rendering is invisible here
+      # and permanent there.
+      - name: Distribution metadata
+        run: twine check dist/*
+
+      # Pinned at the rating this tree already earns, so the check catches a regression
+      # instead of asking for a round number. The two missing points are one complaint —
+      # no `author-email` — and that is deliberate: @spintax/core and spintax/core both
+      # publish name plus https://301.st and no address, routing contact through Issues.
+      # Do not "fix" it to 10 by adding an inbox the other two packages do not expose.
+      - name: Packaging quality
+        run: pyroma -n 8 .
+
+      # tests/test_packaging.py checks the marker beside the IMPORTED module, which under
+      # `pip install -e .` is the source tree — it would stay green if packaging config
+      # ever excluded the file. Only a built artifact can answer whether it ships.
+      - name: The typing marker must ship, not merely exist in the tree
+        run: |
+          python - <<'PY'
+          import glob, sys, tarfile, zipfile
+          wheel = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          sdist = tarfile.open(glob.glob("dist/*.tar.gz")[0]).getnames()
+          missing = [
+              kind
+              for kind, names in (("wheel", wheel), ("sdist", sdist))
+              if not any(n.endswith("py.typed") for n in names)
+          ]
+          if missing:
+              sys.exit(f"py.typed is absent from: {', '.join(missing)}")
+          print("py.typed ships in both the wheel and the sdist")
+          PY

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

@@ -0,0 +1,103 @@
+name: Release
+
+# Tag-driven, and deliberately not automatic on push to main: a release is a decision, not
+# a side effect of merging. Tag `v0.1.0` and this builds, re-verifies and uploads.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # The CI workflow already runs on every push, but a tag can be placed on any commit —
+  # including one CI never saw green. Re-running the gate here means the artifact that
+  # reaches PyPI is one that passed, rather than one that probably did.
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Check out the golden corpus
+        uses: actions/checkout@v7
+        with:
+          repository: investblog/spintax-js
+          path: .corpus
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . pytest ruff mypy
+
+      - name: Test
+        env:
+          SPINTAX_FIXTURES: ${{ github.workspace }}/.corpus/packages/conformance/fixtures
+        run: pytest -q
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Types
+        run: mypy
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      # The same three checks the `package` job runs on every push. Repeated here because
+      # this is the last point at which a bad artifact can still be stopped.
+      - name: Distribution metadata
+        run: twine check dist/*
+
+      - name: The version being published matches the tag
+        run: |
+          python - <<'PY'
+          import glob, os, re, sys
+          tag = os.environ["GITHUB_REF_NAME"].lstrip("v")
+          names = [os.path.basename(p) for p in glob.glob("dist/*.whl")]
+          built = re.match(r"spintax_core-([^-]+)-", names[0]).group(1)
+          if built != tag:
+              sys.exit(f"tag says {tag!r} but the wheel is {built!r} — bump pyproject or retag")
+          print(f"tag and wheel agree on {built}")
+          PY
+
+      - name: The typing marker ships
+        run: |
+          python - <<'PY'
+          import glob, sys, tarfile, zipfile
+          wheel = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          sdist = tarfile.open(glob.glob("dist/*.tar.gz")[0]).getnames()
+          missing = [
+              kind
+              for kind, names in (("wheel", wheel), ("sdist", sdist))
+              if not any(n.endswith("py.typed") for n in names)
+          ]
+          if missing:
+              sys.exit(f"py.typed is absent from: {', '.join(missing)}")
+          print("py.typed ships in both the wheel and the sdist")
+          PY
+
+      - name: Upload to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

spintax_core-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Agent charters live locally, not in the repo (mirrors the spintax-js convention).
+CLAUDE.md
+AGENTS.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+# `dist*` rather than `dist`: a wheel built into `dist-review/` for a one-off
+# inspection slipped past a plain `dist/` and was committed (291ac13). The pattern
+# has to cover the directory names people actually type, not just the canonical one.
+dist*/
+.venv/
+venv/
+.python-version
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local corpus checkout / fixture sync (see spec §6 Q4). `.corpus/` is where CI
+# puts it and where the test fallback looks; never commit the fixtures here.
+/fixtures-local/
+/.corpus/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

spintax_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 301st (https://301.st)
+
+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.

spintax_core-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: spintax-core
+Version: 0.1.0
+Summary: Spintax engine for Python — enumerations, permutations, variables, conditionals, plural agreement, includes. Zero dependencies.
+Project-URL: Homepage, https://spintax.net
+Project-URL: Source, https://github.com/investblog/spintax-py
+Project-URL: Issues, https://github.com/investblog/spintax-py/issues
+Author: 301st
+License-Expression: MIT
+License-File: LICENSE
+Keywords: content-spinning,spinner,spintax,template-variations,text-spinning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# spintax-core (Python)
+
+A framework-agnostic **[Spintax](https://spintax.net) engine** for Python — parse, render,
+validate, extract, analyze, and neutralize spintax templates. MIT, zero runtime dependencies,
+Python 3.10+.
+
+This is the third engine in the Spintax family, and an **independent implementation** — not a
+transcription of the others. It is held to the same behavior contract by a **shared golden corpus**
+of language-neutral fixtures, which already gates the TypeScript engine and the PHP one. All 168
+of them pass here, none skipped, none expected to fail.
+
+## Install
+
+```bash
+pip install spintax-core
+```
+
+## Use
+
+```python
+from spintax_core import render, validate, parse
+
+render("{Hello|Hi} there!")                        # "Hello there!" or "Hi there!"
+render("{Hello|Hi} there!", seed=42)               # same seed, same output, every time
+render("%greeting%, world", context={"greeting": "Hello"})   # "Hello, world"
+
+# Reuse a template: parse once, render many.
+ast = parse('[<sep=", ">fast|cheap|good]')
+[render(ast) for _ in range(3)]
+# ['Cheap, fast, good', 'Good, cheap, fast', 'Cheap, good, fast']
+
+# Check a template before you ship it.
+[d.code for d in validate("{a|b")]                 # -> ['bracket.unclosed']
+```
+
+Rendering is **lenient**: malformed markup degrades rather than raising, so a template a
+non-programmer wrote cannot take a page down.
+
+Syntax — enumerations `{a|b}`, permutations `[a|b]`, variables `%name%`, conditionals
+`{?VAR?yes|no}`, plural agreement `{plural 3: one|few|many}`, `#set` / `#def` / `#include` — is
+documented at **[spintax.net/docs](https://spintax.net/docs/)**.
+
+- **Spec:** [`docs/spec-python-port.md`](docs/spec-python-port.md) — read it before writing any
+  code. It records the parity contract, the API surface, and the open questions. Corpus access
+  (Q4) is decided; Unicode in post-process (Q5) is a known trap with a verified stdlib answer,
+  and lands with P2.
+- **Sibling engines:** [`@spintax/core`](https://www.npmjs.com/package/@spintax/core) (TypeScript,
+  MIT, published) · [Spintax for WordPress](https://wordpress.org/plugins/spintax/) (PHP, GPL, the
+  origin).
+- **Tracking issue:** [investblog/spintax-js#43](https://github.com/investblog/spintax-js/issues/43).
+
+## Why
+
+The existing PyPI `spintax` package is **GPLv3** and has not shipped since **2018**. GPL blocks
+commercial adoption; this one is MIT and maintained.
+
+## License
+
+[MIT](LICENSE). The WordPress plugin remains GPL; MIT/Expat is GPL-compatible.
+
+---
+
+Part of the [301.st](https://301.st) toolset. Product home: [spintax.net](https://spintax.net).
+
+## Development
+
+The test suite **is** the shared golden corpus — the same JSON fixtures the TypeScript and PHP
+engines are tested against, read from a checkout rather than vendored here. A copy would drift,
+and a drifting contract is not a contract.
+
+```sh
+git clone https://github.com/investblog/spintax-js ../spintax-js   # once
+python -m venv .venv && .venv/bin/pip install -e . pytest
+SPINTAX_FIXTURES=../spintax-js/packages/conformance/fixtures pytest
+```
+
+Without the fixtures the suite **fails** rather than passing an empty run — a green suite that
+tested nothing is the most expensive kind of green. The shape of the output is:
+
+```
+N passed, M xfailed, 0 skipped
+```
+
+The two numbers are the milestone tracker: `passed` grows as the engine does, `xfailed` is what
+the corpus still expects and the engine cannot yet do. A **skip** should never appear — it would
+mean a case is being neither asserted nor counted.
+
+The xfails are the whole cross-engine contract, waiting on P1–P3. As milestones land, cases turn
+into real passes with no change to the runner.
+
+> **If you mutate a source file to check that a test catches it, delete `__pycache__` first.**
+> Python invalidates bytecode on (mtime, size). A mutation that preserves both — swapping `.*?`
+> for `.+?`, say — leaves the stale `.pyc` in place, so the *next* run still imports the mutated
+> module after you have restored the file. That produced a failure pointing at correct code, and
+> the obvious response to it would have been to break the code for real.

spintax_core-0.1.0/README.md

@@ -0,0 +1,95 @@
+# spintax-core (Python)
+
+A framework-agnostic **[Spintax](https://spintax.net) engine** for Python — parse, render,
+validate, extract, analyze, and neutralize spintax templates. MIT, zero runtime dependencies,
+Python 3.10+.
+
+This is the third engine in the Spintax family, and an **independent implementation** — not a
+transcription of the others. It is held to the same behavior contract by a **shared golden corpus**
+of language-neutral fixtures, which already gates the TypeScript engine and the PHP one. All 168
+of them pass here, none skipped, none expected to fail.
+
+## Install
+
+```bash
+pip install spintax-core
+```
+
+## Use
+
+```python
+from spintax_core import render, validate, parse
+
+render("{Hello|Hi} there!")                        # "Hello there!" or "Hi there!"
+render("{Hello|Hi} there!", seed=42)               # same seed, same output, every time
+render("%greeting%, world", context={"greeting": "Hello"})   # "Hello, world"
+
+# Reuse a template: parse once, render many.
+ast = parse('[<sep=", ">fast|cheap|good]')
+[render(ast) for _ in range(3)]
+# ['Cheap, fast, good', 'Good, cheap, fast', 'Cheap, good, fast']
+
+# Check a template before you ship it.
+[d.code for d in validate("{a|b")]                 # -> ['bracket.unclosed']
+```
+
+Rendering is **lenient**: malformed markup degrades rather than raising, so a template a
+non-programmer wrote cannot take a page down.
+
+Syntax — enumerations `{a|b}`, permutations `[a|b]`, variables `%name%`, conditionals
+`{?VAR?yes|no}`, plural agreement `{plural 3: one|few|many}`, `#set` / `#def` / `#include` — is
+documented at **[spintax.net/docs](https://spintax.net/docs/)**.
+
+- **Spec:** [`docs/spec-python-port.md`](docs/spec-python-port.md) — read it before writing any
+  code. It records the parity contract, the API surface, and the open questions. Corpus access
+  (Q4) is decided; Unicode in post-process (Q5) is a known trap with a verified stdlib answer,
+  and lands with P2.
+- **Sibling engines:** [`@spintax/core`](https://www.npmjs.com/package/@spintax/core) (TypeScript,
+  MIT, published) · [Spintax for WordPress](https://wordpress.org/plugins/spintax/) (PHP, GPL, the
+  origin).
+- **Tracking issue:** [investblog/spintax-js#43](https://github.com/investblog/spintax-js/issues/43).
+
+## Why
+
+The existing PyPI `spintax` package is **GPLv3** and has not shipped since **2018**. GPL blocks
+commercial adoption; this one is MIT and maintained.
+
+## License
+
+[MIT](LICENSE). The WordPress plugin remains GPL; MIT/Expat is GPL-compatible.
+
+---
+
+Part of the [301.st](https://301.st) toolset. Product home: [spintax.net](https://spintax.net).
+
+## Development
+
+The test suite **is** the shared golden corpus — the same JSON fixtures the TypeScript and PHP
+engines are tested against, read from a checkout rather than vendored here. A copy would drift,
+and a drifting contract is not a contract.
+
+```sh
+git clone https://github.com/investblog/spintax-js ../spintax-js   # once
+python -m venv .venv && .venv/bin/pip install -e . pytest
+SPINTAX_FIXTURES=../spintax-js/packages/conformance/fixtures pytest
+```
+
+Without the fixtures the suite **fails** rather than passing an empty run — a green suite that
+tested nothing is the most expensive kind of green. The shape of the output is:
+
+```
+N passed, M xfailed, 0 skipped
+```
+
+The two numbers are the milestone tracker: `passed` grows as the engine does, `xfailed` is what
+the corpus still expects and the engine cannot yet do. A **skip** should never appear — it would
+mean a case is being neither asserted nor counted.
+
+The xfails are the whole cross-engine contract, waiting on P1–P3. As milestones land, cases turn
+into real passes with no change to the runner.
+
+> **If you mutate a source file to check that a test catches it, delete `__pycache__` first.**
+> Python invalidates bytecode on (mtime, size). A mutation that preserves both — swapping `.*?`
+> for `.+?`, say — leaves the stale `.pyc` in place, so the *next* run still imports the mutated
+> module after you have restored the file. That produced a failure pointing at correct code, and
+> the obvious response to it would have been to break the code for real.

spintax_core-0.1.0/docs/plan-p1.md

@@ -0,0 +1,142 @@
+# P1 — parser, validator, extract
+
+Status: **complete**, with one step moved rather than done. `validate()` and `extract()` are
+wired and every case in `validate.json` and `extract.json` passes. Governing contract:
+[`spec-python-port.md`](spec-python-port.md). Next: P2 (parser + renderer).
+
+P0 left the corpus running against an empty engine: **7 passed, 168 xfailed, 0 skipped**. P1's
+progress metric is that number moving — every step below turns a named set of xfails into passes,
+and no step is "done" until its cases pass for the reason intended.
+
+## What P1 must close
+
+`validate.json` — 40 cases (15 valid, 25 invalid) across **17 distinct diagnostic codes** — plus
+`extract.json` (2 cases). That is 42 of the 168.
+
+Two scope corrections against the spec's milestone list, both found by reading the fixtures rather
+than the plan:
+
+- **Plural *arity* belongs to P1, not P2.** 14 validate cases carry a `locale` and 5 assert
+  `plural.arity`, so `normalize_base_lang` and the arity table are P1 work. Rendering plurals
+  stays P2; deciding whether a template *could* render is P1.
+- **`extract` is pulled forward from P3.** Once the parser exists, the names are already collected
+  for the diagnostics — `refs`, `sets`, `defs`, `includes` fall out of work P1 has to do anyway.
+  Leaving it in P3 would mean building the same index twice.
+
+## Steps
+
+Ordered so that each one moves the counter, and the hardest lands last against a suite that is
+already mostly green.
+
+### 1. Parser → `Ast` — **moved to P2, not done**
+
+Reading the reference before writing any of it showed the premise was wrong: `validate` and
+`extract` are raw-text scanners *by design*, because the AST is lenient — an unbalanced bracket
+is not represented in it at all, and a `[…]` body stays a raw string. Neither needs a tree, so
+building one first would have been a week with no case moving. It is P2's opening, where the
+renderer actually requires it. `parse()` still raises.
+
+What did survive from this step is the position work, and it moved into `_source.py`: comment
+stripping keeps a map back to the original offsets, so a diagnostic points at the place the
+author is looking at rather than at a place that existed before the comments were removed.
+
+### 2. Structural diagnostics — 8 codes
+
+`bracket.unclosed`, `bracket.mismatched`, `bracket.unexpected-closing`, `set.malformed`,
+`def.malformed`, `permutation.minsize-not-integer`, `permutation.maxsize-not-integer`,
+`permutation.unknown-key`.
+
+Mechanical, and the first visible movement in the corpus.
+
+### 3. Variable graph — 3 codes
+
+`variable.self-reference`, `variable.circular-reference`, `variable.undefined` (a **warning**, and
+the only one that must not flip a verdict to invalid).
+
+`known_variables` suppression is implemented here and **is not gated by the corpus** — the fixture
+schema has no such field. It needs local tests or it can break silently.
+
+### 4. Plural diagnostics — 2 codes, 14 cases touched
+
+`normalize_base_lang` (`sr-Latn` → `sr`, `pt-BR` → `pt`; three-letter tags are *not* mapped) plus
+the arity table: 3 forms for `ru`/`uk`/`be`/`sr`/`hr`/`bs`, 2 for everything else — including
+`pl`/`cs`/`sk`/`sl`/`bg`, which are wrong-but-accepted by design.
+
+Then `plural.arity`. Note an empty or absent locale **skips** the arity check entirely.
+
+`plural.nested-brackets` lands here too, and needs no locale: a form slot must be plain text, so
+`{plural 1: {a|b}|c}` is rejected structurally. Keep it distinct from step 6 — this one is about
+brackets *inside a form*, that one about a count that only becomes bracketed after expansion.
+
+### 5. Definitions and includes — 3 codes
+
+`definition.duplicate-name`, `def.include-in-value`, and `include.unknown-target`.
+
+The include check is the only diagnostic that depends on caller-supplied data: it fires only when
+`known_includes` is non-empty, so with no list every target is assumed to exist. Two fixtures
+cover it, and one of them is a *valid* verdict — a circular include is a runtime outcome, not a
+static error.
+
+Read spec §5.3 before writing this: duplicate detection requires keeping directive **occurrences**
+until after the diagnostic runs. Folding directives into a `dict[str, str]` first destroys the
+evidence — the second assignment overwrites the first and there is nothing left to report. The PHP
+pass lost duplicates exactly this way.
+
+### 6. `plural.count-macro` — 1 code, 5 cases, and the real work
+
+A taint analysis, not a node check. A count slot is poisoned when it resolves — possibly through a
+chain of `#set` aliases — to a value that still holds unresolved spintax at the moment plurals run.
+
+```
+#set %m% = {1|4|9}            # chained alias: taint must reach %n%
+#set %n% = %m%
+{plural %n%: item|items}      # error
+
+#set %n% = {?flag?{1|4}|2}    # a conditional is exempt (resolves before plurals)…
+{plural %n%: item|items}      # …but the enumeration inside it is not — still an error
+```
+
+The rule is **stage order**, not bracket-spotting: conditionals resolve before the plural pass, so
+they are the single exemption; a nested `{plural …}` is not. Propagate to a fixed point — a
+one-pass walk gets `plural-count-macro` right and `plural-count-macro-chained` wrong.
+
+There is a paired case where a conditional count **is valid**. If both pass, the rule is a rule; if
+only the error cases pass, it is over-eager and the valid one will say so.
+
+### 7. `extract`
+
+`refs` / `sets` / `defs` / `includes` from the index step 3 already built. `sets` and `defs` are
+separate buckets — the whole point of the fixture we added upstream.
+
+## What the corpus will not catch
+
+Local tests are mandatory for these; a green corpus says nothing about any of them:
+
+| surface | why it is invisible |
+| --- | --- |
+| `line` / `column` | **zero** fixtures assert positions |
+| `known_variables` | no such field in the fixture schema |
+| `max_depth` | only the circular-include outcome is pinned |
+| `parse` itself | no fixtures; only observable through other ops |
+
+## Why `validate()` was wired only at the end
+
+The corpus reports by **op**. While `validate` raised `NotImplementedError` all 40 of its cases
+were xfails, which reads as "not built". Wiring a half-finished validator would have run them for
+real — the ones whose codes existed passing, the rest **failing** — and turned the suite red for
+work nobody had claimed was done. Red would have stopped meaning "something broke".
+
+So each check was proved by its own tests first and the public entry point flipped exactly once,
+when all seventeen codes existed. Same reason the reference suite lights up by op, not by code.
+Worth repeating at P2: `render` should stay unwired until it can pass its own cases.
+
+## Definition of done
+
+- `validate.json` and `extract.json` fully green — 42 cases moved from xfail to pass.
+- The corpus's 42 P1 cases move from xfail to passed, and no case is ever skipped. The absolute
+  totals are deliberately not written down here: they change with every local test added, and a
+  number in a document is a number that goes stale.
+- Local tests covering the ungated surfaces above, each verified by breaking the implementation
+  and watching the test fail — not by observing that it passes. `max_depth` is excluded: it is a
+  render budget, so it belongs to P2 with the code that enforces it.
+- `mypy --strict` and `ruff` clean.