@sdotwinter/openclaw-deterministic 0.17.4 → 0.17.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +204 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,2 +1,204 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
1
|
+
# OpenClaw Deterministic
|
|
2
|
+
|
|
3
|
+
A deterministic execution, memory governance, and integrity enforcement framework for OpenClaw.
|
|
4
|
+
|
|
5
|
+
OpenClaw Deterministic enforces canonical template integrity, semantic memory limits, and execution discipline to transform OpenClaw into a predictable, auditable system suitable for long-running agent deployments.
|
|
6
|
+
|
|
7
|
+
This is not an assistant plugin.
|
|
8
|
+
|
|
9
|
+
It is a governance layer.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
Install globally:
|
|
16
|
+
|
|
17
|
+
npm install -g @sdotwinter/openclaw-deterministic
|
|
18
|
+
|
|
19
|
+
Then initialize governance inside your OpenClaw workspace:
|
|
20
|
+
|
|
21
|
+
oc-deterministic install
|
|
22
|
+
|
|
23
|
+
Verify installation:
|
|
24
|
+
|
|
25
|
+
oc-deterministic doctor
|
|
26
|
+
|
|
27
|
+
Concise health summary:
|
|
28
|
+
|
|
29
|
+
oc-deterministic status
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## What This Solves
|
|
34
|
+
|
|
35
|
+
AI systems drift.
|
|
36
|
+
|
|
37
|
+
They drift in:
|
|
38
|
+
- Memory usage
|
|
39
|
+
- Execution classification
|
|
40
|
+
- File modification behavior
|
|
41
|
+
- Configuration alignment
|
|
42
|
+
- Contract integrity
|
|
43
|
+
|
|
44
|
+
OpenClaw Deterministic enforces:
|
|
45
|
+
|
|
46
|
+
- Explicit execution tiers
|
|
47
|
+
- Canonical template integrity verification
|
|
48
|
+
- Semantic memory limits
|
|
49
|
+
- Config-driven thresholds
|
|
50
|
+
- Governance event logging
|
|
51
|
+
- Structured machine-readable health reporting
|
|
52
|
+
|
|
53
|
+
The goal:
|
|
54
|
+
|
|
55
|
+
Predictable execution under defined constraints.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Core Concepts
|
|
60
|
+
|
|
61
|
+
### Deterministic Execution Tiers
|
|
62
|
+
|
|
63
|
+
Execution is classified into three tiers:
|
|
64
|
+
|
|
65
|
+
Tier A — Safe
|
|
66
|
+
Tier B — Governed Modification
|
|
67
|
+
Tier C — Destructive / Structural
|
|
68
|
+
|
|
69
|
+
Each tier defines:
|
|
70
|
+
- Whether diffs are required
|
|
71
|
+
- Whether confirmation is required
|
|
72
|
+
- Whether auto-execution is allowed
|
|
73
|
+
|
|
74
|
+
This prevents silent behavioral drift.
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
### Canonical Template Integrity
|
|
79
|
+
|
|
80
|
+
Deterministic templates embed canonical SHA256 hashes.
|
|
81
|
+
|
|
82
|
+
`doctor` verifies:
|
|
83
|
+
|
|
84
|
+
- Template presence
|
|
85
|
+
- Version alignment
|
|
86
|
+
- Canonical integrity
|
|
87
|
+
|
|
88
|
+
If a file is manually edited outside deterministic flow, the system detects it.
|
|
89
|
+
|
|
90
|
+
This enables tamper visibility.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
### Semantic Memory Governance
|
|
95
|
+
|
|
96
|
+
Semantic memory is:
|
|
97
|
+
|
|
98
|
+
- Token-estimated
|
|
99
|
+
- Compared against configurable HARD_LIMIT
|
|
100
|
+
- Evaluated against risk thresholds
|
|
101
|
+
- Logged on violation
|
|
102
|
+
|
|
103
|
+
Configuration:
|
|
104
|
+
|
|
105
|
+
~/.openclaw/.deterministic.json
|
|
106
|
+
|
|
107
|
+
Example:
|
|
108
|
+
|
|
109
|
+
{
|
|
110
|
+
"semantic": {
|
|
111
|
+
"HARD_LIMIT": 1200,
|
|
112
|
+
"RISK_THRESHOLD_PERCENT": 85
|
|
113
|
+
},
|
|
114
|
+
"governance": {
|
|
115
|
+
"strict_mode": false,
|
|
116
|
+
"violation_logging": true
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
This prevents uncontrolled memory expansion.
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
### Observability
|
|
125
|
+
|
|
126
|
+
Available commands:
|
|
127
|
+
|
|
128
|
+
init
|
|
129
|
+
install
|
|
130
|
+
upgrade
|
|
131
|
+
doctor
|
|
132
|
+
doctor --json
|
|
133
|
+
status
|
|
134
|
+
enable
|
|
135
|
+
revert
|
|
136
|
+
audit
|
|
137
|
+
|
|
138
|
+
Supports:
|
|
139
|
+
|
|
140
|
+
- Machine-readable JSON output
|
|
141
|
+
- Deterministic backup snapshots
|
|
142
|
+
- Governance event logging
|
|
143
|
+
- CI integration
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Upgrade Model
|
|
148
|
+
|
|
149
|
+
Templates are version-stamped.
|
|
150
|
+
|
|
151
|
+
Upgrade flow preserves:
|
|
152
|
+
|
|
153
|
+
- Backups
|
|
154
|
+
- Deterministic config
|
|
155
|
+
- User SOUL.md
|
|
156
|
+
|
|
157
|
+
Future releases include safe merge flows for template upgrades.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Architecture
|
|
162
|
+
|
|
163
|
+
Governance operates at three layers:
|
|
164
|
+
|
|
165
|
+
1. Execution classification
|
|
166
|
+
2. Memory pressure management
|
|
167
|
+
3. Canonical integrity verification
|
|
168
|
+
|
|
169
|
+
OpenClaw Deterministic does not replace OpenClaw.
|
|
170
|
+
|
|
171
|
+
It constrains it.
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Intended Use
|
|
176
|
+
|
|
177
|
+
Designed for:
|
|
178
|
+
|
|
179
|
+
- Production OpenClaw deployments
|
|
180
|
+
- Long-running agent systems
|
|
181
|
+
- CI-integrated governance
|
|
182
|
+
- Environments requiring auditability
|
|
183
|
+
|
|
184
|
+
If you need experimentation, use OpenClaw alone.
|
|
185
|
+
|
|
186
|
+
If you need discipline, use Deterministic.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Philosophy
|
|
191
|
+
|
|
192
|
+
Determinism over autonomy.
|
|
193
|
+
|
|
194
|
+
No silent behavior changes.
|
|
195
|
+
|
|
196
|
+
Explicit classification before execution.
|
|
197
|
+
|
|
198
|
+
Auditable state at all times.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## License
|
|
203
|
+
|
|
204
|
+
MIT
|