---
id: ADR-PFM-QRY-017
title: Descriptions use change stamps as cache keys
product_area: platform
module: queries
revision: 1
status: proposed
design_intent: confirmed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
decision: >-
  Dataset descriptions use local and shared caches keyed by database-maintained change stamps, with
  cache failures treated as misses rather than requiring explicit invalidation messages.
constrains:
  - DOM-PFM-QRY-001
  - WF-PFM-QRY-003
  - SVC-PFM-QRY-queries
origin: >-
  docs/queries/semantic-query-layer.md (The description cache); Andrew 2026-10-15 (shared stamps
  table)
alternatives:
  - option: Broadcast invalidation messages
    why_not: A lost message could leave a previously cached description in use.
  - option: Resolve every description without caching
    why_not: Repeated queries would reread the same metadata tables.
consequences:
  - >-
    Participating tables need the stamp trigger, including configuration tables owned by other
    services.
  - The shared stamp writer uses the database definer function.
  - Separate stamp and metadata reads do not establish one consistent database snapshot.
supersedes: []
evidence:
  - 'services-platform at ad3f6a6: modules/queries/db/query-description-stamps.table.ts'
---

# Descriptions use change stamps as cache keys

## Context

Description resolution combines multiple registries and configuration sources. Stamp changes let a later request use a different cache key.

## Decision

Dataset descriptions use local and shared caches keyed by database-maintained change stamps, with cache failures treated as misses rather than requiring explicit invalidation messages.

## Alternatives Considered

Broadcast invalidation messages: A lost message could leave a previously cached description in use.

Resolve every description without caching: Repeated queries would reread the same metadata tables.

## Consequences

Participating tables need the stamp trigger, including configuration tables owned by other services. The shared stamp writer uses the database definer function. Separate stamp and metadata reads do not establish one consistent database snapshot.