@sdotwinter/openclaw-deterministic 0.17.5 → 0.17.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Sean
+Copyright (c) 2026 Sean Winter
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,8 @@
-# OpenClaw Deterministic
+# OpenClaw Deterministic (OCD)
 
-A deterministic execution, memory governance, and integrity enforcement framework for OpenClaw.
+Deterministic governance, memory discipline, and integrity enforcement framework for OpenClaw.
 
-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.
+OpenClaw Deterministic transforms OpenClaw into a predictable, auditable execution system suitable for long-running agent deployments and CI environments.
 
 This is not an assistant plugin.
 
@@ -16,7 +16,7 @@ Install globally:
 
 npm install -g @sdotwinter/openclaw-deterministic
 
-Then initialize governance inside your OpenClaw workspace:
+Apply deterministic governance to an existing OpenClaw workspace:
 
 oc-deterministic install
 
@@ -24,22 +24,39 @@ Verify installation:
 
 oc-deterministic doctor
 
-Concise health summary:
+Concise health summary (CI-friendly):
 
 oc-deterministic status
 
 ---
 
+## Safety Guarantees
+
+OpenClaw Deterministic enforces execution discipline with explicit safety guarantees:
+
+- Does not overwrite an existing SOUL.md
+- Verifies canonical integrity before upgrade
+- Refuses to upgrade drifted files (unless --force)
+- Creates deterministic backup snapshots before mutation
+- Supports structured revert to previous snapshot
+- Exposes machine-readable health status
+- Blocks silent structural mutation
+
+This system assumes drift is inevitable.
+
+It makes drift visible.
+
+---
+
 ## What This Solves
 
-AI systems drift.
+AI systems drift over time:
 
-They drift in:
-- Memory usage
-- Execution classification
-- File modification behavior
-- Configuration alignment
-- Contract integrity
+- Memory growth
+- File mutation
+- Execution misclassification
+- Configuration divergence
+- Contract ambiguity
 
 OpenClaw Deterministic enforces:
 
@@ -48,9 +65,9 @@ OpenClaw Deterministic enforces:
 - Semantic memory limits
 - Config-driven thresholds
 - Governance event logging
-- Structured machine-readable health reporting
+- Structured health reporting
 
-The goal:
+The objective:
 
 Predictable execution under defined constraints.
 
@@ -60,14 +77,15 @@ Predictable execution under defined constraints.
 
 ### Deterministic Execution Tiers
 
-Execution is classified into three tiers:
+Execution is classified into:
 
 Tier A — Safe  
 Tier B — Governed Modification  
 Tier C — Destructive / Structural  
 
 Each tier defines:
-- Whether diffs are required
+
+- Whether a diff preview is required
 - Whether confirmation is required
 - Whether auto-execution is allowed
 
@@ -79,7 +97,7 @@ This prevents silent behavioral drift.
 
 Deterministic templates embed canonical SHA256 hashes.
 
-`doctor` verifies:
+doctor verifies:
 
 - Template presence
 - Version alignment
@@ -87,7 +105,39 @@ Deterministic templates embed canonical SHA256 hashes.
 
 If a file is manually edited outside deterministic flow, the system detects it.
 
-This enables tamper visibility.
+Tamper visibility is enforced.
+
+---
+
+### Upgrade Integrity Gate
+
+oc-deterministic upgrade:
+
+- Verifies canonical integrity before applying changes
+- Refuses overwrite if drift is detected
+- Supports --force override
+- Supports --dry-run
+
+Upgrade is governed mutation — not blind overwrite.
+
+---
+
+### Deterministic Backup + Revert
+
+Before template mutation:
+
+Snapshots are stored at:
+
+~/.openclaw/backups/deterministic/<timestamp>/
+
+Revert commands:
+
+oc-deterministic revert --list  
+oc-deterministic revert --to <timestamp>
+
+Revert restores deterministic files from snapshot.
+
+This enables safe experimentation without state loss.
 
 ---
 
@@ -100,7 +150,7 @@ Semantic memory is:
 - Evaluated against risk thresholds
 - Logged on violation
 
-Configuration:
+Configuration file:
 
 ~/.openclaw/.deterministic.json
 
@@ -110,10 +160,6 @@ Example:
   "semantic": {
     "HARD_LIMIT": 1200,
     "RISK_THRESHOLD_PERCENT": 85
-  },
-  "governance": {
-    "strict_mode": false,
-    "violation_logging": true
   }
 }
 
