# WorldCore worker

A local worker for agents and LLM hosts: versioned memory, evidence, bounded WHAT IF scenarios and measured predictions. Connect through MCP stdio, JSONL or the Python API.

**1.3.0rc3 is a technical release candidate**, published under the Apache-2.0 license.

## Install

Python 3.11 or later; Linux and macOS are the intended first targets. The current evidence was collected on macOS; the repository includes a cross-platform CI matrix whose remote results must be checked before publication.

```sh
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/worldcore-worker --version
```

No external Python dependencies are required by the base worker. For MCP:

```sh
.venv/bin/python -m pip install '.[mcp]'
WORLDCORE_DB=./local-state/worker.db WORLDCORE_OWNER=local WORLDCORE_SPACE=demo .venv/bin/worldcore-mcp
```

The MCP process speaks stdio; its owner and space come from the operator environment, never model arguments.

## JSONL quick start

```sh
printf '%s\n' '{"op":"health","_req":"ready"}' | .venv/bin/worldcore-worker --db ./local-state/worker.db --owner local --space demo
```

Start the same command as a long-lived child for an agent. Send one UTF-8 JSON object per line and correlate replies using `_req`. The worker binds identity at launch: requests cannot choose another owner or space. The bound worker rejects real-action proposals/execution even if a legacy action environment flag is set.

```json
{"op":"whatif_compare","_req":"example","question":"Compare two assumptions","scenarios":[{"id":"a","actions":[{"op":"set","key":"budget","value":90}]},{"id":"b","actions":[{"op":"set","key":"budget","value":110}]}],"objectives":[]}
```

WHAT IF returns `action_executed:false`. It records a scenario comparison; it does not perform those actions in the real world. See the [wire protocol](docs/WORKER_PROTOCOL.md) for limits, error handling and restart rules.

## Hosts and verification

- MCP SDK/stdio has real local validation evidence. Native Hermes AIAgent + a real model passed a three-case model/tool/result cycle on simulated inboxes and calendars; see [the verified Hermes profile](docs/HERMES_SIMULATED_WORKSPACE.md).
- OpenCode V2 uses `adapters/opencode/v2` and Code Mode. Use catalog discovery before calling `tools["worldcore"].whatif_compare(...)`. Earlier probes showed the same invocation fail once and then succeed; syntax alone did not explain that behavior. Enabling `execute` requires the operator's explicit permission and does not replace nested tool permissions.
- Claude Code has a real probe but previously hit its provider usage limit. OpenClaw adapter tests use a simulated host. Neither is claimed as fully certified here.

The real OpenCode certification command is opt-in, sends only synthetic states and verifies structured tool events, returned result, independent SQLite receipt, native observation hook, final model acknowledgement and unchanged real state:

```sh
.venv/bin/python scripts/certify_opencode.py ./validation/opencode --model PROVIDER/MODEL --repeats 3 --allow-code-mode
```

This makes real model calls and requires the selected host/provider to be installed and configured. Model-generated claims alone cannot pass.

## Development

```sh
.venv/bin/python -m pip install '.[test,benchmark,mcp]' build
.venv/bin/python -B scripts/run_bounded_pytests.py --selftest --timeout 40 --total-timeout 200
.venv/bin/python -B scripts/repeat_validation_v12.py /tmp/worldcore-validation
```

The runner saves full logs, diagnostics and atomic reports. Optional browser/desktop tests may skip when their dependencies are unavailable; a skipped test is not certified coverage. See [security boundaries](SECURITY.md), [contribution checks](CONTRIBUTING.md) and [changes](CHANGELOG.md).

## What the product can claim

WorldCore manages evidence, evaluates declared alternatives and scores forecasts against observed outcomes. Its temporal prediction path uses separated fit/calibration/validation data and can abstain. Coverage measured in a small controlled filesystem benchmark is not a guarantee for arbitrary applications, users or future conditions.

It is not a general causal model or an autonomous execution authority. Legacy research modules remain available with their own limitations; their presence does not certify their domain accuracy. Historical details are in [the v1.2 report](docs/VALIDATION_V12_IT.md).

## Learning with stable code

The host can call `refresh_adaptive_world` when new observed batches arrive. Candidates need chronological validation and a fresh comparison against the incumbent. Used evaluation samples cannot be reused for model selection. Host-verified forecast outcomes automatically trigger rollback or suspension after demonstrated coverage failure. Existing memory remains versioned; procedure variants are immutable text data ranked from verified outcomes. None of these paths rewrite Python code or grant action permissions. See [adaptive data lifecycle](docs/ADAPTIVE_LIFECYCLE.md).

Host ingestion APIs require an authenticated operator adapter. JSONL exposes only adaptive status and advisory procedure recommendations. This is an event-driven data mechanism, not a running monitor or proof of complete autonomous Hermes integration.