sutra-dev 0.9.2__tar.gz → 0.9.3__tar.gz

{sutra_dev-0.9.2/sutra_dev.egg-info → sutra_dev-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sutra-dev
-Version: 0.9.2
+Version: 0.9.3
 Summary: Compiler for the Sutra programming language — tensor ops on frozen-LLM embedding vectors.
 Author: Emma Leonhart
 License-Expression: AGPL-3.0-only

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sutra-dev"
-version = "0.9.2"
+version = "0.9.3"
 description = "Compiler for the Sutra programming language — tensor ops on frozen-LLM embedding vectors."
 readme = "README.md"
 requires-python = ">=3.11"

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/sutra_compiler/__init__.py

@@ -28,7 +28,7 @@ The compiler is intentionally liberal where the spec is still open
 forms and flags the clearly-forbidden ones.
 """
 
-__version__ = "0.9.2"
+__version__ = "0.9.3"
 
 from .diagnostics import Diagnostic, DiagnosticLevel, DiagnosticBag
 from .lexer import Lexer, Token, TokenKind

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/sutra_compiler/__main__.py

@@ -325,11 +325,24 @@ def _run_execute(path: str, *, runtime_dim: int, runtime_seed: int,
         return 1
     mod = types.ModuleType("_sutra_run")
     mod.__file__ = f"<generated from {path}>"
-    exec(compile(py_src, mod.__file__, "exec"), mod.__dict__)
-    if hasattr(mod, "main") and callable(mod.main):
-        result = mod.main()
-        if result is not None:
-            print(_decode_terminal_result(mod, result))
+    try:
+        exec(compile(py_src, mod.__file__, "exec"), mod.__dict__)
+        if hasattr(mod, "main") and callable(mod.main):
+            result = mod.main()
+            if result is not None:
+                print(_decode_terminal_result(mod, result))
+        else:
+            # The substrate program is the body of main(); a file without one
+            # has nothing to run. Say so rather than exiting silently with no
+            # output (a newcomer otherwise can't tell why nothing happened).
+            print(f"{path}: no main() found - nothing to run", file=sys.stderr)
+    except Exception as exc:
+        # A runtime error in the generated module — e.g. a type mismatch the v0.1
+        # validator can't catch yet — should read like a Sutra diagnostic, not an
+        # uncaught Python traceback. KeyboardInterrupt / SystemExit are not caught
+        # (they subclass BaseException, not Exception), so Ctrl-C still works.
+        print(f"{path}: runtime error: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
     return 0
 
 
@@ -387,7 +400,7 @@ def _run_viz(path: str, *, runtime_dim: int, runtime_seed: int,
     # Inject tracing shim: after the _VSA = _TorchVSA(...) line,
     # wrap every method with a tracing version.
     shim = '''
-# ── Tracing shim (injected by --run-viz) ──
+# -- Tracing shim (injected by --run-viz) --
 _orig_embed = _VSA.embed
 _orig_bind = _VSA.bind
 _orig_unbind = _VSA.unbind
@@ -417,7 +430,7 @@ _VSA.embed = _traced_embed
 _VSA.bind = _traced_bind
 _VSA.unbind = _traced_unbind
 _VSA.bundle = _traced_bundle
-# ── End tracing shim ──
+# -- End tracing shim --
 '''
     # Find the _VSA = _TorchVSA(...) line and inject after it
     lines = py_src.split('\n')
@@ -514,6 +527,19 @@ def main(argv: List[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="sutrac",
         description="Validate Sutra (.su) source files.",
+        epilog=(
+            "interactive REPL:\n"
+            "  sutrac repl          Launch the interactive evaluator (takes no\n"
+            "                       file). Type an expression to see its value;\n"
+            "                       declarations accumulate as session state.\n"
+            "\n"
+            "examples:\n"
+            "  sutrac file.su               Validate a source file.\n"
+            "  sutrac --run file.su         Compile and execute (needs torch).\n"
+            "  sutrac --emit file.su        Print the generated PyTorch module.\n"
+            "  sutrac repl                  Explore interactively."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument(
         "paths",
@@ -541,7 +567,7 @@ def main(argv: List[str] | None = None) -> int:
         help=(
             "Compile the first input file to self-contained torch Python and "
             "print it to stdout. Picks CUDA at module init if available; "
-            "falls back to CPU otherwise. This is the one main codegen target — "
+            "falls back to CPU otherwise. This is the one main codegen target - "
             "PyTorch is the runtime and the tensor-op library Sutra compiles "
             "against."
         ),
@@ -564,7 +590,7 @@ def main(argv: List[str] | None = None) -> int:
             "stdout. The default PyTorch path (--emit/--run) is untouched; this is "
             "the Extropic thermodynamic-sampling compile target (queue.md approach "
             "G). Requires jax + the thrml submodule. Lowering coverage is the "
-            "validated subset only — see codegen_thrml.py."
+            "validated subset only - see codegen_thrml.py."
         ),
     )
     parser.add_argument(

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/sutra_compiler/codegen.py

@@ -1700,7 +1700,7 @@ class Codegen(BaseCodegen):
         self._emit("distinguish `'a'` (97 with flag) from `97` (97 without).")
         self._emit("Arithmetic on chars works the same as on ints — both")
         self._emit("live on the number axis. Downstream code that cares")
-        self._emit("about the distinction can read the flag via `is_char`.")
+        self._emit("about the distinction can read the flag via `is_string`.")
         self._emit('"""')
         self._emit("v = _np.zeros(self.dim, dtype=_np.float64)")
         self._emit("v[self.semantic_dim + self.AXIS_REAL] = float(codepoint)")

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/sutra_compiler/codegen_base.py

@@ -3021,6 +3021,30 @@ class BaseCodegen:
          "char", "Character", "string", "String"}
     )
 
