spiralthink-core 0.9.0__py3-none-any.whl

encoder/__init__.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+# SpiralThink — Baseline encoder package (L1)
+# (c) 2026 pfreig-art. Apache License 2.0.
+"""
+L1 baseline encoder package.
+
+Re-exports the baseline (CPU-only) encoder API so downstream code can do:
+
+    from encoder import Params, encode, coord_descent, hamming
+
+The baseline encoder searches a 4-parameter helical SpiralProgram by random
+restart + coordinate descent on Hamming distance, then records the XOR residual
+to guarantee bit-exact (zero-error) reconstruction.
+
+This package is deliberately pure-Python + stdlib. GPU experiments live under
+`encoder.experimental` (not yet present); the industrial encoder lives under
+the proprietary L2 (`spiralcore/`).
+"""
+from __future__ import annotations
+
+from .baseline import (
+    Params,
+    coord_descent,
+    encode,
+    encode_from_params,
+    encode_with_params,
+    hamming,
+)
+
+__all__ = [
+    "Params",
+    "coord_descent",
+    "encode",
+    "encode_from_params",
+    "encode_with_params",
+    "hamming",
+]
+
+__version__ = "0.9.0"

encoder/baseline.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+# SpiralThink — Baseline Encoder (L1)
+# (c) 2026 pfreig-art. Apache License 2.0.
+"""
+Baseline encoder: searches a SpiralProgram pi = (a, b, c, d) parametrizing
+the canonical 4-parameter helix family
+
+    r(t)     = a
+    theta(t) = b * t
+    z(t)     = c * t
+    phi(x,y,z) = floor((x + a) * d) mod 256
+
+over a target byte stream x. We optimize (a, b, c, d) by random restart +
+coordinate descent on Hamming distance. After convergence, residual bytes
+are recorded in pi.residual to guarantee zero-error reconstruction.
+
+This is a *baseline* encoder — deliberately simple, CPU only, no learned
+priors, no GPU. The L2 industrial encoder (SpiralCore™) lives in the
+proprietary tree and uses neural priors + ASIC-friendly kernels.
+"""
+from __future__ import annotations
+
+import math
+import random
+from dataclasses import dataclass
+
+from reference import SpiralProgram, decode, verify
+
+
+@dataclass
+class Params:
+    a: float
+    b: float
+    c: float
+    d: float
+
+    def to_program(self, n: int) -> SpiralProgram:
+        # Closure builders for the 4-parameter helix family. We use nested defs
+        # (not lambdas) so mypy --strict can infer signatures without resorting
+        # to # type: ignore. The captured-by-default-arg pattern is preserved
+        # to keep each closure independent of mutable outer state.
+        a, b, c, d = self.a, self.b, self.c, self.d
+
+        def r_fn(t: float, a: float = a) -> float:
+            return a
+
+        def theta_fn(t: float, b: float = b) -> float:
+            return b * t
+
+        def z_fn(t: float, c: float = c) -> float:
+            return c * t
+
+        def phi_fn(
+            x: float, y: float, z: float, a: float = a, d: float = d
+        ) -> int:
+            return int((x + a) * d) & 0xFF
+
+        return SpiralProgram(
+            r=r_fn,
+            theta=theta_fn,
+            z=z_fn,
+            phi=phi_fn,
+            n=n,
+        )
+
+
+def hamming(a: bytes, b: bytes) -> int:
+    # zip(strict=False) is intentional: the length-mismatch term `abs(len(a)-len(b))`
+    # below counts the unpaired tail bytes as full mismatches. Using strict=True
+    # would forbid the common case where decode() output is shorter than the target.
+    return sum(x ^ y != 0 for x, y in zip(a, b, strict=False)) + abs(len(a) - len(b))
+
+
+def coord_descent(
+    x: bytes,
+    p: Params,
+    *,
+    steps: int = 200,
+    sigma: float = 0.05,
+    rng: random.Random | None = None,
+) -> Params:
+    rng = rng or random.Random(0xC0FFEE)
+    best = p
+    best_err = hamming(decode(best.to_program(len(x))), x)
+    for _ in range(steps):
+        cand = Params(
+            a=best.a + rng.gauss(0, sigma),
+            b=best.b + rng.gauss(0, sigma * 0.1),
+            c=best.c + rng.gauss(0, sigma * 0.1),
+            d=max(1.0, best.d + rng.gauss(0, sigma)),
+        )
+        err = hamming(decode(cand.to_program(len(x))), x)
+        if err < best_err:
+            best, best_err = cand, err
+            if err == 0:
+                break
+    return best
+
+
+def _finalize_with_residual(
+    x: bytes, params: Params, label: str
+) -> SpiralProgram:
+    """Common finalization: build pi from params, compute residual, optimize.
+
+    If the helix-only decode already equals ``x`` the residual is all zeros
+    and we replace it with ``b""``. The reference decoder skips the residual
+    pass entirely on empty bytes (see ``reference.decode``), so this is a
+    pure semantic-preserving optimization that lets ``pi.bitlen()`` stay
+    constant in ``len(x)`` for inputs the helix family fits exactly. This
+    is the regime in which the algorithmic ratio ``rho_pi`` grows with n.
+    """
+    pi_no_residual = params.to_program(len(x))
+    y = decode(pi_no_residual)
+    # strict=True validates the invariant that the helix-only decode produces
+    # exactly len(x) bytes for an n=len(x) SpiralProgram. A length mismatch here
+    # would be a reference-decoder bug; fail loudly rather than silently truncate.
+    raw_residual = bytes(a ^ b for a, b in zip(x, y, strict=True))
+    residual = raw_residual if any(raw_residual) else b""
+    pi = SpiralProgram(
+        r=pi_no_residual.r, theta=pi_no_residual.theta,
+        z=pi_no_residual.z, phi=pi_no_residual.phi,
+        n=pi_no_residual.n, residual=residual,
+    )
+    assert verify(pi, x), f"{label} encoder failed zero-error invariant"
+    return pi
+
+
+def encode_from_params(
+    x: bytes,
+    params: Params,
+) -> tuple[SpiralProgram, Params]:
+    """Oracle encode: skip the search and use the caller-supplied ``params``.
+
+    This is useful when the caller already knows (or can cheaply compute) a
+    near-optimal helix fit — e.g. for synthetic structured inputs used in
+    scaling benchmarks, or for an offline pre-fit pipeline that hands the
+    fitted params to the L1 encoder for finalization.
+
+    The XOR residual is still computed and applied, so the zero-error
+    invariant holds regardless of how good ``params`` actually are. With an
+    exact fit the residual is ``b""`` and ``pi.bitlen()`` is constant in
+    ``len(x)`` — this is the regime where the algorithmic ratio
+    ``rho_pi = 8 * n / pi.bitlen()`` diverges with n.
+    """
+    pi = _finalize_with_residual(x, params, label="oracle")
+    return pi, params
+
+
+def encode_with_params(
+    x: bytes,
+    *,
+    restarts: int = 8,
+    steps_per_restart: int = 200,
+    seed: int = 0xC0FFEE,
+) -> tuple[SpiralProgram, Params]:
+    """Same as ``encode`` but also returns the underlying 4-parameter ``Params``.
+
+    The container layer (``spiral_format``) needs the raw ``(a, b, c, d)`` to
+    serialize the program without pickling closures. The ``SpiralProgram``
+    return value carries the residual; the ``Params`` value carries the helix
+    family parameters.
+    """
+    rng = random.Random(seed)
+    best: Params | None = None
+    best_err = math.inf
+    for _ in range(restarts):
+        p0 = Params(
+            a=rng.uniform(0.5, 1.5),
+            b=rng.uniform(0.05, 0.2),
+            c=rng.uniform(0.005, 0.02),
+            d=rng.uniform(64, 192),
+        )
+        p = coord_descent(x, p0, steps=steps_per_restart, rng=rng)
+        err = hamming(decode(p.to_program(len(x))), x)
+        if err < best_err:
+            best, best_err = p, err
+            if err == 0:
+                break
+    assert best is not None
+    pi = _finalize_with_residual(x, best, label="baseline")
+    return pi, best
+
+
+def encode(
+    x: bytes,
+    *,
+    restarts: int = 8,
+    steps_per_restart: int = 200,
+    seed: int = 0xC0FFEE,
+) -> SpiralProgram:
+    """Search for pi minimizing Hamming(U(pi), x); finalize with residual XOR."""
+    pi, _ = encode_with_params(
+        x,
+        restarts=restarts,
+        steps_per_restart=steps_per_restart,
+        seed=seed,
+    )
+    return pi
+
+
+if __name__ == "__main__":
+    target = bytes((i * 7 + 13) & 0xFF for i in range(2048))
+    pi = encode(target, restarts=4, steps_per_restart=100)
+    print(f"|x| = {len(target)} B, |pi| ~= {pi.bitlen()} bits")
+    print(f"verify = {verify(pi, target)}  (zero-error)")

