server-decorator-entity 2.0.19__tar.gz

server_decorator_entity-2.0.19/.gitignore

@@ -0,0 +1,57 @@
+.npmrc
+dist
+node_modules
+.astro
+
+
+# GitHub Actions
+.env
+*.log
+
+# Package managers
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+package-lock.json  # Use pnpm-lock.yaml instead
+yarn.lock         # Use pnpm-lock.yaml instead
+# uv is dev-only; do not commit the lockfile
+python/uv.lock
+
+# iCloud-style duplicate files (D-D)
+* 2
+* 2.*
+* 3
+* 3.*
+
+# Python (added during polyglot migration)
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+# ps-release-workflow (gitignored state)
+.claude/state/
+.claude/worktrees/
+
+# Rendered design HTML — local view artifacts only (global rule)
+docs/superpowers/**/*.html
+research/**/*.html
+
+# Nim (F-006): `nim c` drops binaries beside sources; `nim r`/`nimble test` do not, but be safe.
+nimcache/
+nim/tests/t_*
+!nim/tests/t_*.nim
+nim/examples/emit_*
+!nim/examples/emit_*.nim
+nim/examples/user
+nim/nimble.lock
+# ^ the package has zero dependencies (plan constraint) — this lockfile must never be committed.
+
+# graft's local graph cache — regenerable, not committed (run `graft build`).
+graft/
+# Rust build artifacts
+target/
+rust/target/
+

server_decorator_entity-2.0.19/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: server-decorator-entity
+Version: 2.0.19
+Summary: Declarative entity decorators emitting the language-neutral EntitySpec IR. Polyglot sibling of @montionugera/entity-spec.
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.21; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# server-decorator-entity (Python)
+
+Declarative entity decorators (`@restful`, `@action`, field markers) emitting the language-neutral EntitySpec IR — polyglot sibling of `@montionugera/entity-spec`, sharing the wire-format contracts in [`../../../contracts`](../../../contracts).
+
+## Install
+
+```bash
+pip install server-decorator-entity
+```
+
+## Usage
+
+```python
+from typing import Annotated
+from server_decorator_entity import restful, Id, Email, entity_spec
+
+@restful(path="users")
+class User:
+    id: Annotated[str, Id()]
+    email: Annotated[str, Email()]
+
+spec = entity_spec(User)  # -> EntitySpec IR, byte-identical to the Node emitter
+```
+
+`entity_spec_canonical(User)` returns the IR as a canonical JSON string (codepoint-sorted keys,
+`None`-dropping) — the exact bytes both languages' generators and the cross-language parity
+check compare against.

server_decorator_entity-2.0.19/README.md

@@ -0,0 +1,27 @@
+# server-decorator-entity (Python)
+
+Declarative entity decorators (`@restful`, `@action`, field markers) emitting the language-neutral EntitySpec IR — polyglot sibling of `@montionugera/entity-spec`, sharing the wire-format contracts in [`../../../contracts`](../../../contracts).
+
+## Install
+
+```bash
+pip install server-decorator-entity
+```
+
+## Usage
+
+```python
+from typing import Annotated
+from server_decorator_entity import restful, Id, Email, entity_spec
+
+@restful(path="users")
+class User:
+    id: Annotated[str, Id()]
+    email: Annotated[str, Email()]
+
+spec = entity_spec(User)  # -> EntitySpec IR, byte-identical to the Node emitter
+```
+
+`entity_spec_canonical(User)` returns the IR as a canonical JSON string (codepoint-sorted keys,
+`None`-dropping) — the exact bytes both languages' generators and the cross-language parity
+check compare against.

server_decorator_entity-2.0.19/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "server-decorator-entity"
+version = "2.0.19"
+description = "Declarative entity decorators emitting the language-neutral EntitySpec IR. Polyglot sibling of @montionugera/entity-spec."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.5", "mypy>=1.10", "jsonschema>=4.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/server_decorator_entity"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "ASYNC", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/server_decorator_entity"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

server_decorator_entity-2.0.19/scripts/check.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# python/packages/entity/scripts/check.sh — lint + type-check + unit tests.
+# Assumes `uv` is installed; `pip install uv` if not.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if command -v uv >/dev/null 2>&1; then
+  uv sync --extra dev >/dev/null
+  RUN="uv run"
+else
+  echo "warning: uv not found; falling back to plain python+pytest. Install uv for the full dev experience." >&2
+  RUN=""
+fi
+
+$RUN ruff check src tests
+$RUN ruff format --check src tests
+$RUN mypy src
+
+# Coverage gate (unit tests only; integration-marked tests are excluded).
+# COV_MIN is a ratchet: achieved line+branch coverage (--cov-branch) rounded down,
+# measured on Python 3.10, 3.12 and 3.14. Raise it, never lower it.
+COV_MIN=${COV_MIN:-95}
+export COVERAGE_FILE="${COVERAGE_FILE:-${TMPDIR:-/tmp}/server-decorator-entity.coverage}"
+$RUN pytest -q tests/unit -m "not integration" \
+  --cov=src --cov-branch --cov-report=term-missing:skip-covered --cov-fail-under="$COV_MIN"

server_decorator_entity-2.0.19/scripts/emit_fixture.py

