RFC 0013: SQLite snapshot backup artifacts by giodl73-repo · Pull Request #20 · openclaw/rfcs

giodl73-repo · 2026-06-18T21:25:19Z

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 · 2026-06-18T21:26:01Z

Codex review: needs real behavior proof before merge. Reviewed July 6, 2026, 9:05 PM ET / 01:05 UTC.

Summary
Adds a 600-line RFC proposing openclaw backup sqlite snapshot as a SQLite-safe backup artifact boundary for hosted file-sync scenarios.

Reproducibility: not applicable. this is a feature RFC pull request, not a bug report. The merge blocker is source-verifiable from the added frontmatter and the repository RFC lifecycle docs.

Review metrics: 3 noteworthy metrics.

RFC Diff Size: 1 file added, 600 lines. The patch is Markdown-only, but it records broad product direction that maintainers should accept deliberately.
Proof Freshness: current head e26ef5c, proof head 6e46159. The contributor proof no longer matches the live PR head after the July 7 update.
Lifecycle Fields: 2 blocking fields. status: draft and blank issue are the exact metadata fields that must change before an accepted RFC merges.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦐 gold shrimp
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Refresh the PR body proof against current head e26ef5c73814ab1fc327f878a4ae7e10af2d9a68.
[P1] After maintainer acceptance, update status and issue before merge.
Keep the RFC scope aligned with Add SQLite snapshot artifacts under backup openclaw#94805 and Add snapshot SQLite stress harness openclaw#94967.

Proof guidance:

[P1] Needs stronger real behavior proof before merge: The PR body contains terminal proof for an older head (6e46159), but the live PR head is e26ef5c; refresh proof with current-head output and redact any private paths or identifiers. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] Merging now would publish an RFC with status: draft and no implementation issue, contrary to the repository lifecycle docs.
[P1] The RFC itself says the Scout/Lobster pilot should answer whether the long-term surface is a core command, host-owned plugin command, or both before acceptance.
[P1] The current PR body proof is stale: it verifies 6e4615948d376581cbf0e74343b08e0a5f4c61b1, but the live head is e26ef5c73814ab1fc327f878a4ae7e10af2d9a68.
[P1] The linked OpenClaw implementation and stress-harness PRs remain open draft proof paths, so acceptance should stay coordinated with that stack.

Maintainer options:

Hold Until Acceptance Package Is Current (recommended)
Keep the PR open until pilot/product direction is settled, then update accepted metadata and refresh proof against the current head before merge.
Merge As A Deliberate RFC Lifecycle Exception
Maintainers could intentionally merge the draft, but main would contain unaccepted product direction with a blank implementation issue.
Pause Or Redirect If Core Is Not The Owner
If the pilot proves this should stay in a host/plugin path, pause or close the RFC rather than publishing a core command proposal.

Next step before merge

[P1] Maintainer RFC acceptance and contributor current-head proof are needed; there is no narrow automated code repair to queue.

Maintainer decision needed

Question: Should this RFC be accepted as a core openclaw backup sqlite snapshot command now, held until pilot evidence settles the core/plugin split, or redirected away from core?
Rationale: The RFC proposes a new core backup command and explicitly says pilot evidence should decide whether the long-term owner is core, a host-owned plugin, or both; automation cannot choose that product boundary.
Likely owner: kevinlin-openai — The strongest same-repository history signal is ownership of the RFC lifecycle policy that governs when this document can merge.
Options:
- Hold For Pilot, Then Accept Metadata (recommended): Wait for the Scout/Lobster checkpoint, choose the core/plugin scope, create or select the implementation issue, and update the RFC metadata before merge.
- Accept Core Command Now: Maintainers can accept the core command direction immediately, but should still update the RFC status, issue, and current-head proof before merging.
- Redirect To Host Plugin Path: If pilot evidence shows this belongs outside core, keep or close this RFC in favor of the host/plugin implementation path.

Security
Cleared: The diff adds one Markdown RFC and does not introduce code execution, dependency, workflow, secret-handling, or supply-chain changes.

Review findings

[P1] Update RFC metadata before merging — rfcs/0013-cloud-serializable-sqlite-state.md:7-8

Review details

Best possible solution:

Keep this PR open until the pilot and maintainer discussion settle the core-versus-plugin scope, then update status, issue, and current-head proof before merge.

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

Not applicable; this is a feature RFC pull request, not a bug report. The merge blocker is source-verifiable from the added frontmatter and the repository RFC lifecycle docs.

Is this the best way to solve the issue?