+    #: Types whose values are substrate Strings (text family).
+    _TEXT_TYPES = frozenset({"string", "String", "char", "Character"})
+
+    def _is_text_expr(self, expr: ast.Expr) -> bool:
+        """True iff expr is provably a text (String) value at compile
+        time. Conservative — unknown falls through to the numeric /
+        element-wise `+` paths, same posture as _is_number_expr."""
+        if isinstance(expr, (ast.StringLiteral, ast.CharLiteral,
+                             ast.InterpolatedString)):
+            return True
+        if isinstance(expr, ast.Identifier):
+            return self._var_type.get(expr.name) in self._TEXT_TYPES
+        if isinstance(expr, ast.Parenthesized):
+            return self._is_text_expr(expr.inner)
+        if isinstance(expr, (ast.CastExpr, ast.UnsafeCastExpr)):
+            return (expr.target_type is not None
+                    and expr.target_type.name in self._TEXT_TYPES)
+        if isinstance(expr, ast.BinaryOp) and expr.op == "+":
+            return (self._is_text_expr(expr.left)
+                    and self._is_text_expr(expr.right))
+        if isinstance(expr, ast.Call):
+            return self._resolved_return_type(expr.callee) in self._TEXT_TYPES
+        return False
+
     def _is_synthetic_axis_expr(self, expr: ast.Expr) -> bool:
         """True iff expr is provably a synthetic-axis-encoded value at
         compile time — int, float, complex, scalar, char, or string.
@@ -3380,6 +3404,21 @@ class BaseCodegen:
             )
             if user_op_name is not None:
                 return f"{user_op_name}({left}, {right})"
+            # Text concatenation: `+` with BOTH operands provably text
+            # dispatches to the substrate string_concat (round-17 audit
+            # fix). Without this, lowercase-`string`-typed operands fell
+            # through to ELEMENT-WISE VECTOR ADD — 'ab' + 'cd' silently
+            # summed codepoint axes into garbage — and two string
+            # literals crashed at runtime (host strs reached
+            # string_concat). The String CLASS `operator +` still wins
+            # above for class-typed operands. Literals re-translate with
+            # dest_type="string" so they cross as substrate Strings.
+            if (expr.op == "+" and self.supports_string_runtime
+                    and self._is_text_expr(expr.left)
+                    and self._is_text_expr(expr.right)):
+                lt = self._translate_expr(expr.left, dest_type="string")
+                rt = self._translate_expr(expr.right, dest_type="string")
+                return f"_VSA.string_concat({lt}, {rt})"
             # Logical operators dispatch through the substrate so they
             # work uniformly on bool / fuzzy / trit / truth-axis-vector
             # inputs. Zadeh fuzzy logic — min for AND, max for OR — on
@@ -3589,10 +3628,214 @@ class BaseCodegen:
             return self._embed_expr_src(expr)
         if isinstance(expr, ast.DefuzzyExpr):
             return self._defuzzy_expr_src(expr)
+        if isinstance(expr, ast.InterpolatedString):
+            # `$"hello {s}!"` desugars to a make_string / string_concat
+            # chain — every piece a substrate String, every join a
+            # substrate op (strings.md). Only STRING-TYPED interpolants
+            # are lowerable today: a number/fuzzy interpolant needs the
+            # substrate number→string formatter, which is not built, so
+            # those reject with a steer (same wall as the text casts).
+            if not self.supports_string_runtime:
+                raise CodegenNotSupported(
+                    expr,
+                    "interpolated strings need the substrate String "
+                    "runtime; use the PyTorch backend (codegen_pytorch)."
+                )
+            pieces: list[str] = []
+            for part in expr.parts:
+                if isinstance(part, str):
+                    if part:
+                        pieces.append(f"_VSA.make_string({part!r})")
+                    continue
+                part_t = self._infer_cast_operand_type(part)
+                if self._CAST_FAMILY.get(part_t) == "text":
+                    pieces.append(
+                        self._translate_expr(part, dest_type="string"))
+                    continue
+                if part_t == "int":
+                    # strings.md § Integer formatting: the substrate
+                    # int→string formatter. int ONLY — a fractional
+                    # `number` rendering as its rounded integer would
+                    # silently lie, so it keeps rejecting below.
+                    pieces.append(
+                        f"_VSA.int_to_string("
+                        f"{self._translate_expr(part)})")
+                    continue
+                if part_t is None:
+                    raise CodegenNotSupported(
+                        part,
+                        "interpolated expression must be string- or "
+                        "int-typed and statically inferable — assign it "
+                        "to a `string` (or `int`) variable first, or "
+                        "build the text with make_string / string_concat."
+                    )
+                raise CodegenNotSupported(
+                    part,
+                    f"cannot interpolate a `{part_t}` value: only string- "
+                    "and int-typed interpolants lower (int_to_string is "
+                    "integer-shaped; fractional rendering is not built). "
+                    "For an integer value, declare it `int`; otherwise "
+                    "build the text with make_string / string_concat."
+                )
+            if not pieces:
+                return "_VSA.make_string('')"
+            src = pieces[0]
+            for nxt in pieces[1:]:
+                src = f"_VSA.string_concat({src}, {nxt})"
+            return src
+        if isinstance(expr, ast.UnsafeCastExpr):
+            # types.md § "Casting — relabeling, not transformation":
+            # unsafeCast<T>(x) is ALWAYS the pure relabel — the value
+            # crosses unchanged and only the static type changes. It
+            # never axis-moves; `(fuzzy) n` converts, `unsafeCast<fuzzy>(n)`
+            # reinterprets (truth reading of a real-axis value is 0).
+            return self._translate_expr(expr.expr)
+        if isinstance(expr, ast.UnsafeOverrideExpr):
+            # `unsafeOverride(v)` suppresses a type-check at the call
+            # site and does not change the value — the runtime lowering
+            # is the pure passthrough (same class as unsafeCast, minus
+            # the type argument). Round-19 audit: was the last special
+            # call form with no codegen.
+            return self._translate_expr(expr.expr)
+        if isinstance(expr, ast.CastExpr):
+            return self._translate_cast(expr)
         raise CodegenNotSupported(
             expr, f"unsupported expression: {type(expr).__name__}"
         )
 
+    # ---- cast lowering (types.md § "Casting — relabeling, not
+    # transformation") -------------------------------------------------
+    #
+    # The default cast is a NO-OP relabel: every Sutra value is already a
+    # d-dim substrate vector (or a 0-d number at the entry boundary), and
+    # downstream ops project the axes they need, so relabeling is free.
+    # The ONE genuine axis-move pair is numeric↔truth: a number carries
+    # its value on AXIS_REAL, a fuzzy/bool/trit on AXIS_TRUTH — a pure
+    # relabel would strand the value on the wrong axis and every read
+    # would see 0 (neutral). Text is walled off: number→string needs the
+    # unbuilt substrate formatter; string→vector is the spec's "embedding
+    # cast" whose real implementation is `embed()` at the entry boundary.
+
+    #: Sutra type name → cast family. Types not in the map (user classes,
+    #: generics) relabel as "geometric" — the spec's free no-op default.
+    _CAST_FAMILY = {
+        "int": "number", "number": "number",
+        "fuzzy": "truth", "bool": "truth", "trit": "truth",
+        "complex": "geometric", "vector": "geometric", "role": "geometric",
+        "matrix": "geometric",
+        "string": "text", "String": "text",
+        "char": "text", "Character": "text",
+    }
+
+    #: Whether this backend's runtime carries the numeric↔truth cast
+    #: helpers (cast_number_to_truth / cast_truth_to_number / _cnum).
+    #: The deprecated numpy backend does not; it keeps rejecting casts.
+    supports_cast_lowering = False
+
+    #: Whether this backend's runtime carries the substrate String ops
+    #: (make_string / string_concat). Gates InterpolatedString lowering;
+    #: the deprecated numpy backend has no String runtime.
+    supports_string_runtime = False
+
+    def _infer_cast_operand_type(self, expr: ast.Expr) -> str | None:
+        """Conservative static type of a cast operand: literals, typed
+        locals/params (via _var_type), nested casts, parenthesized
+        exprs. None when unknown — the caller decides whether the
+        target makes the relabel/axis-move distinction load-bearing."""
+        from .symbol_table import _LITERAL_TYPES
+        kind = type(expr).__name__
+        if kind in _LITERAL_TYPES:
+            return _LITERAL_TYPES[kind]
+        if isinstance(expr, ast.Identifier):
+            return self._var_type.get(expr.name)
+        if isinstance(expr, (ast.CastExpr, ast.UnsafeCastExpr)):
+            return expr.target_type.name if expr.target_type else None
+        if type(expr).__name__ == "Parenthesized" and hasattr(expr, "inner"):
+            return self._infer_cast_operand_type(expr.inner)
+        if isinstance(expr, ast.BinaryOp):
+            if expr.op in ("==", "!=", "<", ">", "<=", ">=", "&&", "||"):
+                return "bool"
+            if expr.op in ("+", "-", "*", "/", "%"):
+                lt = self._infer_cast_operand_type(expr.left)
+                rt = self._infer_cast_operand_type(expr.right)
+                if (self._CAST_FAMILY.get(lt) == "number"
+                        and self._CAST_FAMILY.get(rt) == "number"):
+                    return "number"
+        return None
+
+    def _translate_cast(self, expr: ast.CastExpr) -> str:
+        if not self.supports_cast_lowering:
+            raise CodegenNotSupported(
+                expr,
+                "`(Type) expr` casts are not supported by this backend; "
+                "use the PyTorch backend (codegen_pytorch)."
+            )
+        dst = expr.target_type.name if expr.target_type else None
+        dst_family = self._CAST_FAMILY.get(dst, "geometric")
+        src = self._infer_cast_operand_type(expr.expr)
+        src_family = self._CAST_FAMILY.get(src, "geometric") if src else None
+
+        # --- text walls -------------------------------------------------
+        if dst_family == "text" and src_family != "text":
+            if src == "int":
+                # strings.md § Integer formatting: `(string) n` on an
+                # int is the integer formatter — the one number→text
+                # cast with a real substrate implementation.
+                return (f"_VSA.int_to_string("
+                        f"{self._translate_expr(expr.expr)})")
+            raise CodegenNotSupported(
+                expr,
+                f"cannot cast to `{dst}`: only `int` values format "
+                "(int_to_string — integer-shaped; fractional rendering is "
+                "not built). For a literal, use `make_string(\"...\")`; "
+                "join strings with `string_concat`."
+            )
+        if src_family == "text" and dst_family != "text":
+            if dst_family == "geometric":
+                raise CodegenNotSupported(
+                    expr,
+                    f"cannot cast a string to `{dst}`: that is the embedding "
+                    "cast, and its implementation is `embed(...)` at the "
+                    "program boundary — a String vector encodes codepoints, "
+                    "not semantics."
+                )
+            raise CodegenNotSupported(
+                expr,
+                f"cannot cast a string to `{dst}`: a String vector encodes "
+                "packed codepoints, so its numeric axes are not a number. "
+                "Use the string operations (string_length, char_at, ...) "
+                "instead."
+            )
+
+        inner = self._translate_expr(expr.expr)
+
+        # --- same family / text→text: the free relabel --------------------
+        if src_family == dst_family:
+            return inner
+
+        # --- the one genuine axis-move pair -------------------------------
+        if src_family == "number" and dst_family == "truth":
+            return f"_VSA.cast_number_to_truth({inner})"
+        if src_family == "truth" and dst_family == "number":
+            return f"_VSA.cast_truth_to_number({inner})"
+
+        # --- unknown source: only reject when the move/relabel choice
+        # --- is load-bearing (truth/number targets read a single axis) ----
+        if src_family is None and dst_family in ("truth", "number"):
+            raise CodegenNotSupported(
+                expr,
+                f"cannot cast to `{dst}` here: the operand's static type "
+                "can't be inferred, and truth/number casts need it to pick "
+                "between relabel and axis-move. Assign the operand to a "
+                "typed variable first."
+            )
+
+        # --- every remaining pair relabels; _cnum canonicalizes a 0-d
+        # --- number at the entry boundary and passes vectors through ------
+        if src_family == "number" or src is None:
+            return f"_VSA._cnum({inner})"
+        return inner
+
     def _embed_expr_src(self, expr: ast.EmbedExpr) -> str:
         """Override point for per-backend `embed(<expr>)` lowering.
 

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/sutra_compiler/codegen_pytorch.py

