clawql-cellrt — Specification v0.1

clawql-cellrt binary (Rust, static, ~50–80 MB target)
│
├─ Fleet coordinator (Tokio async)
│    ├─ S3/R2 bucket as coordinator (compare-and-swap ownership leases)
│    ├─ LTX replication (SQLite WAL segments → bucket, RPO=0)
│    ├─ Peer authentication (HMAC-SHA256, WireGuard-compatible)
│    ├─ Node discovery (bucket-based, no membership protocol)
│    └─ Fault recovery (ownership lease expiry → another node acquires)
│
├─ Cell runtime (per-cell, Tokio task)
│    ├─ Wasmtime engine (embedded, one instance per cell)
│    │    └─ clawql-core.wasm (Effect-TS via ComponentizeJS + jco)
│    │         ├─ search · execute · memory_* · audit · cache
│    │         ├─ clawql-ontology (structured filter queries)
│    │         └─ mcp-api-adapter (six protocol surfaces)
│    ├─ Capability grants (network, storage, crypto — explicit WIT imports)
│    ├─ HTTP handler (axum, per-cell)
│    ├─ WebSocket handler (tokio-tungstenite, hibernation via task suspend)
│    └─ Alarm scheduler (tokio time::sleep_until, durable via SQLite)
│
├─ Storage (per-cell)
│    ├─ SQLite via rusqlite (WAL mode, per-cell file)
│    ├─ LTX writer (streams WAL segments to bucket coordinator)
│    └─ WORM guarantees (acknowledge write only after bucket replication)
│
├─ Security layer (clawql-security embedded)
│    ├─ eBPF program loader (libbpf-rs, Linux only)
│    ├─ Syscall monitor (Falco-equivalent rules engine)
│    ├─ WASM capability enforcer (validates WIT imports at instantiation)
│    ├─ Virtual key lifecycle (Rust struct, scoped to cell ID)
│    └─ Cosign binary attestation (verified at startup via sigstore-rs)
│
├─ Inference layer (clawql-inference embedded)
│    ├─ PAL router (Frugal → Standard → Frontier based on policy.yaml)
│    ├─ Virtual key manager (issue on spawn, expire on drop)
│    ├─ Budget enforcer (hard cap, DeductionService via HTTP)
│    └─ WORM inference call store (SQLite, LTX-replicated)
│
├─ Vault client (HashiCorp Vault dynamic secrets)
│    ├─ AppRole auth (VAULT_ROLE_ID + VAULT_SECRET_ID)
│    ├─ Dynamic secret lease on cell spawn
│    ├─ Secret injection into WASM env before instantiation
│    └─ Lease renewal tied to cell alarm lifecycle
│
└─ Observability (embedded)
     ├─ OTel SDK (opentelemetry-rust — traces, metrics, logs)
     ├─ Prometheus exporter (/metrics on fleet HTTP)
     ├─ Langfuse forwarder (RTP/OBT training data emission)
     └─ Structured logging (tracing → JSON → Loki push)

packages/                         — TypeScript (npm)
  clawql-core/
  clawql-streams/
  mcp-api-adapter/
  wasm-polyfills/                 — @clawql/wasm-polyfills (planned)
  effect-wasm/                    — @clawql/effect-wasm (planned)

crates/
  clawql-cellrt/                  — Cargo workspace (ClawQL-specific)
    Cargo.toml
    cellrt-coordinator/           — wraps bucket-coordinator + ClawQL fleet semantics
    cellrt-runtime/               — cell lifecycle, Wasmtime, HTTP/WS, alarms
    cellrt-storage/               — SQLite + LTX WORM
    cellrt-security/              — eBPF, capability enforcer, Cosign startup
    cellrt-attestation/           — SEV-SNP/TDX remote attestation (tee path)
    cellrt-inference/             — PAL, virtual keys, call store
    cellrt-vault/                 — AppRole bootstrap; attestation auth for tee
    cellrt-observability/         — OTel, Prometheus, Langfuse
    cellrt-cli/                   — start / deploy / diagnose / audit export

# Extract later (crates.io, no ClawQL deps):
bucket-coordinator                — CAS leases, LTX, peer HMAC over S3/R2

pub struct CellId(String);   // "agent:{subscription_id}:{event_id}"

