quickbase-extract 0.2.1__tar.gz → 0.3.0__tar.gz

{quickbase_extract-0.2.1 → quickbase_extract-0.3.0}/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-04-27
+
+### Added
+
+- `complete_cache_refresh()` function in `cache_sync` module for selective cache refresh in development
+- Support for granular cache refresh control:
+  - `force_all=True`: Refresh both metadata and data caches
+  - `force_metadata=True`: Refresh only metadata cache
+  - `force_data=True`: Refresh only data cache
+- Cache refresh workflow: clear /tmp → fetch fresh from Quickbase → update S3 → re-sync to /tmp
+- Manual development toggles in Lambda handlers for testing cache refresh without API changes
+- Comprehensive test suite for complete cache refresh functionality
+
+### Changed
+
+- Lambda workers can now force complete cache refresh for development/debugging by toggling code variables
+- Cache refresh strategy clarified: selective refresh based on what changed (metadata vs data)
+
+### Fixed
+
+- Dev workflow now supports forcing cache refresh without modifying Lambda event API
+- Ensures /tmp and S3 are synchronized after cache refresh operations
+
 ## [0.2.1] - 2026-04-25
 
 ### Fixed

{quickbase_extract-0.2.1 → quickbase_extract-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickbase-extract
-Version: 0.2.1
+Version: 0.3.0
 Summary: Extract and cache Quickbase report data with built-in error handling and S3 support
 Project-URL: Homepage, https://github.com/tbrezler/quickbase-extract
 Project-URL: Repository, https://github.com/tbrezler/quickbase-extract.git
@@ -955,10 +955,30 @@ def lambda_handler(event, context):
     - Cold start: Syncs cache from S3
     - Cache freshness: Auto-refreshes if stale
     - Data fetching: Queries Quickbase and caches results
+    - Development: Supports forcing complete cache refresh for testing
     """
     client = get_client()
     cache_mgr = get_cache_manager()
 
+    # OPTIONAL: Set to True to force cache refresh (for development/debugging only)
+    # Only one should be True at a time. force_all overrides the others.
+    FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+    FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+    # Force complete cache refresh if needed (dev/debugging only)
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_all=FORCE_COMPLETE_CACHE_REFRESH_ALL,
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+            force_data=FORCE_COMPLETE_CACHE_REFRESH_DATA,
+        )
+
     # Step 1: Sync cache from S3 on cold start (only on first invocation)
     sync_from_s3_once(cache_mgr)
 
@@ -1563,6 +1583,48 @@ def lambda_handler(event, context):
     metadata = load_report_metadata_batch(cache_mgr, config)
 ```
 
+#### `complete_cache_refresh(cache_manager, client, report_configs, force_all=False, force_metadata=False, force_data=False)`
+
+Completely refresh cache for development/debugging: clear /tmp, fetch fresh from Quickbase, update S3, re-sync to /tmp.
+
+This is a development utility for forcing a complete cache refresh when report metadata or configurations change. Clears local /tmp cache, fetches fresh data from Quickbase, writes to S3, and re-syncs to /tmp.
+
+**Parameters:**
+- `cache_manager` (CacheManager): Cache manager instance
+- `client`: Quickbase API client for fetching fresh data
+- `report_configs` (list[ReportConfig]): List of all ReportConfig instances to refresh
+- `force_all` (bool): If True, refresh both metadata and data. Defaults to False.
+- `force_metadata` (bool): If True (and `force_all` is False), refresh only metadata. Defaults to False.
+- `force_data` (bool): If True (and `force_all` is False), refresh only data. Defaults to False.
+
+**Returns:** None
+
+**Raises:**
+- `Exception`: If cache clearing or refresh operations fail
+
+**Example:**
+```python
+from quickbase_extract import complete_cache_refresh
+
+# Refresh only metadata (after changing report configurations)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_metadata=True
+)
+
+# Refresh all (metadata + data)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_all=True
+)
+```
+
+**Note:** This function is designed for development/debugging. To use in Lambda, add toggles to your handler (see "Development/Debug Mode" section below).
+
 ### Query Execution with Retry Logic
 
 #### `handle_query(client, table_id, *, select=None, where=None, sort_by=None, group_by=None, options=None, description="", max_retries=3)`
@@ -2243,6 +2305,47 @@ ask_values = {"ask1": "value"}    # No underscores
 
 ---
 
+### Issue: Lambda has old cached data after I changed report metadata
+
+**Symptom:** You updated a Quickbase report's fields, filters, or configuration, but your Lambda returns stale data.
+
+**Cause:** Cache was loaded before your changes, and it hasn't become "stale" enough to auto-refresh yet.
+
+**Solutions:**
+
+1. **Quick fix: Use force refresh toggle (development only)**
+
+   In your Lambda handler, temporarily set:
+   ```python
+   FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+   ```
+
+   Upload new build, invoke Lambda, check logs for refresh. Then revert flag to `False`.
+
+2. **For immediate production fix:**
+
+   Manually delete files from S3:
+   ```bash
+   aws s3 rm s3://my-quickbase-cache-bucket/prod/cache/report_metadata/ --recursive
+   ```
+
+   Next Lambda cold start will re-fetch fresh metadata.
+
+3. **To prevent in future:**
+
+   Reduce `metadata_stale_hours` threshold:
+   ```python
+   ensure_cache_freshness(
+       client=client,
+       cache_manager=cache_mgr,
+       report_configs_all=get_all_reports(),
+       report_configs_to_cache=get_reports_to_cache(),
+       metadata_stale_hours=24  # Check daily instead of 30 days
+   )
+   ```
+
+---
+
 ### Issue: Performance degradation over time
 
 **Symptom:** First request fast, subsequent requests slow.
@@ -2622,6 +2725,95 @@ def scheduled_cache_refresh(event, context):
     return {"statusCode": 200, "message": "Cache refreshed"}
 ```
 
+### Development/Debug Mode: Forcing Complete Cache Refresh
+
+When you modify report metadata or configurations in Quickbase, your Lambda may still use stale cached data. Use the force refresh toggles to clear everything and fetch fresh data.
+
+#### When to Use
+
+- You changed a report's filters or fields in Quickbase
+- You added/removed fields from a report
+- You renamed a report or table
+- You need to verify fresh data is being fetched
+
+#### How to Use
+
+1. Open your Lambda handler code
+2. Set one of the toggle flags to `True`:
+
+```python
+# In lambda_handler, find these lines:
+FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+# Change to (example: refresh only metadata):
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+```
+
+3. Upload new Lambda build
+4. Invoke your Lambda (via API or CloudWatch event)
+5. Check CloudWatch logs for cache refresh messages
+6. **Revert the flag back to `False`** for normal operation
+
+#### Flag Options
+
+| Flag | What Gets Refreshed | Use When |
+|------|---------------------|----------|
+| `force_all=True` | Both metadata + data | Complete cache overhaul needed |
+| `force_metadata=True` | Only metadata | Report configuration changed |
+| `force_data=True` | Only data | Data needs fresh pull |
+
+#### What Happens
+
+When you trigger a force refresh:
+
+1. ✓ `/tmp` cache directories are deleted
+2. ✓ Fresh data fetched from Quickbase API
+3. ✓ Data written to S3
+4. ✓ `/tmp` re-synced from updated S3
+
+Your Lambda now has fresh data from Quickbase.
+
+#### Example
+
+```python
+def lambda_handler(event, context):
+    client = get_client()
+    cache_mgr = get_cache_manager()
+
+    # Metadata changed in Quickbase? Force refresh it:
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = True  # ← Toggle this
+
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+        )
+
+    # Rest of handler...
+```
+
+**CloudWatch logs will show:**
+```
+WARNING: Starting complete cache refresh for: metadata (clearing /tmp, refreshing from Quickbase, updating S3...)
+DEBUG: Reset cache sync flag
+INFO: Fetching fresh data from Quickbase...
+INFO: Re-syncing /tmp from S3...
+WARNING: Complete cache refresh finished for metadata: /tmp and S3 now have fresh data from Quickbase
+```
+
+#### Important Notes
+
+- **Don't leave toggles set to `True`** — revert to `False` after testing
+- **Only for development** — not a production workflow
+- Logs will show exactly what was refreshed
+- Safe to use — doesn't affect running processes, only next Lambda invocation
+
 ## Advanced Usage
 
 ### Custom Report Configurations

{quickbase_extract-0.2.1 → quickbase_extract-0.3.0}/README.md

@@ -928,10 +928,30 @@ def lambda_handler(event, context):
     - Cold start: Syncs cache from S3
     - Cache freshness: Auto-refreshes if stale
     - Data fetching: Queries Quickbase and caches results
+    - Development: Supports forcing complete cache refresh for testing
     """
     client = get_client()
     cache_mgr = get_cache_manager()
 
+    # OPTIONAL: Set to True to force cache refresh (for development/debugging only)
+    # Only one should be True at a time. force_all overrides the others.
+    FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+    FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+    # Force complete cache refresh if needed (dev/debugging only)
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_all=FORCE_COMPLETE_CACHE_REFRESH_ALL,
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+            force_data=FORCE_COMPLETE_CACHE_REFRESH_DATA,
+        )
+
     # Step 1: Sync cache from S3 on cold start (only on first invocation)
     sync_from_s3_once(cache_mgr)
 
@@ -1536,6 +1556,48 @@ def lambda_handler(event, context):
     metadata = load_report_metadata_batch(cache_mgr, config)
 ```
 
+#### `complete_cache_refresh(cache_manager, client, report_configs, force_all=False, force_metadata=False, force_data=False)`
+
+Completely refresh cache for development/debugging: clear /tmp, fetch fresh from Quickbase, update S3, re-sync to /tmp.
+
+This is a development utility for forcing a complete cache refresh when report metadata or configurations change. Clears local /tmp cache, fetches fresh data from Quickbase, writes to S3, and re-syncs to /tmp.
+
+**Parameters:**
+- `cache_manager` (CacheManager): Cache manager instance
+- `client`: Quickbase API client for fetching fresh data
+- `report_configs` (list[ReportConfig]): List of all ReportConfig instances to refresh
+- `force_all` (bool): If True, refresh both metadata and data. Defaults to False.
+- `force_metadata` (bool): If True (and `force_all` is False), refresh only metadata. Defaults to False.
+- `force_data` (bool): If True (and `force_all` is False), refresh only data. Defaults to False.
+
+**Returns:** None
+
+**Raises:**
+- `Exception`: If cache clearing or refresh operations fail
+
+**Example:**
+```python
+from quickbase_extract import complete_cache_refresh
+
+# Refresh only metadata (after changing report configurations)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_metadata=True
+)
+
+# Refresh all (metadata + data)
+complete_cache_refresh(
+    cache_manager=cache_mgr,
+    client=qb_client,
+    report_configs=get_all_reports(),
+    force_all=True
+)
+```
+
+**Note:** This function is designed for development/debugging. To use in Lambda, add toggles to your handler (see "Development/Debug Mode" section below).
+
 ### Query Execution with Retry Logic
 
 #### `handle_query(client, table_id, *, select=None, where=None, sort_by=None, group_by=None, options=None, description="", max_retries=3)`
@@ -2216,6 +2278,47 @@ ask_values = {"ask1": "value"}    # No underscores
 
 ---
 
+### Issue: Lambda has old cached data after I changed report metadata
+
+**Symptom:** You updated a Quickbase report's fields, filters, or configuration, but your Lambda returns stale data.
+
+**Cause:** Cache was loaded before your changes, and it hasn't become "stale" enough to auto-refresh yet.
+
+**Solutions:**
+
+1. **Quick fix: Use force refresh toggle (development only)**
+
+   In your Lambda handler, temporarily set:
+   ```python
+   FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+   ```
+
+   Upload new build, invoke Lambda, check logs for refresh. Then revert flag to `False`.
+
+2. **For immediate production fix:**
+
+   Manually delete files from S3:
+   ```bash
+   aws s3 rm s3://my-quickbase-cache-bucket/prod/cache/report_metadata/ --recursive
+   ```
+
+   Next Lambda cold start will re-fetch fresh metadata.
+
+3. **To prevent in future:**
+
+   Reduce `metadata_stale_hours` threshold:
+   ```python
+   ensure_cache_freshness(
+       client=client,
+       cache_manager=cache_mgr,
+       report_configs_all=get_all_reports(),
+       report_configs_to_cache=get_reports_to_cache(),
+       metadata_stale_hours=24  # Check daily instead of 30 days
+   )
+   ```
+
+---
+
 ### Issue: Performance degradation over time
 
 **Symptom:** First request fast, subsequent requests slow.
@@ -2595,6 +2698,95 @@ def scheduled_cache_refresh(event, context):
     return {"statusCode": 200, "message": "Cache refreshed"}
 ```
 
+### Development/Debug Mode: Forcing Complete Cache Refresh
+
+When you modify report metadata or configurations in Quickbase, your Lambda may still use stale cached data. Use the force refresh toggles to clear everything and fetch fresh data.
+
+#### When to Use
+
+- You changed a report's filters or fields in Quickbase
+- You added/removed fields from a report
+- You renamed a report or table
+- You need to verify fresh data is being fetched
+
+#### How to Use
+
+1. Open your Lambda handler code
+2. Set one of the toggle flags to `True`:
+
+```python
+# In lambda_handler, find these lines:
+FORCE_COMPLETE_CACHE_REFRESH_ALL = False
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = False
+FORCE_COMPLETE_CACHE_REFRESH_DATA = False
+
+# Change to (example: refresh only metadata):
+FORCE_COMPLETE_CACHE_REFRESH_METADATA = True
+```
+
+3. Upload new Lambda build
+4. Invoke your Lambda (via API or CloudWatch event)
+5. Check CloudWatch logs for cache refresh messages
+6. **Revert the flag back to `False`** for normal operation
+
+#### Flag Options
+
+| Flag | What Gets Refreshed | Use When |
+|------|---------------------|----------|
+| `force_all=True` | Both metadata + data | Complete cache overhaul needed |
+| `force_metadata=True` | Only metadata | Report configuration changed |
+| `force_data=True` | Only data | Data needs fresh pull |
+
+#### What Happens
+
+When you trigger a force refresh:
+
+1. ✓ `/tmp` cache directories are deleted
+2. ✓ Fresh data fetched from Quickbase API
+3. ✓ Data written to S3
+4. ✓ `/tmp` re-synced from updated S3
+
+Your Lambda now has fresh data from Quickbase.
+
+#### Example
+
+```python
+def lambda_handler(event, context):
+    client = get_client()
+    cache_mgr = get_cache_manager()
+
+    # Metadata changed in Quickbase? Force refresh it:
+    FORCE_COMPLETE_CACHE_REFRESH_METADATA = True  # ← Toggle this
+
+    if (FORCE_COMPLETE_CACHE_REFRESH_ALL or FORCE_COMPLETE_CACHE_REFRESH_METADATA
+            or FORCE_COMPLETE_CACHE_REFRESH_DATA):
+        from quickbase_extract import complete_cache_refresh
+        complete_cache_refresh(
+            cache_manager=cache_mgr,
+            client=client,
+            report_configs=get_all_reports(),
+            force_metadata=FORCE_COMPLETE_CACHE_REFRESH_METADATA,
+        )
+
+    # Rest of handler...
+```
+
+**CloudWatch logs will show:**
+```
+WARNING: Starting complete cache refresh for: metadata (clearing /tmp, refreshing from Quickbase, updating S3...)
+DEBUG: Reset cache sync flag
+INFO: Fetching fresh data from Quickbase...
+INFO: Re-syncing /tmp from S3...
+WARNING: Complete cache refresh finished for metadata: /tmp and S3 now have fresh data from Quickbase
+```
+
+#### Important Notes
+
+- **Don't leave toggles set to `True`** — revert to `False` after testing
+- **Only for development** — not a production workflow
+- Logs will show exactly what was refreshed
+- Safe to use — doesn't affect running processes, only next Lambda invocation
+
 ## Advanced Usage
 
 ### Custom Report Configurations

{quickbase_extract-0.2.1 → quickbase_extract-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickbase-extract"
-version = "0.2.1"
+version = "0.3.0"
 description = "Extract and cache Quickbase report data with built-in error handling and S3 support"
 readme = "README.md"
 requires-python = ">=3.12"

quickbase_extract-0.3.0/src/quickbase_extract/cache_sync.py

@@ -0,0 +1,191 @@
+"""S3-backed cache sync for Lambda environments."""
+
+import logging
+import shutil
+
+from quickbase_extract.cache_manager import CacheManager
+from quickbase_extract.cache_orchestration import ensure_cache_freshness
+
+logger = logging.getLogger(__name__)
+
+# Module-level flag to track if we've synced this Lambda invocation
+_CACHE_SYNCED = False
+
+
+def complete_cache_refresh(
+    client,
+    cache_manager: CacheManager,
+    report_configs: list,
+    force_all: bool = False,
+    force_metadata: bool = False,
+    force_data: bool = False,
+) -> None:
+    """Completely refresh cache: clear /tmp, fetch from Quickbase, update S3, re-sync to /tmp.
+
+    This is a dev/debugging utility for forcing a cache refresh when report
+    metadata or configurations change. Clears specified local /tmp cache,
+    fetches fresh data from Quickbase, writes to S3, and re-syncs to /tmp.
+
+    Only the cache types specified by force flags are cleared and refreshed.
+    For example, if only force_metadata=True, only metadata cache is touched.
+
+    Args:
+        cache_manager: CacheManager instance for cache operations.
+        client: Quickbase API client for fetching fresh data.
+        report_configs: List of all ReportConfig instances to refresh.
+        force_all: If True, refresh both metadata and data. Overrides individual flags.
+            Defaults to False.
+        force_metadata: If True (and force_all is False), refresh only metadata.
+            Defaults to False.
+        force_data: If True (and force_all is False), refresh only data.
+            Defaults to False.
+
+    Raises:
+        Exception: If cache clearing or refresh operations fail.
+
+    Example:
+        >>> # Refresh only metadata
+        >>> complete_cache_refresh(
+        ...     cache_manager=cache_mgr,
+        ...     client=qb_client,
+        ...     report_configs=report_config,
+        ...     force_metadata=True,
+        ... )
+        >>>
+        >>> # Refresh all
+        >>> complete_cache_refresh(
+        ...     cache_manager=cache_mgr,
+        ...     client=qb_client,
+        ...     report_configs=report_config,
+        ...     force_all=True,
+        ... )
+    """
+    global _CACHE_SYNCED
+
+    # Determine which caches to refresh (force_all overrides individual flags)
+    should_refresh_metadata = force_all or force_metadata
+    should_refresh_data = force_all or force_data
+
+    if not (should_refresh_metadata or should_refresh_data):
+        logger.debug("No cache refresh flags set, skipping complete cache refresh")
+        return
+
+    refresh_types = []
+    if should_refresh_metadata:
+        refresh_types.append("metadata")
+    if should_refresh_data:
+        refresh_types.append("data")
+
+    logger.warning(
+        f"Starting complete cache refresh for: {', '.join(refresh_types)} "
+        "(clearing /tmp, refreshing from Quickbase, updating S3...)"
+    )
+
+    # Step 1: Clear specified /tmp cache directories
+    if should_refresh_metadata:
+        metadata_dir = cache_manager.cache_root / "report_metadata"
+        if metadata_dir.exists():
+            shutil.rmtree(metadata_dir)
+            logger.info(f"Cleared metadata cache directory: {metadata_dir}")
+
+    if should_refresh_data:
+        data_dir = cache_manager.cache_root / "report_data"
+        if data_dir.exists():
+            shutil.rmtree(data_dir)
+            logger.info(f"Cleared data cache directory: {data_dir}")
+
+    # Step 2: Reset sync flag so fresh data will be fetched
+    _CACHE_SYNCED = False
+    logger.debug("Reset cache sync flag")
+
+    # Step 3: Fetch fresh data from Quickbase and write to S3
+    logger.info("Fetching fresh data from Quickbase...")
+    ensure_cache_freshness(
+        client=client,
+        cache_manager=cache_manager,
+        report_configs_all=report_configs,
+        force_all=force_all,
+        force_metadata=force_metadata,
+        force_data=force_data,
+    )
+
+    # Step 4: Re-sync /tmp from S3 for cleared caches
+    logger.info("Re-syncing /tmp from S3...")
+    sync_from_s3_once(cache_manager, force=True)
+
+    logger.warning(
+        f"Complete cache refresh finished for {', '.join(refresh_types)}: "
+        "/tmp and S3 now have fresh data from Quickbase"
+    )
+
+
+def sync_from_s3_once(cache_manager: CacheManager, force: bool = False) -> None:
+    """Download cache from S3 to /tmp on Lambda cold start.
+
+    Only syncs if cache hasn't been synced in this invocation.
+    Subsequent calls are no-ops unless force=True.
+
+    On Lambda, the sync flag persists across warm invocations within the same
+    container, so warm starts skip the sync (Lambda /tmp persists). Only cold
+    starts trigger a sync.
+
+    On local environments, automatically detects if CACHE_BUCKET is configured.
+    If not configured, does nothing (local caching only).
+
+    Args:
+        cache_manager: CacheManager instance for cache operations.
+        force: If True, sync even if already synced in this invocation.
+            Defaults to False.
+
+    Raises:
+        Exception: If S3 operations fail.
+
+    Example:
+        >>> # In Lambda handler initialization
+        >>> cache_manager = CacheManager(
+        ...     cache_root=Path("/tmp/my_project/dev/cache"),
+        ...     s3_bucket="mit-bio-quickbase",
+        ...     s3_prefix="my_project/dev/cache",
+        ... )
+        >>> sync_from_s3_once(cache_manager)  # Syncs on cold start
+        >>> sync_from_s3_once(cache_manager)  # No-op on same invocation
+        >>>
+        >>> # Force re-sync if needed (programmatically)
+        >>> sync_from_s3_once(cache_manager, force=True)
+    """
+    global _CACHE_SYNCED
+
+    # Check for force refresh
+    already_synced = _CACHE_SYNCED and not force
+
+    if already_synced:
+        logger.debug("Cache already synced in this invocation, skipping")
+        return
+
+    cache_manager.sync_from_s3()  # Handles Lambda detection internally
+    _CACHE_SYNCED = True
+    logger.info("Cache synced from S3")
+
+
+def is_cache_synced() -> bool:
+    """Check if cache has been synced in this invocation.
+
+    Returns:
+        True if cache has been synced, False otherwise.
+
+    Example:
+        >>> if not is_cache_synced():
+        ...     print("Cache needs syncing")
+    """
+    return _CACHE_SYNCED
+
+
+def _reset_cache_sync() -> None:
+    """Reset the cache sync flag. For testing only.
+
+    Example:
+        >>> # In test teardown
+        >>> _reset_cache_sync()
+    """
+    global _CACHE_SYNCED
+    _CACHE_SYNCED = False