@@ -49,6 +49,15 @@ class PyTorchCodegen(Codegen):
     _as_truth_vector.
     """
 
+    # The torch runtime carries the numeric↔truth cast helpers
+    # (cast_number_to_truth / cast_truth_to_number / _cnum), so `(Type)`
+    # cast lowering is live on this backend (types.md § Casting).
+    supports_cast_lowering = True
+
+    # The torch runtime carries the substrate String ops (make_string /
+    # string_concat), so InterpolatedString lowering is live here.
+    supports_string_runtime = True
+
     # The numpy `Codegen` lists the immutable list ops (array_concat /
     # array_map / array_filter) as unsupported — it has no runtime methods
     # for them. The PyTorch runtime DOES implement them (Emma 2026-06-20),
@@ -2772,14 +2781,8 @@ class PyTorchCodegen(Codegen):
         self._emit("return self.make_string(chr(int(codepoint)))")
         self._indent -= 1
         self._emit()
-        self._emit("def is_char(self, v):")
-        self._indent += 1
-        self._emit('"""True iff v is a String value (kept as `is_char` for')
-        self._emit('backward-compat with code that pre-dated the rename to')
-        self._emit('AXIS_STRING_FLAG; new code should use is_string)."""')
-        self._emit("return bool(v[self.semantic_dim + self.AXIS_STRING_FLAG].item() >= 0.5)")
-        self._indent -= 1
-        self._emit()
+        # `is_char` (a pure alias of is_string) retired 2026-07-08 —
+        # zero call sites; CLAUDE.md § "Deprecate aliases aggressively".
         self._emit("# ---- String runtime methods ----")
         self._emit("# Encoding: AXIS_STRING_FLAG marks the vector as a String.")
         self._emit("# Characters pack into the synthetic axes — char[0] at")
@@ -2828,7 +2831,16 @@ class PyTorchCodegen(Codegen):
         self._emit()
         self._emit("def make_string(self, s):")
         self._indent += 1
-        self._emit('"""Construct a String value from a Python str."""')
+        self._emit('"""Construct a String value from a Python str. IDEMPOTENT on an')
+        self._emit('already-String vector: the type-coercion pass can wrap a String-typed')
+        self._emit("initializer in make_string even when it is already a String (e.g.")
+        self._emit('`String g = make_string(\"hi\")`), so a double make_string must return')
+        self._emit('the value unchanged, not `str(tensor)`-encode its repr as text."""')
+        self._emit("if _torch.is_tensor(s) and s.ndim >= 1 and "
+                   "s.shape[-1] == self.dim and bool(self.is_string(s)):")
+        self._indent += 1
+        self._emit("return s")
+        self._indent -= 1
         self._emit("if not isinstance(s, str):")
         self._indent += 1
         self._emit("s = str(s)")
@@ -3257,6 +3269,57 @@ class PyTorchCodegen(Codegen):
         self._emit("return v")
         self._indent -= 1
         self._emit()
+        self._emit("def _i2s_pows(self):")
+        self._indent += 1
+        self._emit('"""Cached power-of-10 table for int_to_string digit')
+        self._emit('extraction. Length = the dtype exactness bound (7 digits')
+        self._emit('float32, 15 float64) — beyond it the input integer is')
+        self._emit('already inexact in the dtype."""')
+        self._emit("if not hasattr(self, '_i2s_pows_cache') or self._i2s_pows_cache is None:")
+        self._indent += 1
+        self._emit("D = 15 if self.dtype == _torch.float64 else 7")
+        self._emit("self._i2s_pows_cache = 10.0 ** _torch.arange("
+                   "D, dtype=self.dtype, device=self.device)")
+        self._indent -= 1
+        self._emit("return self._i2s_pows_cache")
+        self._indent -= 1
+        self._emit()
+        self._emit("def int_to_string(self, x):")
+        self._indent += 1
+        self._emit('"""Render an integer NUMBER as a substrate String — the')
+        self._emit("number->string formatter (strings.md § Integer formatting).")
+        self._emit("Digit extraction is MOD-FREE (Math.mod is banned; measured")
+        self._emit("vector-collapse): digit_k = floor(a/10^k) - 10*floor(a/10^(k+1)).")
+        self._emit("Leading zeros gate on the quotient-significance mask (0 renders")
+        self._emit("'0'); negatives gate codepoint 45 into slot 0 and shift digits")
+        self._emit("right by one — a gather by shifted index, the same VSA-native")
+        self._emit("permutation string_concat uses. round() first: the INT contract.")
+        self._emit("Exact within the dtype bound (7 digits float32 / 15 float64);")
+        self._emit('beyond it output is valid-but-unspecified (input already inexact)."""')
+        self._emit("a0 = self._scalar(x)")
+        self._emit("neg = (a0 < 0).to(self.dtype)")
+        self._emit("a = _torch.round(_torch.abs(a0))")
+        self._emit("pows = self._i2s_pows()")
+        self._emit("D = pows.shape[0]")
+        self._emit("q = _torch.floor(a / pows)")
+        self._emit("qn = _torch.floor(a / (pows * 10.0))")
+        self._emit("digits = q - 10.0 * qn")
+        self._emit("nd = _torch.clamp((q > 0).to(self.dtype).sum(), min=1.0)")
+        self._emit("ax = self._str_axes()")
+        self._emit("n = ax.shape[0]")
+        self._emit("idx = _torch.arange(n, dtype=self.dtype, device=self.device)")
+        self._emit("place = nd - 1.0 - (idx - neg)")
+        self._emit("valid = ((place >= 0) & (place < D) & (idx - neg >= 0))"
+                   ".to(self.dtype)")
+        self._emit("gath = digits[place.clamp(0, D - 1).long()]")
+        self._emit("out_cps = valid * (48.0 + gath) + "
+                   "(idx == 0).to(self.dtype) * neg * 45.0")
+        self._emit("v = _torch.zeros(self.dim, dtype=self.dtype, device=self.device)")
+        self._emit("v[self.semantic_dim + self.AXIS_STRING_FLAG] = 1.0")
+        self._emit("v = v.index_copy(0, ax, out_cps)")
+        self._emit("return v")
+        self._indent -= 1
+        self._emit()
         self._emit("def string_to_python(self, v):")
         self._indent += 1
         self._emit('"""Decode a String value back to a Python str. This is the')
@@ -3459,6 +3522,41 @@ class PyTorchCodegen(Codegen):
         self._emit("return self._t_from_r_cache")
         self._indent -= 1
         self._emit()
+        self._emit("def _real_from_truth(self):")
+        self._indent += 1
+        self._emit('"""Matrix moving the truth-axis entry to the real axis')
+        self._emit('(cached; the inverse-direction mate of _truth_from_real)."""')
+        self._emit("if not hasattr(self, '_r_from_t_cache') or self._r_from_t_cache is None:")
+        self._indent += 1
+        self._emit("M = _torch.zeros((self.dim, self.dim), dtype=self.dtype, device=self.device)")
+        self._emit("M[self.semantic_dim + self.AXIS_REAL,")
+        self._indent += 1
+        self._emit("self.semantic_dim + self.AXIS_TRUTH] = 1.0")
+        self._indent -= 1
+        self._emit("self._r_from_t_cache = M")
+        self._indent -= 1
+        self._emit("return self._r_from_t_cache")
+        self._indent -= 1
+        self._emit()
+        self._emit("def cast_number_to_truth(self, x):")
+        self._indent += 1
+        self._emit('"""`(fuzzy|bool|trit) NUMBER` — the numeric→truth cast')
+        self._emit("(types.md § Casting): the one cast pair that genuinely")
+        self._emit("moves an axis. _cnum lifts a 0-d/host number onto AXIS_REAL")
+        self._emit("(entry boundary), then a cached permutation-style matmul")
+        self._emit('moves that entry to AXIS_TRUTH. Pure tensor ops throughout."""')
+        self._emit("return self._truth_from_real() @ self._cnum(x)")
+        self._indent -= 1
+        self._emit()
+        self._emit("def cast_truth_to_number(self, x):")
+        self._indent += 1
+        self._emit('"""`(number|int) TRUTH` — the truth→numeric cast: moves the')
+        self._emit("AXIS_TRUTH entry to AXIS_REAL by the cached inverse-direction")
+        self._emit('matmul. Truth values are canonical d-dim vectors (make_truth),')
+        self._emit('which _cnum passes through unchanged."""')
+        self._emit("return self._real_from_truth() @ self._cnum(x)")
+        self._indent -= 1
+        self._emit()
         self._emit("CMP_SLOPE = 100.0")
         self._emit()
         self._emit("def gt(self, a, b):")

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/sutra_compiler/embedding.py

@@ -79,10 +79,18 @@ def _get_st_model(model: str):
             file=sys.stderr,
             flush=True,
         )