pub async fn spawn_cell(
    id: CellId,
    config: CellConfig,
    coordinator: &FleetCoordinator,
) -> Result<CellHandle> {
    // 1. Acquire ownership lease (compare-and-swap in bucket)
    let lease = coordinator.acquire_lease(&id).await?;

    // 2. Initialize per-cell SQLite (WAL mode)
    let db = CellStorage::open(&id).await?;

    // 3. Request dynamic secrets from Vault
    let secrets = VaultClient::request_dynamic_secrets(&config.vault_role).await?;

    // 4. Issue virtual key (scoped to cell ID)
    let virtual_key = VirtualKeyManager::issue(
        VirtualKeyParams {
            scope: id.clone(),
            budget_tokens: config.budget_tokens,
            ttl_ms: config.virtual_key_ttl_ms,
        }
    ).await?;

    // 5. Write WORM spawn record (LTX → bucket before ack)
    db.worm_append(WormEvent {
        event_type: "CELL_SPAWNED",
        cell_id: id.clone(),
        virtual_key_id: virtual_key.id.clone(),
        subscription_id: config.subscription_id.clone(),
        event_hash: config.event_hash.clone(),
        timestamp: Utc::now(),
    }).await?;

    // 6. Instantiate WASM (or HTTP bootstrap) with capability grants + secrets
    let wasm_instance = WasmRuntime::instantiate(
        &id,
        WasmConfig {
            component_path: coordinator.resolve_component_path().await?,
            env: secrets.to_env_map(),
            virtual_key: virtual_key.clone(),
            capabilities: config.allowed_capabilities,
        }
    ).await?;

    // 7. Set alarm for virtual key TTL (durable — survives process restart)
    db.set_alarm(Utc::now() + Duration::milliseconds(config.virtual_key_ttl_ms)).await?;

    // 8. Start HTTP + WebSocket handlers
    let http_server = CellHttpServer::start(&id, wasm_instance.clone()).await?;

    Ok(CellHandle { id, db, wasm_instance, virtual_key, http_server, lease })
}

impl CellHandle {
    pub async fn handle_request(&self, req: CellRequest) -> Result<CellResponse> {
        self.inference.check_budget(&self.virtual_key).await?;

        // Bootstrap: HTTP → clawql-mcp
        // Full: in-process WASM via Wasmtime
        let result = self.wasm_instance.call_tool(req).await?;

        self.db.worm_append(WormEvent {
            event_type: "TOOL_CALL",
            tool_name: req.tool_name.clone(),
            input_hash: sha256(&req.arguments),
            atr_scope_check: result.atr_result.clone(),
            timestamp: Utc::now(),
        }).await?;

        Ok(result.into())
    }
}

impl CellHandle {
    pub async fn handle_alarm(&self) -> Result<()> {
        self.inference.expire_key(&self.virtual_key).await?;
        self.flush_training_data().await?;

        self.db.worm_append(WormEvent {
            event_type: "CELL_DESTROYED",
            virtual_key_id: self.virtual_key.id.clone(),
            exit_reason: "ttl_expired",
            tokens_used: self.inference.tokens_used(),
            timestamp: Utc::now(),
        }).await?;

        self.coordinator.release_lease(&self.id).await?;
        self.db.close().await?; // LTX replication completes before close returns
        Ok(())
    }
}

// clawql-core.wit
world clawql-core {
  // Network — fetch only, no raw TCP
  import wasi:http/outgoing-handler@0.2.0

  // Storage — cell SQLite only, no filesystem
  import clawql:storage/cell-storage

  // Crypto — subset of Web Crypto
  import clawql:crypto/digest          // SHA-256/384/512
  import clawql:crypto/hmac            // HMAC sign/verify
  import clawql:crypto/random          // randomUUID, getRandomValues
  import clawql:crypto/aes-gcm         // AES-GCM encrypt/decrypt

  // Node polyfills (from @clawql/wasm-polyfills)
  import clawql:polyfills/async-local-storage
  import clawql:polyfills/event-emitter
  import clawql:polyfills/buffer
  import clawql:polyfills/node-crypto  // subset — maps to clawql:crypto/*

  // Inference — model calls via virtual key
  import clawql:inference/call         // PAL-routed, budget-enforced

  // Audit — WORM writes via host (not direct SQLite)
  import clawql:audit/worm-append

  // Exports — host → component
  export clawql:tools/call-tool
  export clawql:tools/list-tools
  export clawql:mcp/handle-request
  export clawql:mcp/handle-websocket
}