No for merging as-is; the RFC may be useful, but the maintainable path is acceptance/pilot decision first, then accepted metadata and current-head proof before landing.

Full review comments:

[P1] Update RFC metadata before merging — rfcs/0013-cloud-serializable-sqlite-state.md:7-8
README.md and the template say new RFCs should not merge while status: draft; after acceptance they need status: accepted and an implementation issue. This added RFC still has status: draft and a blank issue, so landing this exact diff would publish an unaccepted RFC on main. This remains the previously raised lifecycle blocker.
Confidence: 0.93

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: not found in the target repository.

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

Label changes

Label changes:

add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body contains terminal proof for an older head (6e46159), but the live PR head is e26ef5c; refresh proof with current-head output and redact any private paths or identifiers. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
remove rating: 🦐 gold shrimp: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.
remove status: ⏳ waiting on author: Current PR status label is status: 📣 needs proof.
remove proof: sufficient: Current real behavior proof status is insufficient, not sufficient.

Label justifications:

P3: This is a low-risk RFC/product-direction PR with no runtime code change in this repository.
merge-risk: 🚨 other: The non-CI merge risk is publishing draft product direction before RFC acceptance metadata, pilot evidence, and current-head proof are settled.
rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body contains terminal proof for an older head (6e46159), but the live PR head is e26ef5c; refresh proof with current-head output and redact any private paths or identifiers. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

Target AGENTS.md check: No AGENTS.md exists under the target repository root, so no target-specific AGENTS policy applied. (a8e0ba2701d6)
RFC lifecycle policy: README says new RFCs should not be merged to main while still in draft status and should set an implementation issue when accepted. (README.md:80, e366ea9825a4)
Template lifecycle policy: The RFC template repeats that draft RFCs remain unmerged until accepted, then need status: accepted and an implementation issue URL before merge. (rfcs/0000-template.md:19, e366ea9825a4)
Current PR frontmatter: The added RFC still has status: draft and a blank issue, which is correct for discussion but blocks merging under the documented lifecycle. (rfcs/0013-cloud-serializable-sqlite-state.md:7, e26ef5c73814)
Product-direction scope: The RFC proposes a new core openclaw backup sqlite snapshot command and says a Scout/Lobster pilot should answer whether the long-term shape is core command, host-owned plugin command, or both. (rfcs/0013-cloud-serializable-sqlite-state.md:85, e26ef5c73814)
Proof freshness: Live PR data shows current head e26ef5c73814ab1fc327f878a4ae7e10af2d9a68, while the PR body proof still records head 6e4615948d376581cbf0e74343b08e0a5f4c61b1. (e26ef5c73814)

Likely related people:

kevinlin-openai: Blame ties the README and template lifecycle rules that block merging draft RFCs to this contributor. (role: RFC lifecycle policy author; confidence: high; commits: e366ea9825a4, f4fdf38f; files: README.md, rfcs/0000-template.md)
Dallin Romney: Recent history shows this contributor updated README and template guidance for RFC layout and sidecar conventions. (role: recent RFC documentation contributor; confidence: medium; commits: 3aa7d727383f; files: README.md, rfcs/0000-template.md)
Omar Shahine: Recent main history shows this contributor aligned RFC frontmatter and status metadata across RFC documents. (role: recent RFC metadata contributor; confidence: medium; commits: bab3348050f7, f346050b2878; files: rfcs/0002-approval-prompt-markdown.md, rfcs/needs_refactoring/doctor-health-upgrades.md, rfcs/needs_refactoring/imessage-channel-configuration-cleanup.md)
giodl73-repo: This contributor has current-main RFC history in this repository and authored the proposal branch, so follow-up drafting naturally routes there after maintainer direction. (role: recent RFC area contributor; confidence: medium; commits: 89cf322325b0, a8844eb, e26ef5c73814; files: rfcs/0009-hosted-feeds-for-plugins-and-skills.md, rfcs/0013-cloud-serializable-sqlite-state.md)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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.

Review history (1 earlier review cycle)

reviewed June 25, 2026, 5:19 PM ET / 21:19 UTC sha 6e46159 :: found issues before merge. :: [P1] Update RFC metadata before merging

giodl73-repo · 2026-06-19T00:31:48Z

@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 · 2026-06-19T00:31:51Z

🦞🧹
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 · 2026-06-19T20:27:23Z

@clawsweeper re-review

Updated the RFC and PR body to current head 2586c7aadf26c7bc5a17ff503889cf756baf0254.

What changed:

