starforge-kernel 0.1.0__tar.gz

starforge_kernel-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: starforge-kernel
+Version: 0.1.0
+Summary: *Forge — pipeline canvas, checkpointing, and stale/hydrate execution for the repo you already have open
+Author: Jonathan Potter
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Jonpot/forge
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pandas>=2.0; extra == "dev"
+Requires-Dist: pyarrow>=15.0; extra == "dev"
+Requires-Dist: numpy>=1.26; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.8; extra == "mcp"
+
+# *Forge (`starforge`)
+
+Forge's canvas — checkpointing, provenance, stale/hydrate execution — as a VS Code
+extension over the repo you already have open. Blocks are ordinary Python functions
+tagged with `@block`. See [DESIGN.md](DESIGN.md) for the full design.
+
+## Try it (M0)
+
+```bash
+# 1. Install the kernel + decorator into the venv your target repo uses
+pip install -e <forge-repo>/starforge
+
+# 2. Build the extension
+cd <forge-repo>/starforge/vscode
+npm install && npm run build
+
+# 3. Open starforge/vscode in VS Code and press F5 (extension dev host).
+#    In the dev-host window, open any Python repo.
+```
+
+In your repo:
+
+```python
+# analysis/blocks.py
+import matplotlib.pyplot as plt
+from starforge import block
+
+@block(category="IO")
+def make_numbers(n: int = 5) -> dict:
+    return {"values": list(range(1, n + 1))}
+
+@block
+def scale(data: dict, factor: float = 2.0) -> dict:
+    return {"values": [v * factor for v in data["values"]]}
+
+@block
+def plot(data: dict) -> dict:
+    plt.plot(data["values"])
+    plt.show()  # rendered inline on the canvas node
+    return data
+```
+
+Save, run **“*Forge: New Pipeline”**, drag the blocks from the palette, wire
+`output → data`, hit **▶ Run**. Run again — instant, everything reused. Edit
+`scale`, watch it (and only it) go stale.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/starforge/__init__.py` | the `@block` decorator — zero-dep, the only thing user code touches |
+| `src/starforge/index/` | static AST indexer (discovery, import graph, incremental cache) |
+| `src/starforge/core/` | doc schema, history hashing, serializers, checkpoint store, runner |
+| `src/starforge/kernel/` | stdio JSON-RPC kernel + per-run worker subprocess |
+| `vscode/` | the extension (TS host + React Flow webview) |
+| `tests/` | headless M0 proof — `python -m pytest starforge/tests` |
+
+State lives in the target repo under `.forge/` — `pipelines/` is committable,
+`checkpoints/` and `cache/` are auto-gitignored.

starforge_kernel-0.1.0/README.md

@@ -0,0 +1,59 @@
+# *Forge (`starforge`)
+
+Forge's canvas — checkpointing, provenance, stale/hydrate execution — as a VS Code
+extension over the repo you already have open. Blocks are ordinary Python functions
+tagged with `@block`. See [DESIGN.md](DESIGN.md) for the full design.
+
+## Try it (M0)
+
+```bash
+# 1. Install the kernel + decorator into the venv your target repo uses
+pip install -e <forge-repo>/starforge
+
+# 2. Build the extension
+cd <forge-repo>/starforge/vscode
+npm install && npm run build
+
+# 3. Open starforge/vscode in VS Code and press F5 (extension dev host).
+#    In the dev-host window, open any Python repo.
+```
+
+In your repo:
+
+```python
+# analysis/blocks.py
+import matplotlib.pyplot as plt
+from starforge import block
+
+@block(category="IO")
+def make_numbers(n: int = 5) -> dict:
+    return {"values": list(range(1, n + 1))}
+
+@block
+def scale(data: dict, factor: float = 2.0) -> dict:
+    return {"values": [v * factor for v in data["values"]]}
+
+@block
+def plot(data: dict) -> dict:
+    plt.plot(data["values"])
+    plt.show()  # rendered inline on the canvas node
+    return data
+```
+
+Save, run **“*Forge: New Pipeline”**, drag the blocks from the palette, wire
+`output → data`, hit **▶ Run**. Run again — instant, everything reused. Edit
+`scale`, watch it (and only it) go stale.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/starforge/__init__.py` | the `@block` decorator — zero-dep, the only thing user code touches |
+| `src/starforge/index/` | static AST indexer (discovery, import graph, incremental cache) |
+| `src/starforge/core/` | doc schema, history hashing, serializers, checkpoint store, runner |
+| `src/starforge/kernel/` | stdio JSON-RPC kernel + per-run worker subprocess |
+| `vscode/` | the extension (TS host + React Flow webview) |
+| `tests/` | headless M0 proof — `python -m pytest starforge/tests` |
+
+State lives in the target repo under `.forge/` — `pipelines/` is committable,
+`checkpoints/` and `cache/` are auto-gitignored.

starforge_kernel-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# PyPI name `starforge` is squatted by a dormant Galaxy tool (see DESIGN.md §4);
+# the import name is still `starforge`.
+name = "starforge-kernel"
+version = "0.1.0"
+description = "*Forge — pipeline canvas, checkpointing, and stale/hydrate execution for the repo you already have open"
+readme = "README.md"
+authors = [{ name = "Jonathan Potter" }]
+license = "Apache-2.0"
+requires-python = ">=3.10"
+# Intentionally empty: the decorator must import in microseconds inside user
+# production code, and the kernel runs stdlib-only. pandas/numpy/pyarrow are
+# probed lazily in workers and used only if the workspace env provides them.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Jonpot/forge"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pandas>=2.0", "pyarrow>=15.0", "numpy>=1.26"]
+mcp = ["mcp>=1.8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

starforge_kernel-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starforge_kernel-0.1.0/src/starforge/__init__.py

@@ -0,0 +1,86 @@
+"""*Forge — pipeline canvas for the repo you already have open.
+
+This top-level module is the entire public surface that user code touches.
+It must import in microseconds and depend on nothing: the decorator lives in
+production codebases and has to be free. Everything heavy (indexer, engine,
+kernel) lives in submodules that only *Forge itself* imports.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["block", "progress", "BLOCK_ATTR"]
+
+#: Attribute set on decorated functions. The AST indexer matches the decorator
+#: syntactically and never imports user code; this runtime tag exists so user
+#: code and future runtime introspection can also recognize blocks.
+BLOCK_ATTR = "__starforge_block__"
+
+
+def block(fn=None, *, label=None, category=None, outputs=None):
+    """Register a function as a *Forge block.
+
+    Usable bare or with keyword arguments::
+
+        @block
+        def clean(raw: pd.DataFrame) -> pd.DataFrame: ...
+
+        @block(label="Clean AUC Matrix", category="QC", outputs=("clean", "stats"))
+        def clean_auc(raw, min_coverage: float = 0.8): ...
+
+    The decorated function is returned unchanged — behavior under pytest, in
+    CI, or in production is identical whether or not *Forge is anywhere near.
+
+    Args:
+        label: Palette display name. Defaults to the function name, title-cased.
+        category: Palette grouping. Defaults to the defining module's path.
+        outputs: Names for multiple return values (function must return a tuple
+            of the same length). Defaults to a single output named "output".
+
+    Note for palette metadata: the indexer reads ``label``/``category``/
+    ``outputs`` from the *source*, so they must be literals at the decoration
+    site to appear in the palette.
+    """
+
+    def apply(f):
+        setattr(
+            f,
+            BLOCK_ATTR,
+            {
+                "label": label,
+                "category": category,
+                "outputs": tuple(outputs) if outputs is not None else None,
+            },
+        )
+        return f
+
+    if fn is not None:
+        return apply(fn)
+    return apply
+
+
+#: Installed by the *Forge run worker around each block call; None everywhere
+#: else, which keeps progress() a guaranteed no-op in pytest/CI/production.
+_progress_hook = None
+
+
+def progress(current=None, total=None, label=None):
+    """Report block progress to the *Forge canvas.
+
+    Call freely inside a block::
+
+        for i, chunk in enumerate(chunks):
+            progress(i + 1, len(chunks), "fitting folds")
+            ...
+
+    Outside a *Forge run this does nothing and costs one attribute read —
+    safe to leave in production code. Any combination of arguments works:
+    (current, total) renders a determinate bar, label alone updates the text.
+    """
+    hook = _progress_hook
+    if hook is not None:
+        try:
+            hook(current, total, label)
+        except Exception:
+            pass  # progress must never break user code

starforge_kernel-0.1.0/src/starforge/core/checkpoints.py

@@ -0,0 +1,178 @@
+"""Checkpoint store under ``<workspace>/.forge/checkpoints/``.
+
+One directory per history hash (truncated to 32 hex chars — 128 bits — to
+stay friendly to Windows path limits):
+
+    .forge/checkpoints/<hash32>/
+    ├── provenance.json     # written LAST: its presence marks completeness
+    └── outputs/<name>.<ext per serializer>
+
+The store also owns ``.forge/.gitignore`` so checkpoints and caches never
+land in the user's repo history while ``pipelines/`` remains committable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import time
+from typing import Any
+
+from starforge.core import figures as figmod
+from starforge.core import previews, serializers
+
+FORGE_DIR = ".forge"
+GITIGNORE_BODY = "checkpoints/\ncache/\n"
+
+
+class CheckpointStore:
+    def __init__(self, workspace: str | Path) -> None:
+        self.workspace = Path(workspace)
+        self.forge_dir = self.workspace / FORGE_DIR
+        self.base = self.forge_dir / "checkpoints"
+
+    def ensure_layout(self) -> None:
+        (self.forge_dir / "pipelines").mkdir(parents=True, exist_ok=True)
+        (self.forge_dir / "cache").mkdir(parents=True, exist_ok=True)
+        self.base.mkdir(parents=True, exist_ok=True)
+        gitignore = self.forge_dir / ".gitignore"
+        if not gitignore.exists():
+            gitignore.write_text(GITIGNORE_BODY, encoding="utf-8")
+
+    def dir_for(self, history_hash: str) -> Path:
+        return self.base / history_hash[:32]
+
+    def exists(self, history_hash: str) -> bool:
+        return (self.dir_for(history_hash) / "provenance.json").is_file()
+
+    def read_provenance(self, history_hash: str) -> dict[str, Any]:
+        path = self.dir_for(history_hash) / "provenance.json"
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def write(
+        self,
+        history_hash: str,
+        provenance: dict[str, Any],
+        outputs: dict[str, Any],
+        pickle_enabled: bool = False,
+        side_figures: list[Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Persist outputs then provenance (in that order, for atomicity).
+        Returns the output manifest, including ephemeral entries.
+
+        ``side_figures`` are figures the block created or showed without
+        returning them (plt.show() and friends); they render to artifacts
+        recorded under the provenance ``figures`` key."""
+        directory = self.dir_for(history_hash)
+        outputs_dir = directory / "outputs"
+        directory.mkdir(parents=True, exist_ok=True)
+        manifest = []
+        for name, value in outputs.items():
+            entry = serializers.save_value(value, outputs_dir, name, pickle_enabled=pickle_enabled)
+            try:
+                # Previews ride inside provenance.json so the stdlib-only
+                # kernel can serve them without deserializing data. Computed
+                # for ephemeral outputs too — their only window is right now.
+                if entry.get("artifact"):
+                    entry["preview"] = {
+                        "kind": "figure",
+                        "file": entry["artifact"]["file"],
+                        "format": entry["artifact"]["kind"],
+                    }
+                else:
+                    entry["preview"] = previews.build_preview(value)
+            except Exception:
+                entry["preview"] = {"kind": "text", "text": f"<preview failed for {type(value).__name__}>"}
+            manifest.append(entry)
+
+        rendered_figures: list[dict[str, Any]] = []
+        for i, fig in enumerate(side_figures or []):
+            try:
+                artifact = figmod.render_figure(fig, outputs_dir, f"figure_{i}")
+            except Exception:
+                artifact = None
+            if artifact is not None:
+                rendered_figures.append(artifact)
+
+        record = dict(provenance)
+        record["history_hash"] = history_hash
+        record["outputs"] = manifest
+        record["figures"] = rendered_figures
+        record["dir"] = directory.relative_to(self.workspace).as_posix()
+        path = directory / "provenance.json"
+        tmp = directory / "provenance.json.tmp"
+        tmp.write_text(json.dumps(record, indent=2, default=repr), encoding="utf-8")
+        tmp.replace(path)
+        return manifest
+
+    def output_entry(self, history_hash: str, name: str) -> dict[str, Any]:
+        for entry in self.read_provenance(history_hash).get("outputs", []):
+            if entry.get("name") == name:
+                return entry
+        raise KeyError(f"checkpoint {history_hash[:12]} has no output named '{name}'")
+
+    def load_output(self, history_hash: str, name: str) -> Any:
+        """Raises serializers.EphemeralValueError for non-persisted outputs."""
+        entry = self.output_entry(history_hash, name)
+        return serializers.load_value(self.dir_for(history_hash) / "outputs", entry)
+
+    def is_ephemeral(self, history_hash: str, name: str) -> bool:
+        try:
+            entry = self.output_entry(history_hash, name)
+        except (KeyError, FileNotFoundError, json.JSONDecodeError):
+            return True
+        return entry.get("serializer") == serializers.EPHEMERAL
+
+    def touch(self, history_hash: str) -> None:
+        """Bump the checkpoint dir's mtime so LRU GC sees reuse as recency."""
+        try:
+            os.utime(self.dir_for(history_hash))
+        except OSError:
+            pass
+
+    def gc(self, max_bytes: int) -> dict[str, int]:
+        """Least-recently-used eviction down to ``max_bytes`` total.
+
+        Deleting a live checkpoint is always safe — the node just reads as
+        stale and recomputes — so a plain LRU needs no liveness analysis.
+        Returns {"freed_bytes", "deleted", "remaining_bytes"}.
+        """
+        entries: list[tuple[float, int, Path]] = []
+        total = 0
+        if self.base.is_dir():
+            for directory in self.base.iterdir():
+                if not directory.is_dir():
+                    continue
+                size = sum(f.stat().st_size for f in directory.rglob("*") if f.is_file())
+                try:
+                    mtime = directory.stat().st_mtime
+                except OSError:
+                    continue
+                entries.append((mtime, size, directory))
+                total += size
+
+        freed = 0
+        deleted = 0
+        entries.sort()  # oldest first
+        for _mtime, size, directory in entries:
+            if total - freed <= max_bytes:
+                break
+            shutil.rmtree(directory, ignore_errors=True)
+            freed += size
+            deleted += 1
+        return {"freed_bytes": freed, "deleted": deleted, "remaining_bytes": total - freed}
+
+    def clean_run_specs(self, max_age_seconds: float = 86400.0) -> None:
+        """Run-spec files are one-shot worker inputs; sweep the stale ones."""
+        runs_dir = self.forge_dir / "cache" / "runs"
+        if not runs_dir.is_dir():
+            return
+        cutoff = time.time() - max_age_seconds
+        for spec in runs_dir.glob("*.json"):
+            try:
+                if spec.stat().st_mtime < cutoff:
+                    spec.unlink()
+            except OSError:
+                continue

starforge_kernel-0.1.0/src/starforge/core/figures.py

@@ -0,0 +1,119 @@
+"""Figure capture and artifact rendering.
+
+The notebook muscle memory is ``plt.plot(...); plt.show()`` — or no show()
+at all. The worker honors it with zero code changes: matplotlib runs on the
+Agg backend, and :func:`capture` sweeps every figure that exists after the
+block call that didn't exist before (``plt.show`` is a no-op under Agg, so
+"shown" figures are still open when we sweep). Plotly's ``fig.show()`` is
+intercepted by patching ``plotly.io.show`` while the block runs.
+
+Captured and returned figures render to checkpoint artifacts — matplotlib →
+PNG, plotly → self-contained HTML — and are closed afterward so a long run
+never accumulates canvases.
+
+Import discipline: stdlib-only at import time; matplotlib/plotly are only
+touched when the user's process already loaded them.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+import sys
+from typing import Any, Iterator
+
+
+def _pyplot() -> Any | None:
+    return sys.modules.get("matplotlib.pyplot")
+
+
+def _root_module(value: Any) -> str:
+    return type(value).__module__.split(".")[0]
+
+
+@dataclass
+class CapturedFigures:
+    matplotlib: list[Any] = field(default_factory=list)
+    plotly: list[Any] = field(default_factory=list)
+
+    def all_objects(self) -> list[Any]:
+        return [*self.matplotlib, *self.plotly]
+
+
+@contextmanager
+def capture() -> Iterator[CapturedFigures]:
+    """Collect figures created (matplotlib) or shown (plotly) inside the
+    block call. The matplotlib sweep also catches figures created during the
+    block module's first import, since the import happens inside this
+    context in the runner."""
+    captured = CapturedFigures()
+
+    plt = _pyplot()
+    before: set[int] = set(plt.get_fignums()) if plt is not None else set()
+
+    pio = sys.modules.get("plotly.io")
+    original_show = getattr(pio, "show", None) if pio is not None else None
+    if pio is not None and original_show is not None:
+
+        def _grab(fig: Any, *args: Any, **kwargs: Any) -> None:
+            captured.plotly.append(fig)
+
+        pio.show = _grab
+
+    try:
+        yield captured
+    finally:
+        if pio is not None and original_show is not None:
+            pio.show = original_show
+        plt = _pyplot()  # may have been imported during the call
+        if plt is not None:
+            for num in plt.get_fignums():
+                if num not in before:
+                    captured.matplotlib.append(plt.figure(num))
+
+
+def as_figure(value: Any) -> Any | None:
+    """Return a renderable figure for ``value``, or None.
+
+    Accepts matplotlib Figures, matplotlib Axes (``sns.heatmap`` et al.
+    return Axes — we render their parent figure), and plotly figures.
+    """
+    root = _root_module(value)
+    if root == "matplotlib":
+        if hasattr(value, "savefig"):
+            return value
+        parent = getattr(value, "figure", None)  # Axes and friends
+        if parent is not None and hasattr(parent, "savefig"):
+            return parent
+    if root == "plotly" and hasattr(value, "write_html"):
+        return value
+    return None
+
+
+def render_figure(value: Any, directory: Path, basename: str) -> dict[str, Any] | None:
+    """Render to ``directory/basename.(png|html)``; returns the artifact
+    entry ``{"file", "kind"}`` or None if ``value`` is not a figure."""
+    fig = as_figure(value)
+    if fig is None:
+        return None
+    directory.mkdir(parents=True, exist_ok=True)
+    if _root_module(fig) == "matplotlib":
+        filename = f"{basename}.png"
+        fig.savefig(directory / filename, dpi=110, bbox_inches="tight", facecolor=fig.get_facecolor())
+        return {"file": filename, "kind": "image"}
+    filename = f"{basename}.html"
+    fig.write_html(directory / filename, include_plotlyjs=True, full_html=True)
+    return {"file": filename, "kind": "html"}
+
+
+def close_figures(figures: list[Any]) -> None:
+    plt = _pyplot()
+    if plt is None:
+        return
+    for fig in figures:
+        if _root_module(fig) == "matplotlib":
+            try:
+                plt.close(fig)
+            except Exception:
+                pass

starforge_kernel-0.1.0/src/starforge/core/previews.py

@@ -0,0 +1,109 @@
+"""Cropped, JSON-safe output previews, computed at checkpoint-write time.
+
+Previews are precomputed artifacts stored inside ``provenance.json`` — the
+kernel serves them by reading a file, never by deserializing data (it stays
+stdlib-only and instant). Because they're built while the value is in the
+worker's hands, even EPHEMERAL outputs get a preview of their last run.
+
+Everything emitted here must survive strict JSON.parse on the TypeScript
+side: NaN/Infinity are stringified, containers are size-capped, and unknown
+objects fall back to repr.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+MAX_ROWS = 8
+MAX_COLS = 10
+MAX_ITEMS = 50
+MAX_DEPTH = 5
+MAX_CELL_CHARS = 120
+MAX_TEXT_CHARS = 600
+MAX_VALUE_CHARS = 2000
+
+
+def _cell(value: Any) -> Any:
+    """One scalar table/array cell, strict-JSON safe."""
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return value if value == value and abs(value) != float("inf") else str(value)
+    text = value if isinstance(value, str) else repr(value)
+    return text[:MAX_CELL_CHARS] + ("…" if len(text) > MAX_CELL_CHARS else "")
+
+
+def _sanitize(value: Any, depth: int = 0) -> Any:
+    if depth >= MAX_DEPTH:
+        return _cell(value)
+    if isinstance(value, dict):
+        items = list(value.items())[:MAX_ITEMS]
+        out = {str(k)[:MAX_CELL_CHARS]: _sanitize(v, depth + 1) for k, v in items}
+        if len(value) > MAX_ITEMS:
+            out["…"] = f"+{len(value) - MAX_ITEMS} more"
+        return out
+    if isinstance(value, (list, tuple)):
+        out = [_sanitize(v, depth + 1) for v in value[:MAX_ITEMS]]
+        if len(value) > MAX_ITEMS:
+            out.append(f"… +{len(value) - MAX_ITEMS} more")
+        return out
+    return _cell(value)
+
+
+def _root_type_module(value: Any) -> str:
+    return type(value).__module__.split(".")[0]
+
+
+def build_preview(value: Any) -> dict[str, Any]:
+    if _root_type_module(value) == "pandas":
+        import pandas as pd
+
+        frame = value.to_frame() if isinstance(value, pd.Series) else value
+        if isinstance(frame, pd.DataFrame):
+            columns = [str(c) for c in frame.columns[:MAX_COLS]]
+            head = frame.iloc[:MAX_ROWS, :MAX_COLS]
+            return {
+                "kind": "table",
+                "shape": [int(frame.shape[0]), int(frame.shape[1])],
+                "columns": columns,
+                "columns_truncated": frame.shape[1] > MAX_COLS,
+                "index": [_cell(i) for i in head.index.tolist()],
+                "rows": [[_cell(v) for v in row] for row in head.itertuples(index=False, name=None)],
+            }
+
+    if _root_type_module(value) == "numpy":
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            corner = value
+            if corner.ndim == 0:
+                corner_list: Any = _cell(corner.item())
+            else:
+                slicer = tuple(slice(0, MAX_ROWS) for _ in range(corner.ndim))
+                corner_list = _sanitize(corner[slicer].tolist())
+            return {
+                "kind": "array",
+                "dtype": str(value.dtype),
+                "shape": list(value.shape),
+                "corner": corner_list,
+            }
+        if isinstance(value, np.generic):
+            return {"kind": "value", "value": _cell(value.item())}
+
+    if isinstance(value, (dict, list, tuple, str, int, float, bool)) or value is None:
+        sanitized = _sanitize(value)
+        try:
+            encoded = json.dumps(sanitized, allow_nan=False)
+        except (TypeError, ValueError):
+            encoded = None
+        if encoded is not None:
+            if len(encoded) > MAX_VALUE_CHARS:
+                return {"kind": "text", "text": encoded[:MAX_VALUE_CHARS] + "…"}
+            return {"kind": "value", "value": sanitized}
+
+    # Arbitrary objects: an honest repr, marked as text rather than data.
+    text = repr(value)
+    return {"kind": "text", "text": text[:MAX_TEXT_CHARS] + ("…" if len(text) > MAX_TEXT_CHARS else "")}