lorebase-core 0.2.3__py3-none-any.whl

lorebase_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.3"

lorebase_core/canonical/__init__.py

@@ -0,0 +1,35 @@
+"""Canonical JSON (RFC 8785 with Lorebase rules) and content hashing."""
+
+from lorebase_core.canonical.hashing import (
+    HASH_SCHEME,
+    HASH_SIZE,
+    NODE_HASH_TYPE,
+    REVISION_HASH_TYPE,
+    ObjectType,
+    canonical_bytes,
+    from_hex,
+    hex,
+    node_hash,
+    normalize,
+    object_hash,
+    revision_hash,
+)
+from lorebase_core.canonical.jcs import CanonicalError, format_number, jcs_bytes
+
+__all__ = [
+    "HASH_SCHEME",
+    "HASH_SIZE",
+    "NODE_HASH_TYPE",
+    "REVISION_HASH_TYPE",
+    "CanonicalError",
+    "ObjectType",
+    "canonical_bytes",
+    "format_number",
+    "from_hex",
+    "hex",
+    "jcs_bytes",
+    "node_hash",
+    "normalize",
+    "object_hash",
+    "revision_hash",
+]

lorebase_core/canonical/hashing.py

@@ -0,0 +1,128 @@
+"""Lorebase canonical form and content hashing (design 6.1, AC-09)."""
+
+from __future__ import annotations
+
+import hashlib
+import unicodedata
+from collections.abc import Mapping, Sequence
+from enum import StrEnum
+
+from lorebase_core.canonical.jcs import CanonicalError, jcs_bytes
+
+__all__ = [
+    "HASH_SCHEME",
+    "HASH_SIZE",
+    "NODE_HASH_TYPE",
+    "REVISION_HASH_TYPE",
+    "ObjectType",
+    "canonical_bytes",
+    "from_hex",
+    "hex",
+    "node_hash",
+    "normalize",
+    "object_hash",
+    "revision_hash",
+]
+
+HASH_SCHEME = "lb1"
+"""Version tag of the hashing scheme. Changing any hashing rule requires a new tag."""
+
+HASH_SIZE = hashlib.sha256().digest_size
+"""Size in bytes of every Lorebase hash."""
+
+NODE_HASH_TYPE = "node"
+REVISION_HASH_TYPE = "revision"
+
+_SEPARATOR = b"\x00"
+
+
+class ObjectType(StrEnum):
+    """Types of content-addressed objects (design 6.1)."""
+
+    SCHEMA_KIND = "schema.kind"
+    SCHEMA_RELATION = "schema.relation"
+    SCHEMA_TRAIT = "schema.trait"
+    SCHEMA_OPERATION = "schema.operation"
+    SCHEMA_DERIVATION = "schema.derivation"
+    SCHEMA_SOURCE = "schema.source"
+    SCHEMA_DOMAIN = "schema.domain"
+    RECORD = "record"
+    LINK = "link"
+
+
+_HASHED_TYPES = frozenset({*(t.value for t in ObjectType), REVISION_HASH_TYPE})
+
+
+def normalize(value: object) -> object:
+    """Apply the Lorebase value rules before RFC 8785 serialization.
+
+    Strings (including object keys) are NFC-normalized and object members whose
+    value is ``None`` are omitted, since null and absent are the same. ``None``
+    inside arrays is kept, because array positions are significant.
+    Integers and decimals of Attribute values are expected to arrive already
+    encoded as canonical strings; timestamps are taken as given.
+    """
+    if isinstance(value, str):
+        return unicodedata.normalize("NFC", value)
+    if isinstance(value, Mapping):
+        result: dict[str, object] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise CanonicalError(f"object keys must be strings, got {type(key).__name__}")
+            if item is None:
+                continue
+            nfc_key = unicodedata.normalize("NFC", key)
+            if nfc_key in result:
+                raise CanonicalError(f"duplicate object key after NFC normalization: {nfc_key!r}")
+            result[nfc_key] = normalize(item)
+        return result
+    if isinstance(value, Sequence) and not isinstance(value, bytes | bytearray):
+        return [normalize(item) for item in value]
+    return value
+
+
+def canonical_bytes(value: object) -> bytes:
+    """Return the Lorebase canonical JSON bytes of ``value`` (RFC 8785 plus Lorebase rules)."""
+    return jcs_bytes(normalize(value))
+
+
+def object_hash(object_type: str, value: object) -> bytes:
+    """Return ``sha256("lb1\\x00" + object_type + "\\x00" + canonical_bytes(value))``.
+
+    ``object_type`` is an :class:`ObjectType` or ``"revision"``.
+    """
+    if object_type not in _HASHED_TYPES:
+        raise ValueError(f"unknown object type: {object_type!r}")
+    return _scoped_hash(str(object_type), canonical_bytes(value))
+
+
+def revision_hash(value: object) -> bytes:
+    """Hash a canonical Revision payload (design 6.4)."""
+    return _scoped_hash(REVISION_HASH_TYPE, canonical_bytes(value))
+
+
+def node_hash(body: bytes) -> bytes:
+    """Hash an encoded tree node: ``sha256("lb1\\x00node\\x00" + body)`` (design 6.2)."""
+    return _scoped_hash(NODE_HASH_TYPE, body)
+
+
+def hex(h: bytes) -> str:
+    """Render a hash as lowercase hex, the API representation."""
+    return h.hex()
+
+
+def from_hex(text: str) -> bytes:
+    """Parse a lowercase hex hash produced by :func:`hex`."""
+    if len(text) != 2 * HASH_SIZE or text != text.lower():
+        raise ValueError(f"expected {2 * HASH_SIZE} lowercase hex characters")
+    return bytes.fromhex(text)
+
+
+def _scoped_hash(scope: str, body: bytes) -> bytes:
+    digest = hashlib.sha256()
+    digest.update(HASH_SCHEME.encode("ascii"))
+    digest.update(_SEPARATOR)
+    digest.update(scope.encode("ascii"))
+    digest.update(_SEPARATOR)
+    digest.update(body)
+    return digest.digest()

