@sdotwinter/openclaw-deterministic 0.17.4 → 0.17.6

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,2 +1,204 @@
-# openclaw-deterministic
-Deterministic governance and memory compaction layer for OpenClaw
+# OpenClaw Deterministic
+
+A deterministic execution, memory governance, 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.
+
+This is not an assistant plugin.
+
+It is a governance layer.
+
+---
+
+## Installation
+
+Install globally:
+
+npm install -g @sdotwinter/openclaw-deterministic
+
+Then initialize governance inside your OpenClaw workspace:
+
+oc-deterministic install
+
+Verify installation:
+
+oc-deterministic doctor
+
+Concise health summary:
+
+oc-deterministic status
+
+---
+
+## What This Solves
+
+AI systems drift.
+
+They drift in:
+- Memory usage
+- Execution classification
+- File modification behavior
+- Configuration alignment
+- Contract integrity
+
+OpenClaw Deterministic enforces:
+
+- Explicit execution tiers
+- Canonical template integrity verification
+- Semantic memory limits
+- Config-driven thresholds
+- Governance event logging
+- Structured machine-readable health reporting
+
+The goal:
+
+Predictable execution under defined constraints.
+
+---
+
+## Core Concepts
+
+### Deterministic Execution Tiers
+
+Execution is classified into three tiers:
+
+Tier A — Safe  
+Tier B — Governed Modification  
+Tier C — Destructive / Structural  
+
+Each tier defines:
+- Whether diffs are required
+- Whether confirmation is required
+- Whether auto-execution is allowed
+
+This prevents silent behavioral drift.
+
+---
+
+### Canonical Template Integrity
+
+Deterministic templates embed canonical SHA256 hashes.
+
+`doctor` verifies:
+
+- Template presence
+- Version alignment
+- Canonical integrity
+
+If a file is manually edited outside deterministic flow, the system detects it.
+
+This enables tamper visibility.
+
+---
+
+### Semantic Memory Governance
+
+Semantic memory is:
+
+- Token-estimated
+- Compared against configurable HARD_LIMIT
+- Evaluated against risk thresholds
+- Logged on violation
+
+Configuration:
+
+~/.openclaw/.deterministic.json
+
+Example:
+
+{
+  "semantic": {
+    "HARD_LIMIT": 1200,
+    "RISK_THRESHOLD_PERCENT": 85
+  },
+  "governance": {
+    "strict_mode": false,
+    "violation_logging": true
+  }
+}
+
+This prevents uncontrolled memory expansion.
+
+---
+
+### Observability
+
+Available commands:
+
+init  
+install  
+upgrade  
+doctor  
+doctor --json  
+status  
+enable  
+revert  
+audit  
+
+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.
+
+---
+
+## Architecture
+
+Governance operates at three layers:
+
+1. Execution classification  
+2. Memory pressure management  
+3. Canonical integrity verification  
+
+OpenClaw Deterministic does not replace OpenClaw.
+
+It constrains it.
+
+---
+
+## Intended Use
+
+Designed for:
+
+- Production OpenClaw deployments
+- Long-running agent systems
+- CI-integrated governance
+- Environments requiring auditability
+
+If you need experimentation, use OpenClaw alone.
+
+If you need discipline, use Deterministic.
+
+---
+
+## Philosophy
+
+Determinism over autonomy.
+
+No silent behavior changes.
+
+Explicit classification before execution.
+
+Auditable state at all times.
+
+---
+
+## License
+
+MIT

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.4",
+  "version": "0.17.6",
   "description": "Deterministic governance and memory compaction layer for OpenClaw",
   "keywords": [
     "openclaw",