Metadata Caching Strategy

This strategy is the Honua platform default for metadata caching across SDKs, MCP tools, examples, and server-backed source orchestration. It separates metadata from spatial feature state and query results: metadata is cached by default with explicit revalidation and invalidation rules, while feature, query, and result caching is opt-in materialization only.

The policy applies to adapter metadata needed to construct source handles, render layers, validate capabilities, and drive app startup. It does not make live or ad hoc spatial feature responses cacheable by default.

Default Metadata Set

Honua caches the following metadata types by default when the adapter can identify a stable source, tenant/project boundary, and auth scope:

Feature rows, feature tiles, object id query responses, statistics responses, viewport queries, geometry-service results, route outputs, and analysis outputs are not part of the default metadata cache. Those responses may be persisted only by an explicit materialization workflow.

Cache Keys

Every cache entry uses a deterministic logical key. The key must exclude bearer tokens, session cookies, and raw credentials, and it must include enough context to prevent cross-tenant or cross-scope reuse.

Required cache-key dimensions:

• tenantId and projectId when the source belongs to a Honua tenant/project.
• Auth scope fingerprint derived from user/service-principal id, role grants, source ACL version, and token audience/scope. The fingerprint must not expose the token value.
• Normalized source URL: lowercase scheme/host, normalized path, sorted stable query parameters, removed transient parameters such as tokens and cache busters, and normalized trailing slashes.
• Protocol/adapter id, such as geoservices-feature-service, wms, wmts, wfs, ogc-features, ogc-tiles, ogc-maps, stac, odata, or ogc-processes.
• Service, layer, table, collection, tileset, style, entity set, or process id where the metadata is scoped below the source root.
• CRS, tile matrix set, output format, legend format, language/locale, and profile/media type when the upstream metadata differs by those inputs.
• Upstream ETag and Last-Modified validators when available. Validators are stored with the entry, sent on revalidation requests, and included in the cache-state version fingerprint returned to SDK/MCP callers.
• Adapter schema version and Honua projection version for SDK-shaped metadata derived from raw upstream documents.

The server should normalize keys centrally so SDKs and MCP tools can report a stable key fingerprint without re-implementing credential-sensitive logic.

TTL And Revalidation Policy

TTL is a freshness budget, not a correctness guarantee. Any explicit invalidation event wins over TTL. If an upstream endpoint provides stronger cache headers, Honua may use the shorter of the Honua default TTL and the upstream Cache-Control: max-age value, while still retaining the invalidation rules in this document.

refresh: true means bypass the fresh-cache shortcut, send conditional validators if available, and return either refreshed or hit with a not-modified validator result. It does not bypass auth checks.

stale-if-error is allowed only for metadata. A stale metadata response must be marked as stale in SDK/MCP cache state and must include the refresh error class or diagnostic id. Stale metadata must not be silently presented as fresh.

Invalidation Triggers

Honua treats invalidation as an event-driven operation scoped as tightly as the source can identify.

Distributed deployments should publish invalidation events with tenant/project, source, adapter, resource id, and reason. SDK-local in-memory caches must expose a clear method to drop affected handles or re-read metadata after the platform reports invalidation.

SDK And MCP Cache-State Visibility

SDK responses and MCP tool results that use default metadata caching must expose cache state in a machine-readable field. This keeps demos, logs, and operators from guessing whether a value was fresh, stale, or revalidated.

Recommended cache shape:

type HonuaCacheState = {
  scope: "metadata" | "materialized-result";
  status: "hit" | "miss" | "stale" | "refreshed" | "bypass";
  keyFingerprint: string;
  ageMs?: number;
  ttlMs?: number;
  staleIfErrorMs?: number;
  revalidatedAt?: string;
  sourceUpdatedAt?: string;
  validator?: {
    etag?: string;
    lastModified?: string;
  };
  invalidationReason?: string;
  refreshErrorId?: string;
};

SDK adapters should return this state from metadata calls such as WMS/WFS/WMTS capabilities, OData $metadata, STAC collection discovery, OGC process descriptions, service/layer descriptors, renderer/legend reads, and source-list discovery. MCP tools should include the same state in structured tool metadata or a cache field on the resource/tool response. Text summaries may mention the status, but the structured field is the contract.

Cache-state visibility requirements:

• A fresh cache reuse returns status: "hit" with ageMs and ttlMs.
• A first fetch returns status: "miss" unless the caller explicitly bypassed cache lookup.
• A conditional 304 Not Modified revalidation returns status: "hit" or status: "refreshed" with revalidatedAt; SDKs should prefer refreshed when the caller requested refresh: true.
• A changed upstream response returns status: "refreshed" and updates the validator fingerprint.
• A stale-if-error metadata fallback returns status: "stale" and includes refreshErrorId or an equivalent diagnostic.
• A caller-forced bypass returns status: "bypass" and must not populate a shared cache unless the caller also opts into write-through.

JavaScript SDK Surface

@honua/sdk-js exports the transport-neutral HonuaCacheState, HonuaCacheStatus, HonuaCacheScope, HonuaCacheValidator, and HonuaMetadataRequestOptions types from both the root and /honua entrypoints. Metadata and discovery helpers accept:

await client.getLayerMetadata("civic-services", 0);
await client.getLayerMetadata("civic-services", 0, { refresh: true });
await client.getLayerMetadata("civic-services", 0, { cache: "bypass" });

Default metadata reads reuse the SDK-local metadata entry when present and return cache.status: "hit". refresh: true skips that fresh-cache shortcut, sends ETag / Last-Modified validators when the adapter has them, and reports refreshed for successful revalidation. cache: "bypass" skips cache lookup and write-through for that call.

Feature rows, object ids, counts, statistics, spatial queries, STAC searches, tiles, and process/job results remain uncached by default. Those result reads should expose scope: "materialized-result" only when a separate materialization workflow explicitly owns the persisted result.

Feature, Query, And Result Caching

Feature/query/result caching is opt-in materialization only. Default SDK and MCP read paths must execute ad hoc spatial requests against the current source or live stream instead of reusing long-lived result caches.

Default non-cacheable operations include:

• queryFeatures, object-id queries, counts, statistics, aggregates, and viewport/bbox/intersects filters triggered by user interaction.
• Feature tiles or feature pages whose content depends on current edit state.
• Search results, route results, geometry-service outputs, and process outputs unless a materialization job explicitly owns the result.
• Realtime incident feature snapshots, deltas, cursors, and watermarks.

Materialized outputs are allowed only when the workflow declares:

• Owner, tenant/project, source ids, auth scope, query parameters, geometry, CRS, time extent, upstream metadata versions, and refresh cadence.
• Whether stale materialized results are allowed and how that state is shown to users.
• Provenance fields linking the result to the import, migration, analysis, or scheduled refresh job that produced it.
• A hard invalidation or recompute policy for edits, schema changes, source refreshes, and admin actions.

Materialization caches must use scope: "materialized-result" in cache-state metadata. They must never be confused with default metadata caches.

Realtime Incident Dashboard Constraints

The incident operations dashboard is realtime by default. It may use cached metadata for schemas, layer descriptors, renderers, domains, capabilities, and legends during startup, but it must not show stale spatial feature state from a default feature/result cache.

Incident dashboard requirements:

• Live incident rows, geometries, selections, and counts are driven by realtime events, cursor/watermark replay, or a fresh explicit snapshot request.
• If the realtime transport disconnects, the UI may show the last reconciled in-memory state only with an explicit stale/offline status. It must not replace the live state with long-lived cached query results.
• Reconnect paths must resume from cursor/watermark or request a fresh snapshot. A materialized analytics layer may be shown only if it is labeled as materialized and not used as the authoritative incident state.
• Metadata cache state can be surfaced alongside connection state, but metadata freshness must not imply feature freshness.
• Alerting, dispatch, assignment, and detail panes must hide or disable actions that require authoritative live state when the incident stream is stale.

Recommended Follow-Up Tickets

Do not create these issues automatically from this document. They are proposed implementation slices if the platform wants to schedule the strategy.