lorebase_core/canonical/jcs.py

@@ -0,0 +1,162 @@
+"""RFC 8785 JSON Canonicalization Scheme (JCS) serializer.
+
+This module implements the plain RFC 8785 rules. The Lorebase value rules
+(NFC strings, omitted nulls) are applied on top of it by
+:func:`lorebase_core.canonical.canonical_bytes`.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping, Sequence
+from decimal import Decimal
+
+__all__ = ["CanonicalError", "format_number", "jcs_bytes"]
+
+# ECMAScript Number::toString switches to exponential notation outside
+# 1e-7 < |x| < 1e21 (RFC 8785, section 3.2.2.3).
+_MAX_PLAIN_EXPONENT = 21
+_MIN_PLAIN_EXPONENT = -6
+
+_ESCAPES = {
+    0x08: "\\b",
+    0x09: "\\t",
+    0x0A: "\\n",
+    0x0C: "\\f",
+    0x0D: "\\r",
+    0x22: '\\"',
+    0x5C: "\\\\",
+}
+_FIRST_PRINTABLE = 0x20
+#: Characters `_write_string` escapes; a string without any is written as it is.
+_NEEDS_ESCAPE = re.compile(r'[\x00-\x1f"\\]')
+
+
+class CanonicalError(ValueError):
+    """Raised when a value cannot be represented in canonical JSON."""
+
+
+def jcs_bytes(value: object) -> bytes:
+    """Serialize a JSON-compatible value to RFC 8785 canonical UTF-8 bytes.
+
+    Accepted types: ``None``, ``bool``, ``int`` (only if its decimal text is
+    the canonical text of an IEEE 754 double), ``float`` (finite), ``str``, mappings with ``str``
+    keys, lists and tuples.
+    """
+    parts: list[str] = []
+    _write(value, parts)
+    try:
+        return "".join(parts).encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise CanonicalError("string contains a lone surrogate") from exc
+
+
+def format_number(value: float) -> str:
+    """Format a number with the ECMAScript Number::toString rules (RFC 8785 3.2.2.3)."""
+    if isinstance(value, bool):
+        raise CanonicalError("booleans are not numbers")
+    if isinstance(value, int):
+        # RFC 8785 numbers are IEEE 754 doubles. An integer is accepted only when
+        # its decimal text is already the canonical text of its double, so no
+        # digit is silently changed; other integers must be passed as strings.
+        try:
+            text = format_number(float(value))
+        except OverflowError:
+            text = ""
+        if text != str(value):
+            raise CanonicalError(
+                f"integer {value} is not exactly representable; pass it as a string"
+            )
+        return text
+    if not math.isfinite(value):
+        raise CanonicalError("NaN and Infinity are not valid JSON numbers")
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    # repr() yields the shortest digit string that round-trips, which is the
+    # digit selection ECMAScript requires.
+    _, digit_tuple, exponent = Decimal(repr(abs(value))).as_tuple()
+    assert isinstance(exponent, int)
+    digits = "".join(str(d) for d in digit_tuple).rstrip("0")
+    exponent += len(digit_tuple) - len(digits)
+    k = len(digits)
+    n = exponent + k  # value = 0.digits * 10**n
+    if k <= n <= _MAX_PLAIN_EXPONENT:
+        body = digits + "0" * (n - k)
+    elif 0 < n <= _MAX_PLAIN_EXPONENT:
+        body = digits[:n] + "." + digits[n:]
+    elif _MIN_PLAIN_EXPONENT < n <= 0:
+        body = "0." + "0" * (-n) + digits
+    else:
+        e = n - 1
+        e_text = f"+{e}" if e >= 0 else str(e)
+        mantissa = digits if k == 1 else digits[0] + "." + digits[1:]
+        body = f"{mantissa}e{e_text}"
+    return sign + body
+
+
+def _write(value: object, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, int | float):
+        out.append(format_number(value))
+    elif isinstance(value, str):
+        _write_string(value, out)
+    elif isinstance(value, Mapping):
+        _write_object(value, out)
+    elif isinstance(value, Sequence) and not isinstance(value, bytes | bytearray):
+        out.append("[")
+        for index, item in enumerate(value):
+            if index:
+                out.append(",")
+            _write(item, out)
+        out.append("]")
+    else:
+        raise CanonicalError(f"unsupported type for canonical JSON: {type(value).__name__}")
+
+
+def _write_object(value: Mapping[object, object], out: list[str]) -> None:
+    keys: list[str] = []
+    for key in value:
+        if not isinstance(key, str):
+            raise CanonicalError(f"object keys must be strings, got {type(key).__name__}")
+        keys.append(key)
+    keys.sort(key=_utf16_sort_key)
+    out.append("{")
+    for index, key in enumerate(keys):
+        if index:
+            out.append(",")
+        _write_string(key, out)
+        out.append(":")
+        _write(value[key], out)
+    out.append("}")
+
+
+def _utf16_sort_key(key: str) -> bytes:
+    # Big-endian UTF-16 bytes compare exactly like sequences of UTF-16 code units.
+    try:
+        return key.encode("utf-16-be")
+    except UnicodeEncodeError as exc:
+        raise CanonicalError("object key contains a lone surrogate") from exc
+
+
+def _write_string(value: str, out: list[str]) -> None:
+    if _NEEDS_ESCAPE.search(value) is None:
+        out.append(f'"{value}"')
+        return
+    out.append('"')
+    for char in value:
+        code = ord(char)
+        escaped = _ESCAPES.get(code)
+        if escaped is not None:
+            out.append(escaped)
+        elif code < _FIRST_PRINTABLE:
+            out.append(f"\\u{code:04x}")
+        else:
+            out.append(char)
+    out.append('"')

lorebase_core/expr/__init__.py

@@ -0,0 +1,118 @@
+"""Expression engine (design 5.7, 5.8, AC-06): CEL parsed by cel-python, type checked against
+the Schema and evaluated in a bounded, deterministic sandbox without I/O.
+
+- ``compile(expression, environment)`` parses and type checks; environments come from
+  ``operation_environment`` and ``record_environment``.
+- ``compile_operation`` / ``compile_derivation`` compile every expression of an element;
+  ``derivation_inputs`` and ``links_read`` tell what a Derivation reads.
+- ``evaluate_precondition``, ``check_preconditions``, ``evaluate_review_policy`` and
+  ``plan_steps`` evaluate Operations; ``evaluate_derivation`` and ``matches_filter``
+  evaluate Derivations. Records come from a caller-supplied ``RecordResolver``.
+- ``compile_row_expression`` and ``evaluate_row_expression`` handle the ``expression`` of a
+  Source's Attribute mapping, over one row of the Source; ``RowExpressions`` compiles them
+  once over the Source's columns.
+- ``ExprLimits`` bounds compiling and evaluation; ``ExprError`` reports problems with a
+  stable code, the position in the expression and the path in the schema element.
+"""
+
+from lorebase_core.expr.compiler import CompiledExpression, compile, run
+from lorebase_core.expr.context import EvaluationContext, Principal, activation
+from lorebase_core.expr.derivations import (
+    CompiledDerivation,
+    compile_derivation,
+    derivation_expression_errors,
+    derivation_inputs,
+    derivation_reads,
+    evaluate_derivation,
+    links_read,
+    matches_filter,
+)
+from lorebase_core.expr.environment import (
+    Environment,
+    LinkField,
+    operation_environment,
+    record_environment,
+)
+from lorebase_core.expr.errors import ExprError, ExprErrorCode, Position
+from lorebase_core.expr.limits import ExprLimits
+from lorebase_core.expr.operations import (
+    RESERVED_PARAMETER_NAMES,
+    CompiledOperation,
+    CompiledStep,
+    PreconditionFailure,
+    StepPlan,
+    check_preconditions,
+    compile_operation,
+    evaluate_precondition,
+    evaluate_review_policy,
+    operation_expression_errors,
+    plan_steps,
+)
+from lorebase_core.expr.resolver import (
+    LinkedRecord,
+    LinksRequest,
+    MemoryResolver,
+    RecordNotLoaded,
+    RecordRequest,
+    RecordResolver,
+)
+from lorebase_core.expr.rows import (
+    RowExpressions,
+    compile_row_expression,
+    evaluate_row_expression,
+    row_environment,
+    row_value,
+    row_variables,
+)
+from lorebase_core.expr.types import ExprType, TypeKind, from_type_spec
+
+__all__ = [
+    "RESERVED_PARAMETER_NAMES",
+    "CompiledDerivation",
+    "CompiledExpression",
+    "CompiledOperation",
+    "CompiledStep",
+    "Environment",
+    "EvaluationContext",
+    "ExprError",
+    "ExprErrorCode",
+    "ExprLimits",
+    "ExprType",
+    "LinkField",
+    "LinkedRecord",
+    "LinksRequest",
+    "MemoryResolver",
+    "Position",
+    "PreconditionFailure",
+    "Principal",
+    "RecordNotLoaded",
+    "RecordRequest",
+    "RecordResolver",
+    "RowExpressions",
+    "StepPlan",
+    "TypeKind",
+    "activation",
+    "check_preconditions",
+    "compile",
+    "compile_derivation",
+    "compile_operation",
+    "compile_row_expression",
+    "derivation_expression_errors",
+    "derivation_inputs",
+    "derivation_reads",
+    "evaluate_derivation",
+    "evaluate_precondition",
+    "evaluate_review_policy",
+    "evaluate_row_expression",
+    "from_type_spec",
+    "links_read",
+    "matches_filter",
+    "operation_environment",
+    "operation_expression_errors",
+    "plan_steps",
+    "record_environment",
+    "row_environment",
+    "row_value",
+    "row_variables",
+    "run",
+]