feat(resilience): staleness classifier foundation (T1.5)

[koala73]

Why this PR?

Ships the foundation-only slice of Phase 1 T1.5 of the country-resilience reference-grade upgrade plan (PR #2938): a pure staleness classifier that maps a lastObservedAt timestamp and a source cadence to one of three staleness levels (fresh, aging, stale). This is the primitive that T1.6 (widget dimension confidence bar with freshness badge) and the later T1.5 scorer propagation pass both consume.

Same pattern as the T1.7 foundation PR (#2944): define the type and the primitive in isolation with comprehensive tests, then land the consumer wiring in separate PRs so each unit is bounded and reviewable.

What this PR commits

• New module server/_shared/resilience-freshness.ts:
  • ResilienceCadence type union covering the 5 cadences listed in the methodology document (realtime, daily, weekly, monthly, annual).
  • StalenessLevel type union: fresh / aging / stale.
  • cadenceUnitMs(cadence) helper returning a canonical duration per cadence: realtime 1 hour, daily 1 day, weekly 7 days, monthly 30 days, annual 365 days.
  • FRESH_MULTIPLIER = 1.5 and AGING_MULTIPLIER = 3 exported constants. A signal is fresh when age is strictly less than 1.5x its cadence unit, aging when strictly less than 3x, stale otherwise.
  • classifyStaleness({ lastObservedAtMs, cadence, nowMs }) pure function returning { staleness, ageMs, ageInCadenceUnits }. Null / undefined / NaN / future timestamps return stale with positive-infinity age. nowMs is accepted as a deterministic override for unit testing.
• New test file tests/resilience-freshness.test.mts with 10 tests covering cadence ordering, fresh/aging/stale classification across all 5 cadences, defensive handling of null/undefined/NaN/future timestamps, exact threshold boundaries, internal consistency of ageMs and ageInCadenceUnits, and classifier purity.

What is deliberately NOT in this PR

• No changes to the 13 dimension scorers. Propagating lastObservedAt through each scorer and aggregating max age per dimension is the next slice of T1.5 and will consume this classifier as a pure import. Splitting it this way keeps the classifier testable in isolation.
• No schema changes (proto, OpenAPI, ResilienceDimension response type). The schema field freshness: { lastObservedAt, staleness } lands alongside the widget rendering in T1.6.
• No widget rendering. T1.6 owns the per-dimension freshness badge UI and will call classifyStaleness at render time.

Prerequisite PRs verified merged

• feat(resilience): baseline vs stress scoring engine #2821 (baseline/stress engine)
• fix(resilience): revert overall score to domain-weighted average + fix RSF direction #2847 (formula revert + RSF direction fix)
• fix(seed): compute missing resilience scores directly via scorer import #2858 (seed direct scoring)

Related in-flight Phase 1 PRs from this session

• test(resilience): T1.1 regression test for origin-doc ceiling claim #2941 T1.1 regression test
• feat(resilience): surface dataVersion in widget footer (T1.4) #2943 T1.4 dataVersion widget wire
• feat(resilience): 4-class imputation taxonomy foundation (T1.7) #2944 T1.7 imputation taxonomy foundation
• docs(resilience): promote methodology to .mdx at CII parity (T1.3) #2945 T1.3 methodology mdx promotion
• test(resilience): methodology doc linter enforces dimension parity (T1.8) #2946 T1.8 methodology doc linter

Testing

• npx tsx --test tests/resilience-freshness.test.mts: 10/10 passing
• npm run typecheck: clean
• Pre-push hook (typecheck + build:full + version:check) passes

Post-Deploy Monitoring & Validation

No additional operational monitoring required: this PR only adds a new pure module and its tests. No runtime behavior change, no schema change, no new Redis keys, no new API surface. No existing file is modified.

---

Generated with Claude Opus 4.6 (1M context) via Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
worldmonitor	Ignored		Apr 11, 2026 10:03am

[greptile-apps]

Greptile Summary

This PR adds the foundation of the T1.5 staleness classifier: a new pure module server/_shared/resilience-freshness.ts defining the ResilienceCadence / StalenessLevel types, cadenceUnitMs() helper, threshold constants, and classifyStaleness(), accompanied by 10 deterministic unit tests. No existing files are modified, and all findings are P2 style suggestions.

Confidence Score: 5/5

Safe to merge — isolated new module with no existing-code changes and no P0/P1 findings.

All three comments are P2 style/completeness suggestions (a redundant Math.max, a missing JSDoc note, and missing test assertions). The classifier logic, guards, and boundary semantics are correct.

No files require special attention.

Important Files Changed

Filename	Overview
server/_shared/resilience-freshness.ts	New pure staleness classifier module — logic is correct, guards are sound, one redundant Math.max(0, …) after the future-timestamp guard (P2 only).
tests/resilience-freshness.test.mts	10 deterministic tests with fixed NOW anchor; boundary, defensive, and purity cases all covered; minor gap: ageInCadenceUnits not asserted for defensive (null/NaN/future) cases.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["classifyStaleness(args)"] --> B{"lastObservedAtMs\nnull / undefined / NaN\nor > nowMs?"}
    B -- yes --> C["return stale\nageMs = +Infinity\nageInCadenceUnits = +Infinity"]
    B -- no --> D["ageMs = nowMs − lastObservedAtMs\nageInCadenceUnits = ageMs / cadenceUnit"]
    D --> E{"ageInCadenceUnits\n< FRESH_MULTIPLIER (1.5)?"}
    E -- yes --> F["return fresh"]
    E -- no --> G{"ageInCadenceUnits\n< AGING_MULTIPLIER (3)?"}
    G -- yes --> H["return aging"]
    G -- no --> I["return stale"]

Loading

_{Reviews (1): Last reviewed commit: "feat(resilience): staleness classifier f..." | Re-trigger Greptile}

[greptile-apps]

Redundant Math.max(0, …) guard

The lastObservedAtMs > nowMs check three lines above already ensures the function returns stale for any future timestamp, so by the time execution reaches this line, nowMs - lastObservedAtMs is guaranteed to be ≥ 0 and Math.max is always a no-op. Removing it avoids a misleading hint to future readers that a negative value could arrive here.

Suggested change

	const ageMs = Math.max(0, nowMs - lastObservedAtMs);
	const ageMs = nowMs - lastObservedAtMs;

[koala73]

Fixes landed post-merge in follow-up PR #2953. Removed in the follow-up. Added an inline comment explaining that the defensive branch above already rejects future timestamps, so nowMs - lastObservedAtMs is guaranteed non-negative.

[greptile-apps]

ageMs can be Infinity — worth documenting on the field

When lastObservedAtMs is null/undefined/NaN/future, classifyStaleness returns ageMs: Number.POSITIVE_INFINITY. The TypeScript type number is technically correct, but callers doing arithmetic on ageMs (e.g. formatting a "last seen X ago" label) will silently produce Infinity strings or NaN without a guard. Adding a JSDoc note on the field would help consumers.

Suggested change

	ageMs: number;
	/** The age expressed as a multiple of the cadence unit. Handy for debugging. */
	ageInCadenceUnits: number;
	export interface StalenessResult {
	staleness: StalenessLevel;
	/**
	* Age in milliseconds. `Number.POSITIVE_INFINITY` when `lastObservedAtMs`
	* is null, undefined, NaN, or in the future. Always check for `Infinity`
	* before using this value in arithmetic or display formatting.
	*/
	ageMs: number;
	/** The age expressed as a multiple of the cadence unit. Handy for debugging. */
	ageInCadenceUnits: number;
	}

[koala73]

Fixes landed post-merge in follow-up PR #2953. Added JSDoc to both ageMs and ageInCadenceUnits explaining the Number.POSITIVE_INFINITY contract and recommending Number.isFinite before arithmetic or string formatting.

[greptile-apps]

Missing ageInCadenceUnits assertion for defensive cases

The null branch asserts ageMs === POSITIVE_INFINITY (line 86), but neither ageInCadenceUnits nor ageMs is checked for the undefined, NaN, or future-timestamp branches. Since the contract is that all three fields are POSITIVE_INFINITY in these cases, pinning that would prevent a future regression where one field is accidentally omitted from the defensive return.

Suggested change

	const missingNull = classifyStaleness({ lastObservedAtMs: null, cadence, nowMs: NOW });
	assert.equal(missingNull.staleness, 'stale', `${cadence} null should be stale`);
	assert.equal(missingNull.ageMs, Number.POSITIVE_INFINITY);
	const missingUndefined = classifyStaleness({ lastObservedAtMs: undefined, cadence, nowMs: NOW });
	assert.equal(missingUndefined.staleness, 'stale', `${cadence} undefined should be stale`);
	const nanResult = classifyStaleness({ lastObservedAtMs: Number.NaN, cadence, nowMs: NOW });
	assert.equal(nanResult.staleness, 'stale', `${cadence} NaN should be stale`);
	// A timestamp 10 minutes in the future is nonsensical and treated as stale.
	const futureResult = classifyStaleness({
	lastObservedAtMs: NOW + 10 * 60 * 1000,
	cadence,
	nowMs: NOW,
	});
	assert.equal(futureResult.staleness, 'stale', `${cadence} future timestamp should be stale`);
	}
	const missingNull = classifyStaleness({ lastObservedAtMs: null, cadence, nowMs: NOW });
	assert.equal(missingNull.staleness, 'stale', `${cadence} null should be stale`);
	assert.equal(missingNull.ageMs, Number.POSITIVE_INFINITY);
	assert.equal(missingNull.ageInCadenceUnits, Number.POSITIVE_INFINITY);
	const missingUndefined = classifyStaleness({ lastObservedAtMs: undefined, cadence, nowMs: NOW });
	assert.equal(missingUndefined.staleness, 'stale', `${cadence} undefined should be stale`);
	assert.equal(missingUndefined.ageMs, Number.POSITIVE_INFINITY);
	assert.equal(missingUndefined.ageInCadenceUnits, Number.POSITIVE_INFINITY);
	const nanResult = classifyStaleness({ lastObservedAtMs: Number.NaN, cadence, nowMs: NOW });
	assert.equal(nanResult.staleness, 'stale', `${cadence} NaN should be stale`);
	assert.equal(nanResult.ageMs, Number.POSITIVE_INFINITY);
	assert.equal(nanResult.ageInCadenceUnits, Number.POSITIVE_INFINITY);
	const futureResult = classifyStaleness({
	lastObservedAtMs: NOW + 10 * 60 * 1000,
	cadence,
	nowMs: NOW,
	});
	assert.equal(futureResult.staleness, 'stale', `${cadence} future timestamp should be stale`);
	assert.equal(futureResult.ageMs, Number.POSITIVE_INFINITY);
	assert.equal(futureResult.ageInCadenceUnits, Number.POSITIVE_INFINITY);

[koala73]

Fixes landed post-merge in follow-up PR #2953. Extended the defensive-cases test to pin both ageMs and ageInCadenceUnits as Number.POSITIVE_INFINITY across all four branches (null, undefined, NaN, future). Coverage went from 1/8 to 8/8.