@@ -0,0 +1,6 @@
+import sys
+
+from server_decorator_entity import entity_spec_canonical
+from server_decorator_entity.testing.user_fixture import UserFixture
+
+sys.stdout.write(entity_spec_canonical(UserFixture))

server_decorator_entity-2.0.19/src/server_decorator_entity/__init__.py

@@ -0,0 +1,43 @@
+from server_decorator_entity.action import action
+from server_decorator_entity.canonical import canonical_json
+from server_decorator_entity.markers import (
+    Bool,
+    Datetime,
+    Email,
+    EnumOf,
+    FieldMarker,
+    Float,
+    Id,
+    Int,
+    ListOf,
+    Obj,
+    Ref,
+    Str,
+    Uri,
+    Uuid,
+)
+from server_decorator_entity.restful import entity_spec, entity_spec_canonical, restful
+from server_decorator_entity.validate import RESERVED_WIRE_NAMES
+
+__all__ = [
+    "RESERVED_WIRE_NAMES",
+    "Bool",
+    "Datetime",
+    "Email",
+    "EnumOf",
+    "FieldMarker",
+    "Float",
+    "Id",
+    "Int",
+    "ListOf",
+    "Obj",
+    "Ref",
+    "Str",
+    "Uri",
+    "Uuid",
+    "action",
+    "canonical_json",
+    "entity_spec",
+    "entity_spec_canonical",
+    "restful",
+]

server_decorator_entity-2.0.19/src/server_decorator_entity/action.py

@@ -0,0 +1,45 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from server_decorator_entity.markers import FieldMarker
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_ATTR = "__entity_action__"
+
+
+def action(
+    name: str,
+    *,
+    description: str | None = None,
+    state_field: str | None = None,
+    from_state: str | None = None,
+    to_state: str | None = None,
+    input: list[tuple[str, FieldMarker]] | None = None,
+    transactional: bool = True,
+) -> Callable[[F], F]:
+    def mark(fn: F) -> F:
+        if isinstance(fn, (staticmethod, classmethod)):
+            kind = "static" if isinstance(fn, staticmethod) else "class"
+            underlying = fn.__func__
+            raise TypeError(
+                f"@action must decorate an instance method (got {kind} method "
+                f"'{underlying.__name__}')"
+            )
+        spec: dict[str, Any] = {"name": name}
+        if description is not None:
+            spec["description"] = description
+        if from_state is not None or to_state is not None:
+            spec["stateField"] = state_field or "status"
+            if from_state is not None:
+                spec["from"] = from_state
+            if to_state is not None:
+                spec["to"] = to_state
+        if input:
+            spec["input"] = [m.to_ir(n) for n, m in input]
+        if not transactional:
+            spec["transactional"] = False
+        setattr(fn, _ATTR, spec)
+        return fn
+
+    return mark

server_decorator_entity-2.0.19/src/server_decorator_entity/canonical.py

@@ -0,0 +1,8 @@
+"""Canonical EntitySpec JSON — contracts/rules/entity-spec-canonical.md."""
+
+import json
+from typing import Any
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)

server_decorator_entity-2.0.19/src/server_decorator_entity/markers.py