@@ -140,21 +186,7 @@ Supports:
 - Machine-readable JSON output
 - Deterministic backup snapshots
 - Governance event logging
-- CI integration
-
----
-
-## Upgrade Model
-
-Templates are version-stamped.
-
-Upgrade flow preserves:
-
-- Backups
-- Deterministic config
-- User SOUL.md
-
-Future releases include safe merge flows for template upgrades.
+- CI integration via exit codes
 
 ---
 
@@ -181,9 +213,9 @@ Designed for:
 - CI-integrated governance
 - Environments requiring auditability
 
-If you need experimentation, use OpenClaw alone.
+If you want experimentation, use OpenClaw alone.
 
-If you need discipline, use Deterministic.
+If you want discipline, use OpenClaw Deterministic.
 
 ---
 

package/ROADMAP.md

@@ -0,0 +1,81 @@
+# OpenClaw Deterministic (OCD) — Roadmap
+
+This roadmap outlines the next phases of deterministic governance evolution.
+
+The goal is not feature growth.
+
+The goal is stronger guarantees.
+
+---
+
+## Governance & Integrity
+
+- Safe template merge flow inside upgrade
+- Cooldown state visibility in doctor
+- Semantic shard suggestion automation
+
+---
+
+## Observability & Automation
+
+- Structured logging mode
+- Centralized governance event log (beyond episodic markdown)
+- Compaction activity log
+- Drift detection alerting mode
+
+(Status command complete)
+
+---
+
+## Memory System Enhancements
+
+- Deterministic shard splitting
+- Automatic semantic pressure warnings
+- Episodic summarization quality check
+- Manual compaction preview mode
+- Token estimation normalization
+- Memory integrity checksum tracking
+
+---
+
+## Install & Bootstrap
+
+- Fresh-install auto-enable refinement
+- Install confirmation summary report
+- Rollback preview mode
+- Backup pruning policy
+- Multi-workspace support
+
+---
+
+## CLI Improvements
+
+- enable --dry-run
+- revert --preview
+- Help polish
+- Command aliases
+
+(Exit codes already formalized via doctor/status)
+
+---
+
+## Architecture & Distribution
+
+- Governance flow diagram
+- Memory tier diagram
+- Upgrade policy documentation
+- Integration guide
+- Public positioning statement
+
+---
+
+## Advanced (Future)
+
+- Expanded governance config surface (.deterministic.json)
+- Policy enforcement plugin system
+- Multi-agent compatibility layer
+- External monitoring hook
+- Remote health reporting
+- Immutable governance lock mode
+- Strict mode blocking Tier B auto-execution
+- Deterministic sandbox testing mode

package/bin/audit.js

@@ -34,6 +34,14 @@ function exists(p) {
   }
 }
 
