Checkpoints: create/list/open/diff/revert from palette

[DecisionNerd]

Problem

Checkpoint APIs are unused in the extension; investigations lack an in-editor safety net.

Tracks under #1 (Phase 3).

Objective

Expose create/list/open/diff/revert as palette-first commands with confirmations on destructive revert.

Debt / regime

• Debt type: craft/UX + development
• Quality regime: B (product)

Requirements

• Commands: GraphForge: Create Checkpoint…, List Checkpoints, Open Checkpoint, Diff Checkpoints…, Revert to Checkpoint….
• List via searchable QuickPick (name + time); details as markdown/JSON for agents.
• Open checkpoint: make read-only expectations clear (CheckpointView execute if exposed).
• Revert: confirm + type checkpoint name (or equivalent explicit confirm).
• Flat commands — no nested checkpoint wizard.

Acceptance Criteria

• Create + list round-trip
• Diff produces a readable artifact
• Revert requires explicit confirmation
• Failures surface engine error codes

BDD Completion Scenarios

Scenario: Create and list
Given open project
When user creates checkpoint before-rank
Then List Checkpoints includes before-rank

Scenario: Revert confirm
Given an existing checkpoint
When user runs Revert without confirming
Then project generation is unchanged

Implementation Notes

• Node APIs: checkpoint, listCheckpoints, openCheckpoint, diffCheckpoints, deleteCheckpoint, revertToCheckpoint
• Wire through session; ADR 0014 contract in engine docs

Observability

Toast on create/revert with checkpoint name + generation uuid when available.

Security And Privacy

Revert is destructive local project mutation — hard confirm required.

Testing

• Manual against temp project; skip or gate native CI if binding absent
• Unit for confirm gating logic

Documentation

• README Checkpoints; link engine checkpoint contract

Non-Goals

• Checkpoint UI timeline webview (list + diff docs sufficient for v1)
• Remote/multi-user sync

Related Issues

• Parent: Tracker: Wire GraphForge engine workbench in VS Code (palette-first) #1
• Setup: Setup UX: detect @graphforge/node, install/link binding, detect or init project #2

Open Questions

• None

[coderabbitai]

🔗 Related PRs

CurateLabs/startops-nextjs#73 - Promote staging to production [merged]
CurateLabs/startops-nextjs#83 - Promote staging: MCP evidence file uploads and CI improvements [merged]
CurateLabs/graphforge-legecy#2583 - fix(storage): preserve checkpoint corruption errors [open]
CurateLabs/graphforge#234 - feat: add portable project interchange [open]
CurateLabs/graphforge#235 - feat(cli): add Python and Node lifecycle launchers [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[DecisionNerd]

Implemented on feat/phase-3-4-search-power (commit f2ee652, in isolated worktree graphforge-vscode-phase34):

Flat palette commands in src/commands/checkpoints.ts: GraphForge: Create Checkpoint…, List Checkpoints, Open Checkpoint…, Diff Checkpoints…, Delete Checkpoint…, Revert to Checkpoint…. No cascading checkpoint wizard — each is its own top-level command.

• Open Checkpoint… returns a read-only CheckpointView handle and lets you optionally run a Cypher query against it (mutations fail closed by construction).
• Diff Checkpoints… supports from/to (including "current"), scope (summary|graph|ontology|configuration|capabilities|provenance|knowledge|epistemic|all), and detail (summary|records).
• Revert to Checkpoint… is hard-confirmed: analyst must retype the exact checkpoint name in a second input box (in addition to a reason string) before the destructive engine call fires.
• All ops are async against the binding (Promise<Buffer>) and decode Arrow IPC via decodeTable; missing binding methods raise UnsupportedByBindingError with a clear message rather than throwing an opaque error.

Gaps: no live-binding integration test in this sandbox; tsc --noEmit / build / unit tests pass.

[DecisionNerd]

Shipped in PR #14, merged to main at 4a60284.