@mrtdown/core 2.0.0-alpha.5 → 2.0.0-alpha.7

package/dist/helpers/resolvePeriods.d.ts

@@ -1,224 +0,0 @@
-import type { Period } from '../schema/issue/period.js';
-/**
- * Optional inference tuning for operational mode.
- */
-type ResolvePeriodsOperationalModeConfig = {
-    /**
-     * Minutes after `lastEvidenceAt` before an open period is considered stale.
-     *
-     * @default 120
-     */
-    evidenceStaleAfterMinutes?: number;
-    /**
-     * Grace minutes after crowd activity decays before inferring resolution.
-     *
-     * @default 30
-     */
-    crowdExitGraceMinutes?: number;
-    /**
-     * Hard cap for inferred period length from `startAt`.
-     *
-     * @default 1080
-     */
-    maxInferredDurationMinutes?: number;
-};
-/**
- * Crowd-derived signal used as a positive indicator of ongoing disruption.
- */
-type ResolvePeriodsCrowdSignal = {
-    /**
-     * Whether crowd reports currently indicate active disruption.
-     */
-    activeNow: boolean;
-    /**
-     * Most recent timestamp when crowd activity was observed.
-     */
-    lastActiveAt?: string | null;
-    /**
-     * Explicit timestamp when crowd reports indicate resolution.
-     */
-    exitedAt?: string | null;
-    /**
-     * Optional model confidence for `activeNow` in the [0, 1] range.
-     */
-    confidenceNow?: number | null;
-};
-export type ResolvePeriodsMode = {
-    kind: 'canonical';
-} | {
-    kind: 'operational';
-    /**
-     * Timestamp of the most recent evidence supporting an ongoing state
-     * for this entity.
-     *
-     * If provided and endAt is null:
-     * - May be used to infer an end time after a configured staleness window.
-     *
-     * If null or undefined:
-     * - No evidence-timeout inference will occur.
-     */
-    lastEvidenceAt?: string | null;
-    /**
-     * Optional crowd signal state for this entity.
-     *
-     * Crowd data is treated as a positive signal:
-     * - activeNow = true -> disruption likely ongoing.
-     * - exitedAt or lastActiveAt may be used to infer resolution.
-     */
-    crowd?: ResolvePeriodsCrowdSignal | null;
-    /**
-     * Optional configuration overrides for inference behavior.
-     *
-     * If omitted, sensible defaults are used.
-     *
-     * @default { evidenceStaleAfterMinutes: 120, crowdExitGraceMinutes: 30, maxInferredDurationMinutes: 1080 }
-     */
-    config?: ResolvePeriodsOperationalModeConfig;
-};
-export type ResolvePeriodsEndAtSource = 'fact' | 'inferred' | 'none';
-export type ResolvePeriodsEndAtReason = 'crowd_decay' | 'evidence_timeout';
-/**
- * Parameters for resolvePeriods().
- *
- * These inputs provide:
- * - The canonical periods to resolve
- * - The evaluation timestamp (`asOf`)
- * - The normalization strategy (`mode`)
- * - Optional contextual signals used for inference (evidence + crowd)
- *
- * None of these inputs modify canonical storage. They are used only to
- * derive a view suitable for UI or analytics.
- */
-export type ResolvePeriodsParams = {
-    /**
-     * Canonical periods for a single entity (service or facility).
-     *
-     * Requirements:
-     * - startAt and endAt must be ISO 8601 strings with timezone offsets.
-     * - endAt may be null when resolution was not explicitly recorded.
-     *
-     * These are treated as factual inputs. resolvePeriods() does not
-     * mutate or rewrite them.
-     */
-    periods: Period[];
-    /**
-     * The timestamp at which normalization is evaluated.
-     *
-     * Must be an ISO 8601 string with timezone offset (e.g. +08:00).
-     *
-     * Examples:
-     * - Determines whether a period is currently active.
-     * - Prevents inferred end times from extending into the future.
-     */
-    asOf: string;
-    /**
-     * Controls how open-ended periods are interpreted.
-     */
-    mode: ResolvePeriodsMode;
-};
-/**
- * Normalized periods returned by `resolvePeriods()`.
- *
- * Each item preserves canonical `startAt`/`endAt` values and adds mode-aware
- * resolution metadata for consumers that need either factual timelines or
- * operational "active now" behavior.
- */
-type ResolvePeriodsResult = {
-    /**
-     * Start timestamp from canonical period data.
-     */
-    startAt: string;
-    /**
-     * Canonical end timestamp as stored in source data.
-     *
-     * This remains null for open-ended canonical periods.
-     */
-    endAt: string | null;
-    /**
-     * Effective end timestamp for the selected mode.
-     *
-     * - "canonical": equals `endAt`
-     * - "operational": may be inferred (end of day when inferred)
-     */
-    endAtResolved: string | null;
-    /**
-     * Origin of `endAtResolved`.
-     */
-    endAtSource: ResolvePeriodsEndAtSource;
-    /**
-     * Heuristic used when `endAtSource` is "inferred".
-     */
-    endAtReason?: ResolvePeriodsEndAtReason;
-}[];
-/**
- * Resolves canonical Period[] into a view suitable for UI or statistics.
- *
- * This function does NOT mutate canonical period data. It derives a view over
- * stored periods depending on the selected normalization mode.
- *
- * The core problem this solves:
- * - In real operations, disruption "end" is often not explicitly reported.
- * - Crowd reports are positive-only (people report problems more than resolution).
- * - Canonical logs should not fabricate timestamps, but the product still needs:
- *   - a usable "active now" experience, and
- *   - honest uptime/statistics.
- *
- * ---------------------------------------------------------------------
- * MODES
- * ---------------------------------------------------------------------
- *
- * 1) "canonical"  (truth / audit)
- *
- * Intended for:
- * - Issue detail timelines and audit views ("what do we actually know?")
- * - Debugging and deterministic replay
- * - Data exports and downstream processing
- *
- * Behavior:
- * - Returns periods exactly as stored.
- * - endAtresolved === endAt.
- * - Open-ended periods (endAt = null) remain open.
- * - No inferred end times are introduced.
- *
- * Use this when you want maximum factual integrity and reproducibility.
- *
- *
- * 2) "operational"  (live UX)
- *
- * Intended for:
- * - Live disruption UI (homepage banners, "active now", notifications)
- * - User-facing duration display ("likely ended around ...")
- * - Operational dashboards where preventing "zombie incidents" is important
- *
- * Behavior:
- * - If a period has a factual endAt, use it.
- * - If endAt is null, attempt to infer an end time using heuristics such as:
- *   - crowd signal decay (preferred when available)
- *   - evidence staleness timeout (fallback)
- * - Inferred ends are annotated:
- *   endAtSource = "inferred"
- *   endAtReason = "crowd_decay" | "evidence_timeout"
- * - If inference would produce an end time later than `asOf`,
- *   the period remains open (still active).
- *
- * IMPORTANT:
- * - Inferred ends are derived and reversible.
- * - They must NOT be written back into canonical storage.
- *
- * Inferred ends are set to end of day (00:00 next day, exclusive) in Singapore
- * timezone, not duration-based. This avoids artificially shortening disruption.
- *
- * Use this when you want a stable, user-friendly view of "what's happening now"
- * even when reporting is incomplete.
- *
- *
- * ---------------------------------------------------------------------
- * DESIGN PRINCIPLE
- * ---------------------------------------------------------------------
- *
- * Canonical data must remain factually correct and append-only.
- * Heuristics (timeouts, crowd decay, assumptions) belong in derived views,
- * not in canonical period storage.
- */
-export declare function resolvePeriods(params: ResolvePeriodsParams): ResolvePeriodsResult;
-export {};

