softschema 0.2.1__tar.gz → 0.2.2__tar.gz

{softschema-0.2.1 → softschema-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softschema
-Version: 0.2.1
+Version: 0.2.2
 Summary: Soft schema conventions and validation tools for Markdown/YAML artifacts
 Project-URL: Homepage, https://github.com/jlevy/softschema
 Project-URL: Repository, https://github.com/jlevy/softschema
@@ -232,8 +232,8 @@ Two supported ways to consume softschema; pick by use:
   fast, offline, and the only way to `import` it):
 
   ```bash
-  uv add --dev softschema==0.2.1        # Python
-  npm install -D softschema@0.2.1       # Node (or: bun add -d)
+  uv add --dev softschema==0.2.2        # Python
+  npm install -D softschema@0.2.2       # Node (or: bun add -d)
   ```
 
 - **Zero-install** for one-off checks and agent bootstrap:

{softschema-0.2.1 → softschema-0.2.2}/README.md

@@ -204,8 +204,8 @@ Two supported ways to consume softschema; pick by use:
   fast, offline, and the only way to `import` it):
 
   ```bash
-  uv add --dev softschema==0.2.1        # Python
-  npm install -D softschema@0.2.1       # Node (or: bun add -d)
+  uv add --dev softschema==0.2.2        # Python
+  npm install -D softschema@0.2.2       # Node (or: bun add -d)
   ```
 
 - **Zero-install** for one-off checks and agent bootstrap:

{softschema-0.2.1 → softschema-0.2.2}/docs/installation.md

@@ -9,7 +9,7 @@ Pick the runtime you already have; both validate against the same canonical sche
 |  | Pin as a dependency | Zero-install (`uvx` / `npx`) |
 | --- | --- | --- |
 | **For** | Projects, CI gates, library use | One-off checks, agent bootstrap |
-| **Reproducible** | Yes—the version is locked in `uv.lock` / `package-lock.json` | Only if you pin the runner (`uvx softschema@0.2.1`) |
+| **Reproducible** | Yes—the version is locked in `uv.lock` / `package-lock.json` | Only if you pin the runner (`uvx softschema@0.2.2`) |
 | **Fast / offline** | Yes—the binary is already on disk | Cold-start fetch; needs the network |
 | **Library import** | Yes—the only way | No |
 
@@ -23,14 +23,14 @@ use a zero-install runner**, pinned where the result must be repeatable.
 Python (a dev dependency, or a persistent user tool):
 
 ```bash
-uv add --dev softschema==0.2.1      # project dev dependency; run via `uv run softschema`
+uv add --dev softschema==0.2.2      # project dev dependency; run via `uv run softschema`
 uv tool install softschema          # persistent CLI on your PATH
 ```
 
 Node (>= 22.12):
 
 ```bash
-npm install -D softschema@0.2.1     # or: pnpm add -D / bun add -d
+npm install -D softschema@0.2.2     # or: pnpm add -D / bun add -d
 npx softschema --help               # resolves the local pinned copy
 ```
 
