{
  "markdown": "# Svit\n\n[![CI](https://github.com/everruns/svit/actions/workflows/ci.yml/badge.svg)](https://github.com/everruns/svit/actions/workflows/ci.yml)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](SECURITY.md)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**Memory and behavior, committed together.**\n\nSvit is a research-stage Rust runtime for agents that need durable state and\nreusable code. It keeps structured memory, named Svit Lisp scripts, inbox state,\nbuffered message intents, and runtime metadata in one serializable process.\nEvery activation runs against a bounded working copy and either commits one\ncomplete next version or commits nothing.\n\nOne `Svit` owns one reason/act loop, one durable conversation thread, and one\nserializable `Process`. The host chooses a `Reasoner`, mounts, and ports;\n[Everruns](https://github.com/everruns/everruns) implements the current loop\nbehind the Svit API.\n\n> [!IMPORTANT]\n> Svit is runnable and tested, but it has no stable release and is not a proven\n> hostile multi-tenant isolation boundary. Production use with untrusted code\n> still needs an outer Wasm or OS process boundary.\n\n## Why Svit\n\n- **One process space.** [Memory](docs/memory.md), scripts, queues, metadata,\n  and mounted resources use one absolute-path interface rather than unrelated\n  agent tools.\n- **Atomic activations.** Memory, script, and buffered message changes commit\n  together. Syntax, runtime, validation, conversion, and limit failures roll\n  back the complete activation.\n- **Durable reasoning.** With persistence, process transactions and paged\n  [events](docs/events.md) survive restarts without materializing the full\n  thread in every snapshot.\n- **Portable state.** Processes can be snapshotted, restored, inspected, and\n  forked into independently mutable children.\n- **Explicit authority.** Guest Lisp has no ambient filesystem, network,\n  environment, process, module loader, clock, randomness, or native-extension\n  access. Hosts attach external authority through typed mounts and\n  [ports](docs/ports.md).\n- **Observable change.** Commits report the paths they changed, while committed\n  nodes and roots have structural content hashes for precise cache validation.\n\n## Quick start\n\nCreate a Rust application and add Svit while its public API is still changing:\n\n```console\ncargo new svit-quickstart\ncd svit-quickstart\n```\n\n```toml\n[dependencies]\nsvit = { git = \"https://github.com/everruns/svit\", branch = \"main\" }\ntokio = { version = \"1\", features = [\"macros\", \"rt-multi-thread\"] }\n```\n\nReplace `src/main.rs` with:\n\n```rust\nuse svit::{Message, OpenAI, Reasoner, Svit, value};\n\n#[tokio::main]\nasync fn main() -> Result<(), Box<dyn std::error::Error>> {\n    let mut svit = Svit::builder(\"svit://local/quickstart\")?\n        .memory(\"facts\", value!({}))\n        .instructions(\n            \"Write requested durable facts to the exact process path before replying.\",\n        )\n        .reasoner(Reasoner::new(\"gpt-5.6-terra\", OpenAI::from_env()?))\n        .build()\n        .await?;\n\n    let inbox = svit.inbox();\n    let mut outbox = svit.outbox();\n\n    svit.start()?;\n    inbox\n        .send(Message::user(\n            \"Write blue to /memory/facts/release_color, then confirm it.\",\n        ))\n        .await?;\n\n    let reply = outbox.recv().await?;\n    drop(inbox);\n    svit.block().await?;\n\n    println!(\"{}\", reply.text().unwrap_or_default());\n    println!(\"stored={:?}\", svit.read(\"/memory/facts/release_color\")?);\n    Ok(())\n}\n```\n\nRun it with an OpenAI API key:\n\n```console\nOPENAI_API_KEY=... cargo run\n```\n\n`Inbox::send` commits a message before waking the loop. `Outbox` publishes\ncompleted assistant messages. `Events` publishes committed path changes,\ncanonical conversation events, derived messages, and sanitized terminal\nfailures. Hosts inspect state through owned reads; they never receive a mutable\nreference to the process tree.\n\nFor a complete live example, clone this repository and run the process-owned\nsupport agent:\n\n```console\nOPENAI_API_KEY=... cargo run --locked -p svit-support-agent-svit\n```\n\n## Process model\n\n```text\nHost\n├── Reasoner\n├── Inbox ─────────────┐\n├── Outbox <───────────┤\n├── Events <───────────┤\n├── Ports              │\n└── Mount providers    │\n                       v\n                    Svit\n             reason/act loop + thread\n                       │\n                       v\n                    Process\n             state + scripts + limits\n             transactions + snapshots\n```\n\nThe memory tree is the complete guest-visible namespace below `/`, not just the\n`/memory` node:\n\n```text\n/\n├── thread/      bounded durable session metadata\n├── memory/      durable application values\n├── lib/         named Svit Lisp scripts\n├── ports/       manuals for host-attached ports\n├── inbox/       durable local input queue\n├── mounts/      virtual host resources under explicit grants\n├── tasks/       reserved in the current slice\n├── children/    reserved in the current slice\n└── system/      identity, API, limits, lineage, runtime, and outbox metadata\n```\n\nRust callers, model tools, and Svit Lisp use the same path vocabulary:\n\n```text\ndiscover(path)        list immediate children\nread(path)            read one value\nstat(path)            inspect kind, access, locality, source, and content facts\nwrite(path, value)    commit a memory, script, or granted mount write\nremove(path)          commit a removal\nexec(path, input)     run a named /lib script\n```\n\nThe model-facing `exec` tool can also run transient Svit Lisp source. A fresh,\nrestricted interpreter runs each activation. Successful activations validate\nand commit memory, scripts, and buffered message intents once; failed\nactivations leave the process version and committed root unchanged.\n\nExternal effects have a narrower guarantee. Port calls happen immediately and\ncannot be rolled back. Granted mount writes are delayed until process\nvalidation succeeds, but the external source cannot join the process\ntransaction.\n\n## Persistence, snapshots, and forks\n\nThe default `persistence-turso` feature provides local Turso persistence. One\ncanonical `ProcessTransaction` stream records process mutations; a separate\npaged `EventLog` retains conversation history. Resume verifies transaction\nversions, hashes, mutations, and resulting root hashes without rerunning guest\ncode.\n\n```rust\nuse svit::{OpenAI, Process, Reasoner, Svit, TursoProcessStore};\n\nasync fn build_persisted() -> Result<Svit, Box<dyn std::error::Error>> {\n    let store = TursoProcessStore::open(\"svit.db\").await?;\n    let process = Process::builder(\"svit://local/persisted/demo\")?.build()?;\n    let durable = store.create(process).await?;\n\n    Ok(Svit::persisted(durable)?\n        .reasoner(Reasoner::new(\"gpt-5.6-terra\", OpenAI::from_env()?))\n        .build()\n        .await?)\n}\n```\n\nUse `store.resume(address)` to reopen a process. Snapshots preserve canonical\nprocess state and thread metadata. Durable forks share an immutable history\nprefix at the fork boundary and then commit independently; process-only forks\nstart a fresh child session.\n\n| Feature | Purpose |\n| --- | --- |\n| `persistence-turso` | Local transactions, snapshots, resume, forks, queries, and history cuts |\n| `turso-mount` | A bounded host-selected Turso query exposed as a virtual mount |\n\nUse `--no-default-features` for the adapter-neutral runtime and persistence\ncontracts.\n\n## Ports and mounts\n\nPorts are host-owned async capabilities. `Ports::new()` grants none. Add each\nport deliberately and attach the resulting registry when building Svit:\n\n```rust\nuse svit::{\n    HttpAllowlist, OpenAI, Ports, Reasoner, ReqwestHttpTransport, Svit,\n};\n\nlet reasoner = Reasoner::new(\"gpt-5.6-terra\", OpenAI::from_env()?);\nlet ports = Ports::new()\n    .http(\n        HttpAllowlist::new().allow(\"https://api.github.com/\"),\n        ReqwestHttpTransport::new()?,\n    )\n    .llm(reasoner.clone())\n    .spawn(reasoner.clone());\n\nlet svit = Svit::builder(\"svit://local/explicit-ports\")?\n    .reasoner(reasoner)\n    .ports(ports)\n    .build()\n    .await?;\n```\n\nHere `http` can reach only the allowlisted origin and its path descendants,\n`llm` uses the selected reasoner for nested model calls, and `spawn` uses it for\nchild Svit turns. A research host that intentionally accepts any HTTP(S)\ndestination must call `http_unrestricted` by name. Omit any registration the\nprocess should not receive. Port descriptors appear under `/ports`, but\ndescriptors never carry authority and snapshots never serialize port\nimplementations.\n\nMounts project host-selected folders or values below `/mounts` without copying\ntheir contents into the committed root. The root stores only a descriptor;\nnodes resolve lazily through a host-owned provider. Providers are never\nserialized, so a restored process fails closed until the host reattaches them.\n\n## Lampa process console\n\nLampa is the interactive reference host for one persisted Svit:\n\n```console\nOPENAI_API_KEY=... cargo run --locked -p lampa\n```\n\n![Lampa terminal process viewer](docs/lampa.gif)\n\nLampa shows the conversation beside the complete memory tree, mounts the current\ndirectory read-only at `/mounts/cwd`, and persists each instance in its own\ndatabase. It explicitly registers unrestricted `http` plus model-backed `llm`\nand `spawn` ports as a research host. Reuse an instance name to resume it:\n\n```console\nOPENAI_API_KEY=... cargo run --locked -p lampa -- --instance research-one\n```\n\nUse `--mount name=path` or `--mount-rw name=path` to attach folders and\n`LAMPA_DATA_DIR` to select the storage root.\n\n## Current scope\n\nImplemented now:\n\n- process-owned reasoning with a durable local inbox, thread, and outbox;\n- transactional memory and named Svit Lisp scripts;\n- bounded values, execution, diagnostics, snapshots, restore, and forks;\n- local Turso persistence with validated transaction replay;\n- lazy folder, value, and materialized-query mounts;\n- explicit host ports and pure local `jq` and `search` functions;\n- VAST version preconditions, conflicts, and bounded retry receipts;\n- deterministic examples and adversarial invariant tests.\n\nNot implemented:\n\n- remote message delivery, scheduling, timers, retries, or global routing;\n- authenticated process identity, authorization, or secrets;\n- distributed ownership, migration, or durable control receipts;\n- exactly-once external effects;\n- production Wasm/OS isolation or formal hostile-tenant isolation evidence.\n\nThe public [vision](docs/vision.md) describes the broader research direction,\nnot functionality already promised by this implementation.\n\n## Security\n\nSvit validates persistent values and snapshots, enforces configured limits,\nuses a fresh restricted interpreter for every activation, caps diagnostics, and\nrolls back failed activations. These controls are executable invariants, not a\nproof of hostile multi-tenancy. Ketos uses wall-clock deadlines and estimated\ninterpreter memory rather than deterministic fuel and an allocator byte cap.\n\nDo not report vulnerabilities in public issues. Follow\n[`SECURITY.md`](SECURITY.md) for private reporting and the current support\npolicy.\n\n## Documentation\n\n| Resource | Purpose |\n| --- | --- |\n| [Vision](docs/vision.md) | Product model and research direction |\n| [Examples](examples/README.md) | Runnable end-to-end scenarios |\n| [Svit Lisp contract](knowledge/runtimes/lisp-runtime.md) | Versioned guest-language surface |\n| [Control protocol](docs/control-protocol.md) | VAST semantics and wire contract |\n| [Security policy](SECURITY.md) | Security model, limitations, and reporting |\n| [Changelog](CHANGELOG.md) | Unreleased and released changes |\n| [Svit skill](skills/svit/SKILL.md) | Usage guidance for Svit-aware models |\n\nInternal engineering decisions and executable claims live in the OKF v0.2\n[`knowledge/`](knowledge/) bundle.\n\n## Development\n\n```console\njust --list\njust build\njust test\njust examples\njust check\njust pre-pr\n```\n\nRead [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md) before\nchanging runtime behavior. Behavioral and security claims require executable\nevidence and the corresponding knowledge update.\n\n## License\n\nSvit is available under the [MIT License](LICENSE). See [`NOTICE`](NOTICE) for\nthird-party attribution.\n",
  "bytes": 12268,
  "sha": "2d19005305b4a39b8a68fa22455f1a17d66c9bfeb1b799ecb314dc64bc80db9c",
  "repo_slug": "everruns/svit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_everruns_svit_knowledge_index_md_f48587be/readme"
}