package/dist/helpers/resolvePeriods.js

@@ -1,207 +0,0 @@
-import { DateTime } from 'luxon';
-import { assert } from '../util/assert.js';
-import { normalizeRecurringPeriod } from './normalizeRecurringPeriod.js';
-const DEFAULTS = {
-    evidenceStaleAfterMinutes: 120,
-    crowdExitGraceMinutes: 30,
-    maxInferredDurationMinutes: 18 * 60,
-};
-function resolveByMode(args) {
-    const { period, mode, asOf, lastEvidenceAt, crowd, config } = args;
-    const startAtDt = DateTime.fromISO(period.startAt, { setZone: true });
-    assert(startAtDt.isValid, `Invalid ISO datetime: ${period.startAt}`);
-    if (mode === 'canonical') {
-        return {
-            ...period,
-            endAtResolved: period.endAt,
-            endAtSource: period.endAt ? 'fact' : 'none',
-        };
-    }
-    if (period.endAt) {
-        return {
-            ...period,
-            endAtResolved: period.endAt,
-            endAtSource: 'fact',
-        };
-    }
-    const evidenceTimeoutEnd = lastEvidenceAt
-        ? (() => {
-            const parsedLastEvidenceAt = DateTime.fromISO(lastEvidenceAt, {
-                setZone: true,
-            });
-            assert(parsedLastEvidenceAt.isValid, `Invalid ISO datetime: ${lastEvidenceAt}`);
-            return parsedLastEvidenceAt.plus({
-                minutes: config.evidenceStaleAfterMinutes,
-            });
-        })()
-        : null;
-    let crowdDecayEnd = null;
-    if (crowd) {
-        if (crowd.exitedAt) {
-            crowdDecayEnd = DateTime.fromISO(crowd.exitedAt, { setZone: true });
-            assert(crowdDecayEnd.isValid, `Invalid ISO datetime: ${crowd.exitedAt}`);
-        }
-        else if (!crowd.activeNow && crowd.lastActiveAt) {
-            const parsedLastActiveAt = DateTime.fromISO(crowd.lastActiveAt, {
-                setZone: true,
-            });
-            assert(parsedLastActiveAt.isValid, `Invalid ISO datetime: ${crowd.lastActiveAt}`);
-            crowdDecayEnd = parsedLastActiveAt.plus({
-                minutes: config.crowdExitGraceMinutes,
-            });
-        }
-    }
-    const inferredCandidate = crowdDecayEnd ?? evidenceTimeoutEnd;
-    const inferredReason = crowdDecayEnd
-        ? 'crowd_decay'
-        : evidenceTimeoutEnd
-            ? 'evidence_timeout'
-            : undefined;
-    if (!inferredCandidate || !inferredReason) {
-        return {
-            ...period,
-            endAtResolved: null,
-            endAtSource: 'none',
-        };
-    }
-    const maxInferredEnd = startAtDt.plus({
-        minutes: config.maxInferredDurationMinutes,
-    });
-    // Inferred end = end of day (00:00 next day, exclusive) in Singapore timezone.
-    let inferredEnd = inferredCandidate
-        .setZone('Asia/Singapore')
-        .startOf('day')
-        .plus({ days: 1 });
-    // Never infer an end before the period starts.
-    if (inferredEnd < startAtDt) {
-        inferredEnd = startAtDt;
-    }
-    // Never infer beyond the configured operational maximum window.
-    if (inferredEnd > maxInferredEnd) {
-        inferredEnd = maxInferredEnd;
-    }
-    // If inferred close time is in the future relative to asOf, keep it open.
-    if (inferredEnd > asOf) {
-        return {
-            ...period,
-            endAtResolved: null,
-            endAtSource: 'none',
-        };
-    }
-    return {
-        ...period,
-        endAtResolved: inferredEnd.toISO(),
-        endAtSource: 'inferred',
-        endAtReason: inferredReason,
-    };
-}
-/**
- * Resolves canonical Period[] into a view suitable for UI or statistics.
- *
- * This function does NOT mutate canonical period data. It derives a view over
- * stored periods depending on the selected normalization mode.
- *
- * The core problem this solves:
- * - In real operations, disruption "end" is often not explicitly reported.
- * - Crowd reports are positive-only (people report problems more than resolution).
- * - Canonical logs should not fabricate timestamps, but the product still needs:
- *   - a usable "active now" experience, and
- *   - honest uptime/statistics.
- *
- * ---------------------------------------------------------------------
- * MODES
- * ---------------------------------------------------------------------
- *
- * 1) "canonical"  (truth / audit)
- *
- * Intended for:
- * - Issue detail timelines and audit views ("what do we actually know?")
- * - Debugging and deterministic replay
- * - Data exports and downstream processing
- *
- * Behavior:
- * - Returns periods exactly as stored.
- * - endAtresolved === endAt.
- * - Open-ended periods (endAt = null) remain open.
- * - No inferred end times are introduced.
- *
- * Use this when you want maximum factual integrity and reproducibility.
- *
- *
- * 2) "operational"  (live UX)
- *
- * Intended for:
- * - Live disruption UI (homepage banners, "active now", notifications)
- * - User-facing duration display ("likely ended around ...")
- * - Operational dashboards where preventing "zombie incidents" is important
- *
- * Behavior:
- * - If a period has a factual endAt, use it.
- * - If endAt is null, attempt to infer an end time using heuristics such as:
- *   - crowd signal decay (preferred when available)
- *   - evidence staleness timeout (fallback)
- * - Inferred ends are annotated:
- *   endAtSource = "inferred"
- *   endAtReason = "crowd_decay" | "evidence_timeout"
- * - If inference would produce an end time later than `asOf`,
- *   the period remains open (still active).
- *
- * IMPORTANT:
- * - Inferred ends are derived and reversible.
- * - They must NOT be written back into canonical storage.
- *
- * Inferred ends are set to end of day (00:00 next day, exclusive) in Singapore
- * timezone, not duration-based. This avoids artificially shortening disruption.
- *
- * Use this when you want a stable, user-friendly view of "what's happening now"
- * even when reporting is incomplete.
- *
- *
- * ---------------------------------------------------------------------
- * DESIGN PRINCIPLE
- * ---------------------------------------------------------------------
- *
- * Canonical data must remain factually correct and append-only.
- * Heuristics (timeouts, crowd decay, assumptions) belong in derived views,
- * not in canonical period storage.
- */
-export function resolvePeriods(params) {
-    const { periods, asOf, mode } = params;
-    const lastEvidenceAt = mode.kind === 'operational' ? mode.lastEvidenceAt : undefined;
-    const crowd = mode.kind === 'operational' ? (mode.crowd ?? null) : null;
-    const config = mode.kind === 'operational' ? mode.config : undefined;
-    const normalizedPeriods = periods.flatMap((period) => {
-        switch (period.kind) {
-            case 'fixed':
-                return [period];
-            case 'recurring':
-                return normalizeRecurringPeriod(period);
-            default:
-                // @ts-expect-error - we only support fixed and recurring periods for now
-                throw new Error(`Invalid period kind: ${period.kind}`);
-        }
-    });
-    const effectiveConfig = {
-        evidenceStaleAfterMinutes: config?.evidenceStaleAfterMinutes ?? DEFAULTS.evidenceStaleAfterMinutes,
-        crowdExitGraceMinutes: config?.crowdExitGraceMinutes ?? DEFAULTS.crowdExitGraceMinutes,
-        maxInferredDurationMinutes: config?.maxInferredDurationMinutes ?? DEFAULTS.maxInferredDurationMinutes,
-    };
-    const asOfDt = DateTime.fromISO(asOf, { setZone: true });
-    assert(asOfDt.isValid, `Invalid ISO datetime: ${asOf}`);
-    const sorted = [...normalizedPeriods].sort((a, b) => {
-        const aStart = DateTime.fromISO(a.startAt, { setZone: true });
-        const bStart = DateTime.fromISO(b.startAt, { setZone: true });
-        assert(aStart.isValid, `Invalid ISO datetime: ${a.startAt}`);
-        assert(bStart.isValid, `Invalid ISO datetime: ${b.startAt}`);
-        return aStart.toMillis() - bStart.toMillis();
-    });
-    return sorted.map((period) => resolveByMode({
-        period: { ...period },
-        mode: mode.kind,
-        asOf: asOfDt,
-        lastEvidenceAt,
-        crowd,
-        config: effectiveConfig,
-    }));
-}
-//# sourceMappingURL=resolvePeriods.js.map