@@ -0,0 +1,119 @@
+"""Field markers used inside Annotated[...] on @restful classes."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from server_decorator_entity.validate import (
+    assert_enum_nonempty,
+    assert_format_pattern_exclusive,
+    assert_integer_or_none,
+    assert_portable_pattern,
+    assert_wire_name_not_reserved,
+)
+
+
+@dataclass(frozen=True)
+class FieldMarker:
+    type: str
+    description: str | None = None
+    role: str | None = None
+    format: str | None = None
+    enum: tuple[str, ...] | None = None
+    min: int | None = None
+    max: int | None = None
+    pattern: str | None = None
+    optional: bool = False
+    nullable: bool = False
+    readonly: bool = False
+    writeonly: bool = False
+    filterable: bool = False
+    item: "FieldMarker | None" = None
+    ref: str | None = None
+    fields: tuple[tuple[str, "FieldMarker"], ...] | None = None  # (name, marker) pairs for obj
+
+    def to_ir(self, name: str) -> dict[str, Any]:
+        label = f'field "{name}"'
+        assert_wire_name_not_reserved(name, label)
+        assert_format_pattern_exclusive(self.format, self.pattern, label)
+        assert_portable_pattern(self.pattern, label)
+        assert_enum_nonempty(self.enum, label)
+        assert_integer_or_none(self.min, f"{label}.min")
+        assert_integer_or_none(self.max, f"{label}.max")
+
+        ir: dict[str, Any] = {"name": name, "type": self.type}
+        if self.role:
+            ir["role"] = self.role
+        if self.format:
+            ir["format"] = self.format
+        if self.enum:
+            ir["enum"] = list(self.enum)
+        if self.min is not None:
+            ir["min"] = self.min
+        if self.max is not None:
+            ir["max"] = self.max
+        if self.pattern is not None:
+            ir["pattern"] = self.pattern
+        if self.description is not None:
+            ir["description"] = self.description
+        for flag in ("optional", "nullable", "readonly", "writeonly", "filterable"):
+            if getattr(self, flag):
+                ir[flag] = True
+        if self.item:
+            ir["item"] = self.item.to_ir(name)
+        if self.ref is not None:
+            ir["ref"] = self.ref
+        if self.fields is not None:
+            ir["fields"] = [m.to_ir(n) for n, m in self.fields]
+        return ir
+
+
+def Id() -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", role="id", readonly=True)
+
+
+def Str(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", **kw)
+
+
+def Email(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", format="email", **kw)
+
+
+def Uuid(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", format="uuid", **kw)
+
+
+def Uri(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", format="uri", **kw)
+
+
+def Int(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="int", **kw)
+
+
+def Float(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="float", **kw)
+
+
+def Bool(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="bool", **kw)
+
+
+def Datetime(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="datetime", **kw)
+
+
+def EnumOf(*values: str, **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="enum", enum=values, **kw)
+
+
+def Ref(entity: str, **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="ref", ref=entity, **kw)
+
+
+def ListOf(item: FieldMarker, **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="list", item=item, **kw)
+
+
+def Obj(fields: list[tuple[str, FieldMarker]], **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="obj", fields=tuple(fields), **kw)

server_decorator_entity-2.0.19/src/server_decorator_entity/restful.py

@@ -0,0 +1,128 @@
+import copy
+import inspect
+import re
+import typing
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from server_decorator_entity.action import _ATTR
+from server_decorator_entity.canonical import canonical_json
+from server_decorator_entity.markers import FieldMarker
+from server_decorator_entity.validate import assert_valid_security
+
+C = TypeVar("C", bound=type)
+
+_SPEC_ATTR = "__entity_spec__"
+_DEFAULT_OPS = ["list", "get", "create", "update", "delete"]
+_WIRE_NAME_RE = re.compile(r"^[a-z][A-Za-z0-9]*$")
+
+
+def _camel(name: str) -> str:
+    head, *rest = name.split("_")
+    return head + "".join(s.capitalize() for s in rest)
+
+
+def restful(
+    *,
+    path: str,
+    transports: list[str] | None = None,
+    ops: list[str] | None = None,
+    pagination: str = "offset",
+    description: str | None = None,
+    tags: list[str] | None = None,
+    security: dict[str, Any] | None = None,
+) -> Callable[[C], C]:
+    def wrap(cls: C) -> C:
+        # Own-class declarations only (N2: no MRO walk) — a @restful subclass must not
+        # re-collect its base's fields. get_type_hints() still resolves the (possibly
+        # string/forward-ref) annotation values; own_annotations only supplies which
+        # names — and their declaration order — belong to this class.
+        own_annotations: dict[str, Any] = inspect.get_annotations(cls)
+        hints = typing.get_type_hints(cls, include_extras=True)
+        fields: list[dict[str, Any]] = []
+        seen_wire_names: set[str] = set()
+        for attr_name in own_annotations:
+            hint = hints.get(attr_name)
+            marker = next(
+                (m for m in getattr(hint, "__metadata__", ()) if isinstance(m, FieldMarker)), None
+            )
+            if marker is None:
+                continue
+            wire_name = _camel(attr_name)
+            if not _WIRE_NAME_RE.match(wire_name):
+                raise ValueError(
+                    f"{cls.__name__}.{attr_name}: computed wire name {wire_name!r} does not "
+                    f"match ^[a-z][A-Za-z0-9]*$"
+                )
+            if wire_name in seen_wire_names:
+                raise ValueError(
+                    f"{cls.__name__}.{attr_name}: wire name {wire_name!r} collides with "
+                    f"another field"
+                )
+            seen_wire_names.add(wire_name)
+            fields.append(marker.to_ir(wire_name))
+
+        # `or` is truthiness-coalescing, not None-coalescing — an explicit `transports=[]`/
+        # `ops=[]` must fail fast here (not be silently replaced by the default), matching TS's
+        # `??`-then-validate approach (C4). Only an omitted (`None`) argument gets the default.
+        resolved_transports = ["rest"] if transports is None else transports
+        if not resolved_transports:
+            raise ValueError(f"{cls.__name__}: transports must not be empty")
+        resolved_ops = list(_DEFAULT_OPS) if ops is None else ops
+        if not resolved_ops:
+            raise ValueError(f"{cls.__name__}: ops must not be empty")
+
+        actions: list[dict[str, Any]] = []
+        for member in vars(cls).values():
+            if isinstance(member, (staticmethod, classmethod)):
+                underlying = member.__func__
+                if hasattr(underlying, _ATTR):
+                    kind = "static" if isinstance(member, staticmethod) else "class"
+                    raise TypeError(
+                        f"@action must decorate an instance method (got {kind} method "
+                        f"'{underlying.__name__}')"
+                    )
+                continue
+            if callable(member) and hasattr(member, _ATTR):
+                actions.append(getattr(member, _ATTR))
+        spec: dict[str, Any] = {
+            "specVersion": "1.2.0",
+            "entity": cls.__name__,
+            "path": path,
+            "transports": resolved_transports,
+            "ops": resolved_ops,
+            "pagination": pagination,
+            "fields": fields,
+        }
+        if actions:
+            spec["actions"] = actions
+        assert_valid_security(security, resolved_ops, [a["name"] for a in actions], cls.__name__)
+        # Keep absent keys absent so canonical JSON is byte-unchanged for 1.1-era declarations.
+        if description is not None:
+            spec["description"] = description
+        if tags is not None:
+            spec["tags"] = tags
+        if security is not None:
+            spec["security"] = security
+        setattr(cls, _SPEC_ATTR, spec)
+        return cls
+
+    return wrap
+
+
+def _stored_spec(cls: type) -> dict[str, Any]:
+    # Own-attribute only (cls.__dict__, never getattr's MRO walk) — an undecorated
+    # subclass of a @restful base must not silently inherit the base's spec.
+    spec = cls.__dict__.get(_SPEC_ATTR)
+    if spec is None:
+        raise TypeError(f"{cls.__name__} is not decorated with @restful")
+    return spec  # type: ignore[no-any-return]
+
+
+def entity_spec(cls: type) -> dict[str, Any]:
+    # Deep copy so callers can't poison the memoized spec (parity with Node's deep-freeze).
+    return copy.deepcopy(_stored_spec(cls))
+
+
+def entity_spec_canonical(cls: type) -> str:
+    return canonical_json(_stored_spec(cls))

server_decorator_entity-2.0.19/src/server_decorator_entity/testing/user_fixture.py

@@ -0,0 +1,63 @@
+from typing import Annotated, Any
+
+from server_decorator_entity import (
+    Bool,
+    Datetime,
+    Email,
+    EnumOf,
+    Float,
+    Id,
+    Int,
+    ListOf,
+    Obj,
+    Str,
+    action,
+    restful,
+)
+
+
+@restful(
+    path="users",
+    transports=["rest", "rpc", "sse", "ws"],
+    description="A registered user account",
+    tags=["identity"],
+    security={
+        "schemes": [
+            {"name": "bearerAuth", "type": "http", "scheme": "bearer", "bearerFormat": "JWT"}
+        ],
+        "ops": {"create": ["user:write"], "update": ["user:write"], "delete": ["user:admin"]},
+        "actions": {"activate": ["user:admin"]},
+    },
+)
+class User:
+    id: Annotated[str, Id()]
+    email: Annotated[str, Email(filterable=True, description="Primary contact address")]
+    name: Annotated[str, Str(min=2, max=80)]
+    status: Annotated[str, EnumOf("inactive", "active", "banned", filterable=True)]
+    login_count: Annotated[int, Int(min=0, readonly=True)]
+    tags: Annotated[list[str], ListOf(Str())]
+    profile: Annotated[
+        dict[str, Any] | None, Obj([("bio", Str(max=500, optional=True))], optional=True)
+    ]
+    birthday: Annotated[str | None, Datetime(optional=True, nullable=True)]
+    # I-d (P1 gate-review): writable, non-readonly fields to exercise DTO derivation rules the
+    # original 16-case contract never touched (JSON-type strictness on float/bool, writeonly
+    # exclusion from read).
+    score: Annotated[float | None, Float(min=0, optional=True)]
+    active: Annotated[bool | None, Bool(optional=True)]
+    secret_note: Annotated[str | None, Str(writeonly=True, max=100, optional=True)]
+
+    @action(
+        "activate",
+        description="Move a dormant account back to active",
+        from_state="inactive",
+        to_state="active",
+        input=[("reason", Str(max=200, optional=True))],
+    )
+    def activate(self) -> None: ...
+
+    @action("ping")
+    def ping(self) -> None: ...
+
+
+UserFixture = User

server_decorator_entity-2.0.19/src/server_decorator_entity/validate.py

@@ -0,0 +1,155 @@
+"""Decoration-time IR validation shared across field markers and @restful.
+
+Mirrors node/packages/entity/src/validate.ts — see contracts/rules/entity-spec-validation.md
+for the shared invariants (reserved wire names, format+pattern exclusivity, integer min/max,
+non-empty enum/ops/transports) both language packages enforce identically.
+"""
+
+from typing import Any
+
+# Public pydantic.BaseModel attribute names (pydantic v2). A wire name colliding with one of
+# these makes gen-pydantic's create_model() raise "shadows an attribute in parent BaseModel" —
+# reject at decoration time in BOTH languages instead of letting it crash gen-pydantic's model
+# build. See contracts/rules/entity-spec-validation.md "Reserved wire names".
+RESERVED_WIRE_NAMES: frozenset[str] = frozenset(
+    {
+        "construct",
+        "copy",
+        "dict",
+        "from_orm",
+        "json",
+        "model_computed_fields",
+        "model_config",
+        "model_construct",
+        "model_copy",
+        "model_dump",
+        "model_dump_json",
+        "model_extra",
+        "model_fields",
+        "model_fields_set",
+        "model_json_schema",
+        "model_parametrized_name",
+        "model_post_init",
+        "model_rebuild",
+        "model_validate",
+        "model_validate_json",
+        "model_validate_strings",
+        "parse_file",
+        "parse_obj",
+        "parse_raw",
+        "schema",
+        "schema_json",
+        "update_forward_refs",
+        "validate",
+    }
+)
+
+
+def assert_integer_or_none(value: Any, label: str) -> None:
+    if value is None:
+        return
+    # bool is a subclass of int in Python — isinstance(True, int) is True — so it must be
+    # excluded explicitly, not just checked for isinstance(value, int).
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"{label}: min/max must be integers (got {value!r})")
+
+
+def assert_wire_name_not_reserved(name: str, label: str) -> None:
+    if name in RESERVED_WIRE_NAMES:
+        raise ValueError(
+            f"{label}: wire name {name!r} is reserved (shadows a pydantic BaseModel attribute)"
+        )
+
+
+def assert_format_pattern_exclusive(fmt: Any, pattern: Any, label: str) -> None:
+    if fmt is not None and pattern is not None:
+        raise ValueError(f"{label}: format and pattern are mutually exclusive")
+
+
+def assert_enum_nonempty(enum: Any, label: str) -> None:
+    if enum is not None and len(enum) == 0:
+        raise ValueError(f"{label}: enum must have at least one value")
+
+
+_LOOKAROUND_MARKERS = ("(?=", "(?!", "(?<=", "(?<!")
+
+
+def _has_backreference(pattern: str) -> bool:
+    """A `\\` run of odd length immediately before a digit 1-9 means that digit is escaped — a
+    backreference (`\\1`). An even-length run means the backslashes are themselves escaped
+    (`\\\\1` is a literal backslash followed by the literal digit `1`), so it's NOT a
+    backreference. `\\0` is never a backreference (it's either a literal `0` or, in some engines,
+    a null escape — not a capture-group reference), so only digits 1-9 are scanned. This is a
+    conservative lexical scan, not a regex parser — see
+    contracts/rules/entity-spec-validation.md for what it does and does not catch.
+    """
+    for i, c in enumerate(pattern):
+        if c in "123456789":
+            backslashes = 0
+            j = i - 1
+            while j >= 0 and pattern[j] == "\\":
+                backslashes += 1
+                j -= 1
+            if backslashes % 2 == 1:
+                return True
+    return False
+
+
+def assert_portable_pattern(pattern: Any, label: str) -> None:
+    """pydantic v2's Rust-backed regex engine (used by gen-pydantic) does not support lookaround
+    or backreferences — both are valid Python `re` / JS RegExp syntax, so a pattern using either
+    builds fine in gen-zod but crashes gen-pydantic's entire model build. Reject non-portable
+    patterns at DECORATION time (before either generator ever sees the IR), in both languages —
+    see contracts/rules/entity-spec-validation.md.
+    """
+    if pattern is None:
+        return
+    for marker in _LOOKAROUND_MARKERS:
+        if marker in pattern:
+            raise ValueError(
+                f"{label}: pattern {pattern!r} is not RE2/rust-regex compatible (contains "
+                f"lookaround {marker!r}) — see contracts/rules/entity-spec-validation.md"
+            )
+    if _has_backreference(pattern):
+        raise ValueError(
+            f"{label}: pattern {pattern!r} is not RE2/rust-regex compatible (contains a "
+            f"backreference) — see contracts/rules/entity-spec-validation.md"
+        )
+
+
+__all__ = [
+    "RESERVED_WIRE_NAMES",
+    "assert_enum_nonempty",
+    "assert_format_pattern_exclusive",
+    "assert_integer_or_none",
+    "assert_portable_pattern",
+    "assert_wire_name_not_reserved",
+]
+
+
+def assert_valid_security(
+    security: dict[str, Any] | None,
+    ops: list[str],
+    action_names: list[str],
+    entity: str,
+) -> None:
+    """Mirror of Node's validateSecurity() in packages/entity/src/validate.ts."""
+    if security is None:
+        return
+    schemes = security.get("schemes", [])
+    if not schemes:
+        raise ValueError(f"{entity}: security.schemes must not be empty")
+    for s in schemes:
+        name = s.get("name")
+        if s.get("type") not in ("http", "apiKey"):
+            raise ValueError(f'{entity}: scheme "{name}": type must be "http" or "apiKey"')
+        if s["type"] == "http" and "scheme" not in s:
+            raise ValueError(f'{entity}: scheme "{name}": http requires "scheme"')
+        if s["type"] == "apiKey" and ("in" not in s or "paramName" not in s):
+            raise ValueError(f'{entity}: scheme "{name}": apiKey requires "in" and "paramName"')
+    for op in security.get("ops", {}):
+        if op not in ops:
+            raise ValueError(f"{entity}: security.ops.{op} is not declared in ops")
+    for action_name in security.get("actions", {}):
+        if action_name not in action_names:
+            raise ValueError(f"{entity}: security.actions.{action_name} is not a declared action")