+    import contextlib
+    import sys
+
     from sentence_transformers import SentenceTransformer
 
-    # nomic-bert ships custom modeling code, hence trust_remote_code.
-    st = SentenceTransformer(hf_id, trust_remote_code=True)
+    # nomic-bert ships custom modeling code, hence trust_remote_code. That load
+    # (and sentence-transformers itself) prints framework chatter to stdout —
+    # e.g. "<All keys matched successfully>" from the state-dict load — which
+    # would pollute a program's stdout (main()'s output, or --emit). Route any
+    # such load-time output to stderr, where our own notice already goes.
+    with contextlib.redirect_stdout(sys.stderr):
+        st = SentenceTransformer(hf_id, trust_remote_code=True)
     _ST_CACHE[hf_id] = st
     return st
 

{sutra_dev-0.9.2 → sutra_dev-0.9.3}/sutra_compiler/fv.py

@@ -37,7 +37,20 @@ from .fv_obligation_checker import (
     range_sound_by_composition,
     reduces_to_same_graph,
 )
+from .fv_loop_convergence import (
+    ASYMPTOTICALLY_STABLE,
+    MARGINALLY_STABLE,
+    UNSTABLE,
+    LoopConvergenceReport,
+    analyze_loop_recurrence,
+)
 from .fv_poly_bound import RangeBound, bound_polynomial_over_box
+from .fv_sampler_convergence import (
+    SamplerConvergenceReport,
+    analyze_sampler_convergence,
+    integrate_master_equation,
+    measured_decay_rate,
+)
 
 __all__ = [
     # polynomial range bounding (the §3.2 branch-range obligation)
@@ -52,4 +65,15 @@ __all__ = [
     # extraction + the verifiable-fragment boundary
     "extract_truth_polynomial",
     "NonPolynomialResidual",
+    # loop-convergence obligation via the Z-transform poles (the §3.3 linear core)
+    "analyze_loop_recurrence",
+    "LoopConvergenceReport",
+    "ASYMPTOTICALLY_STABLE",
+    "MARGINALLY_STABLE",
+    "UNSTABLE",
+    # continuous-time convergence of the probabilistic sampler (the §7 SDE angle)
+    "analyze_sampler_convergence",
+    "SamplerConvergenceReport",
+    "integrate_master_equation",
+    "measured_decay_rate",
 ]