reference/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: CC-BY-4.0
+# SpiralThink — Reference package (L0)
+# (c) 2026 pfreig-art. See LICENSES/CC-BY-4.0.txt.
+"""
+L0 reference package.
+
+Re-exports the canonical SpiralProgram contract and the reference decoder so that
+downstream packages (encoder/, demo/, tests/, spiralcore/) can simply do:
+
+    from reference import SpiralProgram, decode, verify, ratio, helix
+
+This module is part of the open-science tier (CC-BY-4.0). Treat it as the
+authoritative specification of the SpiralProgram schema. Any divergence between
+an implementation and this module is, by definition, a bug in the implementation.
+"""
+from __future__ import annotations
+
+from .decoder import (
+    DecodeMap,
+    Scalar,
+    SpiralProgram,
+    decode,
+    helix,
+    ratio,
+    verify,
+)
+
+__all__ = [
+    "DecodeMap",
+    "Scalar",
+    "SpiralProgram",
+    "decode",
+    "helix",
+    "ratio",
+    "verify",
+]
+
+__version__ = "0.9.0"

reference/decoder.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: CC-BY-4.0
+# SpiralThink — Reference Decoder (L0)
+# (c) 2026 pfreig-art. Universal geometric decoder over a parametric helix.
+"""
+Reference decoder for SpiralThink programs.
+
+A SpiralThink program pi = (r, theta, z, phi) is a 4-tuple of callables
+that parametrize a helical trajectory H(t) and a deterministic decoding
+map phi: H -> Sigma^*. Reconstruction is bit-exact (zero-error).
+
+This module is the *minimal canonical* decoder — prioritizes clarity over
+speed. The L1 baseline encoder and the L2 SpiralCore industrial encoder
+live in sibling packages.
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+from collections.abc import Callable
+from dataclasses import dataclass
+
+Scalar = Callable[[float], float]
+DecodeMap = Callable[[float, float, float], int]  # (x, y, z) -> symbol
+
+
+@dataclass(frozen=True)
+class SpiralProgram:
+    """A SpiralThink program pi = (r, theta, z, phi)."""
+    r: Scalar
+    theta: Scalar
+    z: Scalar
+    phi: DecodeMap
+    n: int                # chain length
+    dt: float = 1.0       # sampling step on the helix parameter t
+    residual: bytes = b""  # optional residual patch delta (zero-error guarantee)
+
+    def bitlen(self) -> int:
+        """Approximate program length |pi| in bits (parameters + residual)."""
+        # Each scalar function is assumed encoded with ~32 bits of parameters.
+        # Real encoders compute Kolmogorov-style minimal description.
+        param_bits = 4 * 32
+        return param_bits + 8 * len(self.residual)
+
+
+def helix(pi: SpiralProgram, t: float) -> tuple[float, float, float]:
+    """Evaluate the helical trajectory H(t) = (r cosθ, r sinθ, z)."""
+    r, th, z = pi.r(t), pi.theta(t), pi.z(t)
+    return (r * math.cos(th), r * math.sin(th), z)
+
+
+def decode(pi: SpiralProgram) -> bytes:
+    """Run U(pi) and return the reconstructed byte stream x.
+
+    Zero-error guarantee: if pi.residual is non-empty, it is XOR-applied
+    as a final correction pass. By construction len(residual) << n.
+    """
+    out = bytearray(pi.n)
+    for i in range(pi.n):
+        x, y, z = helix(pi, i * pi.dt)
+        out[i] = pi.phi(x, y, z) & 0xFF
+    if pi.residual:
+        for i, b in enumerate(pi.residual):
+            out[i] ^= b
+    return bytes(out)
+
+
+def verify(pi: SpiralProgram, x: bytes) -> bool:
+    """Cryptographic equality check between U(pi) and the target x."""
+    return hashlib.sha256(decode(pi)).digest() == hashlib.sha256(x).digest()
+
+
+def ratio(pi: SpiralProgram) -> float:
+    """Effective compression ratio rho = |x| / |pi|."""
+    return (8 * pi.n) / max(pi.bitlen(), 1)
+
+
+# --------------------------------------------------------------------------
+# Demo: a periodic byte stream reconstructed from a 4-parameter helix.
+# --------------------------------------------------------------------------
+if __name__ == "__main__":
+    pi = SpiralProgram(
+        r=lambda t: 1.0,
+        theta=lambda t: 0.1 * t,
+        z=lambda t: 0.01 * t,
+        phi=lambda x, y, z: int((x + 1.0) * 127) & 0xFF,
+        n=10_000,
+    )
+    x = decode(pi)
+    print(f"|x| = {len(x)} bytes")
+    print(f"|pi| = {pi.bitlen()} bits")
+    print(f"rho  = {ratio(pi):.1f}x")
+    print(f"verify(pi, x) = {verify(pi, x)}")

spiral_format/__init__.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+# SpiralThink — .spiral on-disk artifact format (L1)
+# (c) 2026 pfreig-art. Apache License 2.0.
+"""
+`spiral_format` — the on-disk `.spiral` artifact container.
+
+This package is a thin, tier-L1 wrapper that turns the in-memory SpiralProgram
+(from `reference/`) plus the L1 baseline encoder (from `encoder/`) into a
+self-describing file format with the canonical extension `.spiral`.
+
+Design constraints (mirrored by the contract tests in `tests/`):
+
+* The format is self-describing: magic bytes + format version + JSON manifest.
+* Integrity is enforced by an explicit SHA-256 of the original payload stored
+  in the artifact trailer. Bit-flip / truncation / wrong-magic / wrong-version
+  MUST cause `decompress`/`inspect` to fail closed, never to silently succeed.
+* Roundtrip is bit-exact: for every input file `x`, `decompress(compress(x))`
+  reproduces `x` byte-for-byte, matching the zero-error invariant defined in
+  `reference/decoder.py`.
+* The file extension is `.spiral`.
+
+PASS 1 ships the public API surface only — implementations raise
+`NotImplementedError` and the contract tests gate further work (PASS 2).
+"""
+from __future__ import annotations
+
+from .constants import MAGIC, MAGIC_LEN, MIME_TYPE, SUPPORTED_VERSIONS, VERSION
+from .errors import (
+    BadMagicError,
+    IntegrityError,
+    SpiralFormatError,
+    TruncatedArtifactError,
+    UnsupportedVersionError,
+)
+
+__all__ = [
+    "MAGIC",
+    "MAGIC_LEN",
+    "MIME_TYPE",
+    "SUPPORTED_VERSIONS",
+    "VERSION",
+    "BadMagicError",
+    "IntegrityError",
+    "SpiralFormatError",
+    "TruncatedArtifactError",
+    "UnsupportedVersionError",
+]
+
+__version__ = "0.1.0"

spiral_format/codec.py

@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: Apache-2.0
+# SpiralThink — SpiralProgram <-> bytes codec (L1)
+# (c) 2026 pfreig-art. Apache License 2.0.
+"""
+Small-struct codec for the L1 baseline helix-4 SpiralProgram.
+
+Wire layout (big-endian):
+
+    +--------+--------+--------+--------+--------+--------+--------+--------+
+    |                  n  (uint64, chain length)                            |
+    +-----------------------------------------------------------------------+
+    |                  a  (float64, r-parameter)                            |
+    +-----------------------------------------------------------------------+
+    |                  b  (float64, theta-parameter)                        |
+    +-----------------------------------------------------------------------+
+    |                  c  (float64, z-parameter)                            |
+    +-----------------------------------------------------------------------+
+    |                  d  (float64, phi-scale)                              |
+    +-----------------------------------------------------------------------+
+    |       residual_len  (uint32)                                          |
+    +-----------------------------------------------------------------------+
+    |       residual_len bytes of XOR residual                              |
+    +-----------------------------------------------------------------------+
+
+Fixed prefix: 8 + 4*8 + 4 = 44 bytes. Total = 44 + residual_len.
+
+The encoding tag stored in the manifest is ``PAYLOAD_ENCODING``. Any future
+encoder family (e.g. a 6-parameter helix) MUST use a different tag so older
+readers fail with ManifestError instead of silently decoding into the wrong
+family.
+
+This codec is deliberately closed-form: no pickle, no eval, no dynamic
+imports. Auditors can verify it by inspection.
+"""
+from __future__ import annotations
+
+import struct
+from typing import Final
+
+from encoder import Params  # type: ignore[import-not-found]
+from reference import SpiralProgram  # type: ignore[import-not-found]
+
+from .errors import SpiralFormatError
+
+#: Manifest tag identifying this payload codec.
+PAYLOAD_ENCODING: Final[str] = "spiralprogram-helix4-v1"
+
+#: struct format: n (u64), a, b, c, d (f64 x 4), residual_len (u32). All big-endian.
+_HEADER_FMT = "!QddddI"
+_HEADER_LEN = struct.calcsize(_HEADER_FMT)  # 44
+
+
+def encode_program(pi: SpiralProgram, params: Params) -> bytes:
+    """Serialize a helix-4 SpiralProgram to bytes.
+
+    ``params`` carries the raw (a, b, c, d) used by the encoder; ``pi`` only
+    carries the residual (and re-derivable n, dt). We never serialize lambdas.
+    """
+    if not isinstance(params, Params):
+        raise SpiralFormatError(
+            f"params must be encoder.Params, got {type(params).__name__}"
+        )
+    if pi.n < 0:
+        raise SpiralFormatError(f"n must be >= 0, got {pi.n}")
+    if pi.dt != 1.0:
+        # Current schema fixes dt=1.0. Keeping the field for forward
+        # compatibility but refusing non-default values prevents a silent
+        # roundtrip mismatch.
+        raise SpiralFormatError(
+            f"helix4-v1 codec requires dt=1.0, got dt={pi.dt}"
+        )
+
+    residual = bytes(pi.residual)
+    if len(residual) > 0xFFFFFFFF:  # pragma: no cover
+        # Defensive: residual_len is a uint32 field. Hitting this requires a
+        # ~4 GiB residual, which the L1 baseline encoder will never produce
+        # (it bounds residual size at len(x) <= input size, and inputs that
+        # large blow up before reaching this codec). Untested by design.
+        raise SpiralFormatError(
+            f"residual too large for uint32 length field: {len(residual)}"
+        )
+
+    header = struct.pack(
+        _HEADER_FMT,
+        pi.n,
+        float(params.a),
+        float(params.b),
+        float(params.c),
+        float(params.d),
+        len(residual),
+    )
+    return header + residual
+
+
+def decode_program(blob: bytes) -> SpiralProgram:
+    """Reconstruct the SpiralProgram from a helix-4 byte blob."""
+    if not isinstance(blob, (bytes, bytearray)):
+        raise SpiralFormatError(
+            f"blob must be bytes, got {type(blob).__name__}"
+        )
+    if len(blob) < _HEADER_LEN:
+        raise SpiralFormatError(
+            f"helix4-v1 payload truncated: need at least {_HEADER_LEN} bytes, "
+            f"got {len(blob)}"
+        )
+
+    n, a, b, c, d, residual_len = struct.unpack(_HEADER_FMT, blob[:_HEADER_LEN])
+    expected = _HEADER_LEN + residual_len
+    if len(blob) != expected:
+        raise SpiralFormatError(
+            f"helix4-v1 payload length mismatch: header declares "
+            f"{expected} bytes, blob has {len(blob)}"
+        )
+    residual = bytes(blob[_HEADER_LEN:])
+
+    # Rebuild the same lambdas the L1 baseline encoder produces. This MUST stay
+    # in lock-step with encoder.baseline.Params.to_program.
+    return SpiralProgram(
+        r=lambda t, a=a: a,
+        theta=lambda t, b=b: b * t,
+        z=lambda t, c=c: c * t,
+        phi=lambda x, y, z, a=a, d=d: int((x + a) * d) & 0xFF,
+        n=int(n),
+        dt=1.0,
+        residual=residual,
+    )
+
+
+__all__ = [
+    "PAYLOAD_ENCODING",
+    "decode_program",
+    "encode_program",
+]

spiral_format/constants.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+# SpiralThink — .spiral format constants (L1)
+# (c) 2026 pfreig-art. Apache License 2.0.
+"""
+Constants that define the on-disk `.spiral` artifact.
+
+Stability policy
+----------------
+The values in this module are **the** canonical format identifiers. Changing
+``MAGIC`` is a hard incompatibility and is never allowed. Bumping ``VERSION``
+is allowed only together with an entry in ``SUPPORTED_VERSIONS`` and a
+documented migration note in ``docs/spiral_format.md`` (added in a later pass).
+
+Wire layout (big-endian, see ``docs/spiral_format.md`` once written):
+
+    +--------+--------+--------+--------+--------+--------+
+    |  'S'   |  'P'   |  'R'   |  'L'   |   VERSION (u16) |
+    +--------+--------+--------+--------+--------+--------+
+    |        manifest length (uint32, big-endian)         |
+    +--------+--------+--------+--------+--------+--------+
+    |              manifest bytes (UTF-8 JSON)            |
+    +-----------------------------------------------------+
+    |        payload length (uint64, big-endian)          |
+    +-----------------------------------------------------+
+    |                payload bytes (opaque)               |
+    +-----------------------------------------------------+
+    |     SHA-256 of original input (32 bytes, trailer)   |
+    +-----------------------------------------------------+
+
+The trailer SHA-256 is the bit-exact integrity field. It is computed over the
+**uncompressed input**, not over the artifact, and is the value that
+``verify_roundtrip`` compares against the decoded output.
+"""
+from __future__ import annotations
+
+from typing import Final
+
+MAGIC: Final[bytes] = b"SPRL"
+MAGIC_LEN: Final[int] = len(MAGIC)
+
+#: Current format version written by ``pack_artifact``.
+VERSION: Final[int] = 1
+
+#: Format versions ``unpack_artifact`` knows how to read. Forward-compatible
+#: readers may add older versions here; never remove a version once shipped.
+SUPPORTED_VERSIONS: Final[frozenset[int]] = frozenset({1})
+
+#: Suggested MIME type for tooling (mailers, browsers). Not yet IANA-registered.
+MIME_TYPE: Final[str] = "application/vnd.spiralthink.spiral"
+
+#: Canonical filename extension, including the leading dot.
+FILE_EXTENSION: Final[str] = ".spiral"
+
+#: SHA-256 digest size in bytes.
+TRAILER_HASH_LEN: Final[int] = 32