@transitrix/diagrams 1.0.0

package/dist/confidence/__tests__/score.test.js

@@ -0,0 +1,188 @@
+// Pins CONTRACT §11 — source-trust scale, freshness curve, element confidence,
+// view composite, unsourced handling, manifest decay resolution, A–D bands.
+import { describe, it, expect } from 'vitest';
+import { IMPLICIT_DECAY_DEFAULTS, composeView, confidenceBand, formatConfidenceHeader, freshness, resolveDecayParams, scoreElement, scoreView, sourceTrustWeight, } from '../score.js';
+const D = { fresh_days: 100, stale_days: 200, floor: 0.3 };
+describe('sourceTrustWeight (§11.2)', () => {
+    it('matches the closed scale', () => {
+        expect(sourceTrustWeight('authoritative')).toBe(1.0);
+        expect(sourceTrustWeight('corroborated')).toBe(0.8);
+        expect(sourceTrustWeight('single_source')).toBe(0.5);
+        expect(sourceTrustWeight('unverified')).toBe(0.25);
+    });
+});
+describe('freshness (§11.3)', () => {
+    const today = '2026-06-05';
+    it('returns 1.0 when age ≤ fresh_days', () => {
+        expect(freshness('2026-05-01', today, D)).toBe(1.0);
+        expect(freshness('2026-06-05', today, D)).toBe(1.0);
+    });
+    it('returns floor when age ≥ stale_days', () => {
+        expect(freshness('2025-01-01', today, D)).toBeCloseTo(0.3, 10);
+        const exactlyStale = '2025-11-17';
+        expect(freshness(exactlyStale, today, { fresh_days: 100, stale_days: 200, floor: 0.3 })).toBeCloseTo(0.3, 10);
+    });
+    it('interpolates linearly between fresh_days and stale_days', () => {
+        // midpoint: age 150 → 1.0 − (1.0 − 0.3) · (150 − 100) / (200 − 100) = 0.65
+        const midAge = new Date(Date.UTC(2026, 5, 5));
+        midAge.setUTCDate(midAge.getUTCDate() - 150);
+        const iso = midAge.toISOString().slice(0, 10);
+        expect(freshness(iso, today, D)).toBeCloseTo(0.65, 10);
+    });
+    it('clamps future-dated admitted_at to 1.0', () => {
+        expect(freshness('2030-01-01', today, D)).toBe(1.0);
+    });
+    it('treats absent admitted_at as fully stale (returns floor)', () => {
+        expect(freshness(undefined, today, D)).toBe(0.3);
+    });
+    it('treats unparseable admitted_at as fully stale', () => {
+        expect(freshness('not-a-date', today, D)).toBe(0.3);
+        expect(freshness('2026/06/05', today, D)).toBe(0.3);
+        expect(freshness('2026-13-01', today, D)).toBe(0.3);
+    });
+    it('returns floor when stale_days <= fresh_days (degenerate config) and age exceeds fresh', () => {
+        // age 365d for 2025-06-05; both branches collapse to floor.
+        expect(freshness('2025-06-05', today, { fresh_days: 100, stale_days: 100, floor: 0.4 })).toBe(0.4);
+        expect(freshness('2025-06-05', today, { fresh_days: 200, stale_days: 100, floor: 0.4 })).toBe(0.4);
+    });
+});
+describe('resolveDecayParams (§11.3 + MANIFEST §2)', () => {
+    const config = {
+        defaults: { fresh_days: 180, stale_days: 730, floor: 0.3 },
+        by_type: {
+            CAPABILITY: { fresh_days: 365, stale_days: 1825 },
+            APPLICATION: { fresh_days: 180, stale_days: 730 },
+        },
+    };
+    it('uses by_type overrides and inherits missing fields from defaults', () => {
+        // Pins the §11.3 example: CAPABILITY overrides fresh/stale but inherits floor=0.3.
+        expect(resolveDecayParams('CAPABILITY', config)).toEqual({ fresh_days: 365, stale_days: 1825, floor: 0.3 });
+    });
+    it('falls back to defaults for an unknown TYPE', () => {
+        expect(resolveDecayParams('PROCESS', config)).toEqual({ fresh_days: 180, stale_days: 730, floor: 0.3 });
+    });
+    it('falls back to §11.3 implicit defaults when the whole block is omitted', () => {
+        expect(resolveDecayParams('CAPABILITY', undefined)).toEqual(IMPLICIT_DECAY_DEFAULTS);
+        expect(resolveDecayParams('CAPABILITY', {})).toEqual(IMPLICIT_DECAY_DEFAULTS);
+    });
+    it('fills missing defaults fields from §11.3 implicit defaults', () => {
+        const partial = { defaults: { floor: 0.5 } };
+        expect(resolveDecayParams('PROCESS', partial)).toEqual({
+            fresh_days: IMPLICIT_DECAY_DEFAULTS.fresh_days,
+            stale_days: IMPLICIT_DECAY_DEFAULTS.stale_days,
+            floor: 0.5,
+        });
+    });
+});
+describe('scoreElement (§11.4–11.5)', () => {
+    const today = '2026-06-05';
+    it('takes the max source-trust weight (§11.4): extra weak sources never subtract', () => {
+        const score = scoreElement({ type: 'CAPABILITY', admitted_at: today, sources: ['unverified', 'authoritative', 'single_source'] }, today);
+        expect(score.source_trust).toBe(1.0);
+        expect(score.confidence).toBe(1.0);
+        expect(score.sourced).toBe(true);
+    });
+    it('multiplies source_trust by freshness', () => {
+        // §11.4 worked example: authoritative · floor.
+        const score = scoreElement({ type: 'X', admitted_at: '2024-01-01', sources: ['authoritative'] }, today, { defaults: D });
+        expect(score.source_trust).toBe(1.0);
+        expect(score.freshness).toBeCloseTo(0.3, 10);
+        expect(score.confidence).toBeCloseTo(0.3, 10);
+    });
+    it('marks unsourced elements at the unverified floor (§11.5) and sourced=false', () => {
+        const undef = scoreElement({ type: 'X', admitted_at: today }, today);
+        const empty = scoreElement({ type: 'X', admitted_at: today, sources: [] }, today);
+        for (const score of [undef, empty]) {
+            expect(score.source_trust).toBe(0.25);
+            expect(score.sourced).toBe(false);
+            expect(score.confidence).toBeCloseTo(0.25, 10);
+        }
+    });
+    it('distinguishes unsourced (counted separately) from sourced-but-unverified', () => {
+        const unsourced = scoreElement({ type: 'X', admitted_at: today }, today);
+        const sourcedUnverified = scoreElement({ type: 'X', admitted_at: today, sources: ['unverified'] }, today);
+        expect(unsourced.source_trust).toBe(sourcedUnverified.source_trust);
+        expect(unsourced.sourced).toBe(false);
+        expect(sourcedUnverified.sourced).toBe(true);
+    });
+});
+describe('confidenceBand (§11.6)', () => {
+    it('uses the documented thresholds', () => {
+        expect(confidenceBand(1.0)).toBe('A');
+        expect(confidenceBand(0.8)).toBe('A');
+        expect(confidenceBand(0.79)).toBe('B');
+        expect(confidenceBand(0.6)).toBe('B');
+        expect(confidenceBand(0.59)).toBe('C');
+        expect(confidenceBand(0.4)).toBe('C');
+        expect(confidenceBand(0.39)).toBe('D');
+        expect(confidenceBand(0)).toBe('D');
+    });
+});
+describe('composeView (§11.6)', () => {
+    it('headlines weakest link, reports mean and coverage', () => {
+        const composite = composeView([
+            { source_trust: 1.0, freshness: 1.0, confidence: 1.0, sourced: true },
+            { source_trust: 0.5, freshness: 0.8, confidence: 0.4, sourced: true },
+            { source_trust: 0.25, freshness: 1.0, confidence: 0.25, sourced: false },
+        ]);
+        expect(composite.weakest_link).toBeCloseTo(0.25, 10);
+        expect(composite.band).toBe('D');
+        expect(composite.mean).toBeCloseTo((1.0 + 0.4 + 0.25) / 3, 10);
+        expect(composite.coverage).toBeCloseTo(2 / 3, 10);
+        expect(composite.element_count).toBe(3);
+        expect(composite.unsourced_count).toBe(1);
+    });
+    it('returns a degenerate composite (band D, counts 0) for an empty set', () => {
+        const composite = composeView([]);
+        expect(composite.element_count).toBe(0);
+        expect(composite.weakest_link).toBe(0);
+        expect(composite.mean).toBe(0);
+        expect(composite.coverage).toBe(0);
+        expect(composite.band).toBe('D');
+    });
+});
+describe('scoreView end-to-end', () => {
+    const today = '2026-06-05';
+    it('composes weakest-link / mean / coverage / band from heterogenous elements', () => {
+        const view = scoreView([
+            // weakest link = 0.50 → band C
+            { type: 'X', admitted_at: today, sources: ['authoritative'] }, // 1.00
+            { type: 'X', admitted_at: today, sources: ['corroborated'] }, // 0.80
+            { type: 'X', admitted_at: today, sources: ['single_source'] }, // 0.50
+            { type: 'X', admitted_at: today, sources: ['corroborated'] }, // 0.80
+        ], today);
+        expect(view.composite.weakest_link).toBeCloseTo(0.5, 10);
+        expect(view.composite.band).toBe('C');
+        expect(view.composite.mean).toBeCloseTo((1.0 + 0.8 + 0.5 + 0.8) / 4, 10);
+        expect(view.composite.coverage).toBe(1);
+        expect(view.composite.unsourced_count).toBe(0);
+        expect(view.today).toBe(today);
+    });
+    it('accepts Date for today and converts to ISO', () => {
+        const view = scoreView([{ type: 'X', admitted_at: '2026-06-05', sources: ['authoritative'] }], new Date(Date.UTC(2026, 5, 5)));
+        expect(view.today).toBe('2026-06-05');
+        expect(view.composite.band).toBe('A');
+    });
+    it('reports band D and 0% coverage when every element is unsourced and fully stale', () => {
+        const view = scoreView([
+            { type: 'X' },
+            { type: 'X' },
+        ], '2026-06-05', { defaults: D });
+        // unsourced (0.25) · freshness floor (0.3) = 0.075 → band D.
+        expect(view.composite.coverage).toBe(0);
+        expect(view.composite.unsourced_count).toBe(2);
+        expect(view.composite.band).toBe('D');
+        expect(view.composite.weakest_link).toBeCloseTo(0.075, 10);
+    });
+});
+describe('formatConfidenceHeader (§11.6)', () => {
+    it('renders the documented header shape', () => {
+        const view = scoreView([{ type: 'X', admitted_at: '2026-06-05', sources: ['corroborated'] }], '2026-06-05');
+        // corroborated (0.8) · freshness 1.0 = 0.80 → band A (A is ≥ 0.8).
+        expect(formatConfidenceHeader(view)).toBe('Data confidence (as of 2026-06-05): A (weakest link) · 0.80 mean · 100% sourced');
+    });
+    it('returns an empty string for an empty composite', () => {
+        const view = scoreView([], '2026-06-05');
+        expect(formatConfidenceHeader(view)).toBe('');
+    });
+});