package/dist/helpers/resolvePeriods.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolvePeriods.js","sourceRoot":"/","sources":["helpers/resolvePeriods.ts"],"names":[],"mappings":"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","sourcesContent":["import { DateTime } from 'luxon';\nimport type { Period, PeriodFixed } from '../schema/issue/period.js';\nimport { assert } from '../util/assert.js';\nimport { normalizeRecurringPeriod } from './normalizeRecurringPeriod.js';\n\nconst DEFAULTS: ResolvePeriodsOperationalModeConfig = {\n  evidenceStaleAfterMinutes: 120,\n  crowdExitGraceMinutes: 30,\n  maxInferredDurationMinutes: 18 * 60,\n};\n\n/**\n * Optional inference tuning for operational mode.\n */\ntype ResolvePeriodsOperationalModeConfig = {\n  /**\n   * Minutes after `lastEvidenceAt` before an open period is considered stale.\n   *\n   * @default 120\n   */\n  evidenceStaleAfterMinutes?: number;\n  /**\n   * Grace minutes after crowd activity decays before inferring resolution.\n   *\n   * @default 30\n   */\n  crowdExitGraceMinutes?: number;\n  /**\n   * Hard cap for inferred period length from `startAt`.\n   *\n   * @default 1080\n   */\n  maxInferredDurationMinutes?: number;\n};\n\n/**\n * Crowd-derived signal used as a positive indicator of ongoing disruption.\n */\ntype ResolvePeriodsCrowdSignal = {\n  /**\n   * Whether crowd reports currently indicate active disruption.\n   */\n  activeNow: boolean;\n  /**\n   * Most recent timestamp when crowd activity was observed.\n   */\n  lastActiveAt?: string | null;\n  /**\n   * Explicit timestamp when crowd reports indicate resolution.\n   */\n  exitedAt?: string | null;\n  /**\n   * Optional model confidence for `activeNow` in the [0, 1] range.\n   */\n  confidenceNow?: number | null;\n};\n\nexport type ResolvePeriodsMode =\n  | { kind: 'canonical' }\n  | {\n      kind: 'operational';\n      /**\n       * Timestamp of the most recent evidence supporting an ongoing state\n       * for this entity.\n       *\n       * If provided and endAt is null:\n       * - May be used to infer an end time after a configured staleness window.\n       *\n       * If null or undefined:\n       * - No evidence-timeout inference will occur.\n       */\n      lastEvidenceAt?: string | null;\n      /**\n       * Optional crowd signal state for this entity.\n       *\n       * Crowd data is treated as a positive signal:\n       * - activeNow = true -> disruption likely ongoing.\n       * - exitedAt or lastActiveAt may be used to infer resolution.\n       */\n      crowd?: ResolvePeriodsCrowdSignal | null;\n      /**\n       * Optional configuration overrides for inference behavior.\n       *\n       * If omitted, sensible defaults are used.\n       *\n       * @default { evidenceStaleAfterMinutes: 120, crowdExitGraceMinutes: 30, maxInferredDurationMinutes: 1080 }\n       */\n      config?: ResolvePeriodsOperationalModeConfig;\n    };\n\nexport type ResolvePeriodsEndAtSource = 'fact' | 'inferred' | 'none';\nexport type ResolvePeriodsEndAtReason = 'crowd_decay' | 'evidence_timeout';\n\n/**\n * Parameters for resolvePeriods().\n *\n * These inputs provide:\n * - The canonical periods to resolve\n * - The evaluation timestamp (`asOf`)\n * - The normalization strategy (`mode`)\n * - Optional contextual signals used for inference (evidence + crowd)\n *\n * None of these inputs modify canonical storage. They are used only to\n * derive a view suitable for UI or analytics.\n */\nexport type ResolvePeriodsParams = {\n  /**\n   * Canonical periods for a single entity (service or facility).\n   *\n   * Requirements:\n   * - startAt and endAt must be ISO 8601 strings with timezone offsets.\n   * - endAt may be null when resolution was not explicitly recorded.\n   *\n   * These are treated as factual inputs. resolvePeriods() does not\n   * mutate or rewrite them.\n   */\n  periods: Period[];\n\n  /**\n   * The timestamp at which normalization is evaluated.\n   *\n   * Must be an ISO 8601 string with timezone offset (e.g. +08:00).\n   *\n   * Examples:\n   * - Determines whether a period is currently active.\n   * - Prevents inferred end times from extending into the future.\n   */\n  asOf: string;\n\n  /**\n   * Controls how open-ended periods are interpreted.\n   */\n  mode: ResolvePeriodsMode;\n};\n\n/**\n * Normalized periods returned by `resolvePeriods()`.\n *\n * Each item preserves canonical `startAt`/`endAt` values and adds mode-aware\n * resolution metadata for consumers that need either factual timelines or\n * operational \"active now\" behavior.\n */\ntype ResolvePeriodsResult = {\n  /**\n   * Start timestamp from canonical period data.\n   */\n  startAt: string;\n  /**\n   * Canonical end timestamp as stored in source data.\n   *\n   * This remains null for open-ended canonical periods.\n   */\n  endAt: string | null;\n  /**\n   * Effective end timestamp for the selected mode.\n   *\n   * - \"canonical\": equals `endAt`\n   * - \"operational\": may be inferred (end of day when inferred)\n   */\n  endAtResolved: string | null;\n  /**\n   * Origin of `endAtResolved`.\n   */\n  endAtSource: ResolvePeriodsEndAtSource;\n  /**\n   * Heuristic used when `endAtSource` is \"inferred\".\n   */\n  endAtReason?: ResolvePeriodsEndAtReason;\n}[];\n\nfunction resolveByMode(args: {\n  period: PeriodFixed;\n  mode: ResolvePeriodsMode['kind'];\n  asOf: DateTime;\n  lastEvidenceAt?: string | null;\n  crowd?: ResolvePeriodsCrowdSignal | null;\n  config: ResolvePeriodsOperationalModeConfig;\n}): ResolvePeriodsResult[number] {\n  const { period, mode, asOf, lastEvidenceAt, crowd, config } = args;\n  const startAtDt = DateTime.fromISO(period.startAt, { setZone: true });\n  assert(startAtDt.isValid, `Invalid ISO datetime: ${period.startAt}`);\n\n  if (mode === 'canonical') {\n    return {\n      ...period,\n      endAtResolved: period.endAt,\n      endAtSource: period.endAt ? 'fact' : 'none',\n    };\n  }\n\n  if (period.endAt) {\n    return {\n      ...period,\n      endAtResolved: period.endAt,\n      endAtSource: 'fact',\n    };\n  }\n\n  const evidenceTimeoutEnd = lastEvidenceAt\n    ? (() => {\n        const parsedLastEvidenceAt = DateTime.fromISO(lastEvidenceAt, {\n          setZone: true,\n        });\n        assert(\n          parsedLastEvidenceAt.isValid,\n          `Invalid ISO datetime: ${lastEvidenceAt}`,\n        );\n        return parsedLastEvidenceAt.plus({\n          minutes: config.evidenceStaleAfterMinutes,\n        });\n      })()\n    : null;\n\n  let crowdDecayEnd: DateTime | null = null;\n  if (crowd) {\n    if (crowd.exitedAt) {\n      crowdDecayEnd = DateTime.fromISO(crowd.exitedAt, { setZone: true });\n      assert(crowdDecayEnd.isValid, `Invalid ISO datetime: ${crowd.exitedAt}`);\n    } else if (!crowd.activeNow && crowd.lastActiveAt) {\n      const parsedLastActiveAt = DateTime.fromISO(crowd.lastActiveAt, {\n        setZone: true,\n      });\n      assert(\n        parsedLastActiveAt.isValid,\n        `Invalid ISO datetime: ${crowd.lastActiveAt}`,\n      );\n      crowdDecayEnd = parsedLastActiveAt.plus({\n        minutes: config.crowdExitGraceMinutes,\n      });\n    }\n  }\n\n  const inferredCandidate = crowdDecayEnd ?? evidenceTimeoutEnd;\n  const inferredReason: ResolvePeriodsResult[number]['endAtReason'] =\n    crowdDecayEnd\n      ? 'crowd_decay'\n      : evidenceTimeoutEnd\n        ? 'evidence_timeout'\n        : undefined;\n\n  if (!inferredCandidate || !inferredReason) {\n    return {\n      ...period,\n      endAtResolved: null,\n      endAtSource: 'none',\n    };\n  }\n\n  const maxInferredEnd = startAtDt.plus({\n    minutes: config.maxInferredDurationMinutes,\n  });\n\n  // Inferred end = end of day (00:00 next day, exclusive) in Singapore timezone.\n  let inferredEnd = inferredCandidate\n    .setZone('Asia/Singapore')\n    .startOf('day')\n    .plus({ days: 1 });\n\n  // Never infer an end before the period starts.\n  if (inferredEnd < startAtDt) {\n    inferredEnd = startAtDt;\n  }\n  // Never infer beyond the configured operational maximum window.\n  if (inferredEnd > maxInferredEnd) {\n    inferredEnd = maxInferredEnd;\n  }\n\n  // If inferred close time is in the future relative to asOf, keep it open.\n  if (inferredEnd > asOf) {\n    return {\n      ...period,\n      endAtResolved: null,\n      endAtSource: 'none',\n    };\n  }\n\n  return {\n    ...period,\n    endAtResolved: inferredEnd.toISO(),\n    endAtSource: 'inferred',\n    endAtReason: inferredReason,\n  };\n}\n\n/**\n * Resolves canonical Period[] into a view suitable for UI or statistics.\n *\n * This function does NOT mutate canonical period data. It derives a view over\n * stored periods depending on the selected normalization mode.\n *\n * The core problem this solves:\n * - In real operations, disruption \"end\" is often not explicitly reported.\n * - Crowd reports are positive-only (people report problems more than resolution).\n * - Canonical logs should not fabricate timestamps, but the product still needs:\n *   - a usable \"active now\" experience, and\n *   - honest uptime/statistics.\n *\n * ---------------------------------------------------------------------\n * MODES\n * ---------------------------------------------------------------------\n *\n * 1) \"canonical\"  (truth / audit)\n *\n * Intended for:\n * - Issue detail timelines and audit views (\"what do we actually know?\")\n * - Debugging and deterministic replay\n * - Data exports and downstream processing\n *\n * Behavior:\n * - Returns periods exactly as stored.\n * - endAtresolved === endAt.\n * - Open-ended periods (endAt = null) remain open.\n * - No inferred end times are introduced.\n *\n * Use this when you want maximum factual integrity and reproducibility.\n *\n *\n * 2) \"operational\"  (live UX)\n *\n * Intended for:\n * - Live disruption UI (homepage banners, \"active now\", notifications)\n * - User-facing duration display (\"likely ended around ...\")\n * - Operational dashboards where preventing \"zombie incidents\" is important\n *\n * Behavior:\n * - If a period has a factual endAt, use it.\n * - If endAt is null, attempt to infer an end time using heuristics such as:\n *   - crowd signal decay (preferred when available)\n *   - evidence staleness timeout (fallback)\n * - Inferred ends are annotated:\n *   endAtSource = \"inferred\"\n *   endAtReason = \"crowd_decay\" | \"evidence_timeout\"\n * - If inference would produce an end time later than `asOf`,\n *   the period remains open (still active).\n *\n * IMPORTANT:\n * - Inferred ends are derived and reversible.\n * - They must NOT be written back into canonical storage.\n *\n * Inferred ends are set to end of day (00:00 next day, exclusive) in Singapore\n * timezone, not duration-based. This avoids artificially shortening disruption.\n *\n * Use this when you want a stable, user-friendly view of \"what's happening now\"\n * even when reporting is incomplete.\n *\n *\n * ---------------------------------------------------------------------\n * DESIGN PRINCIPLE\n * ---------------------------------------------------------------------\n *\n * Canonical data must remain factually correct and append-only.\n * Heuristics (timeouts, crowd decay, assumptions) belong in derived views,\n * not in canonical period storage.\n */\nexport function resolvePeriods(\n  params: ResolvePeriodsParams,\n): ResolvePeriodsResult {\n  const { periods, asOf, mode } = params;\n  const lastEvidenceAt =\n    mode.kind === 'operational' ? mode.lastEvidenceAt : undefined;\n  const crowd = mode.kind === 'operational' ? (mode.crowd ?? null) : null;\n  const config = mode.kind === 'operational' ? mode.config : undefined;\n\n  const normalizedPeriods = periods.flatMap((period) => {\n    switch (period.kind) {\n      case 'fixed':\n        return [period];\n      case 'recurring':\n        return normalizeRecurringPeriod(period);\n      default:\n        // @ts-expect-error - we only support fixed and recurring periods for now\n        throw new Error(`Invalid period kind: ${period.kind}`);\n    }\n  });\n\n  const effectiveConfig = {\n    evidenceStaleAfterMinutes:\n      config?.evidenceStaleAfterMinutes ?? DEFAULTS.evidenceStaleAfterMinutes,\n    crowdExitGraceMinutes:\n      config?.crowdExitGraceMinutes ?? DEFAULTS.crowdExitGraceMinutes,\n    maxInferredDurationMinutes:\n      config?.maxInferredDurationMinutes ?? DEFAULTS.maxInferredDurationMinutes,\n  };\n  const asOfDt = DateTime.fromISO(asOf, { setZone: true });\n  assert(asOfDt.isValid, `Invalid ISO datetime: ${asOf}`);\n  const sorted = [...normalizedPeriods].sort((a, b) => {\n    const aStart = DateTime.fromISO(a.startAt, { setZone: true });\n    const bStart = DateTime.fromISO(b.startAt, { setZone: true });\n    assert(aStart.isValid, `Invalid ISO datetime: ${a.startAt}`);\n    assert(bStart.isValid, `Invalid ISO datetime: ${b.startAt}`);\n    return aStart.toMillis() - bStart.toMillis();\n  });\n\n  return sorted.map((period) =>\n    resolveByMode({\n      period: { ...period },\n      mode: mode.kind,\n      asOf: asOfDt,\n      lastEvidenceAt,\n      crowd,\n      config: effectiveConfig,\n    }),\n  );\n}\n"]}

package/dist/helpers/resolvePeriods.test.d.ts

@@ -1 +0,0 @@
-export {};