RFC 0013: SQLite snapshot backup artifacts

[giodl73-repo]

Summary

RFC 0013 defines the SQLite-safe artifact boundary now implemented by
openclaw/openclaw#105718:

one live OpenClaw-owned SQLite database -> one verified, immutable snapshot
directory -> fresh-target restore

The landed command is:

openclaw backup sqlite create
openclaw backup sqlite list
openclaw backup sqlite verify
openclaw backup sqlite restore

OpenClaw owns database roles, SQLite-safe capture, manifest and hash creation,
strict verification, private staging, atomic local publication, and
fresh-target restore. Hosts and operators own upload, encryption, retention,
restore timing, startup orchestration, and failover policy.

What We Learned From Running Snapshots In Lobster

We have learned a lot since we first started running the snapshot boundary in
Lobster:

• syncing completed manifest.json plus database.sqlite artifacts is the
  right boundary; syncing live SQLite files and sidecars is not;
• the SQLite owner must author and verify the artifact because a host cannot
  infer database role, WAL state, schema, indexes, ownership, or safe restore
  semantics from paths;
• a verified local snapshot is intentionally smaller than a complete
  replacement or scale-from-zero transaction;
• portable recovery still needs explicit treatment for non-SQLite state,
  credentials and external dependencies, durable host acceptance, final
  quiescence, generation fencing, restored readiness, and coordinator replay;
  and
• those lifecycle concerns should compose above this RFC rather than expanding
  or duplicating the landed SQLite implementation.

OpenClaw main also already has the host-neutral
gateway.suspend.prepare|status|resume contract from
openclaw/openclaw#103618,
with Vincent's validation repair in
openclaw/openclaw#103925.
Follow-on handoff work should reuse that cooperative tracked-work fence rather
than propose another pause API. The host still owns external ingress fencing,
third-party Channel handling, and full process/filesystem consistency.

The result is a simpler follow-on direction: keep RFC 0013 and PR 105718 as the
authoritative owner primitive, then discuss small optional sidecars for
aggregate recovery-point components, portable handoff, and restored admission.
Lobster remains one proving host, not part of the core snapshot contract.

Scope

This RFC remains deliberately narrow:

• shared OpenClaw state and per-agent SQLite databases;
• verified local snapshot repositories;
• committed WAL-state capture through SQLite;
• strict manifests, hashes, schema/role/owner verification;
• safe cross-platform staging and publication; and
• restore only to a fresh target.

It does not define:

• scheduling, upload, object storage, or retention;
• credential transfer;
• aggregate OpenClaw state capture;
• restore-on-boot;
• leases, generation fencing, or safeToDestroy;
• retained ingress, hibernation, wake, or managed failover.

Implementation

Implementation landed in
openclaw/openclaw#105718,
commit
2f25e9cba384acfc06cdf83640f236fdb7c1af33.

The original contributor implementation in
openclaw/openclaw#94805 was
superseded by Vincent's hardened implementation while preserving the
SQLite-safe artifact direction.

Current-Head Validation

• RFC head:
  864d7dee6ba6b9cf9e2f902f174408e5fbc570db
• One RFC file, rfcs/0013-cloud-serializable-sqlite-state.md
• Frontmatter records status: completed and the landed implementation.
• The RFC matches the final backup sqlite command and responsibility split.
• PR 105718 records Linux, Windows, and macOS proof for the landed behavior.
• RFC checks currently pass.

Review Request

Please review RFC 0013 as the completed SQLite owner-artifact contract.

Separately, we would value feedback on whether its completed snapshot
directories and exact manifests are the right substrate for small,
host-neutral follow-on sidecars. Those sidecars would not change this RFC's
snapshot semantics, add Lobster-specific APIs, or duplicate the existing
gateway.suspend.* contract.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 15, 2026, 12:02 AM ET / 04:02 UTC.

ClawSweeper review

What this changes

This PR adds a completed RFC documenting OpenClaw’s SQLite-safe backup artifacts, verification boundary, and fresh-target restore workflow.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep open for a maintainer lifecycle decision: the RFC is useful, but its unchanged frontmatter records a pull request as the accepted implementation issue, contrary to this repository’s RFC process. Likely related people: kevinlin-openai (high) and Dallin Romney (medium).

Priority: P3
Reviewed head: 864d7dee6ba6b9cf9e2f902f174408e5fbc570db
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is focused and useful, but its completed acceptance record needs correction before it is merge-ready.
Proof confidence	🌊 off-meta tidepool	Not applicable: This is a documentation-only change; the merge blocker is RFC lifecycle metadata, not independently executable behavior.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This is a documentation-only change; the merge blocker is RFC lifecycle metadata, not independently executable behavior.
Evidence reviewed	7 items	RFC lifecycle requires an implementation issue: Current main says an accepted RFC must create a GitHub issue for implementation and put that issue URL in frontmatter before merging. Current accepted RFCs use issue URLs: Current main records accepted RFC implementation trackers under /issues/, demonstrating the intended metadata shape. Proposed metadata conflicts with that lifecycle: The supplied PR patch’s line 7 sets issue to https://github.com/openclaw/openclaw/pull/105718 while declaring the RFC completed; that is an implementation pull request, not the required implementation issue.
Findings	1 actionable finding	[P1] Record the accepted implementation issue
Security	None	None.

