simplicio-prompt 0.1.0

package/examples/python/minimal_bus.py

@@ -0,0 +1,134 @@
+"""
+Minimal Linda-style tuple-space bus. See YOOL_TUPLE_HAMT.md §2.4.
+
+Implements `out`, `in_`, `rd`, `eval_` primitives. Single-process reference
+impl; multi-process variant swaps the dict for SQLite or Redis.
+
+Pattern matching is by predicate (callable on tuple dict). For production,
+prefer indexed lookup by (lane, yool) — see spec §7.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+import uuid
+from concurrent.futures import Future, ThreadPoolExecutor
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+
+Predicate = Callable[[dict[str, Any]], bool]
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class TupleSpace:
+    def __init__(self, log_path: str | Path | None = None, workers: int = 4):
+        self._tuples: dict[str, dict[str, Any]] = {}
+        self._cond = threading.Condition()
+        self._log = Path(log_path).expanduser() if log_path else None
+        if self._log:
+            self._log.parent.mkdir(parents=True, exist_ok=True)
+        self._pool = ThreadPoolExecutor(max_workers=workers)
+
+    def _persist(self, op: str, tup: dict[str, Any]) -> None:
+        if not self._log:
+            return
+        line = json.dumps({"op": op, "at": _now_iso(), "tuple": tup}, ensure_ascii=False)
+        with self._log.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+
+    def out(self, tup: dict[str, Any]) -> str:
+        """Place a tuple into the space. Returns tuple id."""
+        tid = tup.get("id") or f"t-{uuid.uuid4().hex[:12]}"
+        tup = {**tup, "id": tid, "created_at": tup.get("created_at") or _now_iso()}
+        with self._cond:
+            self._tuples[tid] = tup
+            self._persist("out", tup)
+            self._cond.notify_all()
+        return tid
+
+    def rd(self, pred: Predicate, timeout: float | None = None) -> dict[str, Any] | None:
+        """Non-destructive read. Blocks until a matching tuple appears or timeout."""
+        deadline = (time.monotonic() + timeout) if timeout is not None else None
+        with self._cond:
+            while True:
+                for tup in self._tuples.values():
+                    if pred(tup):
+                        return dict(tup)
+                if deadline is None:
+                    self._cond.wait()
+                else:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        return None
+                    self._cond.wait(timeout=remaining)
+
+    def in_(self, pred: Predicate, timeout: float | None = None) -> dict[str, Any] | None:
+        """Destructive take. Removes the first matching tuple from the space."""
+        deadline = (time.monotonic() + timeout) if timeout is not None else None
+        with self._cond:
+            while True:
+                for tid, tup in list(self._tuples.items()):
+                    if pred(tup):
+                        del self._tuples[tid]
+                        self._persist("in", tup)
+                        return dict(tup)
+                if deadline is None:
+                    self._cond.wait()
+                else:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        return None
+                    self._cond.wait(timeout=remaining)
+
+    def eval_(self, fn: Callable[[], dict[str, Any]]) -> Future:
+        """Run fn() asynchronously; resulting tuple is placed in the space."""
+        def _runner() -> dict[str, Any]:
+            result = fn()
+            self.out(result)
+            return result
+        return self._pool.submit(_runner)
+
+    def all(self) -> list[dict[str, Any]]:
+        with self._cond:
+            return [dict(t) for t in self._tuples.values()]
+
+    def shutdown(self) -> None:
+        self._pool.shutdown(wait=True)
+
+
+def by_yool(yool: str) -> Predicate:
+    return lambda t: t.get("yool") == yool
+
+
+def by_lane(lane: str) -> Predicate:
+    return lambda t: t.get("lane") == lane
+
+
+if __name__ == "__main__":
+    bus = TupleSpace(log_path=".catalog/tuples.jsonl")
+
+    bus.out({"yool": "ide.cursor.send", "args": {"file": "x.py"}, "lane": "dev"})
+    bus.out({"yool": "op.jira.fetch_sprint", "args": {"sprint": 42}, "lane": "ops"})
+
+    def worker_dev() -> None:
+        while True:
+            t = bus.in_(by_lane("dev"), timeout=1.0)
+            if t is None:
+                return
+            print(f"[dev] processing {t['yool']} args={t['args']}")
+            bus.out({
+                "yool": "receipt",
+                "lane": "audit",
+                "parent_id": t["id"],
+                "status": "ok",
+            })
+
+    worker_dev()
+    print("final state:", bus.all())
+    bus.shutdown()

package/examples/python/receipts.py

@@ -0,0 +1,152 @@
+"""
+Content-addressable receipt store. See YOOL_TUPLE_HAMT.md §2.5, §4.3.
+
+A receipt is the immutable record of a single yool execution: inputs (hashed),
+outputs (referenced by sha256), timing, status. The receipt's own sha256 over
+its canonical JSON acts as both ID and cache key.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def canonical_json(obj: Any) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def sha256_text(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def sha256_file(path: str | Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def input_hash(
+    yool: str,
+    args: dict[str, Any],
+    file_shas: list[str] | None = None,
+    env_whitelist: dict[str, str] | None = None,
+) -> str:
+    """Cache key. See spec §4.3."""
+    payload = {
+        "yool": yool,
+        "args": args,
+        "files": sorted(file_shas or []),
+        "env": dict(sorted((env_whitelist or {}).items())),
+    }
+    return sha256_text(canonical_json(payload))
+
+
+@dataclass
+class Artifact:
+    path: str
+    sha256: str
+    size_bytes: int
+    mime: str = "application/octet-stream"
+
+
+@dataclass
+class Receipt:
+    id: str
+    yool: str
+    input_hash: str
+    args: dict[str, Any]
+    status: str
+    started_at: str
+    ended_at: str
+    duration_ms: int
+    artifacts: list[Artifact] = field(default_factory=list)
+    error: str | None = None
+    parent_id: str | None = None
+    cpu_quota_pct: int = 100
+    artifacts_purged_at: str | None = None
+
+    def to_canonical(self) -> str:
+        d = asdict(self)
+        d.pop("id", None)
+        return canonical_json(d)
+
+
+class ReceiptStore:
+    """Stores receipts as .catalog/receipts/<sha>.json. Lookup by input_hash via index."""
+
+    def __init__(self, base_dir: str | Path):
+        self.base = Path(base_dir).expanduser()
+        self.receipts_dir = self.base / "receipts"
+        self.index_path = self.base / "receipts.index.json"
+        self.receipts_dir.mkdir(parents=True, exist_ok=True)
+        self._index: dict[str, str] = {}
+        if self.index_path.exists():
+            try:
+                self._index = json.loads(self.index_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                self._index = {}
+
+    def get_by_input_hash(self, ih: str) -> Receipt | None:
+        rid = self._index.get(ih)
+        if not rid:
+            return None
+        return self.load(rid)
+
+    def load(self, receipt_id: str) -> Receipt | None:
+        p = self.receipts_dir / f"{receipt_id}.json"
+        if not p.exists():
+            return None
+        data = json.loads(p.read_text(encoding="utf-8"))
+        arts = [Artifact(**a) for a in data.pop("artifacts", [])]
+        return Receipt(artifacts=arts, **data)
+
+    def put(self, r: Receipt) -> str:
+        if not r.id:
+            r.id = sha256_text(r.to_canonical())
+        path = self.receipts_dir / f"{r.id}.json"
+        data = asdict(r)
+        path.write_text(canonical_json(data), encoding="utf-8")
+        self._index[r.input_hash] = r.id
+        tmp = self.index_path.with_suffix(".json.tmp")
+        tmp.write_text(canonical_json(self._index), encoding="utf-8")
+        os.replace(tmp, self.index_path)
+        return r.id
+
+
+def make_receipt(
+    yool: str,
+    args: dict[str, Any],
+    status: str,
+    started: datetime,
+    ended: datetime,
+    artifacts: list[Artifact] | None = None,
+    error: str | None = None,
+    parent_id: str | None = None,
+    file_shas: list[str] | None = None,
+    env_whitelist: dict[str, str] | None = None,
+    cpu_quota_pct: int = 100,
+) -> Receipt:
+    ih = input_hash(yool, args, file_shas, env_whitelist)
+    r = Receipt(
+        id="",
+        yool=yool,
+        input_hash=ih,
+        args=args,
+        status=status,
+        started_at=started.astimezone(timezone.utc).isoformat(),
+        ended_at=ended.astimezone(timezone.utc).isoformat(),
+        duration_ms=int((ended - started).total_seconds() * 1000),
+        artifacts=list(artifacts or []),
+        error=error,
+        parent_id=parent_id,
+        cpu_quota_pct=cpu_quota_pct,
+    )
+    r.id = sha256_text(r.to_canonical())
+    return r

package/guardrails/cpu_throttle.py

@@ -0,0 +1,119 @@
+"""
+CPU throttle guardrail. See YOOL_TUPLE_HAMT.md §11.1.
+
+Soft throttle via process niceness. For hard throttle, use cgroups (Linux)
+or taskpolicy (macOS) at process launch — see spec §11.1.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import time
+
+DEFAULT_CPU_QUOTA_PCT = 95
+DEFAULT_LANE_CONCURRENCY = 32
+DEFAULT_MAX_LANE_CONCURRENCY = 64
+
+
+def _positive_int_from_env(names: tuple[str, ...], default: int) -> int:
+    for name in names:
+        value = os.getenv(name)
+        if value is None or not value.strip():
+            continue
+        try:
+            parsed = int(value)
+        except ValueError:
+            return default
+        return parsed if parsed > 0 else default
+    return default
+
+
+def cpu_quota_from_env(default: int = DEFAULT_CPU_QUOTA_PCT) -> int:
+    """Return CPU quota from env aliases, clamped to [1, 100]."""
+    quota = _positive_int_from_env(
+        ("YOOL_TUPLE_CPU_QUOTA_PCT", "YOOL_CPU_QUOTA_PCT"), default
+    )
+    return max(1, min(100, quota))
+
+
+def lane_concurrency_from_env(default: int = DEFAULT_LANE_CONCURRENCY) -> int:
+    """Return preferred workers per lane for high-throughput runtimes."""
+    return _positive_int_from_env(
+        ("YOOL_TUPLE_LANE_CONCURRENCY", "YOOL_LANE_CONCURRENCY"),
+        default,
+    )
+
+
+def max_lane_concurrency_from_env(default: int = DEFAULT_MAX_LANE_CONCURRENCY) -> int:
+    """Return the per-lane worker ceiling used by high-throughput runtimes."""
+    return _positive_int_from_env(
+        ("YOOL_TUPLE_MAX_LANE_CONCURRENCY", "YOOL_MAX_LANE_CONCURRENCY"),
+        default,
+    )
+
+
+@contextlib.contextmanager
+def cpu_throttle(quota_pct: int):
+    """
+    Reduce CPU pressure by raising process niceness for the duration.
+    quota_pct in [1, 100]. quota=100 -> no-op.
+    """
+    if quota_pct >= 100:
+        yield
+        return
+    if quota_pct < 1:
+        quota_pct = 1
+
+    nice_delta = max(0, min(19, int(round((100 - quota_pct) / 5.2))))
+    applied = False
+    try:
+        os.nice(nice_delta)
+        applied = True
+    except OSError:
+        pass
+    try:
+        yield
+    finally:
+        if applied:
+            try:
+                os.nice(-nice_delta)
+            except OSError:
+                pass
+
+
+def cooperative_yield(quota_pct: int, last_yield: list[float]) -> None:
+    """In-loop cooperative throttle. Caller passes mutable single-element list as state."""
+    if quota_pct >= 100:
+        return
+    now = time.monotonic()
+    elapsed = now - last_yield[0]
+    sleep_for = elapsed * (100 - quota_pct) / max(1, quota_pct)
+    if sleep_for > 0.001:
+        time.sleep(min(sleep_for, 1.0))
+    last_yield[0] = time.monotonic()
+
+
+class DiskQuotaExceeded(RuntimeError):
+    pass
+
+
+def disk_quota_check(path: str, max_mb: int) -> None:
+    """Raise DiskQuotaExceeded if `path` exceeds max_mb."""
+    total = 0
+    for root, _dirs, files in os.walk(path):
+        for f in files:
+            try:
+                total += os.path.getsize(os.path.join(root, f))
+            except OSError:
+                pass
+    mb = total / (1024 * 1024)
+    if mb > max_mb:
+        raise DiskQuotaExceeded(f"{path} = {mb:.1f}MB > limit {max_mb}MB")
+
+
+@contextlib.contextmanager
+def disk_quota(max_mb: int, path: str = "."):
+    """Context-manager wrapper around disk_quota_check."""
+    yield
+    disk_quota_check(path, max_mb)

package/guardrails/disk_gc.py

@@ -0,0 +1,212 @@
+"""
+Disk garbage collector. See YOOL_TUPLE_HAMT.md §11.2.
+
+Three-tier retention: hot (default 30d) keeps artifact bodies + receipts;
+warm (default 365d) keeps receipts only; cold keeps receipts forever
+(Merkle chain integrity). Receipts are NEVER deleted, only artifact bodies.
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import os
+import shutil
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class DiskPressure(RuntimeError):
+    pass
+
+
+def _du_mb(path: Path) -> float:
+    total = 0
+    for root, _dirs, files in os.walk(path):
+        for f in files:
+            try:
+                total += os.path.getsize(os.path.join(root, f))
+            except OSError:
+                pass
+    return total / (1024 * 1024)
+
+
+def _parse_iso(ts: str) -> float:
+    try:
+        return datetime.fromisoformat(ts.replace("Z", "+00:00")).timestamp()
+    except (ValueError, AttributeError):
+        return 0.0
+
+
+def _purge_artifact_bodies(receipt_path: Path, dry_run: bool) -> tuple[int, int]:
+    """Delete artifact files referenced by receipt. Mark receipt as purged.
+    Returns (files_deleted, bytes_freed)."""
+    try:
+        data = json.loads(receipt_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return 0, 0
+    if data.get("artifacts_purged_at"):
+        return 0, 0
+    deleted = 0
+    freed = 0
+    for art in data.get("artifacts", []):
+        p = Path(art.get("path", ""))
+        if not p.is_absolute():
+            p = receipt_path.parent.parent / p
+        if p.exists() and p.is_file():
+            try:
+                sz = p.stat().st_size
+                if not dry_run:
+                    p.unlink()
+                deleted += 1
+                freed += sz
+            except OSError:
+                pass
+    if deleted and not dry_run:
+        data["artifacts_purged_at"] = datetime.now(timezone.utc).isoformat()
+        try:
+            receipt_path.write_text(json.dumps(data), encoding="utf-8")
+        except OSError:
+            pass
+    return deleted, freed
+
+
+def _find_oldest_artifact(receipts_dir: Path) -> Path | None:
+    oldest_ts = float("inf")
+    oldest: Path | None = None
+    for rp in receipts_dir.glob("*.json"):
+        try:
+            data = json.loads(rp.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if data.get("artifacts_purged_at"):
+            continue
+        if not data.get("artifacts"):
+            continue
+        ts = _parse_iso(data.get("ended_at", ""))
+        if ts and ts < oldest_ts:
+            oldest_ts = ts
+            oldest = rp
+    return oldest
+
+
+def _rotate_daily(tuples_log: Path, dry_run: bool) -> bool:
+    """Rotate tuples.jsonl daily, gzip yesterday's."""
+    if not tuples_log.exists():
+        return False
+    mtime = tuples_log.stat().st_mtime
+    age_days = (time.time() - mtime) / 86400
+    if age_days < 1.0:
+        return False
+    stamp = datetime.fromtimestamp(mtime, timezone.utc).strftime("%Y%m%d")
+    rotated = tuples_log.with_name(f"tuples-{stamp}.jsonl.gz")
+    if rotated.exists():
+        return False
+    if dry_run:
+        return True
+    with tuples_log.open("rb") as src, gzip.open(rotated, "wb") as dst:
+        shutil.copyfileobj(src, dst)
+    tuples_log.write_bytes(b"")
+    return True
+
+
+def gc_run(
+    catalog_dir: str | Path,
+    hot_days: int = 30,
+    warm_days: int = 365,
+    max_total_mb: int = 5000,
+    dry_run: bool = False,
+) -> dict:
+    """Run garbage collection over a .catalog directory.
+
+    Phase 1: purge artifact bodies for receipts older than hot_days.
+    Phase 2: enforce size cap by purging oldest artifacts until under max_total_mb.
+    Phase 3: rotate tuples.jsonl daily, gzip yesterday's.
+    """
+    base = Path(catalog_dir).expanduser()
+    receipts_dir = base / "receipts"
+    tuples_log = base / "tuples.jsonl"
+
+    stats = {
+        "phase1_purged_files": 0,
+        "phase1_freed_mb": 0.0,
+        "phase2_purged_files": 0,
+        "phase2_freed_mb": 0.0,
+        "rotated": False,
+        "size_before_mb": 0.0,
+        "size_after_mb": 0.0,
+        "dry_run": dry_run,
+    }
+    if not base.exists():
+        return stats
+
+    stats["size_before_mb"] = _du_mb(base)
+    now = time.time()
+    hot_cutoff = now - hot_days * 86400
+    _warm_cutoff = now - warm_days * 86400
+
+    if receipts_dir.exists():
+        for rp in receipts_dir.glob("*.json"):
+            try:
+                data = json.loads(rp.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            ts = _parse_iso(data.get("ended_at", ""))
+            if ts and ts < hot_cutoff and not data.get("artifacts_purged_at"):
+                d, freed = _purge_artifact_bodies(rp, dry_run)
+                stats["phase1_purged_files"] += d
+                stats["phase1_freed_mb"] += freed / (1024 * 1024)
+
+    current_mb = _du_mb(base)
+    while current_mb > max_total_mb and receipts_dir.exists():
+        target = _find_oldest_artifact(receipts_dir)
+        if target is None:
+            break
+        d, freed = _purge_artifact_bodies(target, dry_run)
+        if d == 0:
+            break
+        stats["phase2_purged_files"] += d
+        stats["phase2_freed_mb"] += freed / (1024 * 1024)
+        current_mb = _du_mb(base)
+
+    stats["rotated"] = _rotate_daily(tuples_log, dry_run)
+    stats["size_after_mb"] = _du_mb(base)
+    return stats
+
+
+def check_disk_pressure(catalog_dir: str | Path, free_mb_floor: int = 1000) -> None:
+    """Raise DiskPressure if free space on catalog_dir's filesystem drops below floor."""
+    base = Path(catalog_dir).expanduser()
+    try:
+        usage = shutil.disk_usage(base if base.exists() else base.parent)
+    except OSError as e:
+        raise DiskPressure(f"cannot stat {base}: {e}") from e
+    free_mb = usage.free / (1024 * 1024)
+    if free_mb < free_mb_floor:
+        raise DiskPressure(f"free={free_mb:.0f}MB < floor={free_mb_floor}MB on {base}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Run disk GC over a .catalog directory.")
+    ap.add_argument("--catalog-dir", required=True, help="Path to .catalog directory")
+    ap.add_argument("--hot-days", type=int, default=30)
+    ap.add_argument("--warm-days", type=int, default=365)
+    ap.add_argument("--max-mb", type=int, default=5000)
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    stats = gc_run(
+        args.catalog_dir,
+        hot_days=args.hot_days,
+        warm_days=args.warm_days,
+        max_total_mb=args.max_mb,
+        dry_run=args.dry_run,
+    )
+    print(json.dumps(stats, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/kernel/README.md

@@ -0,0 +1,82 @@
+# Yool Tuple Space Kernel
+
+Reference Python kernel for Tuple-Space + Yool Architecture.
+
+Core file: `kernel/yool_tuple_kernel.py`.
+
+## Primitives
+
+- `out_tuple`, `in_tuple`, `rd_tuple`
+- `spawn_agent`
+- `batch_spawn(depth, branching, compression_threshold)`
+- `route_packet`
+- `scan_index`
+- `hookwall`
+- `compress_token`
+- `prune_idle`
+- `ReceiptCache` for receipt/input-hash dedupe
+- `ProviderCircuitBreaker` and jittered backoff for API/LLM calls
+- `ContextCompressor` for large prompt/context payloads
+- `LaneWorkerPool` for adaptive per-lane fan-out and small-task batching
+
+## Scale model
+
+Use `batch_spawn(root, "codex_worker", depth=4, branching=32)` to represent
+1,048,576 subagents without materializing a flat million-item Python list. The
+kernel stores a lazy batch controller tuple plus compressed virtual-agent
+accounting, then materializes only active work.
+
+Inactive materialized agents can be compacted with `compress_token(agent_id)`.
+`prune_idle(max_active)` automatically compresses the oldest active subagents.
+
+## Safe speed model
+
+The reference kernel increases throughput without provider-ban risk by avoiding
+repeat work and by slowing down safely when providers fail:
+
+- `TupleSpace.execute_tuple(...)` checks registered local yools first, compresses
+  large LLM context, hits `ReceiptCache`, then calls the provider with jittered
+  backoff and a provider-level circuit breaker.
+- `LaneWorkerPool.concurrency_for(lane)` adapts from lane queue depth, latency,
+  failures, and env ceilings instead of using one fixed worker count forever.
+- `LaneWorkerPool.run_lane_batched(...)` groups small lane tasks into bounded
+  batches.
+- `speculative_executor` is only used when the tuple data explicitly sets
+  `idempotent=True`.
+
+## Runtime policy
+
+Environment aliases:
+
+- `YOOL_TUPLE_LANE_CONCURRENCY` / `YOOL_LANE_CONCURRENCY`, default `32`
+- `YOOL_TUPLE_MAX_LANE_CONCURRENCY` / `YOOL_MAX_LANE_CONCURRENCY`, default `64`
+- `YOOL_TUPLE_CPU_QUOTA_PCT` / `YOOL_CPU_QUOTA_PCT`, default `95`
+- `YOOL_TUPLE_QUEUE_MAXSIZE` / `YOOL_QUEUE_MAXSIZE`, default `8192`
+- `YOOL_TUPLE_COMPRESSION_THRESHOLD` / `YOOL_COMPRESSION_THRESHOLD`, default `1024`
+- `YOOL_TUPLE_CACHE_MAX_ENTRIES` / `YOOL_CACHE_MAX_ENTRIES`, default `16384`
+- `YOOL_TUPLE_CACHE_TTL_S` / `YOOL_CACHE_TTL_S`, default `3600`
+- `YOOL_TUPLE_API_MAX_RETRIES` / `YOOL_API_MAX_RETRIES`, default `3`
+- `YOOL_TUPLE_API_BACKOFF_BASE_MS` / `YOOL_API_BACKOFF_BASE_MS`, default `100`
+- `YOOL_TUPLE_API_BACKOFF_MAX_MS` / `YOOL_API_BACKOFF_MAX_MS`, default `5000`
+- `YOOL_TUPLE_CIRCUIT_FAILURE_THRESHOLD` / `YOOL_CIRCUIT_FAILURE_THRESHOLD`, default `5`
+- `YOOL_TUPLE_CIRCUIT_COOLDOWN_S` / `YOOL_CIRCUIT_COOLDOWN_S`, default `30`
+- `YOOL_TUPLE_BATCH_SMALL_TASK_SIZE` / `YOOL_BATCH_SMALL_TASK_SIZE`, default `32`
+- `YOOL_TUPLE_CONTEXT_COMPRESSION_CHARS` / `YOOL_CONTEXT_COMPRESSION_CHARS`, default `6000`
+
+## Usage
+
+```python
+from kernel.yool_tuple_kernel import build_default_space
+
+space, root = build_default_space()
+receipt = space.batch_spawn(root, "codex_worker", depth=4, branching=32)
+print(receipt.virtual_agents)  # 1048576
+print(space.snapshot())
+```
+
+Run:
+
+```bash
+python kernel/yool_tuple_kernel.py
+python -m unittest discover -s tests -p "test_*.py"
+```