Skip to content

feat(seed): support explicit checkpoint resume - #648

Open
RerankerGuo wants to merge 1 commit into
TencentCloud:mainfrom
RerankerGuo:feat/seed-checkpoint-resume
Open

feat(seed): support explicit checkpoint resume#648
RerankerGuo wants to merge 1 commit into
TencentCloud:mainfrom
RerankerGuo:feat/seed-checkpoint-resume

Conversation

@RerankerGuo

Copy link
Copy Markdown

Background

The seed command already persists per-session capture and L1 cursors in
.metadata/checkpoint.json, but it unconditionally rejects every output
directory containing a checkpoint. An interrupted historical import therefore
cannot reuse its durable progress and must start from an empty directory.

This PR adds a conservative, explicit resume mode. It replays the full input
through the existing cursor-based capture path, which skips already captured
timestamps and continues with appended rounds.

Refs #115.

Changes

  • Add --resume to openclaw memory-tdai seed.
  • Require all resume preconditions before starting:
    • an explicit --output-dir;
    • an existing output directory;
    • an existing .metadata/checkpoint.json;
    • stable timestamps already present on every input message.
  • Preserve the existing fail-safe behavior without --resume: checkpointed and
    non-empty directories remain rejected.
  • Move output-plan validation before timestamp confirmation so an invalid resume
    fails without prompting or mutating normalized input.
  • Add six focused tests for valid resume and every rejection branch.
  • Document the append-only resume contract and example command.

Why stable timestamps are mandatory

Auto-filled timestamps use the current time. Generating them again on a resumed
run would make old messages appear new and duplicate the import. Requiring
source timestamps makes the existing per-session cursor idempotent without a
new checkpoint schema or input-side index.

Out of scope

  • No checkpoint format or storage migration.
  • No arbitrary mid-file rewrite detection.
  • No change to L1/L2/L3 scheduling.
  • No automatic resume; users must opt in with --resume.

Verification

  • npm test -- src/cli/commands/seed.test.ts — 6 passed
  • npm test — 73 passed
  • npm run build — passed
  • npm pack --dry-run — passed, package size 716.4 kB
  • git diff --check — clean

Impact

  • Breaking change: No.
  • Default behavior: Unchanged.
  • Persistence: Reuses existing checkpoint fields; no schema changes.
  • Safety: Resume is rejected unless the input can be replayed
    deterministically.

Checklist

  • Resume requires explicit user intent.
  • Missing/unstable inputs fail before pipeline startup.
  • Existing overwrite protections remain intact.
  • Focused and full test suites pass.
  • Full build and package dry-run pass.
  • Documentation includes constraints and example usage.

Add --resume for append-only seed imports using an existing output directory and checkpoint. Require an explicit output path and stable input timestamps so replay remains idempotent; preserve the existing refusal to overwrite checkpointed or non-empty directories without opt-in. Document the recovery contract and cover all validation branches with focused tests.\n\nRefs TencentCloud#115.
@Maxwell-Code07

Copy link
Copy Markdown
Collaborator

Thank you for your interest and contributions! We will review your code and get back to you as soon as possible!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants