# Version Contract

> Defines the interface contract between custom protocol layer and OpenClaw Core.
> Part of COMPATIBILITY-STRATEGY.md §D.

---

## §1 Supported OpenClaw Versions

| Version | Status | Tested | Notes |
|---------|--------|--------|-------|
| v0.9.x | ✅ Supported | 2026-06-06 | Current production |
| v0.10.x | ✅ Supported | — | Expected compatibility |
| v1.0.x | 🔮 Future | — | May require minor updates |

## §2 Contract Scope

This contract covers **only** the integration between the custom protocol layer (AGENTS.md, GOVERNANCE.md, PORTFOLIO.md, audit scripts) and OpenClaw Core. It does NOT cover:

- General OpenClaw feature usage
- Third-party plugins or skills
- LLM model behavior

## §3 Required Interfaces

### 3.1 Tool Names (stable)

The following tools are referenced by name in protocol files and must exist:

| Tool Name | Referenced In | Usage |
|-----------|---------------|-------|
| `ctx_search` | AGENTS.md §3b, §6 | Knowledge base search for learning context |
| `memory_search` | AGENTS.md §3b, §6 | Memory recall for lessons learned |
| `ctx_index` | AGENTS.md §CPB | Indexing large reference files |

### 3.2 Execution Environment

| Requirement | Detail |
|-------------|--------|
| Node.js | ≥ v20 (audit scripts use ESM via .mjs) |
| File system | Read/write access to workspace root |
| Process execution | Standard `exec()` with timeout support |

### 3.3 Cron Jobs

| Job ID | Schedule | Purpose |
|--------|----------|---------|
| dream-cycle | Daily 04:00 Asia/Shanghai | Memory consolidation |
| heartbeat | Periodic | Workspace health checks |

### 3.4 Configuration Files

| File | Format | Purpose |
|------|--------|---------|
| AGENTS.md | Markdown | Execution protocol |
| GOVERNANCE.md | Markdown | Governance protocol |
| PORTFOLIO.md | Markdown | Portfolio management protocol |
| MEMORY.md | Markdown | Stable memory |
| HEARTBEAT.md | Markdown | Heartbeat checklist |

## §4 Forbidden Interfaces

The current codebase does NOT use any of the following:

| Interface | Reason |
|-----------|--------|
| OpenClaw internal runtime state | Would break on upgrade |
| Private scheduler APIs | No dependency needed |
| Experimental/alpha tool names | No dependency needed |
| Internal memory backend APIs | All memory accessed through public tools |
| Gateway internal config schema | No dependency needed |

## §5 Runtime Context Dependency

The protocol layer relies on standard runtime context provided by OpenClaw:

| Context Element | Required? | Fallback |
|----------------|-----------|----------|
| Current workspace path | ✅ Yes | `process.cwd()` |
| Available tools list | ✅ Yes | Manual validation |
| Session history | ❌ No | N/A |
| Agent identity | ⚠️ Soft | Defaults to assumptions in SOUL.md |

## §6 Breaking Change Notification

If OpenClaw changes any Required Interface (§3), the following notice period applies:

| Change Type | Notice Period | Action Required |
|-------------|---------------|-----------------|
| Tool name rename | 1 major version | Update 5 references in AGENTS.md + guard script |
| Tool removal | 1 major version | Replace with equivalent or remove protocol refs |
| Cron format change | 1 major version | Re-register cron jobs via `cron(action="add", ...)` |
| Config format change | 1 major version | Follow upgrade-playbook.md |

## §7 Contract Version

| Field | Value |
|-------|-------|
| Contract Version | 1.0 |
| Last Updated | 2026-06-06 |
| Maintainer | 小龙 |
| Validation | `node scripts/upgrade-test.mjs` |