removed the stale configured memorySearch.store.path framing
aligned memory-search with the database-first ownership model
refreshed PR body proof and removed the line-count claim that was mismatched in the previous body
git diff --check origin/main...HEAD passes

clawsweeper · 2026-06-19T20:27:25Z

🦞🧹
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 · 2026-06-19T20:51:45Z

@clawsweeper re-review

Updated the RFC and PR body to current head 7f09e0a22adc9e18caf7f0b1a16113eae703f0f5.

What changed:

Phase 1 command examples now only include --target global and --agent main
memory-search-only artifacts are explicitly deferred to future design because current memory-search state is owned by the per-agent database-first store
RFC now says a future memory-search-only target needs either a dedicated owner database or a true logical export
roadmap matches the current OpenClaw stack: PR #94805 for core snapshot, PR #94967 for stress validation, Phase 2 WAL bundles only after metrics greenlight
git diff --check origin/main...HEAD passes

clawsweeper · 2026-06-19T20:51:47Z

🦞🧹
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 · 2026-07-21T15:02:25Z

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?

clawsweeper · 2026-07-21T15:08:00Z

ClawSweeper status: review started.

I am starting a fresh review of this pull request: RFC 0013: SQLite snapshot backup artifacts This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

giodl73-repo · 2026-07-21T15:43:34Z

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: recovery lifecycle sidecars #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.

Add cloud-serializable SQLite state RFC

b5b35e4

Update RFC PR metadata

1c0bbe1

giodl73-repo mentioned this pull request Jun 18, 2026

[Feature Request] 支持PostgreSQL替代SQLite作为内部存储 openclaw/openclaw#90370

Closed

Clarify opt-in durability provider model

56abc0a

Refocus RFC on snapshot plugin

3996309

giodl73-repo changed the title ~~RFC 0013: Cloud-Serializable SQLite State~~ RFC 0013: SQLite State Snapshot Plugin Jun 18, 2026

giodl73-repo added 2 commits June 18, 2026 15:01

Clarify reusable snapshot provider contract

9441622

Add snapshot implementation roadmap

798f80c

clawsweeper Bot added the feature: ✨ showcase ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. label Jun 18, 2026

This was referenced Jun 18, 2026

Add core snapshot provider proof openclaw/openclaw#94694

Closed

Add core snapshot CLI openclaw/openclaw#94717

Closed

giodl73-repo marked this pull request as ready for review June 19, 2026 01:52

clarify snapshot database-first targets

4d0320b

clawsweeper Bot removed the proof: sufficient Contributor real behavior proof is sufficient. label Jun 19, 2026

Align snapshot RFC with database-first memory search

2586c7a

Move memory search snapshot target to future design

7f09e0a

giodl73-repo added 2 commits June 22, 2026 10:42

Add Scout snapshot pilot checkpoint

6e46159

Frame snapshots as SQLite backup artifacts

e26ef5c

giodl73-repo changed the title ~~RFC 0013: SQLite State Snapshot Command~~ RFC 0013: SQLite snapshot backup artifacts Jul 7, 2026

Update SQLite snapshot RFC to landed implementation

864d7de

giodl73-repo mentioned this pull request Jul 21, 2026

RFC 0013 addendum: recovery lifecycle sidecars #46

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

RFC 0013: SQLite snapshot backup artifacts#20

RFC 0013: SQLite snapshot backup artifacts#20
giodl73-repo wants to merge 24 commits into
mainfrom
rfc/cloud-serializable-sqlite-state

giodl73-repo commented Jun 18, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

giodl73-repo commented Jun 19, 2026

Uh oh!

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

giodl73-repo commented Jun 19, 2026

Uh oh!

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

giodl73-repo commented Jun 19, 2026

Uh oh!

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

giodl73-repo commented Jul 21, 2026

Uh oh!

clawsweeper Bot commented Jul 21, 2026

Uh oh!

giodl73-repo commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

giodl73-repo commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What We Learned From Running Snapshots In Lobster

Scope

Implementation

Current-Head Validation

Review Request

Uh oh!

clawsweeper Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented Jun 19, 2026

Uh oh!

clawsweeper Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented Jun 19, 2026

Uh oh!

clawsweeper Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented Jun 19, 2026

Uh oh!

clawsweeper Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented Jul 21, 2026

Uh oh!

clawsweeper Bot commented Jul 21, 2026

Uh oh!

giodl73-repo commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

giodl73-repo commented Jun 18, 2026 •

edited

Loading

clawsweeper Bot commented Jun 18, 2026 •

edited

Loading

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading