From a49d6008a4a97dfed3c13ffa5b9a362ce45bde0e Mon Sep 17 00:00:00 2001
From: John Dvorak <john@johnsdvorak.com>
Date: Fri, 22 May 2026 13:35:12 -0700
Subject: [PATCH] fix: add WORLD_CACHE_SCHEMA_VERSION to cache key for
 automatic invalidation

Cache keys now include a schema version prefix so that world-schema
changes automatically invalidate stale cached extraction results.
Previously two incompatible schema versions would share the same
cache key if URL/selectors/env matched, silently returning stale data.

WORLD_CACHE_SCHEMA_VERSION exported publicly so consumers can
increment it when making schema-incompatible changes to extraction.

658 tests pass.
---
 packages/imhotep-core/src/geometry-cache.ts | 9 ++++++++-
 packages/imhotep-core/src/index.ts          | 1 +
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/packages/imhotep-core/src/geometry-cache.ts b/packages/imhotep-core/src/geometry-cache.ts
index 74bc1e9..b32f3e0 100644
--- a/packages/imhotep-core/src/geometry-cache.ts
+++ b/packages/imhotep-core/src/geometry-cache.ts
@@ -193,10 +193,17 @@ function djb2Hash(str: string): string {
   return hash.toString(16).padStart(8, '0')
 }
 
+/**
+ * Schema version for cache invalidation. Increment when the world schema
+ * changes in a way that makes previously cached extraction results incompatible.
+ */
+export const WORLD_CACHE_SCHEMA_VERSION = 2
+
 /**
  * Compute a stable cache key for a geometry extraction.
  *
  * The key incorporates:
+ * - schema version (automatic invalidation on schema changes)
  * - page URL
  * - sorted selectors (so order doesn't matter)
  * - environment (viewport dimensions, color scheme, etc.)
@@ -221,7 +228,7 @@ export function computeGeometryCacheKey(
     }),
   )
   const urlHash = djb2Hash(pageUrl)
-  return `${urlHash}-${selectorsHash}-${envHash}`
+  return `${WORLD_CACHE_SCHEMA_VERSION}-${urlHash}-${selectorsHash}-${envHash}`
 }
 
 // ---------------------------------------------------------------------------
diff --git a/packages/imhotep-core/src/index.ts b/packages/imhotep-core/src/index.ts
index 145e099..b3a447d 100644
--- a/packages/imhotep-core/src/index.ts
+++ b/packages/imhotep-core/src/index.ts
@@ -60,6 +60,7 @@ export {
   getDefaultCacheDir,
   readCachedExtractionResult,
   writeCachedExtractionResult,
+  WORLD_CACHE_SCHEMA_VERSION,
 } from './geometry-cache.js'
 
 // Public API type aliases for high-level evaluation results