package/dist/confidence/index.d.ts

@@ -0,0 +1,2 @@
+export { IMPLICIT_DECAY_DEFAULTS, composeView, confidenceBand, formatConfidenceHeader, freshness, resolveDecayParams, scoreElement, scoreView, sourceTrustWeight, } from './score.js';
+export type { ConfidenceBand, ConfidenceDecayConfig, DecayParams, ElementScore, ScoringElement, SourceQuality, ViewComposite, ViewScore, } from './types.js';

package/dist/confidence/index.js

@@ -0,0 +1 @@
+export { IMPLICIT_DECAY_DEFAULTS, composeView, confidenceBand, formatConfidenceHeader, freshness, resolveDecayParams, scoreElement, scoreView, sourceTrustWeight, } from './score.js';

package/dist/confidence/score.d.ts

@@ -0,0 +1,62 @@
+import type { ConfidenceBand, ConfidenceDecayConfig, DecayParams, ElementScore, ScoringElement, SourceQuality, ViewComposite, ViewScore } from './types.js';
+/** §11.3 implicit defaults — used when the adopter omits `confidence_decay`. */
+export declare const IMPLICIT_DECAY_DEFAULTS: DecayParams;
+export declare function sourceTrustWeight(q: SourceQuality): number;
+/**
+ * Resolves the decay parameters for one element TYPE: `by_type[type]` overrides
+ * `defaults`, which overrides {@link IMPLICIT_DECAY_DEFAULTS}. Each field
+ * resolves independently — a `by_type` entry that sets only `fresh_days` /
+ * `stale_days` inherits `floor` from `defaults` (per the §11.3 example).
+ */
+export declare function resolveDecayParams(type: string, config?: ConfidenceDecayConfig): DecayParams;
+/**
+ * Computes freshness per CONTRACT §11.3.
+ *
+ * ```
+ * freshness = 1.0      if age_days ≤ fresh_days
+ *           = floor    if age_days ≥ stale_days
+ *           = 1.0 − (1.0 − floor) · (age_days − fresh_days) / (stale_days − fresh_days)   otherwise
+ * ```
+ *
+ * Future-dated `admitted_at` (negative age) is clamped to 1.0. An absent or
+ * unparseable `admitted_at` returns `floor` — the element is treated as fully
+ * stale, never as fresh.
+ */
+export declare function freshness(admittedAt: string | undefined, today: string, params: DecayParams): number;
+/**
+ * Scores one element per §11.4–11.5. The element's `sources` list is the
+ * resolved `derived_from` provenance: max trust wins (`max` in §11.4), and
+ * an empty / absent list marks the element unsourced — scored at the
+ * `unverified` floor and `sourced: false` so the view composite can count
+ * it separately per §11.5.
+ */
+export declare function scoreElement(element: ScoringElement, today: string, config?: ConfidenceDecayConfig): ElementScore;
+/** Confidence band per §11.6: A ≥ 0.8, B ≥ 0.6, C ≥ 0.4, D < 0.4. */
+export declare function confidenceBand(confidence: number): ConfidenceBand;
+/**
+ * Rolls per-element scores up to the view composite per §11.6. The weakest
+ * link is the headline; mean and coverage are reported alongside. An empty
+ * element set returns a degenerate composite (`weakest_link` and `mean` of 0,
+ * coverage 0, band `D`) — callers should detect `element_count === 0` if they
+ * want to suppress the header entirely rather than display the floor.
+ */
+export declare function composeView(scores: ElementScore[]): ViewComposite;
+/**
+ * Scores a view's elements end-to-end. The caller passes the rendered set,
+ * the adopter manifest's `confidence_decay` block (optional), and the
+ * reference date (`today`); the result is purely derived and never stored
+ * — re-running on the same inputs yields the same numbers (§11.6).
+ */
+export declare function scoreView(elements: ScoringElement[], today: string | Date, config?: ConfidenceDecayConfig): ViewScore;
+/**
+ * Renders the §11.6 example header line, e.g.:
+ *
+ * ```
+ * Data confidence (as of 2026-06-05): B (weakest link) · 0.71 mean · 92% sourced
+ * ```
+ *
+ * Shared between Studio (DQ-2) and DSM (DQ-5) so the banding/labels stay
+ * consistent across the two consumers. Returns an empty string for an empty
+ * composite — callers decide whether to suppress the header in that case.
+ */
+export declare function formatConfidenceHeader(view: ViewScore): string;