@@ -41,7 +41,7 @@ uvx softschema@latest --help        # Python implementation, ephemeral
 npx softschema@latest --help        # Node implementation, ephemeral
 ```
 
-Use `uvx softschema@0.2.1` / `npx -y softschema@0.2.1` when a repeated ad-hoc run must
+Use `uvx softschema@0.2.2` / `npx -y softschema@0.2.2` when a repeated ad-hoc run must
 resolve the same version every time.
 
 ## Quick Start for Agents

{softschema-0.2.1 → softschema-0.2.2}/docs/softschema-spec.md

@@ -335,6 +335,18 @@ A validator must reject:
 - undeclared payload fields rejected by the `enforced` strictness rule (see Status
   Values)
 
+Validation output is deterministic across conforming implementations: structural error
+records share an engine-neutral shape and message wording, and numbers — in an error
+record’s `value`/`validator_value`, in a synthesized message, and in an echoed payload —
+render in a canonical form, where a whole-valued number carries no trailing fraction
+(`2`, not `2.0`).
+Output is byte-identical for every number an implementation can represent exactly:
+integers and whole-valued numbers within the IEEE-754 safe-integer range (`abs < 2^53`),
+and ordinary floats.
+A whole-valued magnitude at or beyond 2^53 is out of scope, because an arbitrary-precision
+integer runtime and a double-only runtime cannot always render it identically; validated
+payloads should avoid such literals.
+
 ## Generated Sections
 
 A conforming implementation may regenerate Markdown sections from a compiled schema

softschema-0.2.2/packages/python/README.md

@@ -0,0 +1,48 @@
+# softschema (Python)
+
+Soft schemas: gradual, practical validation for Markdown/YAML artifacts that mix prose
+and structured data—built for humans and coding agents.
+
+This is the Python implementation of [softschema](https://github.com/jlevy/softschema),
+published on [PyPI](https://pypi.org/project/softschema/). A fully synchronized
+TypeScript implementation is also available on npm.
+
+## Install
+
+```bash
+pip install softschema
+# or:
+uv add softschema
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from softschema import validate_artifact
+
+# A self-describing artifact validates with no extra arguments; pass contract=,
+# contract_id=, or registry= to bind a schema explicitly.
+result = validate_artifact(Path("doc.md"))
+```
+
+Or from the command line:
+
+```bash
+softschema validate doc.md
+```
+
+## Documentation
+
+- [softschema Guide](https://github.com/jlevy/softschema/blob/main/docs/softschema-guide.md):
+  the full mental model and adoption playbooks
+- [softschema Spec](https://github.com/jlevy/softschema/blob/main/docs/softschema-spec.md):
+  the exact artifact format and validation rules
+- [Installation](https://github.com/jlevy/softschema/blob/main/docs/installation.md):
+  pinned vs zero-install, uv and Node setup
+- [Repository](https://github.com/jlevy/softschema)
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

{softschema-0.2.1 → softschema-0.2.2}/packages/python/src/softschema/cli.py

@@ -21,6 +21,7 @@ from ruamel.yaml import YAMLError
 from strif import atomic_write_text
 
 from softschema.compile import compile_model
+from softschema.errors import canonical_number
 from softschema.generate import regenerate
 from softschema.models import Contract, SchemaStatus, parse_schema_metadata
 from softschema.validate import EnvelopeAmbiguityError, infer_envelope_key, validate_artifact
@@ -42,19 +43,30 @@ AGENT_HELP_EPILOG = """IMPORTANT for agents:
   Then read `softschema skill --brief` and `softschema docs --list` for operating rules
   and bundled docs."""
 
-# Exception families that represent user mistakes (bad files, bad input, bad
-# config) rather than internal bugs.  Caught by the per-subcommand error
-# boundary so that ordinary mistakes never produce a traceback.
+
+class UsageError(ValueError):
+    """A user/input mistake: bad flags, a bad model spec, or an unusable document.
+
+    Subclasses ``ValueError`` so it is reported through the CLI's user-error boundary
+    (clean one-line message, exit 2) and so library callers that already catch
+    ``ValueError`` keep working.
+    """
+
+
+# Exit codes: 0 ok, 1 validation failure or drift (``--check``), 2 user/usage error.
+# The families below are user mistakes (bad files, bad input, bad config), caught by the
+# per-subcommand error boundary so an ordinary mistake never prints a traceback.
+# ``TypeError`` and ``KeyError`` are deliberately excluded: nothing in the package raises
+# them for user input, so they only ever signal an internal bug and must surface as a
+# traceback rather than be masked as a clean exit 2.
 _USER_ERRORS = (
     OSError,
     FmFormatError,
     YAMLError,
     ModuleNotFoundError,
     ImportError,
-    TypeError,
-    ValueError,
     ValidationError,
-    KeyError,
+    ValueError,
 )
 
 
@@ -242,6 +254,12 @@ def main(argv: list[str] | None = None) -> int:
     )
     generate_parser.set_defaults(func=_generate_cmd)
 
+    prime_parser = subparsers.add_parser(
+        "prime",
+        help="Print the full agent context: skill rules and the bundled docs index.",
+    )
+    prime_parser.set_defaults(func=_prime_cmd)
+
     doctor_parser = subparsers.add_parser(
         "doctor",
         help="Report softschema version and runner availability.",
@@ -299,13 +317,13 @@ def _infer_validation_binding(
 ) -> tuple[str, SchemaStatus, str | None]:
     if not isinstance(frontmatter, dict):
         if args.contract is None:
-            raise ValueError("missing --contract because the document has no YAML frontmatter")
+            raise UsageError("missing --contract because the document has no YAML frontmatter")
         return args.contract, _status_from_args(args, None), args.envelope
 
     metadata = parse_schema_metadata(frontmatter.get("softschema"))
     contract_id = args.contract or (metadata.contract_id if metadata is not None else None)
     if contract_id is None:
-        raise ValueError("missing --contract because the document has no softschema.contract")
+        raise UsageError("missing --contract because the document has no softschema.contract")
 
     return (
         contract_id,
@@ -333,18 +351,16 @@ def _envelope_from_args(
     try:
         return infer_envelope_key(frontmatter)
     except EnvelopeAmbiguityError as exc:
-        raise ValueError(
+        raise UsageError(
             "multiple top-level frontmatter keys; pass --envelope to designate the "
             f"softschema payload (candidates: {', '.join(exc.candidates)})"
         ) from exc
 
 
 def _compile_cmd(args: argparse.Namespace) -> int:
-    try:
-        model = _load_model(args.model)
-    except (TypeError, ValueError) as exc:
-        print(f"softschema compile: {exc}", file=sys.stderr)
-        return 2
+    # Model-load and compile errors (UsageError, OSError, ...) propagate to the shared
+    # `_run_cmd` boundary, which reports them as `softschema compile: ...` and exits 2.
+    model = _load_model(args.model)
     result = compile_model(model, args.out, contract_id=args.contract, check_only=args.check)
     print(_json(result))
     return 1 if result.drift else 0
@@ -395,13 +411,27 @@ def _docs_cmd(args: argparse.Namespace) -> int:
     return 0
 
 
+def _prime_text() -> str:
+    """Full agent context: the skill operating rules plus the bundled docs index.
+
+    Byte-identical to the TypeScript ``prime`` command (same SKILL.md, same listing).
+    """
+    skill = _read_resource("skills/softschema/SKILL.md")
+    return f"{skill.rstrip()}\n\n{_docs_listing()}"
+
+
+def _prime_cmd(args: argparse.Namespace) -> int:
+    _write_text(_prime_text())
+    return 0
+
+
 def _generate_cmd(args: argparse.Namespace) -> int:
     any_drift = False
     summary: list[dict[str, Any]] = []
     for path in args.paths:
         try:
             result = regenerate(path, check=args.check)
-        except (OSError, ValueError, KeyError) as exc:
+        except (OSError, ValueError) as exc:
             print(f"softschema generate: {path}: {exc}", file=sys.stderr)
             return 2
         any_drift = any_drift or result.drift
@@ -548,7 +578,7 @@ def _skill_cmd(args: argparse.Namespace) -> int:
 def _load_model(spec: str) -> type[BaseModel]:
     module_name, _, attr = spec.partition(":")
     if not module_name or not attr:
-        raise ValueError(f"model spec must be module:Class, got {spec!r}")
+        raise UsageError(f"model spec must be module:Class, got {spec!r}")
     # Make the invoking directory importable so example modules outside the package
     # (e.g. examples.movie_page.model) resolve when running the CLI from a checkout.
     cwd = str(Path.cwd())
@@ -557,9 +587,9 @@ def _load_model(spec: str) -> type[BaseModel]:
     module = importlib.import_module(module_name)
     obj = getattr(module, attr, None)
     if obj is None:
-        raise ValueError(f"{spec!r} has no attribute {attr!r}")
+        raise UsageError(f"{spec!r} has no attribute {attr!r}")
     if not isinstance(obj, type) or not issubclass(obj, BaseModel):
-        raise TypeError(f"{spec!r} is not a Pydantic BaseModel class")
+        raise UsageError(f"{spec!r} is not a Pydantic BaseModel class")
     return obj
 
 
@@ -665,7 +695,9 @@ def _plain(value: Any) -> Any:
         return [_plain(item) for item in value]
     if isinstance(value, type):
         return f"{value.__module__}:{value.__name__}"
-    return value
+    # Canonical number form (whole-valued floats without a trailing `.0`) so the
+    # echoed `values` block matches the TypeScript CLI byte-for-byte; see errors.py.
+    return canonical_number(value)
 
 
 if __name__ == "__main__":

{softschema-0.2.1 → softschema-0.2.2}/packages/python/src/softschema/errors.py

@@ -18,6 +18,11 @@ Record shape (every structural validation error):
         "message": "<synthesized, engine-neutral>",
     }
 
+Numeric values in a record (and in the rendered message) use a canonical form:
+a whole-valued float renders without a trailing fraction (``2.0`` -> ``2``), the
+JSON-natural form the TypeScript implementation emits natively. See
+``canonical_number``.
+
 softschema-level artifact errors (missing envelope, malformed metadata, ...)
 use the separate ``{"kind": ..., "message": ...}`` shape produced by
 ``softschema.validate._error`` and are not routed through here.
@@ -30,6 +35,43 @@ from typing import Any
 SCHEMA_VIOLATION_KIND = "schema_violation"
 
 
+def canonical_number(value: Any) -> Any:
+    """Render a whole-valued float in its canonical (integer) form.
+
+    JSON does not distinguish ``2`` from ``2.0``; the canonical softschema form
+    drops a redundant trailing fraction so numeric values render byte-identically
+    across the Python and TypeScript implementations (a YAML ``2.0`` token parses
+    as the integer ``2`` in JS, which has no int/float distinction to lose).
+
+    A whole-valued float below ``1e21`` is returned as ``int`` — that is exactly the
+    range where JavaScript serializes a whole-valued ``number`` in plain integer form
+    (``JSON.stringify``/``String``), so the Python ``int`` repr matches it. At or beyond
+    ``1e21`` JavaScript switches to exponential notation, which Python's float repr also
+    uses, so those floats are left unchanged. Ints, bools, and non-whole floats are
+    returned unchanged.
+
+    Byte-parity is guaranteed within the IEEE-754 safe-integer range (``abs < 2**53``).
+    A larger *non-round* integer-valued magnitude cannot render identically on a
+    double-only runtime and an arbitrary-precision one (Python's exact ``int`` vs JS's
+    shortest round-trip), and is out of scope — see the golden corpus README, "Number
+    formatting", edge (b).
+    """
+    if isinstance(value, float) and value.is_integer() and abs(value) < 1e21:
+        return int(value)
+    return value
+
+
+def _canonical(value: Any) -> Any:
+    """Apply :func:`canonical_number` recursively through lists and dicts."""
+    if isinstance(value, list):
+        return [_canonical(v) for v in value]
+    if isinstance(value, tuple):
+        return tuple(_canonical(v) for v in value)
+    if isinstance(value, dict):
+        return {k: _canonical(v) for k, v in value.items()}
+    return canonical_number(value)
+
+
 def _fmt(value: Any) -> str:
     """Render a value compactly and deterministically for messages."""
     return repr(value)
@@ -50,8 +92,12 @@ def render_structural_message(
 
     The wording here is the cross-language contract: both the Python and the
     TypeScript implementations must produce byte-identical strings, so this
-    template table is the single source of truth.
+    template table is the single source of truth. Numeric values are rendered in
+    their canonical form (whole-valued floats without a trailing fraction) so the
+    string matches the TS renderer, which has no float/int distinction.
     """
+    value = _canonical(value)
+    validator_value = _canonical(validator_value)
     if validator == "enum":
         return f"value {_fmt(value)} is not one of [{_fmt_list(validator_value)}]"
     if validator == "type":
@@ -92,6 +138,10 @@ def structural_error_record(
     value: Any,
 ) -> dict[str, Any]:
     """Build one engine-neutral structural error record."""
+    # Store numbers in canonical form so the echoed `value`/`validator_value`
+    # fields match the rendered message and the TS records byte-for-byte.
+    validator_value = _canonical(validator_value)
+    value = _canonical(value)
     return {
         "kind": SCHEMA_VIOLATION_KIND,
         "path": path,

{softschema-0.2.1 → softschema-0.2.2}/packages/python/src/softschema/models.py

@@ -117,4 +117,4 @@ def parse_schema_metadata(raw: Any) -> SchemaMetadata | None:
     if isinstance(raw, dict):
         return SchemaMetadata.model_validate(raw)
     msg = f"softschema metadata must be a string or mapping, got {type(raw).__name__}"
-    raise TypeError(msg)
+    raise ValueError(msg)

{softschema-0.2.1 → softschema-0.2.2}/packages/python/src/softschema/validate.py

@@ -407,7 +407,7 @@ def _metadata_from_frontmatter(
 ) -> SchemaMetadata | ArtifactValidationResult | None:
     try:
         metadata = parse_schema_metadata(frontmatter.get("softschema"))
-    except (TypeError, ValidationError) as exc:
+    except (ValueError, ValidationError) as exc:
         return _artifact_failure(
             doc_path,
             contract,

{softschema-0.2.1 → softschema-0.2.2}/packages/python/tests/test_cli.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import argparse
 import json
 from pathlib import Path
 from textwrap import dedent
@@ -510,3 +511,41 @@ def test_inspect_malformed_softschema_block_exits_two(
     err = capsys.readouterr().err
     assert "softschema inspect:" in err
     assert "Traceback" not in err
+
+
+def test_run_cmd_surfaces_internal_bugs() -> None:
+    """TypeError/KeyError signal internal bugs and must surface, not be masked as exit 2."""
+
+    def raise_type(_args: object) -> int:
+        raise TypeError("internal bug")
+
+    def raise_key(_args: object) -> int:
+        raise KeyError("missing")
+
+    with pytest.raises(TypeError):
+        cli._run_cmd("validate", raise_type, argparse.Namespace())
+    with pytest.raises(KeyError):
+        cli._run_cmd("validate", raise_key, argparse.Namespace())
+
+
+def test_run_cmd_reports_usage_error_as_exit_2(capsys: pytest.CaptureFixture[str]) -> None:
+    """A UsageError (and any ValueError) is a user mistake: clean one-liner, exit 2."""
+
+    def raise_usage(_args: object) -> int:
+        raise cli.UsageError("bad flag")
+
+    exit_code = cli._run_cmd("validate", raise_usage, argparse.Namespace())
+
+    assert exit_code == 2
+    assert "softschema validate: bad flag" in capsys.readouterr().err
+
+
+def test_prime_prints_skill_and_docs_index(capsys: pytest.CaptureFixture[str]) -> None:
+    """`prime` restores full agent context: skill operating rules + the bundled docs index."""
+    exit_code = softschema_main(["prime"])
+
+    assert exit_code == 0
+    out = capsys.readouterr().out
+    assert "softschema" in out  # skill content
+    assert "Available softschema docs:" in out  # docs index
+    assert "Run `softschema docs <topic>`" in out

softschema-0.2.2/packages/python/tests/test_errors.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from softschema import compile_model, validate_structural
+from softschema.errors import canonical_number, render_structural_message, structural_error_record
+
+
+class Sample(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    count: int = Field(ge=0, le=10)
+    label: str
+
+
+def test_render_structural_message_is_engine_neutral() -> None:
+    # The wording is the cross-language contract; pin a few keywords exactly.
+    assert render_structural_message("minimum", 0, -1) == "value -1 is less than the minimum of 0"
+    assert (
+        render_structural_message("enum", ["G", "PG"], "X") == "value 'X' is not one of ['G', 'PG']"
+    )
+    assert render_structural_message("type", "integer", "x") == "value 'x' is not of type 'integer'"
+
+
+def test_canonical_number_drops_trailing_fraction() -> None:
+    # ss-wbnm: a whole-valued float renders in canonical (int) form so it is
+    # byte-identical to the TypeScript impl, which has no float/int distinction.
+    assert canonical_number(2.0) == 2
+    assert isinstance(canonical_number(2.0), int)
+    assert canonical_number(-2.0) == -2
+    assert canonical_number(0.0) == 0
+    # Whole floats below 1e21 become canonical ints (the range where JS renders a
+    # whole-valued number as a plain integer via String()/JSON.stringify()).
+    assert canonical_number(1e15) == 1000000000000000
+    assert isinstance(canonical_number(1e15), int)
+    assert canonical_number(1e16) == 10000000000000000  # the reviewer's divergence case
+    assert isinstance(canonical_number(1e16), int)
+    assert canonical_number(1e20) == 100000000000000000000
+    # Non-whole floats keep their fraction; ints and bools are untouched.
+    assert canonical_number(0.3) == 0.3
+    assert canonical_number(7) == 7
+    assert canonical_number(True) is True
+    # Floats at/beyond 1e21 keep exponential repr (matches the TS formatter and JS String).
+    assert canonical_number(1e21) == 1e21
+    assert isinstance(canonical_number(1e21), float)
+    assert repr(canonical_number(1e21)) == "1e+21"
+
+
+def test_whole_float_renders_canonically_in_messages_and_records() -> None:
+    # The bound 2.0 and the offending 1.0 both render without a trailing `.0`.
+    assert render_structural_message("minimum", 2.0, 1.0) == "value 1 is less than the minimum of 2"
+    assert render_structural_message("enum", [1.0, 2.0], 3.0) == "value 3 is not one of [1, 2]"
+    record = structural_error_record(
+        path=["ratio"], validator="minimum", validator_value=2.0, value=1.0
+    )
+    # Stored fields are canonicalized too, so they match the message and the TS record.
+    assert record["value"] == 1
+    assert record["validator_value"] == 2
+    assert record["message"] == "value 1 is less than the minimum of 2"
+
+
+def test_structural_error_record_shape() -> None:
+    record = structural_error_record(
+        path=["count"], validator="maximum", validator_value=10, value=11
+    )
+    assert record == {
+        "kind": "schema_violation",
+        "path": ["count"],
+        "validator": "maximum",
+        "validator_value": 10,
+        "value": 11,
+        "message": "value 11 is greater than the maximum of 10",
+    }
+
+
+def test_validate_structural_emits_neutral_records(tmp_path: Path) -> None:
+    schema_path = tmp_path / "sample.schema.yaml"
+    compile_model(Sample, schema_path, contract_id="example:Sample/v1")
+
+    result = validate_structural({"count": 99, "label": "ok"}, schema_path)
+
+    assert not result.ok
+    error = result.errors[0]
+    assert error["kind"] == "schema_violation"
+    assert error["validator"] == "maximum"
+    assert "greater than the maximum" in error["message"]

{softschema-0.2.1 → softschema-0.2.2}/pyproject.toml

@@ -46,12 +46,15 @@ dev = [
 ]
 
 [tool.uv]
-# Trusted-package exception to the 14-day supply-chain cool-off. strif is a reviewed,
-# zero-dependency, first-party package, so the latest release is allowed. This records
-# the decision and applies for local resolution; CI sets a global UV_EXCLUDE_NEWER that
-# overrides config, so ci.yml ALSO passes `--exclude-newer-package strif=...` with the
-# same date. Bump the date in both places to adopt a newer strif.
-exclude-newer-package = { strif = "2026-06-03" }
+# Local resolution honors the supply-chain cool-off: cap dependencies at a reviewed
+# cutoff (bump deliberately). strif is a reviewed, zero-dependency, first-party package,
+# so it gets a per-package exception to that cutoff. Both values need a full RFC3339
+# timestamp -- a date-only string fails to parse and uv silently drops the setting. CI
+# sets a global UV_EXCLUDE_NEWER (14 days ago) that overrides `exclude-newer` here, and
+# because that env override also replaces the per-package map, ci.yml re-passes
+# `--exclude-newer-package strif=...` on the CLI. Bump the dates together.
+exclude-newer = "2026-06-02T00:00:00Z"
+exclude-newer-package = { strif = "2026-06-03T00:00:00Z" }
 
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning"]

{softschema-0.2.1 → softschema-0.2.2}/tests/golden/README.md

@@ -56,21 +56,27 @@ Otherwise no patterns are needed. Note in particular:
   streams with `2>&1` and asserts the stable `softschema <cmd>:` prefix plus exit code,
   eliding the engine-specific tail with `[..]`/`...`. Where the wording is identical
   (ambiguous envelope, missing implementation) it is asserted in full on stderr (`!`).
-- **Number formatting limitations.** The `pyRepr` formatter in both implementations
-  renders numbers to match Python's `repr()`, but two edge cases cannot be aligned:
-  - **(a) Whole-number floats below 1e16 render without `.0` on TS** (`ss-wbnm`). Python
-    preserves the int/float distinction from the YAML source token
-    (`repr(2.0) == "2.0"`); JS collapses `2.0` to `2` at parse, so a whole-number float
-    renders as `2` on the TypeScript side. Keep golden values that appear in a `value`,
-    `validator_value`, or message as integers or **non-whole** floats (`0.3`, `8.6`) so
-    the corpus stays byte-identical on both engines. Non-error values elsewhere are
-    unaffected.
-  - **(b) Integer literals >= 2^53 diverge.** Python has arbitrary-precision integers
-    (`repr(10000000000000000)` is `10000000000000000`), while JS collapses large integer
-    literals into IEEE 754 doubles, losing precision. A YAML integer literal like
-    `10000000000000000` stays `int` in Python but becomes a float in JS (same numeric
-    value, different repr). Avoid integer-valued literals >= 2^53 in error-exercising
-    fixtures.
+- **Number formatting.** Both implementations render numbers to match Python's `repr()`.
+  Numbers follow one canonical rule; one genuine edge case remains:
+  - **(a) Whole-valued numbers render in canonical form** (`ss-wbnm`, resolved). A
+    whole-valued number below 1e21 renders without a trailing fraction and without an
+    exponent (`2.0` -> `2`, `1.0e16` -> `10000000000000000`) — the form JS emits natively
+    (it has no int/float distinction, and `String()`/`JSON.stringify()` print a
+    whole-valued number in plain integer notation below 1e21). The Python side converts
+    its whole-valued floats below 1e21 to int to match (`canonical_number` in `errors.py`,
+    applied to error records and the `values` echo), so such a number is byte-identical in
+    a `value`, `validator_value`, or message on both engines. Non-whole floats (`0.3`,
+    `8.6`) keep their fraction. The `error-normalization` scenario exercises the small case
+    (`ratio: 1.0` vs `minimum: 2.0`), and `number-large-whole` the large case (`9.0e15` vs
+    `minimum: 1.0e16`, both rendering full integers).
+  - **(b) Non-round integer-valued magnitudes >= 2^53 diverge.** Byte-parity is guaranteed
+    only within the IEEE-754 safe-integer range. Above 2^53 not every integer is
+    representable, so a *non-round* value differs between Python's exact `int`
+    (`9.999999999999998e16` -> `99999999999999984`) and JS's shortest round-trip
+    (`99999999999999980`); likewise a YAML integer literal like `9007199254740993` keeps
+    full precision in Python but loses it as a JS double. Round magnitudes (powers/simple
+    multiples of ten) below 1e21 still match — see (a) — but avoid non-round integer-valued
+    literals >= 2^53 in error-exercising fixtures.
 
 ## Updating
 

softschema-0.2.1/packages/python/README.md

@@ -1,31 +0,0 @@
-# softschema Python Package
-
-The Python package provides:
-
-- `Contract` and `Contracts`
-- `validate_artifact` for Markdown/YAML artifact validation
-- `validate_structural` for JSON Schema validation
-- `validate_semantic` for Pydantic validation
-- `compile_model` for Pydantic-to-JSON-Schema compilation
-- the `softschema` CLI, including bundled docs through `softschema docs` and
-  `softschema skill`
-
-The package source lives under `packages/python/src/softschema`, but the root
-`pyproject.toml` owns builds and dependency management.
-
-Use the root [softschema Guide](../../docs/softschema-guide.md) for the concept and
-[softschema Spec](../../docs/softschema-spec.md) for the artifact format.
-
-Installed environments can print the same reference material:
-
-```bash
-softschema docs --list
-softschema docs --list --json
-softschema docs guide
-softschema docs example-artifact
-softschema skill --brief
-```
-
-<!-- This document follows common-doc-guidelines.md.
-See github.com/jlevy/practical-prose and review guidelines before editing.
--->

softschema-0.2.1/packages/python/tests/test_errors.py

@@ -1,51 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-from pydantic import BaseModel, ConfigDict, Field
-
-from softschema import compile_model, validate_structural
-from softschema.errors import render_structural_message, structural_error_record
-
-
-class Sample(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    count: int = Field(ge=0, le=10)
-    label: str
-
-
-def test_render_structural_message_is_engine_neutral() -> None:
-    # The wording is the cross-language contract; pin a few keywords exactly.
-    assert render_structural_message("minimum", 0, -1) == "value -1 is less than the minimum of 0"
-    assert (
-        render_structural_message("enum", ["G", "PG"], "X") == "value 'X' is not one of ['G', 'PG']"
-    )
-    assert render_structural_message("type", "integer", "x") == "value 'x' is not of type 'integer'"
-
-
-def test_structural_error_record_shape() -> None:
-    record = structural_error_record(
-        path=["count"], validator="maximum", validator_value=10, value=11
-    )
-    assert record == {
-        "kind": "schema_violation",
-        "path": ["count"],
-        "validator": "maximum",
-        "validator_value": 10,
-        "value": 11,
-        "message": "value 11 is greater than the maximum of 10",
-    }
-
-
-def test_validate_structural_emits_neutral_records(tmp_path: Path) -> None:
-    schema_path = tmp_path / "sample.schema.yaml"
-    compile_model(Sample, schema_path, contract_id="example:Sample/v1")
-
-    result = validate_structural({"count": 99, "label": "ok"}, schema_path)
-
-    assert not result.ok
-    error = result.errors[0]
-    assert error["kind"] == "schema_violation"
-    assert error["validator"] == "maximum"
-    assert "greater than the maximum" in error["message"]