@wipcomputer/wip-ldm-os 0.4.87-alpha.1 → 0.4.87-alpha.3

package/scripts/test-ldm-install-preserves-foreign-bin.mjs

@@ -102,6 +102,11 @@ exit 0
   assert((readFileSync(shimPath).length > 0), 'foreign shim remains non-empty', output);
   assert((statSync(shimPath).mode & 0o111) !== 0, 'foreign shim remains executable', output);
   assert((existsSync(join(binDir, 'ldm-backup.sh'))), 'ldm-owned scripts still deploy into ~/.ldm/bin', output);
+  assert((existsSync(join(binDir, 'ldm-backup-engine.py'))), 'backup engine deploys into ~/.ldm/bin', output);
+  assert((existsSync(join(binDir, 'ldm-backup-policy.json'))), 'backup policy deploys into ~/.ldm/bin', output);
+  assert((statSync(join(binDir, 'ldm-backup-engine.py')).mode & 0o111) !== 0, 'backup engine is executable', output);
+  assert((statSync(join(binDir, 'ldm-backup-policy.json')).mode & 0o111) === 0, 'backup policy is not executable', output);
+  assert(readFileSync(join(binDir, 'ldm-backup-policy.json'), 'utf8') === readFileSync(join(repo, 'scripts', 'ldm-backup-policy.json'), 'utf8'), 'backup policy content matches package source', output);
 
   const restored = readFileSync(shimPath);
   assert(restored.length === Buffer.byteLength(shimContent), 'foreign shim size is unchanged', output);

package/shared/docs/README.md.tmpl

@@ -16,7 +16,7 @@ If something is wrong, update `~/.ldm/config.json` or run `ldm install`. The doc
 | `what-is-dotldm.md` | The `~/.ldm/` runtime directory explained |
 | `directory-map.md` | What lives where and why |
 | `how-worktrees-work.md` | Git worktrees, the _worktrees/ convention |
-| `how-backup-works.md` | Daily backup, iCloud offsite, restore |
+| `how-backup-works.md` | Safe dry run, verified internal snapshots, and later-tier gates |
 | `how-releases-work.md` | The full release pipeline |
 | `how-install-works.md` | ldm install, the install prompt, dogfooding |
 | `how-agents-work.md` | Agents, harnesses, bridge, memory |

package/shared/docs/directory-map.md.tmpl

@@ -43,7 +43,7 @@
   hooks/                    <- Claude Code hooks
   state/                    <- runtime state
   tmp/                      <- install staging