package/dist/confidence/score.js

@@ -0,0 +1,215 @@
+// Pure confidence-scoring per methodology CONTRACT §11. No I/O, no mutation:
+// callers (Studio previews, DSM React) pass already-resolved element inputs
+// and a `today` reference; this module returns the per-element scores and
+// the view composite. Lives in @transitrix/diagrams so Studio and DSM share
+// one implementation (see vkgeorgia/strategy#159 — DQ-1).
+/** §11.3 implicit defaults — used when the adopter omits `confidence_decay`. */
+export const IMPLICIT_DECAY_DEFAULTS = {
+    fresh_days: 180,
+    stale_days: 730,
+    floor: 0.3,
+};
+/** §11.2 source-trust weights. The fallback for an unknown label is `unverified`. */
+const SOURCE_TRUST_WEIGHTS = {
+    authoritative: 1.0,
+    corroborated: 0.8,
+    single_source: 0.5,
+    unverified: 0.25,
+};
+/** Weight for the `unverified` floor — both an explicit label and the unsourced fallback. */
+const UNVERIFIED_WEIGHT = SOURCE_TRUST_WEIGHTS.unverified;
+export function sourceTrustWeight(q) {
+    return SOURCE_TRUST_WEIGHTS[q] ?? UNVERIFIED_WEIGHT;
+}
+/**
+ * Resolves the decay parameters for one element TYPE: `by_type[type]` overrides
+ * `defaults`, which overrides {@link IMPLICIT_DECAY_DEFAULTS}. Each field
+ * resolves independently — a `by_type` entry that sets only `fresh_days` /
+ * `stale_days` inherits `floor` from `defaults` (per the §11.3 example).
+ */
+export function resolveDecayParams(type, config) {
+    const typeOverride = config?.by_type?.[type] ?? {};
+    const defaults = config?.defaults ?? {};
+    return {
+        fresh_days: pick(typeOverride.fresh_days, defaults.fresh_days, IMPLICIT_DECAY_DEFAULTS.fresh_days),
+        stale_days: pick(typeOverride.stale_days, defaults.stale_days, IMPLICIT_DECAY_DEFAULTS.stale_days),
+        floor: pick(typeOverride.floor, defaults.floor, IMPLICIT_DECAY_DEFAULTS.floor),
+    };
+}
+function pick(...values) {
+    for (const v of values)
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    // The trailing implicit default is always finite; this is only reached if a
+    // caller passes a non-finite implicit default — which we treat as 0.
+    return 0;
+}
+/**
+ * Computes freshness per CONTRACT §11.3.
+ *
+ * ```
+ * freshness = 1.0      if age_days ≤ fresh_days
+ *           = floor    if age_days ≥ stale_days
+ *           = 1.0 − (1.0 − floor) · (age_days − fresh_days) / (stale_days − fresh_days)   otherwise
+ * ```
+ *
+ * Future-dated `admitted_at` (negative age) is clamped to 1.0. An absent or
+ * unparseable `admitted_at` returns `floor` — the element is treated as fully
+ * stale, never as fresh.
+ */
+export function freshness(admittedAt, today, params) {
+    if (!admittedAt)
+        return params.floor;
+    const age = daysBetween(admittedAt, today);
+    if (age === null)
+        return params.floor;
+    if (age <= params.fresh_days)
+        return 1.0;
+    if (age >= params.stale_days)
+        return params.floor;
+    // Linear interpolation. Guard against a degenerate fresh==stale config: the
+    // two equalities above would already have returned, but if a caller passes
+    // stale_days < fresh_days we keep monotonic behaviour by returning floor.
+    const span = params.stale_days - params.fresh_days;
+    if (span <= 0)
+        return params.floor;
+    return 1.0 - (1.0 - params.floor) * ((age - params.fresh_days) / span);
+}
+/**
+ * Scores one element per §11.4–11.5. The element's `sources` list is the
+ * resolved `derived_from` provenance: max trust wins (`max` in §11.4), and
+ * an empty / absent list marks the element unsourced — scored at the
+ * `unverified` floor and `sourced: false` so the view composite can count
+ * it separately per §11.5.
+ */
+export function scoreElement(element, today, config) {
+    const sources = element.sources ?? [];
+    const sourced = sources.length > 0;
+    const source_trust = sourced
+        ? Math.max(...sources.map(sourceTrustWeight))
+        : UNVERIFIED_WEIGHT;
+    const params = resolveDecayParams(element.type, config);
+    const f = freshness(element.admitted_at, today, params);
+    return {
+        source_trust,
+        freshness: f,
+        confidence: source_trust * f,
+        sourced,
+    };
+}
+/** Confidence band per §11.6: A ≥ 0.8, B ≥ 0.6, C ≥ 0.4, D < 0.4. */
+export function confidenceBand(confidence) {
+    if (confidence >= 0.8)
+        return 'A';
+    if (confidence >= 0.6)
+        return 'B';
+    if (confidence >= 0.4)
+        return 'C';
+    return 'D';
+}
+/**
+ * Rolls per-element scores up to the view composite per §11.6. The weakest
+ * link is the headline; mean and coverage are reported alongside. An empty
+ * element set returns a degenerate composite (`weakest_link` and `mean` of 0,
+ * coverage 0, band `D`) — callers should detect `element_count === 0` if they
+ * want to suppress the header entirely rather than display the floor.
+ */
+export function composeView(scores) {
+    if (scores.length === 0) {
+        return {
+            weakest_link: 0,
+            mean: 0,
+            coverage: 0,
+            band: 'D',
+            element_count: 0,
+            unsourced_count: 0,
+        };
+    }
+    let min = Infinity;
+    let sum = 0;
+    let sourcedCount = 0;
+    for (const s of scores) {
+        if (s.confidence < min)
+            min = s.confidence;
+        sum += s.confidence;
+        if (s.sourced)
+            sourcedCount += 1;
+    }
+    const mean = sum / scores.length;
+    return {
+        weakest_link: min,
+        mean,
+        coverage: sourcedCount / scores.length,
+        band: confidenceBand(min),
+        element_count: scores.length,
+        unsourced_count: scores.length - sourcedCount,
+    };
+}
+/**
+ * Scores a view's elements end-to-end. The caller passes the rendered set,
+ * the adopter manifest's `confidence_decay` block (optional), and the
+ * reference date (`today`); the result is purely derived and never stored
+ * — re-running on the same inputs yields the same numbers (§11.6).
+ */
+export function scoreView(elements, today, config) {
+    const todayIso = toIsoDate(today);
+    const elementScores = elements.map(e => scoreElement(e, todayIso, config));
+    return {
+        elements: elementScores,
+        composite: composeView(elementScores),
+        today: todayIso,
+    };
+}
+/**
+ * Renders the §11.6 example header line, e.g.:
+ *
+ * ```
+ * Data confidence (as of 2026-06-05): B (weakest link) · 0.71 mean · 92% sourced
+ * ```
+ *
+ * Shared between Studio (DQ-2) and DSM (DQ-5) so the banding/labels stay
+ * consistent across the two consumers. Returns an empty string for an empty
+ * composite — callers decide whether to suppress the header in that case.
+ */
+export function formatConfidenceHeader(view) {
+    const c = view.composite;
+    if (c.element_count === 0)
+        return '';
+    const mean = c.mean.toFixed(2);
+    const coverage = Math.round(c.coverage * 100);
+    return `Data confidence (as of ${view.today}): ${c.band} (weakest link) · ${mean} mean · ${coverage}% sourced`;
+}
+// ── Date helpers ────────────────────────────────────────────────────────────
+/** Strict ISO-date parser. Accepts `YYYY-MM-DD`; returns null on anything else. */
+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function parseIsoDate(s) {
+    const m = ISO_DATE_RE.exec(s);
+    if (!m)
+        return null;
+    const year = Number(m[1]);
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    // UTC to avoid the host TZ shifting age_days by ±1.
+    const d = new Date(Date.UTC(year, month - 1, day));
+    if (d.getUTCFullYear() !== year ||
+        d.getUTCMonth() !== month - 1 ||
+        d.getUTCDate() !== day)
+        return null;
+    return d;
+}
+function toIsoDate(d) {
+    if (typeof d === 'string')
+        return d;
+    const y = d.getUTCFullYear();
+    const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+function daysBetween(fromIso, toIso) {
+    const from = parseIsoDate(fromIso);
+    const to = parseIsoDate(toIso);
+    if (!from || !to)
+        return null;
+    const ms = to.getTime() - from.getTime();
+    return Math.floor(ms / (24 * 60 * 60 * 1000));
+}

package/dist/confidence/types.d.ts

@@ -0,0 +1,79 @@
+/** Closed source-trust scale per CONTRACT §11.2. */
+export type SourceQuality = 'authoritative' | 'corroborated' | 'single_source' | 'unverified';
+/** Confidence band per CONTRACT §11.6 — derived from a numeric confidence. */
+export type ConfidenceBand = 'A' | 'B' | 'C' | 'D';
+/** Per-TYPE freshness-decay parameters per CONTRACT §11.3. */
+export interface DecayParams {
+    fresh_days: number;
+    stale_days: number;
+    floor: number;
+}
+/**
+ * Adopter-manifest `confidence_decay` block (MANIFEST.md §2). Both halves
+ * are optional: an absent `defaults` block falls back to the §11.3 implicit
+ * defaults, and an absent `by_type` entry inherits from `defaults`.
+ */
+export interface ConfidenceDecayConfig {
+    defaults?: Partial<DecayParams>;
+    by_type?: Record<string, Partial<DecayParams>>;
+}
+/**
+ * One canonical element fed to the scorer. The caller (Studio / DSM) has
+ * already resolved `derived_from` to the field artefacts and extracted their
+ * `source_quality` labels — this module never reads files.
+ */
+export interface ScoringElement {
+    /** Element TYPE name, used to look up per-TYPE decay (e.g. `CAPABILITY`). */
+    type: string;
+    /**
+     * ISO 8601 date the admission gate last ran for this element
+     * (`admitted_at`, CONTRACT §6). Reaffirmation bumps this date — the cure
+     * for staleness. Absent ⇒ treated as fully stale (freshness = floor).
+     */
+    admitted_at?: string;
+    /**
+     * Source qualities resolved from `derived_from` — one entry per cited
+     * field artefact. Undefined or empty ⇒ unsourced: scored as `unverified`
+     * (0.25) and counted separately per §11.5.
+     */
+    sources?: SourceQuality[];
+}
+/** Per-element scoring output. */
+export interface ElementScore {
+    /** Max source-trust weight over `sources`; 0.25 (`unverified`) if unsourced. */
+    source_trust: number;
+    /** Freshness in [floor, 1.0] per the §11.3 curve. */
+    freshness: number;
+    /** `source_trust × freshness`. */
+    confidence: number;
+    /**
+     * True iff at least one resolvable `derived_from` source was supplied.
+     * Drives the §11.5 "counted separately" gap signal and view coverage.
+     */
+    sourced: boolean;
+}
+/**
+ * View-level composite per CONTRACT §11.6. Three numbers surfaced alongside
+ * the view's formation date; the headline `band` is the band of the
+ * weakest link.
+ */
+export interface ViewComposite {
+    /** `min(confidence)` over the rendered elements. The headline figure. */
+    weakest_link: number;
+    /** Arithmetic mean of `confidence` (equal element weight in v1). */
+    mean: number;
+    /** Fraction of elements with `sourced === true`. */
+    coverage: number;
+    /** Band of the weakest link. */
+    band: ConfidenceBand;
+    element_count: number;
+    /** Elements with no resolvable `derived_from` — `unsourced_count` / `element_count` is the gap. */
+    unsourced_count: number;
+}
+/** Full scorer output: per-element + composite, plus the `today` used. */
+export interface ViewScore {
+    elements: ElementScore[];
+    composite: ViewComposite;
+    /** The date used as `today` (the reference for `age_days`). */
+    today: string;
+}

package/dist/confidence/types.js

@@ -0,0 +1,6 @@
+// Confidence-scoring types per methodology CONTRACT §11 (Confidence and
+// freshness). Two independent signals — source trust (authored, fixed) and
+// freshness (derived, recomputed on read) — combined per element and rolled
+// up to a view composite. See packages/diagrams/src/confidence/score.ts for
+// the pure scoring functions.
+export {};

package/dist/edge-path.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base handle length floor + span factors. The handle grows with both the
+ * horizontal and vertical span so the curve stays visibly horizontal long
+ * enough for the arrowhead to sit flush against the line.
+ */
+export declare const EDGE_MIN_HANDLE = 64;
+/** Multiplier applied to the base handle length. 1 = historical appearance. */
+export declare const DEFAULT_EDGE_CURVATURE = 1;
+/**
+ * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
+ * (tx,ty).
+ *
+ * `curvature` scales the control-handle length:
+ *   - 0   → control points collapse onto the endpoints ⇒ a straight line.
+ *   - 1   → the historical curve (no visual change from before #76).
+ *   - >1  → progressively stronger arc.
+ */
+export declare function horizontalCubicEdgePath(sx: number, sy: number, tx: number, ty: number, curvature?: number): string;

package/dist/edge-path.js

@@ -0,0 +1,35 @@
+// Shared edge geometry for the static notation previews (Goals, FGCA, FGA,
+// Activities). All four render dependency/relationship edges as a single cubic
+// Bézier with horizontal control handles: each control point shares its
+// endpoint's Y, so the tangent is horizontal at both ends and the marker-end
+// arrow reads as perpendicular to the node's vertical edge.
+//
+// Pulling the path math here (rather than duplicating it inline in each
+// preview) makes the configurable-curvature behaviour (vkgeorgia/strategy#76)
+// unit-testable — the extension has no test harness.
+/**
+ * Base handle length floor + span factors. The handle grows with both the
+ * horizontal and vertical span so the curve stays visibly horizontal long
+ * enough for the arrowhead to sit flush against the line.
+ */
+export const EDGE_MIN_HANDLE = 64;
+const DX_FACTOR = 0.5;
+const DY_FACTOR = 0.8;
+/** Multiplier applied to the base handle length. 1 = historical appearance. */
+export const DEFAULT_EDGE_CURVATURE = 1;
+/**
+ * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
+ * (tx,ty).
+ *
+ * `curvature` scales the control-handle length:
+ *   - 0   → control points collapse onto the endpoints ⇒ a straight line.
+ *   - 1   → the historical curve (no visual change from before #76).
+ *   - >1  → progressively stronger arc.
+ */
+export function horizontalCubicEdgePath(sx, sy, tx, ty, curvature = DEFAULT_EDGE_CURVATURE) {
+    const dx = tx - sx;
+    const dy = ty - sy;
+    const baseHandle = Math.max(EDGE_MIN_HANDLE, Math.abs(dx) * DX_FACTOR, Math.abs(dy) * DY_FACTOR);
+    const handle = baseHandle * curvature;
+    return `M${sx},${sy} C${sx + handle},${sy} ${tx - handle},${ty} ${tx},${ty}`;
+}

package/dist/element-envelope.d.ts

@@ -0,0 +1,15 @@
+import type { ValidationError } from './validation-types.js';
+export interface EnvelopeOptions {
+    /** Fixed `notation:` tag — lowercased TYPE short name (e.g. `factor`). */
+    notation: string;
+    /** Required `id:` TYPE prefix (e.g. `FACTOR`). */
+    idType: string;
+    /** Error code used for every envelope failure (e.g. `FACTOR-001`). */
+    code: string;
+}
+export interface EnvelopeResult {
+    /** The input narrowed to a record on success; `null` when the input is not a mapping. */
+    record: Record<string, unknown> | null;
+    errors: ValidationError[];
+}
+export declare function validateElementEnvelope(input: unknown, opts: EnvelopeOptions): EnvelopeResult;