server_decorator_entity-2.0.19/tests/unit/test_canonical.py

@@ -0,0 +1,10 @@
+from server_decorator_entity.canonical import canonical_json
+
+
+def test_sorts_keys_no_whitespace() -> None:
+    result = canonical_json({"b": 1, "a": {"d": [2, 1], "c": "x"}})
+    assert result == '{"a":{"c":"x","d":[2,1]},"b":1}'
+
+
+def test_non_ascii_not_escaped() -> None:
+    assert canonical_json({"a": "ราคา"}) == '{"a":"ราคา"}'

server_decorator_entity-2.0.19/tests/unit/test_entity_spec.py

@@ -0,0 +1,29 @@
+import json
+from pathlib import Path
+
+import jsonschema
+import pytest
+
+from server_decorator_entity import entity_spec, entity_spec_canonical
+from server_decorator_entity.testing.user_fixture import UserFixture
+
+# test_entity_spec.py -> unit -> tests -> entity -> packages -> python -> repo root
+CONTRACTS = Path(__file__).resolve().parents[5] / "contracts"
+
+
+def test_canonical_parity_with_contract_fixture() -> None:
+    expected = (CONTRACTS / "fixtures/entity-spec.valid-user.json").read_text().strip()
+    assert entity_spec_canonical(UserFixture) == expected
+
+
+def test_validates_against_schema() -> None:
+    schema = json.loads((CONTRACTS / "schemas/entity-spec.schema.json").read_text())
+    jsonschema.validate(entity_spec(UserFixture), schema)
+
+
+def test_undecorated_class_raises() -> None:
+    class Naked:
+        pass
+
+    with pytest.raises(TypeError, match="not decorated with @restful"):
+        entity_spec(Naked)

