snapshot-lifecycle-and-diff

What problem does it solve?

This Skill defines how to keep derived “bundles” consistent with evolving “snapshots” by detecting page-level version changes and propagating lifecycle status without directly broadcasting invalidations to every consumer.

Core Features & Use Cases

• Snapshot lifecycle orchestration: Updates snapshot meta.LifecycleStatus (e.g., "Stale" / "Invalidated") so all referencing bundles lazily reflect the latest state on BundleStatus reads.
• Append-only source event logging: Records VersionedUpdate, Retraction, SourceDeletion, and SchemaChange into events/source-events.jsonl using iSanitizeForJSON and a deterministic read/write path.
• Page-hash diff computation: Computes diffs between page-hashes.json snapshots and produces a normalized Added/Removed/Changed/Unchanged summary.
• High-level refresh API: Provides a composed workflow (RefreshSnapshot) that merges diffing + lifecycle updates + event append + SupersededBy handling in one call.
• Use case: When an external paper updates (e.g., arXiv v2 → v3), automatically mark affected snapshots as stale so generated bundles become outdated and are reconsidered during later audits.

Quick Start

Ask your system to run the “RefreshSnapshot” workflow for the old and new snapshot IDs, then verify bundle states via the lazy BundleStatus evaluation.