How this fits together

The documented backup boundary turns a live OpenClaw-owned SQLite database into a verified local snapshot directory for operators or hosts to retain. A fresh target can then restore that artifact before reopening the database.

flowchart LR
  A[Live SQLite database] --> B[Backup command]
  B --> C[SQLite-safe snapshot capture]
  C --> D[Manifest and hash verification]
  D --> E[Immutable snapshot directory]
  E --> F[Fresh-target restore]

Loading

Decision needed

Question	Recommendation
Was the SQLite snapshot contract formally accepted through an implementation issue that this RFC should record, or should the RFC remain in the draft lifecycle pending that decision?	Record the accepted implementation issue: If maintainers accepted this contract, replace the issue value with the formal implementation issue and keep the RFC completed.

Why: The repository process requires an explicit acceptance/implementation issue, and the review cannot infer whether an external implementation pull request represents that missing governance record.

Before merge

• Add real behavior proof - Not applicable: This is a documentation-only change; the merge blocker is RFC lifecycle metadata, not independently executable behavior.
• Record the accepted implementation issue (P1) - The new frontmatter points issue at feat(backup): add verified SQLite snapshots openclaw#105718, but the repository lifecycle requires an accepted RFC to record the GitHub implementation issue there. Replace it with that formal issue URL, or return the RFC to draft with a blank field; otherwise this merge records an unsupported completed/accepted state.
• Resolve merge risk (P1) - Merging as completed with a pull-request URL in issue would leave an inaccurate acceptance and implementation-tracking record for this RFC.
• Resolve merge risk (P1) - The local partial clone could not fetch the PR blob during this review because GitHub DNS resolution failed; the finding is nevertheless directly supported by the supplied patch and locally inspected lifecycle policy.
• Complete next step (P2) - A maintainer must confirm the RFC’s formal acceptance and implementation issue; automation must not invent that governance record.

Findings

• [P1] Record the accepted implementation issue — rfcs/0013-cloud-serializable-sqlite-state.md:7

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	1 file affected; 290 lines added	The PR is a single RFC document, so correcting its frontmatter is a focused prerequisite to merge.

Root-cause cluster

Relationship: canonical
Canonical: #20
Summary: This RFC is the stated SQLite snapshot baseline; the related addendum is a separate lifecycle proposal built above it.

Members:

• adjacent_distinct: RFC 0013 addendum: application-consistent recovery for scale-to-zero #46 - Its supplied description explicitly treats this RFC as the authoritative one-database snapshot contract while proposing separate host lifecycle and restored-admission concerns.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Correct the lifecycle record before merge (recommended)
   Record the actual accepted implementation issue in frontmatter and retain the core implementation pull request as evidence.
2. Hold the RFC as unaccepted
   Keep the document in draft state until maintainers choose and record the acceptance path.

Technical review

Best possible solution:

Retain a compact completed RFC only after it records the formal accepted implementation issue and separately links the landed implementation pull request as supporting evidence.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a documentation-only RFC, and the blocker is an inspectable lifecycle-metadata inconsistency rather than runtime behavior.

Is this the best way to solve the issue?

No: marking the RFC completed while its required issue field points to an implementation pull request is not the repository’s documented lifecycle; record the accepted issue or return the RFC to draft.

Full review comments:

• [P1] Record the accepted implementation issue — rfcs/0013-cloud-serializable-sqlite-state.md:7
  The new frontmatter points issue at feat(backup): add verified SQLite snapshots openclaw#105718, but the repository lifecycle requires an accepted RFC to record the GitHub implementation issue there. Replace it with that formal issue URL, or return the RFC to draft with a blank field; otherwise this merge records an unsupported completed/accepted state.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against af708f0ddb6f.

Labels

Label changes:

• add merge-risk: 🚨 other: The proposed completed status and non-issue tracker could create a misleading RFC acceptance record after merge.

Label justifications:

• P3: This is a documentation-process correction with no demonstrated runtime regression.
• merge-risk: 🚨 other: The proposed completed status and non-issue tracker could create a misleading RFC acceptance record after merge.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This is a documentation-only change; the merge blocker is RFC lifecycle metadata, not independently executable behavior.

Evidence

What I checked:

• RFC lifecycle requires an implementation issue: Current main says an accepted RFC must create a GitHub issue for implementation and put that issue URL in frontmatter before merging. (README.md:91, af708f0ddb6f)
• Current accepted RFCs use issue URLs: Current main records accepted RFC implementation trackers under /issues/, demonstrating the intended metadata shape. (rfcs/0008-context-engine-runtime-settings.md:8, af708f0ddb6f)
• Proposed metadata conflicts with that lifecycle: The supplied PR patch’s line 7 sets issue to https://github.com/openclaw/openclaw/pull/105718 while declaring the RFC completed; that is an implementation pull request, not the required implementation issue. (rfcs/0013-cloud-serializable-sqlite-state.md:7, 864d7dee6ba6)
• Prior blocker remains at the current head: The supplied prior review identified the same missing accepted-implementation issue, and the current reviewed SHA is unchanged from that review. (rfcs/0013-cloud-serializable-sqlite-state.md:7, 864d7dee6ba6)
• Current main does not already contain this RFC: The proposed RFC path is added relative to the PR base and is absent from the current default branch, so this documentation change is still necessary if its lifecycle record is corrected. (rfcs/0013-cloud-serializable-sqlite-state.md, af708f0ddb6f)
• Lifecycle-policy provenance: The RFC-process guidance appears to date to the README history entry docs: update rfc process, authored by kevinlin-openai. (README.md:78, e366ea9825a4)

Likely related people:

• kevinlin-openai: README history attributes docs: update rfc process to this author; that guidance defines the required accepted-RFC implementation-issue record. (role: RFC lifecycle guidance author; confidence: high; commits: e366ea9825a4; files: README.md)
• Dallin Romney: README history attributes the recent RFC structure clarification to this contributor, making them an adjacent routing contact for RFC document conventions. (role: recent RFC documentation contributor; confidence: medium; commits: 3aa7d727383f; files: README.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Replace the frontmatter issue value with the formal accepted implementation issue, or restore draft lifecycle metadata.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (45 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T10:59:45.543Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Record the accepted implementation issue
• reviewed 2026-08-09T12:42:08.718Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Restore the required RFC acceptance record
• reviewed 2026-08-09T14:50:52.171Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Record the accepted implementation issue
• reviewed 2026-08-09T19:49:33.805Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Record the accepted implementation issue
• reviewed 2026-08-09T22:00:38.165Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Record the accepted implementation issue
• reviewed 2026-08-09T23:13:46.602Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Record the required accepted implementation issue
• reviewed 2026-08-11T03:13:24.429Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Link the required implementation issue
• reviewed 2026-08-12T19:14:17.581Z sha 864d7de :: needs real behavior proof before merge. :: [P1] Record the accepted implementation issue

[giodl73-repo]

@clawsweeper re-review

Updated the PR body with final-head RFC proof, including head SHA, diff stat, frontmatter, line count, and git diff --check output. The maintainer-discussion thread remains pending maintainer-side Discord action/access, and acceptance metadata is intentionally unchanged while draft.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[giodl73-repo]

Hey @vincentkoc — we have learned a lot since we first started running the
snapshot boundary in Lobster.

Your #105718 implementation gave us the native owner seam we were missing. The
main lesson from the broader continuity proof is that we should not build a
parallel snapshot/archive system. We can keep RFC 0013 and backup sqlite
authoritative, then make any follow-on much smaller: verified owner snapshots
plus explicit non-SQLite components and external obligations, followed by
host-owned acceptance, fenced restore, and restored readiness.

We also confirmed that current main already has the host-neutral
gateway.suspend.prepare|status|resume seam from #103618, including your
#103925 validation repair. Any follow-on handoff should compose that shipped
cooperative fence with backup sqlite, not invent another pause or drain API.

The real process/container proof also clarified where snapshot semantics should
end:

• local snapshot success is not durable host acceptance or safeToDestroy;
• portable state needs explicit credential and dependency treatment;
• final capture should reuse gateway.suspend.* while the host separately
  fences external ingress and untracked work, rather than infer safety from
  process exit;
• restore success is not readiness or admission; and
• coordinator replay must reuse the same child/generation without repeating
  preparation or restore.

We have updated this PR body to match the landed implementation and current RFC
head. Before authoring any follow-on sidecars, we would like your read on the
ownership split: does composing completed snapshot directories and exact
manifests above RFC 0013 feel like the right direction, while keeping upload,
retention, lifecycle, and wake host-owned?

[giodl73-repo]

Follow-on sidecars are now isolated in draft PR #46 rather than expanding this
completed RFC directly:

• RFC 0013 and #105718 remain the SQLite snapshot authority.
• Current-main gateway.suspend.* remains the cooperative tracked-work fence.
• PR RFC 0013 addendum: application-consistent recovery for scale-to-zero #46 defines only aggregate components, portable handoff, and restored
  admission above those shipped seams.

This keeps PR #20 narrow and lets the lifecycle contracts receive independent
review before any implementation work.