Console Consumption of LNM Linksets

This document defines how the Stella Ops Console reads Link-Not-Merge (LNM) data now that the LNM schema is frozen (2025-11-17) and the cache plan exists. It is the authoritative contract for Console linkset consumption (Sprint 110, CONCELIER-CONSOLE-23-001…003) and is intended for the Console and Concelier WebService implementers who wire the read path.

Related references:

• LNM schema — frozen v1 schema and the advisory_linksets collection.
• LNM cache plan — cache payload shape, storage/eviction, and telemetry.

Data sources

• Primary collection: advisory_linksets (see LNM schema).
• Cache: advisory_linkset_cache (see LNM cache plan). Console should read from the cache when present and fall back to a live rebuild otherwise.

API shape (WebService)

• Endpoint to expose via Console: GET /v1/lnm/linksets/{advisoryId}
  • Query: source (required), tenant, optional includeConflicts=true|false (default true).
  • Response JSON (deterministic key order):

    {
      "advisoryId": "GHSA-123",
      "source": "ghsa",
      "observations": ["<mongoId>", "<mongoId2>"],
      "normalized": {
        "purls": ["pkg:npm/foo@1.0.0"],
        "versions": ["1.0.0"],
        "ranges": [],
        "severities": [{"system":"cvssv3","score":7.5}]
      },
      "conflicts": [
        {"field":"severities","reason":"disagreement","values":["7.5","9.8"]}
      ],
      "provenance": {
        "observationHashes": ["..."],
        "toolVersion": "lnm-1.0"
      },
      "createdAt": "2025-11-20T00:00:00Z"
    }
    

• Sorting: observations sorted by source, advisoryId, fetchedAt before hashing; response preserves that order.
• Caching: when cache hit, return cached document; when miss, rebuild, write cache, then return.

Console rendering contract

• Fields to surface:
  • normalized.purls (list) and normalized.versions
  • conflicts if non-empty: show field + reason text; keep order as returned.
  • provenance.observationHashes as “evidence anchors” (list); do not prettify.
• Tenant header required; no cross-tenant leakage. Scope concelier:lnm.read.

Error handling

• 404 when linkset missing for advisory/source.
• 409 when tenant header missing/invalid.
• Deterministic error body: { "error": "<code>", "message": "..." }.

Telemetry (reuse existing meters)

• Increment lnm.cache.hit_total / lnm.cache.write_total as defined in cache plan.
• Log template on returns: lnm_console_success tenant={Tenant} advisoryId={AdvisoryId} source={Source} cached={Cached}.

Owners

• Concelier Console Guild (primary)
• Concelier Core Guild (review)