spiralthink-core 0.9.0__tar.gz

spiralthink_core-0.9.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: spiralthink-core
+Version: 0.9.0
+Summary: Universal geometric compression with bit-exact reconstruction. Reference decoder (L0) and baseline encoder (L1).
+Author: pfreig-art
+License: Apache-2.0 AND CC-BY-4.0
+Project-URL: Homepage, https://github.com/pfreig-art/spiralthink-core
+Project-URL: Issues, https://github.com/pfreig-art/spiralthink-core/issues
+Keywords: compression,kolmogorov,helix,spiral,bit-exact,reconstruction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+
+# SpiralThink — Core
+
+> **Universal geometric machine for sub-Kolmogorov effective compression and zero-error reconstruction.**
+
+[![Status](https://img.shields.io/badge/status-preprint--v0.9-blueviolet)]() [![License](https://img.shields.io/badge/license-mixed-green)]() [![Private](https://img.shields.io/badge/repo-private-red)]()
+
+---
+
+## TL;DR
+
+SpiralThink represents arbitrary data as trajectories on a parametric helical manifold $\mathcal{H}(r,\theta,z)$ generated by a short program $\pi$. We target the **algorithmic** lower bound $K(x)$ (Kolmogorov), not Shannon's $H(X)$. Reconstruction is **bit-exact** (zero-error) by design. Effective ratio $\rho = |x|/|\pi|$ diverges with chain length $n$.
+
+| n | Raw bits | \|π\| | ρ |
+|---|---|---|---|
+| 10³ | 8 000 | 96 | 83× |
+| 10⁶ | 8·10⁶ | 112 | 7.1·10⁴× |
+| 10⁹ | 8·10⁹ | 128 | 6.25·10⁷× |
+| 10¹² | 8·10¹² | 144 | 5.5·10¹⁰× |
+
+---
+
+## Repository layout
+
+```
+spiralthink-core/
+├── paper/              # L0 · CC-BY 4.0 · preprint LaTeX + PDF
+├── reference/          # L0 · CC-BY 4.0 · Python reference decoder
+├── encoder/            # L1 · Apache-2.0 · baseline gradient encoder
+├── spiralcore/         # L2 · PROPRIETARY · industrial encoder + GPU kernels
+├── demo/               # shock-demo notebooks (numerical scaling §4)
+├── docs/               # deployment manual
+└── LICENSES/           # CC-BY-4.0, Apache-2.0, SpiralCore-EULA
+```
+
+---
+
+## Mixed licensing model
+
+| Layer | Path | License | Audience |
+|---|---|---|---|
+| **L0** Theory + reference decoder | `paper/`, `reference/` | CC-BY 4.0 | academia, open community |
+| **L1** Baseline encoder | `encoder/` | Apache-2.0 | OSS contributors, integrators |
+| **L2** Industrial encoder *SpiralCore™* | `spiralcore/` | Proprietary EULA | enterprise / unicorn moat |
+
+---
+
+## Core idea
+
+$$\pi^\star = \arg\min_{\pi\,:\,U(\pi)=x} |\pi|, \qquad |\pi^\star| \approx K(x)$$
+
+**Theorem 1 (Compression–Computation Tradeoff).**
+
+$$|\pi| \cdot \log T_\pi \;\geq\; K(x) - O(1)$$
+
+SpiralThink trades *space* for *deterministic recomputation*, never for accuracy.
+
+## Zero-error architecture
+
+```
+Encoder ──π──▶ Decoder  U(π) = x
+   ▲                       │
+   └── hash(x) == hash(U(π)) ──┘
+```
+
+If hash mismatch → encoder appends residual patch $\delta$; total $|\pi|+|\delta| \ll |x|$ for structured data.
+
+## Helical spring analogy
+
+$U = \tfrac12 k\,\Delta x^2$. SpiralThink stores informational tension in $\pi$; uncoiling regenerates the chain — like a spring releases stored length without memorizing each coil.
+
+## Universal passive storage
+
+Substrate-agnostic: DNA, optical phase plates, magnetic domains, silicon. Exabyte archives → kilobyte inscriptions.
+
+---
+
+## Applications
+
+1. LLM weights & KV-cache compression
+2. Vector DB embeddings (RAM ↔ disk parity)
+3. Cold archival (tape replacement)
+4. Edge sub-MB foundation models
+
+---
+
+## Roadmap
+
+- [x] Preprint v0.9 draft
+- [x] Private repo bootstrap
+- [ ] LaTeX compilation → arXiv
+- [ ] Reference decoder (Python, NumPy)
+- [ ] Baseline encoder (gradient search over $\pi$)
+- [ ] Shock-demo notebook (§4 numerical examples)
+- [ ] SpiralCore™ GPU kernel prototype
+- [ ] Deployment manual v1
+
+---
+
+## Contact
+
+Maintainer: **pfreig-art** · Palma / Maó, Illes Balears · 2026
+
+*This repository is private. All rights reserved on L2 components. L0/L1 will be split into a public mirror at release time.*

spiralthink_core-0.9.0/README.md

@@ -0,0 +1,103 @@
+# SpiralThink — Core
+
+> **Universal geometric machine for sub-Kolmogorov effective compression and zero-error reconstruction.**
+
+[![Status](https://img.shields.io/badge/status-preprint--v0.9-blueviolet)]() [![License](https://img.shields.io/badge/license-mixed-green)]() [![Private](https://img.shields.io/badge/repo-private-red)]()
+
+---
+
+## TL;DR
+
+SpiralThink represents arbitrary data as trajectories on a parametric helical manifold $\mathcal{H}(r,\theta,z)$ generated by a short program $\pi$. We target the **algorithmic** lower bound $K(x)$ (Kolmogorov), not Shannon's $H(X)$. Reconstruction is **bit-exact** (zero-error) by design. Effective ratio $\rho = |x|/|\pi|$ diverges with chain length $n$.
+
+| n | Raw bits | \|π\| | ρ |
+|---|---|---|---|
+| 10³ | 8 000 | 96 | 83× |
+| 10⁶ | 8·10⁶ | 112 | 7.1·10⁴× |
+| 10⁹ | 8·10⁹ | 128 | 6.25·10⁷× |
+| 10¹² | 8·10¹² | 144 | 5.5·10¹⁰× |
+
+---
+
+## Repository layout
+
+```
+spiralthink-core/
+├── paper/              # L0 · CC-BY 4.0 · preprint LaTeX + PDF
+├── reference/          # L0 · CC-BY 4.0 · Python reference decoder
+├── encoder/            # L1 · Apache-2.0 · baseline gradient encoder
+├── spiralcore/         # L2 · PROPRIETARY · industrial encoder + GPU kernels
+├── demo/               # shock-demo notebooks (numerical scaling §4)
+├── docs/               # deployment manual
+└── LICENSES/           # CC-BY-4.0, Apache-2.0, SpiralCore-EULA
+```
+
+---
+
+## Mixed licensing model
+
+| Layer | Path | License | Audience |
+|---|---|---|---|
+| **L0** Theory + reference decoder | `paper/`, `reference/` | CC-BY 4.0 | academia, open community |
+| **L1** Baseline encoder | `encoder/` | Apache-2.0 | OSS contributors, integrators |
+| **L2** Industrial encoder *SpiralCore™* | `spiralcore/` | Proprietary EULA | enterprise / unicorn moat |
+
+---
+
+## Core idea
+
+$$\pi^\star = \arg\min_{\pi\,:\,U(\pi)=x} |\pi|, \qquad |\pi^\star| \approx K(x)$$
+
+**Theorem 1 (Compression–Computation Tradeoff).**
+
+$$|\pi| \cdot \log T_\pi \;\geq\; K(x) - O(1)$$
+
+SpiralThink trades *space* for *deterministic recomputation*, never for accuracy.
+
+## Zero-error architecture
+
+```
+Encoder ──π──▶ Decoder  U(π) = x
+   ▲                       │
+   └── hash(x) == hash(U(π)) ──┘
+```
+
+If hash mismatch → encoder appends residual patch $\delta$; total $|\pi|+|\delta| \ll |x|$ for structured data.
+
+## Helical spring analogy
+
+$U = \tfrac12 k\,\Delta x^2$. SpiralThink stores informational tension in $\pi$; uncoiling regenerates the chain — like a spring releases stored length without memorizing each coil.
+
+## Universal passive storage
+
+Substrate-agnostic: DNA, optical phase plates, magnetic domains, silicon. Exabyte archives → kilobyte inscriptions.
+
+---
+
+## Applications
+
+1. LLM weights & KV-cache compression
+2. Vector DB embeddings (RAM ↔ disk parity)
+3. Cold archival (tape replacement)
+4. Edge sub-MB foundation models
+
+---
+
+## Roadmap
+
+- [x] Preprint v0.9 draft
+- [x] Private repo bootstrap
+- [ ] LaTeX compilation → arXiv
+- [ ] Reference decoder (Python, NumPy)
+- [ ] Baseline encoder (gradient search over $\pi$)
+- [ ] Shock-demo notebook (§4 numerical examples)
+- [ ] SpiralCore™ GPU kernel prototype
+- [ ] Deployment manual v1
+
+---
+
+## Contact
+
+Maintainer: **pfreig-art** · Palma / Maó, Illes Balears · 2026
+
+*This repository is private. All rights reserved on L2 components. L0/L1 will be split into a public mirror at release time.*

spiralthink_core-0.9.0/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"

spiralthink_core-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)")

spiralthink_core-0.9.0/pyproject.toml

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: Apache-2.0
+# SpiralThink Core — build & test configuration
+# (c) 2026 pfreig-art.
+#
+# Per-tier source licensing (preserved by the wheel):
+#   reference/      CC-BY-4.0  — open science L0 (canonical decoder)
+#   encoder/        Apache-2.0 — open baseline L1 (coord-descent encoder)
+#   spiral_format/  Apache-2.0 — on-disk .spiral container (L1)
+#   spiralcore/     Proprietary EULA — L2, README-only in this public mirror
+#                   (intentionally excluded from the wheel; ships via signed
+#                    encrypted tarballs to licensees).
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spiralthink-core"
+version = "0.9.0"
+description = "Universal geometric compression with bit-exact reconstruction. Reference decoder (L0) and baseline encoder (L1)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0 AND CC-BY-4.0" }
+authors = [{ name = "pfreig-art" }]
+keywords = ["compression", "kolmogorov", "helix", "spiral", "bit-exact", "reconstruction"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "pytest-benchmark>=4.0",
+    "ruff>=0.15",
+    "mypy>=1.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/pfreig-art/spiralthink-core"
+Issues = "https://github.com/pfreig-art/spiralthink-core/issues"
+
+# ---------------------------------------------------------------------------
+# Setuptools — explicit top-level packages.
+# ---------------------------------------------------------------------------
+[tool.setuptools]
+packages = ["reference", "encoder", "spiral_format"]
+
+# ---------------------------------------------------------------------------
+# pytest configuration
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "7.4"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]
+xfail_strict = true
+# Benchmarks live under bench/ and are invoked explicitly by the CI bench
+# job (pytest bench/ --benchmark-only). Default test runs MUST stay fast,
+# so the tests/ default invocation should NOT trigger the bench suite.
+# We keep pytest-benchmark loaded (because some tests may want to assert
+# its availability), but the default ``testpaths = ["tests"]`` already
+# excludes bench/ from default collection.
+
+# ---------------------------------------------------------------------------
+# coverage.py configuration
+# ---------------------------------------------------------------------------
+[tool.coverage.run]
+branch = true
+# spiral_lab is a research-lane package (NOT shipped in the wheel) but it is
+# under test and contributes to the global coverage gate so its instrumentation
+# stays honest. Its tests live alongside the product tests under tests/.
+source = ["reference", "encoder", "spiral_format", "spiral_lab"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]
+
+# ---------------------------------------------------------------------------
+# Ruff — linter + import sorter.
+#
+# Pragmatic rule profile (per maintainer directive 2026-05-25):
+#   E,F  pycodestyle errors + pyflakes      — baseline correctness gates.
+#   I    isort                              — import order is part of the contract.
+#   B    flake8-bugbear                     — catches common bug patterns (zip strict, etc.).
+#   UP   pyupgrade                          — keep py3.10+ idioms current.
+#   SIM  flake8-simplify                    — readability without overreach.
+#   RUF  ruff-specific                      — includes RUF022 (sorted __all__).
+#
+# Deliberately NOT enabled: ALL, ANN, D, PT (D = docstring style; pep257-style
+# docstrings are already mixed throughout. ANN duplicates mypy. PT is opinionated
+# about pytest style and would churn ~30 tests for zero correctness gain).
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+# Per-file rule relaxations only when they survive code review.
+
+[tool.ruff.lint.per-file-ignores]
+# Tests intentionally use unused imports for fixtures / patching surfaces.
+"tests/*" = ["F401"]
+
+# ---------------------------------------------------------------------------
+# Mypy — static type gate.
+#
+# Strict on reference/ (frozen contract, must be a fortress).
+# Strict on encoder/ with --disallow-any-generics RELAXED for Params.to_program
+# lambdas — those are Callable[[float], float] by construction and forcing a
+# Protocol there is ceremony without bug-detection value (per maintainer
+# directive 2026-05-25).
+#
+# spiral_format/ is not yet strict-gated; it will be hardened in a later PR
+# once the contract surface stabilizes.
+# ---------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.10"
+files = ["reference", "encoder"]
+show_error_codes = true
+show_column_numbers = true
+pretty = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "reference.*"
+strict = true
+
+[[tool.mypy.overrides]]
+module = "encoder.*"
+strict = true
+disallow_any_generics = false  # relaxed for SpiralProgram closure builders
+

spiralthink_core-0.9.0/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"