Adds docs/CACHE_CONTRACT.md defining the two-tier replacement for
today's single CACHE_VERSION=3 constant:
cache_schema force rebuild on mismatch (today's semantics)
id_rules mark stale, allow lazy re-extract w/o rescan
id_rules_signature sha256 over canonical text of all extraction
rule sources (regexes, normalizers, part
detectors, FC2 handling, user-config rules)
as a belt-and-braces drift check
Documents:
- new cache.json header shape
- one-shot in-place migration for legacy `version: 3` users (no
forced rescan)
- behavior matrix for the three resulting states
- extension UX: fresh / stale-by-rules amber / schema-mismatch red
- new "Re-extract IDs" action that walks files[] in place and
never touches rclone
- what counts as a rules change vs. unrelated code change
- open questions deferred to step 10 (per-remote tracking,
custom-rules signature handling, host wiring)
No code changes — step 10 implements. This commit only locks the
contract so step 10 has a single source of truth for both the
Python and extension sides.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
admin