Concelier LNM Cache Plan

This document finalizes the structured caching fields for Link-Not-Merge (LNM) linksets now that the LNM schema is frozen (2025-11-17) and the Evidence Locker contract is published. It is intended for Concelier Core and WebService implementers (Sprint 110) and is the source of truth for the advisory_linkset_cache payload shape, storage, and telemetry.

Related references:

• LNM schema — frozen v1 schema and the advisory_linksets collection.
• Console LNM consumption — how Console reads cached linksets through the WebService.

Cache payload shape

• Source: advisory_linksets collection (see LNM schema).
• Cache entry key: {tenant}:{advisoryId}:{source}.
• Cached fields (deterministic order):
  • observations (ObjectId list, already sorted by source, advisoryId, fetchedAt)
  • normalized.purls, normalized.versions, normalized.ranges, normalized.severities
  • conflicts array (field, reason, values)
  • provenance.observationHashes
  • builtByJobId, createdAt
• Exclude mutable/derived fields; cache is rebuilt on ingestion replay, not updated in place.

Storage & eviction

• Collection: advisory_linkset_cache (per-tenant index {tenantId:1, advisoryId:1, source:1} unique).
• Eviction: TTL on createdAt disabled by default; cache is replaced when a newer provenance.observationHashes differs.
• Determinism: cache documents written via canonical JSON writer (sorted keys); timestamps UTC.

API exposure

• WebService: surface cached linksets via existing /v1/lnm/linksets/{advisoryId}?source=... (read-through); if cache miss, rebuild synchronously and store.
• Console: may rely on this cache for Advisory AI surfaces; no new payload fields required.

Telemetry

• Meter StellaOps.Concelier.Linksets (existing) to add counters: lnm.cache.write_total{result}, lnm.cache.hit_total{source}; histogram lnm.cache.rebuild_ms for synchronous rebuilds. (To be wired in subsequent sprint.)

Alignment

• Schema source of truth: LNM schema (frozen v1).
• Evidence Locker contract: attestation contract informs provenance fields; no shape changes required.

Ownership

• Concelier Core + WebService guilds.