+function read(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+function stripHeaders(content) {
+  return content.replace(/<!--[\s\S]*?-->/g, "").trim();
+}
+
 console.log("\nRunning deterministic audit...\n");
 
 let driftFound = false;
@@ -52,11 +60,27 @@ for (const file of files) {
   }
 
   try {
+    const templateContent = stripHeaders(read(file.template));
+    const installedContent = stripHeaders(read(file.installed));
+
+    // Write stripped content to temp files for diff
+    const tmpDir = fs.mkdtempSync(path.join(require("os").tmpdir(), "audit-"));
+    const tmpTemplate = path.join(tmpDir, "template");
+    const tmpInstalled = path.join(tmpDir, "installed");
+
+    fs.writeFileSync(tmpTemplate, templateContent);
+    fs.writeFileSync(tmpInstalled, installedContent);
+
     const diff = execSync(
-      `diff -u "${file.template}" "${file.installed}"`,
+      `diff -u "${tmpTemplate}" "${tmpInstalled}"`,
       { stdio: "pipe" }
     ).toString();
 
+    // Cleanup temp files
+    fs.unlinkSync(tmpTemplate);
+    fs.unlinkSync(tmpInstalled);
+    fs.rmdirSync(tmpDir);
+
     if (diff.trim().length === 0) {
       console.log(`✅ ${file.name} matches template.`);
     } else {

package/bin/upgrade.js

@@ -6,6 +6,7 @@ const path = require("path");
 
 const args = process.argv.slice(2);
 const DRY_RUN = args.includes("--dry-run");
+const FORCE = args.includes("--force");
 
 const pkg = require(path.join(__dirname, "..", "package.json"));
 const CLI_VERSION = pkg.version;
@@ -15,6 +16,7 @@ const openclawRoot = path.join(home, ".openclaw");
 const workspace = path.join(openclawRoot, "workspace");
 
 const VERSION_REGEX = /Installed by openclaw-deterministic v([0-9.]+)/;
+const HASH_REGEX = /Canonical-Hash:\s*SHA256:([a-f0-9]+)/;
 
 const files = [
   "OPERATING_RULES.md",
@@ -48,37 +50,100 @@ function getInstalledVersion(content) {
   return match ? match[1] : null;
 }
 
-function upgradeFile(relPath) {
-  const targetPath = path.join(workspace, relPath);
-  const templatePath = path.join(__dirname, "..", "templates", relPath);
+function extractHash(content) {
+  const match = content.match(HASH_REGEX);
+  return match ? match[1] : null;
+}
 
-  if (!exists(targetPath)) return;
+function stripHeaders(content) {
+  return content.replace(/<!--[\s\S]*?-->/g, "").trim();
+}
 
-  const installed = read(targetPath);
-  const template = read(templatePath);
+function verifyIntegrity(installedContent) {
+  const storedHash = extractHash(installedContent);
+  if (!storedHash) {
+    return { valid: false, reason: "missing-canonical-hash" };
+  }
+
+  const stripped = stripHeaders(installedContent);
+  const crypto = require("crypto");
+  const currentHash = crypto
+    .createHash("sha256")
+    .update(stripped)
+    .digest("hex");
+
+  if (storedHash !== currentHash) {
+    return { valid: false, reason: "hash-mismatch" };
+  }
+
+  return { valid: true };
+}
+
+function loadTemplate(relPath) {
+  const templatePath = path.join(__dirname, "..", "templates", relPath);
+  if (!exists(templatePath)) {
+    console.error(`Template missing: ${relPath}`);
+    process.exit(1);
+  }
+  return read(templatePath);
+}
 
-  const installedVersion = getInstalledVersion(installed);
+function upgradeFile(relPath) {
+  const targetPath = path.join(workspace, relPath);
 
-  if (installedVersion === CLI_VERSION) {
-    console.log(`✓ ${relPath} already up to date.`);
+  if (!exists(targetPath)) {
+    console.log(`⚠ Skipping ${relPath} (not installed).`);
     return;
   }
 
-  console.log(`Upgrading ${relPath} from v${installedVersion} → v${CLI_VERSION}`);
+  const installed = read(targetPath);
+  const integrity = verifyIntegrity(installed);
+
+  if (!integrity.valid && !FORCE) {
+    console.error(
+      `❌ Refusing to upgrade ${relPath}: ${integrity.reason}.`
+    );
+    console.error(
+      "   File has been modified or is missing canonical header."
+    );
+    console.error("   Re-run with --force to override.");
+    process.exit(2);
+  }
 
-  const stamped = `<!-- Installed by openclaw-deterministic v${CLI_VERSION} -->\n${template}`;
+  const template = loadTemplate(relPath);
+
+  const stamped = template.replace(
+    VERSION_REGEX,
+    `Installed by openclaw-deterministic v${CLI_VERSION}`
+  );
 
   write(targetPath, stamped);
+
+  if (!DRY_RUN) {
+    console.log(`✅ Upgraded ${relPath} → v${CLI_VERSION}`);
+  }
+}
+
+if (!exists(openclawRoot)) {
+  console.error("OpenClaw not found at ~/.openclaw");
+  process.exit(1);
 }
 
-if (!exists(openclawRoot) || !exists(workspace)) {
-  console.error("OpenClaw workspace not found.");
+if (!exists(workspace)) {
+  console.error("OpenClaw workspace missing at ~/.openclaw/workspace");
   process.exit(1);
 }
 
-console.log(`Running deterministic upgrade → CLI v${CLI_VERSION}\n`);
+console.log(`\nRunning deterministic upgrade → v${CLI_VERSION}\n`);
 
-files.forEach(upgradeFile);
+for (const rel of files) {
+  upgradeFile(rel);
+}
+
+if (DRY_RUN) {
+  console.log("\nDry-run complete. No changes written.\n");
+} else {
+  console.log("\nUpgrade complete.\n");
+}
 
-console.log("\nUpgrade complete.\n");
 process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdotwinter/openclaw-deterministic",
-  "version": "0.17.5",
+  "version": "0.17.8",
   "description": "Deterministic governance and memory compaction layer for OpenClaw",
   "keywords": [
     "openclaw",