zeroclaw-labs/zeroclaw · error

JSONL archive changed during filesystem handoff

Error message

JSONL archive changed during filesystem handoff

What it means

Consistency guard in archive_staged_jsonl during the JSONL-to-SQLite migration handoff: after hard-linking the staged file to its .migrated archive name, the archive's source fingerprint no longer matches the expected (hash, length) pair captured when the file was staged. Something modified the file across the filesystem handoff, so the no-clobber archive is treated as corrupted and the migration aborts rather than trusting it.

Solutions

  1. Do not modify the JSONL session file while migration is running; stop writers and retry the handoff.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at crates/zeroclaw-infra/src/session_sqlite.rs:270 when the library encounters an invalid state.

Common situations: See trigger scenarios.


AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/883eccacf4db0e12. Report an issue: GitHub.

Appendix: source

Thrown at crates/zeroclaw-infra/src/session_sqlite.rs:270

    fn archive_staged_jsonl(
        staged_path: &Path,
        migrated_path: &Path,
        expected: &(String, i64),
    ) -> Result<()> {
        std::fs::hard_link(staged_path, migrated_path).with_context(|| {
            format!(
                "Failed to create no-clobber JSONL archive {}",
                migrated_path.display()
            )
        })?;
        Self::sync_parent_directory(migrated_path)?;
        let archive_name = migrated_path
            .file_name()
            .and_then(|name| name.to_str())
            .unwrap_or("archive");
        if &Self::source_fingerprint(migrated_path, archive_name)? != expected {
            let _ = std::fs::remove_file(migrated_path);
            bail!("JSONL archive changed during filesystem handoff");
        }
        std::fs::remove_file(staged_path).with_context(|| {
            format!(
                "Failed to remove staged JSONL source {}",
                staged_path.display()
            )
        })?;
        Self::sync_parent_directory(staged_path)?;
        Ok(())
    }

    fn sync_parent_directory(path: &Path) -> Result<()> {
        #[cfg(unix)]
        {
            let parent = path
                .parent()
                .filter(|parent| !parent.as_os_str().is_empty())
                .unwrap_or_else(|| Path::new("."));

View on GitHub (pinned to 88bb9c8533)