Retained Message Staleness

Tell a RETAINED MQTT message from a LIVE one, when the protocol will not. Zero runtime dependencies. Pure function: the caller supplies the message facts and the clock, the library returns a verdict. No I/O, no payload parsing, no network access.

THE SILENT FAILURE. MQTT lets a publisher mark a message RETAIN=1. The broker stores it and hands it to any FUTURE subscriber the instant they subscribe -- that is the feature, and it is how a new dashboard, a restarted service or a freshly reconnected client immediately learns 'the door is closed' or 'the temperature is 21C' without waiting for the next update.

What the protocol does not tell the subscriber is WHEN that message was published. A retained value from four seconds ago and one from last March arrive identically, with the same flag, on the same topic, in the same shape. A client that treats arrival as recency will act on a reading whose publisher has been offline for months -- and nothing in the message says so.

This resolves freshness from the facts a subscriber actually has, and returns NOT DETERMINABLE naming what is missing rather than assuming a retained message is current. Per-topic policy is supported because the tolerance genuinely differs: a door state going stale is a security decision, a room temperature going stale is a cosmetic one.

VERIFIED: 53 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function applyTopicPolicy( verdict: FreshnessVerdict, policy: Pick<TopicStalenessPolicy, "onUnknownAge">, ): TrustDecision;
  export function decideFreshnessAction<T>(verdict: FreshnessVerdict, policy: FreshnessActionPolicy<T>): T;
  export function describeVerdict(verdict: FreshnessVerdict): string;
  export function resolveFreshness( facts: RetainedMessageFacts, clock: FreshnessClock, threshold: StalenessThreshold, ): FreshnessVerdict;

  export type UnknownAgePolicy = "treat-as-stale" | "treat-as-fresh" | "abstain";
  export type FreshnessVerdict = FreshVerdict | StaleVerdict | UnknownAgeVerdict;
  export type TrustDecision = "trust" | "distrust" | "abstain";