server_decorator_entity-2.0.19/tests/unit/test_entity_spec_hardening.py

@@ -0,0 +1,129 @@
+"""Reviewer-confirmed hardening for entity_spec/@restful/@action (Task 9 fix round).
+
+Findings:
+1. entity_spec() must not return the live memoized dict (mutation-proof copy).
+2. Undecorated subclass of a @restful base must not silently inherit the base's spec.
+3. Field collection must be own-class only (no MRO re-collection in subclasses).
+4. _camel()-computed wire names must be validated (format + collisions).
+5. @action on a staticmethod/classmethod must raise, in either decorator order.
+"""
+
+from typing import Annotated
+
+import pytest
+
+from server_decorator_entity import Id, Str, action, entity_spec, entity_spec_canonical, restful
+from server_decorator_entity.testing.user_fixture import UserFixture
+
+# --- Finding 1: copy-on-read -------------------------------------------------
+
+
+def test_entity_spec_returns_copy_not_live_reference() -> None:
+    spec1 = entity_spec(UserFixture)
+    spec1["entity"] = "Poisoned"
+    spec1["fields"].append({"name": "poison", "type": "str"})
+
+    spec2 = entity_spec(UserFixture)
+    assert spec2["entity"] == "User"
+    assert all(f.get("name") != "poison" for f in spec2["fields"])
+
+
+def test_entity_spec_canonical_unaffected_by_prior_mutation_attempt() -> None:
+    spec = entity_spec(UserFixture)
+    spec["fields"] = []
+
+    # entity_spec_canonical reads the internal stored spec, not the poisoned copy.
+    assert '"fields":[]' not in entity_spec_canonical(UserFixture)
+
+
+# --- Finding 2: undecorated subclass must not inherit base's spec via MRO ----
+
+
+def test_undecorated_subclass_of_restful_base_raises() -> None:
+    @restful(path="bases")
+    class Base:
+        id: Annotated[str, Id()]
+
+    class Sub(Base):
+        pass
+
+    with pytest.raises(TypeError, match="not decorated with @restful"):
+        entity_spec(Sub)
+
+
+# --- Finding 3: field collection is own-class only, not MRO-wide ------------
+
+
+def test_subclass_fields_do_not_inherit_base_fields() -> None:
+    @restful(path="bases")
+    class Base:
+        id: Annotated[str, Id()]
+        name: Annotated[str, Str()]
+
+    @restful(path="subs")
+    class Sub(Base):
+        extra: Annotated[str, Str()]
+
+    spec = entity_spec(Sub)
+    assert [f["name"] for f in spec["fields"]] == ["extra"]
+
+
+# --- Finding 4: wire-name validation -----------------------------------------
+
+
+def test_leading_underscore_field_name_raises() -> None:
+    with pytest.raises(ValueError, match="_private"):
+
+        @restful(path="x")
+        class Bad:
+            _private: Annotated[str, Str()]
+
+
+def test_colliding_wire_names_raise() -> None:
+    with pytest.raises(ValueError, match="collides"):
+
+        @restful(path="x")
+        class Bad:
+            foo_bar: Annotated[str, Str()]
+            foo__bar: Annotated[str, Str()]
+
+
+# --- Finding 5: @action on staticmethod/classmethod raises, either order ----
+
+
+def test_action_then_staticmethod_raises_immediately() -> None:
+    with pytest.raises(TypeError, match="static"):
+
+        class Bad:
+            @action("ping")
+            @staticmethod
+            def ping() -> None: ...
+
+
+def test_staticmethod_then_action_raises_at_restful_time() -> None:
+    with pytest.raises(TypeError, match="static"):
+
+        @restful(path="x")
+        class Bad:
+            @staticmethod
+            @action("ping")
+            def ping() -> None: ...
+
+
+def test_action_then_classmethod_raises_immediately() -> None:
+    with pytest.raises(TypeError, match="class"):
+
+        class Bad:
+            @action("ping")
+            @classmethod
+            def ping(cls) -> None: ...
+
+
+def test_classmethod_then_action_raises_at_restful_time() -> None:
+    with pytest.raises(TypeError, match="class"):
+
+        @restful(path="x")
+        class Bad:
+            @classmethod
+            @action("ping")
+            def ping(cls) -> None: ...