-  backups/                  <- daily backups (ldm-backup.sh) + iCloud offsite tars
+  backups/v1/internal/      <- verified internal snapshots and in-progress staging
 ```
 
 ## Harness Directories (deployment targets)

package/shared/docs/how-backup-works.md.tmpl

@@ -1,111 +1,78 @@
 # How Backup Works
 
-## One Script, One Place
+## Safe planning first
 
-`~/.ldm/bin/ldm-backup.sh` runs daily at 3:00 AM via LaunchAgent `ai.openclaw.ldm-backup`. It backs up everything to `~/.ldm/backups/`, then tars it to iCloud for offsite.
+The backup engine has a strictly read-only dry run:
 
-## What Gets Backed Up
+```bash
+~/.ldm/bin/ldm-backup.sh --dry-run
+```
 
-| Source | Method | What's in it |
-|--------|--------|-------------|
-| `~/.ldm/memory/crystal.db` | sqlite3 .backup | Irreplaceable memory (all agents) |
-| `~/.ldm/agents/` | cp -a | Identity files, journals, daily logs |
-| `~/.ldm/state/` | cp -a | Config, version, registry |
-| `~/.ldm/config.json` | cp | Workspace pointer, org |
-| `~/.openclaw/memory/main.sqlite` | sqlite3 .backup | OC conversations |
-| `~/.openclaw/memory/context-embeddings.sqlite` | sqlite3 .backup | Embeddings |
-| `~/.openclaw/workspace/` | tar | Shared context, daily logs |
-| `~/.openclaw/agents/main/sessions/` | tar | OC session JSONL |
-| `~/.openclaw/openclaw.json` | cp | OC config |
-| `~/.claude/CLAUDE.md` | cp | CC instructions |
-| `~/.claude/settings.json` | cp | CC settings |
-| `~/.claude/projects/` | tar | CC auto-memory + transcripts |
-| `~/wipcomputerinc/` | tar (excludes node_modules, .git/objects, old backups, _trash) | Entire workspace |
+It shows every policy source, classification, exclusion reason, per-source estimate, total estimated new bytes, available disk capacity, required reserve, planned staging path, planned internal destination, blocked requirements, and the final preflight verdict.
 
-**NOT backed up:** node_modules/, .git/objects/ (reconstructable), extensions (reinstallable), ~/.claude/cache.
+Dry run does not create files or directories. It does not acquire the persistent lock, write state, copy data, create a manifest, create a completion marker, rotate snapshots, write to Vault or iCloud, change the schedule, enable the LaunchAgent, or modify containment state. Sensitive filenames and contents are not printed.
 
-## Backup Structure
+Exit zero means the proposed run passes the same policy and preflight used by the real engine. Exit nonzero means a required source, encryption gate, destination, or disk reserve blocks the run.
 
-```
-~/.ldm/backups/2026-03-24--09-50-22/
-  ldm/
-    memory/crystal.db
-    agents/
-    state/
-    config.json
-  openclaw/
-    memory/main.sqlite
-    memory/context-embeddings.sqlite
-    workspace.tar
-    sessions.tar
-    openclaw.json
-  claude/
-    CLAUDE.md
-    settings.json
-    projects.tar
-  wipcomputerinc.tar
-```
+## Canonical source policy
 
-## iCloud Offsite
+`~/.ldm/bin/ldm-backup-policy.json` defines required, rebuildable, sensitive, blocked, manifest-only, and excluded sources. Estimation, capture, manifest generation, and exclusion records all use this one policy.
 
-After local backup, the entire dated folder is compressed and copied to iCloud. The iCloud path is read from `~/.ldm/config.json` at `paths.icloudBackup`.
+Sources that require encryption remain visibly blocked until that later gate ships. The engine never turns a blocked or missing required source into a partial success.
 
-```
-~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/
-  wipcomputerinc-lesa-2026-03-24--09-50-22.tar.gz
-```
+The policy has one explicit ID for every approved source-inventory row. The test suite compares the exact ID list so a future omission cannot silently pass.
 
-One file per backup. iCloud syncs it across devices. Rotates to {{backup.keep}} days.
+## Runtime and changing files
 
-## How to Run
+The engine uses Python 3 standard library only. No third-party Python packages are required. If `python3` is unavailable, the runner exits with `Backup failed [python3-missing]`. Owner acceptance of Python 3 as a release prerequisite must be recorded separately at the release gate.
 
-```bash
-~/.ldm/bin/ldm-backup.sh                    # run backup now
-~/.ldm/bin/ldm-backup.sh --dry-run          # preview what would be backed up
-~/.ldm/bin/ldm-backup.sh --keep 14          # keep 14 days instead of 7
-~/.ldm/bin/ldm-backup.sh --include-secrets   # include ~/.ldm/secrets/
-```
+A real run observes each source again immediately before capture. Changes since dry-run or initial planning are recorded and captured from the newer observation. Files and trees must then remain stable while that source is copied. Same-size changes are detected by checksum, and any during-capture mutation fails the run. SQLite uses the SQLite backup API for a transactionally consistent snapshot.
 
-## How to Restore
+The engine recalculates the reserve before copying a changed source. It includes staged bytes, stat-only refreshed remaining sources, a full checksum observation of the source about to be copied, projected metadata, and the required 10 percent reserve. Growth that crosses the floor fails before that source is copied.
 
-```bash
-~/.ldm/bin/ldm-restore.sh                           # list available backups
-~/.ldm/bin/ldm-restore.sh 2026-03-24--09-50-22      # restore everything
-~/.ldm/bin/ldm-restore.sh --only ldm <backup>       # restore only crystal.db + agents
-~/.ldm/bin/ldm-restore.sh --only openclaw <backup>  # restore only OC data
-~/.ldm/bin/ldm-restore.sh --from-icloud <file>      # restore from iCloud tar
-~/.ldm/bin/ldm-restore.sh --dry-run <backup>        # preview
+Manifest-only requirements must produce validated machine-readable evidence. An entry without an implemented generator is marked blocked before its source path is walked. When a required evidence generator is not implemented, including repo-aware Git/worktree and system inventories, the source stays blocked instead of being treated as fulfilled.
+
+## Successful snapshot
+
+A completed internal snapshot lives under:
+
+```text
+~/.ldm/backups/v1/internal/<snapshot-id>/
 ```
 
-After restore: `openclaw gateway restart` then `crystal status` to verify.
+It is built first as `.in-progress-<snapshot-id>`. Promotion happens only after every required capture succeeds, SQLite copies pass `PRAGMA quick_check`, checksums validate, the manifest validates, and `completion.json` is written last.
+
+Any required failure exits nonzero, writes no completion marker, and never prints `Backup complete`.
+
+## Retention
+
+The engine retains {{backup.keep}} unpinned verified snapshots plus every pinned snapshot. Pinned snapshots do not consume an unpinned retention slot. In-progress and unverified directories are never rotated.
+
+## Structured state
+
+Diagnostic state lives under `~/.ldm/state/backup/v1/`:
+
+- `schedule.json`
+- `attempt.json`
+- `result.json`
+- `success-local.json`
 
-## Schedule
+State records are atomic, but they are not completion proof. A snapshot requires a valid manifest and completion marker.
 
-| What | When | How |
-|------|------|-----|
-| Backup | 3:00 AM | LaunchAgent `ai.openclaw.ldm-backup` runs `~/.ldm/bin/ldm-backup.sh` |
+Snapshot identifiers use UTC and end in `Z`. If no valid containment marker is present, schedule state records evidence status as `unknown`.
 
-One LaunchAgent. One script. No Full Disk Access currently (target: midnight via LDMDevTools.app once PID error is fixed). Verify is built into the script (exit code + log).
+## Current boundaries
 
-## Config
+This engine correctness slice covers the internal tier. Vault, iCloud, monitoring, isolated restore, migration, and schedule resumption remain separately gated. Do not run a real backup until those gates are approved.
 
-All backup settings live in `~/.ldm/config.json`:
-- `paths.workspace` ... workspace path
-- `paths.icloudBackup` ... iCloud offsite destination
-- `backup.keep` ... retention days (default: 7)
-- `backup.includeSecrets` ... whether to include `~/.ldm/secrets/`
-- `org` ... used for tar filename prefix
+## Your system
 
-## Logs
+**Internal destination:** `~/.ldm/backups/v1/internal/`
 
-`~/.ldm/logs/backup.log` (LaunchAgent stdout/stderr)
+**Configured iCloud path:** `~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/` (not written by this engine slice)
 
----
+**Schedule label:** `ai.openclaw.ldm-backup`
 
-## Your System
+**Retention:** {{backup.keep}} unpinned verified snapshots
 
-**Local backups:** `~/.ldm/backups/`
-**iCloud offsite:** `~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/`
-**Schedule:** 3:00 AM via LaunchAgent `ai.openclaw.ldm-backup`
-**Retention:** {{backup.keep}} days local, {{backup.keep}} days iCloud
-**Script:** `~/.ldm/bin/ldm-backup.sh` (deployed by `ldm install`)
+**Runner:** `~/.ldm/bin/ldm-backup.sh`

package/shared/docs/system-directories.md.tmpl

@@ -33,7 +33,7 @@ Where LDM OS runs. Rules, commands, and skills are authored here and deployed to
 | `~/.ldm/hooks/` | Claude Code hooks | ldm install |
 | `~/.ldm/state/` | Runtime state | Tools (watermarks, markers) |
 | `~/.ldm/tmp/` | Install staging | ldm install (cleaned after) |
-| `~/.ldm/backups/` | Local backups + iCloud offsite tars | ldm-backup.sh |
+| `~/.ldm/backups/v1/internal/` | Verified internal snapshots and in-progress staging | ldm-backup.sh |
 
 ## Harness Directories (deployment targets)
 

package/shared/docs/what-is-dotldm.md.tmpl

@@ -41,7 +41,7 @@ The LDM OS runtime directory. Everything the system needs to run lives here. You
   hooks/               Claude Code hooks
   state/               runtime state (last release marker, watermarks)
   tmp/                 install staging (cleaned after install)
-  backups/             daily backup output (local + iCloud offsite)
+  backups/v1/internal/ verified internal snapshots and in-progress staging
 ```
 
 ## What Gets Backed Up

package/src/bridge/openclaw.plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "lesa-bridge",
+  "name": "LDM Bridge",
+  "description": "Agent-to-agent communication and shared-memory access through LDM OS.",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/src/bridge/package.json

@@ -4,6 +4,9 @@
   "private": true,
   "type": "module",
   "description": "WIP Bridge ... agent-to-agent communication, memory search, skill bridging. Core module of LDM OS.",
+  "openclaw": {
+    "extensions": ["./dist/openclaw.js"]
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "better-sqlite3": "^11.8.1",