nornicdb-promotion-policies

Promotion Profiles & Policies (Cypher API)

Promotion is the optional second half of NornicDB's scoring pipeline. Decay handles time-based fade and runs entirely on its own (see nornicdb-knowledge-policies and nornicdb-decay-tuning). Promotion does two distinct things:

1. Tracks access — ON ACCESS mutations write to per-entity access metadata (counters, last-access timestamps, smoothed signals). This is the only mechanism that updates access metadata.
2. Changes scores conditionally — WHEN <predicate> APPLY PROFILE '<name>' causes a promotion profile's multiplier/scoreFloor/scoreCap to be applied to the decayed score when the predicate is true.

These two responsibilities are independent:

• A policy with ON ACCESS but no WHEN clauses only tracks. Scores are not promoted, but LAST_ACCESSED decay bindings on the same target can rely on the tracking.
• A policy with WHEN but no ON ACCESS only promotes. It evaluates predicates against existing properties / metadata at score time.
• A policy with both does both.

Two objects

• Promotion profile — CREATE PROMOTION PROFILE <name> OPTIONS { ... }: a named, untargeted parameter set. Inert until referenced by a WHEN ... APPLY PROFILE '<name>' clause.

  CREATE PROMOTION PROFILE <name> OPTIONS {
    multiplier: <float>,    -- < 1.0 dampens, > 1.0 boosts, 1.0 neutral
    scoreFloor: <float>,    -- promoted-score floor, applied before scoreCap
    scoreCap:   <float>,    -- promoted-score ceiling, applied after multiplier
    scope:      'NODE'      -- NODE | EDGE
  }
  

• Promotion policy — CREATE PROMOTION POLICY <name> FOR (...) APPLY { ON ACCESS { ... } WHEN ... APPLY PROFILE '...' }: targets entities with FOR and contains the access mutations and/or WHEN clauses. The FOR clause uses the same target shapes as decay bindings (label, multi-label, edge type, wildcard).

How promotion enters the score

baseScore     = baseDecay(t)                                  // from the decay binding
promoted      = baseScore * multiplier                        // multiplier from the matched WHEN's profile
clampedPromo  = min(scoreCap, max(scoreFloor, promoted))      // promotion profile's floor/cap
finalScore    = max(decayBindingFloor, clampedPromo)          // decay binding's floor (independent)
suppressed    = finalScore < visibilityThreshold              // decay binding's threshold