server_decorator_entity-2.0.19/tests/unit/test_metadata.py

@@ -0,0 +1,51 @@
+"""1.2.0 IR metadata: description, tags and security (mirror of Node's restful.spec.ts)."""
+
+from typing import Annotated
+
+import pytest
+
+from server_decorator_entity import Id, Str, entity_spec, restful
+
+
+def test_metadata_flows_into_spec() -> None:
+    @restful(
+        path="widgets",
+        description="A widget",
+        tags=["catalog"],
+        security={
+            "schemes": [{"name": "bearerAuth", "type": "http", "scheme": "bearer"}],
+            "ops": {"create": ["widget:write"]},
+        },
+    )
+    class Widget:
+        id: Annotated[str, Id()]
+        name: Annotated[str, Str(description="Display name")]
+
+    spec = entity_spec(Widget)
+    assert spec["description"] == "A widget"
+    assert spec["tags"] == ["catalog"]
+    assert spec["security"]["ops"]["create"] == ["widget:write"]
+    assert spec["fields"][1]["description"] == "Display name"
+
+
+def test_security_op_must_be_declared() -> None:
+    with pytest.raises(ValueError, match=r"security\.ops\.create is not declared in ops"):
+
+        @restful(
+            path="widgets",
+            ops=["list"],
+            security={
+                "schemes": [{"name": "bearerAuth", "type": "http", "scheme": "bearer"}],
+                "ops": {"create": ["widget:write"]},
+            },
+        )
+        class Widget:
+            id: Annotated[str, Id()]
+
+
+def test_unknown_scheme_type_rejected() -> None:
+    with pytest.raises(ValueError, match=r'scheme "x": type must be "http" or "apiKey"'):
+
+        @restful(path="widgets", security={"schemes": [{"name": "x", "type": "oauth2"}]})
+        class Widget:
+            id: Annotated[str, Id()]