#[derive(Clone, Debug)]
pub struct VirtualKey {
    pub id: Uuid,
    pub cell_id: CellId,
    pub budget_tokens: u32,
    pub tokens_used: Arc<AtomicU32>,
    pub expires_at: DateTime<Utc>,
    pub state: Arc<RwLock<VirtualKeyState>>,
}

#[derive(Debug, PartialEq)]
pub enum VirtualKeyState {
    Active,
    BudgetExhausted,
    Expired,
    Revoked,
}

storage.put / worm_append
        │
        ▼
SQLite WAL frame
        │
        ▼
LTX segment → cells/{cell_id}/{txn_id}.ltx  (bucket ACK)
        │
        ▼
caller receives Ok(())   // not before bucket ACK

# 1. Bundle with polyfill aliases (provider set compile-time constant — no dynamic import)
CLAWQL_PROVIDER=legal \
esbuild packages/clawql-core/src/index.ts \
  --bundle --platform=browser --target=es2022 \
  --alias:node:async_hooks=@clawql/wasm-polyfills/async-hooks \
  --alias:node:crypto=@clawql/wasm-polyfills/crypto \
  --outfile=dist/clawql-core.bundle.js

# 2. Componentize
jco componentize dist/clawql-core.bundle.js \
  --wit clawql-core.wit --world clawql-core \
  --out dist/clawql-core.wasm

# Must stay under 64 MiB target (CI gate)
wc -c dist/clawql-core.wasm

pub enum WasmMode {
    Http { endpoint: Url, auth: BearerToken },  // → local clawql-mcp
    Wasm { store: Store<CellState>, instance: Instance },
}

cargo build --release --target x86_64-unknown-linux-musl
# Static binary; target ~50–80 MB (Wasmtime ~20 MB + component ~15 MB)

cosign verify-blob \
  --certificate-identity-regexp ".*clawql-cellrt.*" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --signature clawql-cellrt.sig \
  clawql-cellrt

export CELLRT_BUCKET=s3://clawql-streams-state
export CELLRT_S3_ENDPOINT=https://${CF_ACCOUNT_ID}.r2.cloudflarestorage.com
export CELLRT_ADVERTISE=cellrt-node-a.internal:8080
export CELLRT_LISTEN=0.0.0.0:8080
export VAULT_ADDR=https://vault.internal:8200
export VAULT_ROLE_ID=${VAULT_ROLE_ID}
export VAULT_SECRET_ID=${VAULT_SECRET_ID}
export CLAWQL_INFERENCE_ENDPOINT=http://clawql-inference.internal:8080

clawql-cellrt start

npm run build:wasm -w clawql-core
clawql-cellrt deploy dist/clawql-core.wasm --bucket "$CELLRT_BUCKET" --endpoint "$CELLRT_S3_ENDPOINT"

clawql-cellrt diagnose --bucket "$CELLRT_BUCKET" --endpoint "$CELLRT_S3_ENDPOINT"
# Reports: nodes, cells/node, LTX lag, virtual keys, Vault leases, eBPF status, attestation

cellrt:
  enabled: false
  image: ghcr.io/danielsmithdevelopment/clawql-cellrt:latest
  replicas: 2
  bucket: clawql-streams-state
  vault:
    enabled: true
    addr: ''
  inference:
    endpoint: ''
  security:
    ebpf: true # Linux only — disable for macOS/dev
    attestation: true # Cosign binary verification on startup
  tee:
    enabled: false # AMD SEV-SNP / Intel TDX — see clawql-tee.md
    substrate: sev-snp # sev-snp | tdx | nitro
    attestationGatedVault: false
    airgapAudit:
      enabled: false # see clawql-tee-airgap-audit.md
  observability:
    otel:
      enabled: true
      endpoint: ''
    langfuse:
      enabled: false
    prometheus:
      enabled: true
      port: 9090
  wasmMode: http # http (bootstrap) | wasm (full)