server_decorator_entity-2.0.19/tests/unit/test_validate.py

@@ -0,0 +1,231 @@
+"""P1 gate-review fixes (C4, C5, escalated empty-enum, I-a, I-b1). See
+contracts/rules/entity-spec-validation.md for the shared rulings both languages implement, and
+node/packages/entity/src/validate.spec.ts for the Node twin these mirror.
+"""
+
+from typing import Annotated
+
+import pytest
+
+from server_decorator_entity import (
+    EnumOf,
+    Float,
+    Id,
+    Int,
+    ListOf,
+    Obj,
+    Ref,
+    Str,
+    action,
+    entity_spec,
+    restful,
+)
+
+
+def test_empty_transports_raises() -> None:
+    with pytest.raises(ValueError, match="transports must not be empty"):
+
+        @restful(path="x1", transports=[])
+        class X1:
+            id: Annotated[str, Id()]
+
+
+def test_empty_ops_raises() -> None:
+    with pytest.raises(ValueError, match="ops must not be empty"):
+
+        @restful(path="x2", ops=[])
+        class X2:
+            id: Annotated[str, Id()]
+
+
+def test_empty_enum_raises() -> None:
+    with pytest.raises(ValueError, match="enum must have at least one value"):
+
+        @restful(path="x3")
+        class X3:
+            id: Annotated[str, Id()]
+            status: Annotated[str, EnumOf()]
+
+
+def test_non_integer_min_raises() -> None:
+    with pytest.raises(ValueError, match=r"min/max must be integers"):
+
+        @restful(path="x4")
+        class X4:
+            id: Annotated[str, Id()]
+            b: Annotated[int, Int(min=2.5)]  # type: ignore[arg-type]
+
+
+def test_non_integer_max_raises() -> None:
+    with pytest.raises(ValueError, match=r"min/max must be integers"):
+
+        @restful(path="x5")
+        class X5:
+            id: Annotated[str, Id()]
+            b: Annotated[float, Float(max=2.5)]
+
+
+def test_bool_min_raises_even_though_isinstance_int_is_true() -> None:
+    with pytest.raises(ValueError, match=r"min/max must be integers"):
+
+        @restful(path="x5b")
+        class X5b:
+            id: Annotated[str, Id()]
+            b: Annotated[int, Int(min=True)]  # type: ignore[arg-type]
+
+
+def test_format_and_pattern_together_raises() -> None:
+    with pytest.raises(ValueError, match="format and pattern are mutually exclusive"):
+
+        @restful(path="x6")
+        class X6:
+            id: Annotated[str, Id()]
+            e: Annotated[str, Str(format="email", pattern="^admin@")]
+
+
+def test_reserved_wire_name_raises() -> None:
+    with pytest.raises(ValueError, match="reserved"):
+
+        @restful(path="x7")
+        class X7:
+            id: Annotated[str, Id()]
+            copy: Annotated[str, Str()]
+
+
+def test_reserved_wire_name_in_nested_obj_raises() -> None:
+    with pytest.raises(ValueError, match="reserved"):
+
+        @restful(path="x8")
+        class X8:
+            id: Annotated[str, Id()]
+            profile: Annotated[dict, Obj([("schema", Str())])]  # type: ignore[type-arg]
+
+
+def test_reserved_wire_name_in_action_input_raises() -> None:
+    with pytest.raises(ValueError, match="reserved"):
+
+        class X9:
+            id: Annotated[str, Id()]
+
+            @action("go", input=[("json", Str())])
+            def go(self) -> None: ...
+
+        restful(path="x9")(X9)
+
+
+def test_nested_list_of_list_names_every_level_with_the_parent_field_name() -> None:
+    @restful(path="x10")
+    class X10:
+        id: Annotated[str, Id()]
+        grid: Annotated[list, ListOf(ListOf(Str()))]  # type: ignore[type-arg]
+
+    spec = entity_spec(X10)
+    grid_field = next(f for f in spec["fields"] if f["name"] == "grid")
+    assert grid_field["item"]["name"] == "grid"
+    assert grid_field["item"]["item"]["name"] == "grid"
+
+
+def test_lookahead_pattern_raises() -> None:
+    with pytest.raises(ValueError, match=r"not RE2/rust-regex compatible"):
+
+        @restful(path="x12")
+        class X12:
+            id: Annotated[str, Id()]
+            e: Annotated[str, Str(pattern="^(?=.*[0-9]).+$")]
+
+
+def test_negative_lookahead_pattern_raises() -> None:
+    with pytest.raises(ValueError, match="lookaround"):
+
+        @restful(path="x13")
+        class X13:
+            id: Annotated[str, Id()]
+            e: Annotated[str, Str(pattern="^(?!admin).+$")]
+
+
+def test_lookbehind_pattern_raises() -> None:
+    with pytest.raises(ValueError, match="lookaround"):
+
+        @restful(path="x14")
+        class X14:
+            id: Annotated[str, Id()]
+            e: Annotated[str, Str(pattern="(?<=foo)bar")]
+
+
+def test_backreference_pattern_raises() -> None:
+    with pytest.raises(ValueError, match="backreference"):
+
+        @restful(path="x15")
+        class X15:
+            id: Annotated[str, Id()]
+            e: Annotated[str, Str(pattern="(a)\\1")]
+
+
+def test_normal_portable_pattern_still_works() -> None:
+    @restful(path="x16")
+    class X16:
+        id: Annotated[str, Id()]
+        e: Annotated[str, Str(pattern="^[a-z]+$")]
+
+    spec = entity_spec(X16)
+    e_field = next(f for f in spec["fields"] if f["name"] == "e")
+    assert e_field["pattern"] == "^[a-z]+$"
+
+
+def test_doubled_backslash_before_digit_does_not_false_positive() -> None:
+    # Source pattern characters: ^ a \ \ 1 $ — an escaped backslash (\\) followed by a literal
+    # "1", NOT a backreference (\1). The raw Python string r"^a\\1$" contains exactly those six
+    # characters (a raw string literal does not collapse \\ to \).
+    pattern = r"^a\\1$"
+    assert pattern == "^a\\\\1$"  # sanity: 6 chars — ^ a \ \ 1 $
+
+    @restful(path="x17")
+    class X17:
+        id: Annotated[str, Id()]
+        e: Annotated[str, Str(pattern=pattern)]
+
+    spec = entity_spec(X17)
+    e_field = next(f for f in spec["fields"] if f["name"] == "e")
+    assert e_field["pattern"] == pattern
+
+
+def test_empty_string_pattern_is_preserved_in_ir() -> None:
+    # M4 parity bug: FieldMarker.to_ir used truthiness (`if self.pattern:`), which silently
+    # dropped an empty-string pattern from the IR. The TS twin (`str({ pattern: '' })`) spreads
+    # the option straight into FieldSpec and only filters `undefined` in canonicalJson, so it
+    # keeps `pattern: ''`. The schema (`contracts/schemas/entity-spec.schema.json`) declares
+    # `pattern` as a plain `{"type": "string"}` with no minLength, so `""` is schema-valid and
+    # must round-trip byte-identically across languages.
+    @restful(path="x18")
+    class X18:
+        id: Annotated[str, Id()]
+        e: Annotated[str, Str(pattern="")]
+
+    spec = entity_spec(X18)
+    e_field = next(f for f in spec["fields"] if f["name"] == "e")
+    assert "pattern" in e_field
+    assert e_field["pattern"] == ""
+
+
+def test_empty_string_ref_is_preserved_in_ir() -> None:
+    # Same M4 parity bug, `ref` side: FieldMarker.to_ir used `if self.ref:`, dropping an
+    # empty-string ref. The TS twin (`ref('')`) keeps `ref: ''` for the same reason as above.
+    @restful(path="x19")
+    class X19:
+        id: Annotated[str, Id()]
+        r: Annotated[dict, Ref("")]  # type: ignore[type-arg]
+
+    spec = entity_spec(X19)
+    r_field = next(f for f in spec["fields"] if f["name"] == "r")
+    assert "ref" in r_field
+    assert r_field["ref"] == ""
+
+
+def test_valid_entity_unchanged_control_case() -> None:
+    @restful(path="x11")
+    class X11:
+        id: Annotated[str, Id()]
+        name: Annotated[str, Str(min=1, max=10)]
+
+    spec = entity_spec(X11)
+    assert [f["name"] for f in spec["fields"]] == ["id", "name"]