@tmlmobilidade/dates 20260612.214.31 → 20260612.1126.8

package/dist/calendar/rules/calculation/filters.d.ts

@@ -1,5 +1,5 @@
 import type { DayContext } from './types.js';
-import { type EventReplacementRule, HHMM, type ManualRule, type OperationalDate, type ScheduleRule } from '@tmlmobilidade/types';
+import { type EventReplacementRule, type EventRestrictionRule, HHMM, type ManualRule, type OperationalDate, type ScheduleRule } from '@tmlmobilidade/types';
 /**
  * Removes time points based on manual EXCLUDE rules that match a given day context.
  *
@@ -38,6 +38,13 @@ export declare function applyManualExcludes(timepoints: Set<string>, appliedRule
  * @param manualRules - Array of all manual rules to check for intersection
  */
 export declare function applyReplacementManualExcludes(timepoints: Set<string>, appliedRuleIds: string[], replacement: EventReplacementRule, manualRules: ManualRule[]): void;
+/**
+ * Returns candidate timepoints removed by a single event restriction rule.
+ *
+ * Mirrors the three restriction modes used by {@link applyEventRestrictions}:
+ * all day, explicit timepoint list, or start/end window (midnight crossing supported).
+ */
+export declare function getTimepointsRemovedByEventRestriction(restriction: EventRestrictionRule, candidateTimepoints: Iterable<HHMM>): HHMM[];
 /**
  * Applies event restriction rules to remove time points for a specific date.
  *

package/dist/calendar/rules/calculation/filters.js

@@ -96,6 +96,31 @@ function removeTimePointsByWindow(timepoints, startHHMM, endHHMM) {
             timepoints.delete(tp);
     }
 }
+/**
+ * Returns candidate timepoints removed by a single event restriction rule.
+ *
+ * Mirrors the three restriction modes used by {@link applyEventRestrictions}:
+ * all day, explicit timepoint list, or start/end window (midnight crossing supported).
+ */
+export function getTimepointsRemovedByEventRestriction(restriction, candidateTimepoints) {
+    const candidates = [...candidateTimepoints];
+    if (!candidates.length)
+        return [];
+    if (restriction.all_day)
+        return candidates;
+    if (restriction.timepoints?.length) {
+        const explicit = new Set(restriction.timepoints);
+        return candidates.filter(tp => explicit.has(tp));
+    }
+    const start = restriction.start_time;
+    const end = restriction.end_time;
+    if (start && end) {
+        const remaining = new Set(candidates);
+        removeTimePointsByWindow(remaining, start, end);
+        return candidates.filter(tp => !remaining.has(tp));
+    }
+    return [];
+}
 /**
  * Applies event restriction rules to remove time points for a specific date.
  *
@@ -129,24 +154,8 @@ export function applyEventRestrictions(date, timepoints, appliedRuleIds, rules)
             continue;
         if (r._id)
             appliedRuleIds.push(r._id);
-        // 1) all day kills everything
-        if (r?.all_day) {
-            timepoints.clear();
-            continue;
-        }
-        // 2) explicit timepoints removal (UI generated)
-        if (r.timepoints?.length) {
-            for (const tp of r.timepoints)
-                timepoints.delete(tp);
-            continue;
-        }
-        // 3) fallback: compute from window
-        // If start/end exist, remove anything within that time window.
-        // If somehow missing, do nothing.
-        const start = r?.start_time;
-        const end = r?.end_time;
-        if (start && end) {
-            removeTimePointsByWindow(timepoints, start, end);
+        for (const tp of getTimepointsRemovedByEventRestriction(r, timepoints)) {
+            timepoints.delete(tp);
         }
     }
 }

package/dist/calendar/rules/calculation/index.d.ts

@@ -1,40 +1,29 @@
 import type { RuleApplication } from './types.js';
 import type { Event, Holiday, OperationalDate, ScheduleRule, YearPeriod } from '@tmlmobilidade/types';
 /**
- * Calculates which time points are active for each date in a range, based on scheduling rules.
+ * Operating schedule for one operational date: merged timepoints and applied rule IDs.
  *
- * This is the core scheduling algorithm that processes three types of rules:
- * 1. Manual rules (include/exclude) - Define base schedules for weekday/period combinations
- * 2. Event replacement rules - Override base schedules for specific dates
- * 3. Event restriction rules - Remove specific time points or time windows from schedules
+ * This is the core scheduling algorithm for “what runs” (preview, VKM, rules grid).
+ * It processes three rule kinds:
+ * 1. Manual rules (include/exclude) — base schedules for weekday/period combinations
+ * 2. Event replacement rules — override base schedules on specific dates
+ * 3. Event restriction rules — remove timepoints or windows from the result
  *
- * Algorithm flow for each date:
- * - Check for event replacement rule
- *   - If found: Use intersection-based matching with manual rules
- *   - Otherwise: Use context-based matching (weekday + period)
- * - Collect INCLUDE time points
- * - Apply EXCLUDE time points
- * - Apply event restrictions (by date)
- * - Return final time points and applied rule IDs
+ * Algorithm flow:
+ * - If a replacement applies: intersection-based manual matching + replacement excludes
+ * - Otherwise: weekday + period context matching + manual excludes
+ * - Always apply event restrictions by date
  *
- * @param rules - All scheduling rules to process (manual, replacement, restriction)
- * @param dateRange - Array of operational dates to calculate schedules for
- * @param periods - YearPeriod definitions (school term, summer, etc.) for context resolution
- * @returns Map from CalendarKey to RuleApplication with active time points and metadata
+ * For GTFS `service_id` token binding (`operating` / `base_off` rows), use
+ * `collectGtfsIncludeContributionsForDate` in `export-attribution/index.ts`.
+ * That layer delegates here on replacement days; the `operating` timepoint set
+ * should match this function’s result (see SCENARIOS P5).
  *
- * @example
- * ```ts
- * const rules = [...]; // Manual, replacement, and restriction rules
- * const dates = ['2026-02-01', '2026-02-02', ...];
- * const periods = [...]; // YearPeriod definitions
- *
- * const result = computeActiveTimePoints(rules, dates, periods);
- * const feb1 = result.get(calendarKey(Dates.fromOperationalDate('2026-02-01')));
- * // feb1 = {
- * //   timepoints: ['08:00', '09:00', '10:00'],
- * //   appliedRuleIds: ['rule1', 'rule2']
- * // }
- * ```
+ * @param date - Operational date to evaluate
+ * @param rules - All scheduling rules (manual, replacement, restriction)
+ * @param periods - YearPeriod definitions for context resolution
+ * @param holidays - Holiday calendar for weekday resolution
+ * @returns Active timepoints and IDs of rules that contributed
  */
 export declare function computeActiveRules(date: OperationalDate, rules: ScheduleRule[], periods: YearPeriod[], holidays: Holiday[], options?: {
     events?: Event[];

package/dist/calendar/rules/calculation/index.js

@@ -1,44 +1,34 @@
 import { calendarKey, calendarWeekday } from '../../utils/index.js';
 import { Dates } from '../../../dates.js';
+import { resolveEffectiveReplacement } from '../export-attribution/replacement.js';
 import { findReplacementForDate, getActivePeriodId } from '../utils/date.js';
 import { collectManualIncludes, collectReplacementManualIncludes } from './collectors.js';
 import { applyEventRestrictions, applyManualExcludes, applyReplacementManualExcludes } from './filters.js';
 /* * */
 /**
- * Calculates which time points are active for each date in a range, based on scheduling rules.
+ * Operating schedule for one operational date: merged timepoints and applied rule IDs.
  *
- * This is the core scheduling algorithm that processes three types of rules:
- * 1. Manual rules (include/exclude) - Define base schedules for weekday/period combinations
- * 2. Event replacement rules - Override base schedules for specific dates
- * 3. Event restriction rules - Remove specific time points or time windows from schedules
+ * This is the core scheduling algorithm for “what runs” (preview, VKM, rules grid).
+ * It processes three rule kinds:
+ * 1. Manual rules (include/exclude) — base schedules for weekday/period combinations
+ * 2. Event replacement rules — override base schedules on specific dates
+ * 3. Event restriction rules — remove timepoints or windows from the result
  *
- * Algorithm flow for each date:
- * - Check for event replacement rule
- *   - If found: Use intersection-based matching with manual rules
- *   - Otherwise: Use context-based matching (weekday + period)
- * - Collect INCLUDE time points
- * - Apply EXCLUDE time points
- * - Apply event restrictions (by date)
- * - Return final time points and applied rule IDs
+ * Algorithm flow:
+ * - If a replacement applies: intersection-based manual matching + replacement excludes
+ * - Otherwise: weekday + period context matching + manual excludes
+ * - Always apply event restrictions by date
  *
- * @param rules - All scheduling rules to process (manual, replacement, restriction)
- * @param dateRange - Array of operational dates to calculate schedules for
- * @param periods - YearPeriod definitions (school term, summer, etc.) for context resolution
- * @returns Map from CalendarKey to RuleApplication with active time points and metadata
+ * For GTFS `service_id` token binding (`operating` / `base_off` rows), use
+ * `collectGtfsIncludeContributionsForDate` in `export-attribution/index.ts`.
+ * That layer delegates here on replacement days; the `operating` timepoint set
+ * should match this function’s result (see SCENARIOS P5).
  *
- * @example
- * ```ts
- * const rules = [...]; // Manual, replacement, and restriction rules
- * const dates = ['2026-02-01', '2026-02-02', ...];
- * const periods = [...]; // YearPeriod definitions
- *
- * const result = computeActiveTimePoints(rules, dates, periods);
- * const feb1 = result.get(calendarKey(Dates.fromOperationalDate('2026-02-01')));
- * // feb1 = {
- * //   timepoints: ['08:00', '09:00', '10:00'],
- * //   appliedRuleIds: ['rule1', 'rule2']
- * // }
- * ```
+ * @param date - Operational date to evaluate
+ * @param rules - All scheduling rules (manual, replacement, restriction)
+ * @param periods - YearPeriod definitions for context resolution
+ * @param holidays - Holiday calendar for weekday resolution
+ * @returns Active timepoints and IDs of rules that contributed
  */
 export function computeActiveRules(date, rules, periods, holidays, options) {
     const manualRules = rules.filter((r) => r.kind === 'manual');
@@ -61,11 +51,7 @@ export function computeActiveRules(date, rules, periods, holidays, options) {
     let timepoints;
     let appliedRuleIds;
     if (replacement) {
-        // When same_weekday is true, each event date functions as its own actual weekday
-        // within the replacement's target periods, rather than all dates acting as one fixed weekday.
-        const effectiveReplacement = replacement.same_weekday
-            ? { ...replacement, weekdays: [calendarWeekday(key, holidays)] }
-            : replacement;
+        const effectiveReplacement = resolveEffectiveReplacement(date, replacement, holidays);
         // Replacement mode: match manuals by intersection (Option A)
         const base = collectReplacementManualIncludes(effectiveReplacement, monthFilteredManualRules);
         timepoints = base.timepoints;

package/dist/calendar/rules/export-attribution/canonical-registry.d.ts

@@ -0,0 +1,16 @@
+import type { Event, HHMM, Holiday, OperationalDate, ScheduleRule, YearPeriod } from '@tmlmobilidade/types';
+export interface CanonicalRegistryOptions {
+    events?: Event[];
+    holidays: Holiday[];
+    periods: YearPeriod[];
+}
+/**
+ * Date set for a rule token from definition (period × weekday × months × events),
+ * not from trip-day accumulation.
+ */
+export declare function buildCanonicalRuleDates(rule: ScheduleRule, exportDates: readonly OperationalDate[], { events, holidays, periods }: CanonicalRegistryOptions): Set<OperationalDate>;
+/**
+ * On forced-retarget replacement days, emit the replacement token for operating
+ * timepoints unless one calendar manual rule exactly covers the full operating set.
+ */
+export declare function shouldEmitReplacementOnForcedRetarget(operatingTimepoints: Iterable<HHMM>, calendarOperatingByTimepoint: Map<HHMM, ScheduleRule>): boolean;

package/dist/calendar/rules/export-attribution/canonical-registry.js

@@ -0,0 +1,61 @@
+import { calendarKey, calendarWeekday } from '../../utils/index.js';
+import { Dates } from '../../../dates.js';
+import { manualRuleMatchesContext } from '../calculation/matchers.js';
+import { getActivePeriodId } from '../utils/date.js';
+/**
+ * Date set for a rule token from definition (period × weekday × months × events),
+ * not from trip-day accumulation.
+ */
+export function buildCanonicalRuleDates(rule, exportDates, { events, holidays, periods }) {
+    if (rule.kind === 'event_replacement') {
+        const replacement = rule;
+        return new Set(exportDates.filter(date => replacement.dates?.includes(date)));
+    }
+    if (rule.kind !== 'manual' || rule.operating_mode !== 'include') {
+        return new Set();
+    }
+    const manual = rule;
+    const dates = new Set();
+    for (const date of exportDates) {
+        if (!manualRuleAppliesOnDate(manual, date, periods, holidays, events))
+            continue;
+        dates.add(date);
+    }
+    return dates;
+}
+function manualRuleAppliesOnDate(rule, date, periods, holidays, events) {
+    if (rule.event_id) {
+        const event = events?.find(e => e._id === rule.event_id);
+        if (!event?.dates?.length || !event.dates.includes(date))
+            return false;
+    }
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const month = Number(key.slice(5, 7));
+    if (rule.months?.length && !rule.months.includes(month))
+        return false;
+    const ctx = {
+        weekday: calendarWeekday(key, holidays),
+        yearPeriodId: getActivePeriodId(date, periods),
+    };
+    return manualRuleMatchesContext(rule, ctx);
+}
+function soleCalendarOwnerCoversOperating(operatingTimepoints, calendarOperatingByTimepoint) {
+    const sortedOperating = [...operatingTimepoints].sort();
+    if (!sortedOperating.length)
+        return false;
+    const ownerIds = new Set(sortedOperating.map(tp => calendarOperatingByTimepoint.get(tp)?._id));
+    if (ownerIds.size !== 1 || ownerIds.has(undefined))
+        return false;
+    const ownerRule = calendarOperatingByTimepoint.get(sortedOperating[0]);
+    if (ownerRule?.kind !== 'manual')
+        return false;
+    const ownerTimepoints = [...(ownerRule.timepoints ?? [])].sort();
+    return ownerTimepoints.join(',') === sortedOperating.join(',');
+}
+/**
+ * On forced-retarget replacement days, emit the replacement token for operating
+ * timepoints unless one calendar manual rule exactly covers the full operating set.
+ */
+export function shouldEmitReplacementOnForcedRetarget(operatingTimepoints, calendarOperatingByTimepoint) {
+    return !soleCalendarOwnerCoversOperating(operatingTimepoints, calendarOperatingByTimepoint);
+}

package/dist/calendar/rules/export-attribution/collectors.d.ts

@@ -0,0 +1,16 @@
+import type { DayContext } from '../calculation/types.js';
+import { EventReplacementRule, HHMM, ManualRule } from '@tmlmobilidade/types';
+export interface ManualRuleTimepoints {
+    rule: ManualRule;
+    timepoints: HHMM[];
+}
+/**
+ * Per-rule variant of `collectManualIncludes` (calculation) for GTFS token attribution.
+ *
+ * Returns one entry per matching manual instead of merging timepoints into a single set.
+ */
+export declare function collectManualIncludesByRule(manualRules: ManualRule[], ctx: DayContext): ManualRuleTimepoints[];
+/**
+ * Per-rule variant of `collectReplacementManualIncludes` (calculation) for GTFS token attribution.
+ */
+export declare function collectReplacementManualIncludesByRule(replacement: EventReplacementRule, manualRules: ManualRule[]): ManualRuleTimepoints[];

package/dist/calendar/rules/export-attribution/collectors.js

@@ -0,0 +1,37 @@
+import { manualRuleMatchesContext, manualRuleMatchesReplacement } from '../calculation/matchers.js';
+/**
+ * Per-rule variant of `collectManualIncludes` (calculation) for GTFS token attribution.
+ *
+ * Returns one entry per matching manual instead of merging timepoints into a single set.
+ */
+export function collectManualIncludesByRule(manualRules, ctx) {
+    const result = [];
+    for (const rule of manualRules) {
+        if (rule.operating_mode !== 'include')
+            continue;
+        if (!manualRuleMatchesContext(rule, ctx))
+            continue;
+        result.push({
+            rule,
+            timepoints: (rule.timepoints ?? []),
+        });
+    }
+    return result;
+}
+/**
+ * Per-rule variant of `collectReplacementManualIncludes` (calculation) for GTFS token attribution.
+ */
+export function collectReplacementManualIncludesByRule(replacement, manualRules) {
+    const result = [];
+    for (const rule of manualRules) {
+        if (rule.operating_mode !== 'include')
+            continue;
+        if (!manualRuleMatchesReplacement(rule, replacement))
+            continue;
+        result.push({
+            rule,
+            timepoints: (rule.timepoints ?? []),
+        });
+    }
+    return result;
+}

package/dist/calendar/rules/export-attribution/index.d.ts

@@ -0,0 +1,38 @@
+import type { GtfsIncludeContribution } from './types.js';
+import type { Event, Holiday, ManualRule, OperationalDate, ScheduleRule, YearPeriod } from '@tmlmobilidade/types';
+export * from './canonical-registry.js';
+export * from './collectors.js';
+export * from './replacement.js';
+export * from './trip-row-dates.js';
+export * from './types.js';
+/**
+ * Ownership order for overlapping general manuals (ND-03).
+ *
+ * When one rule's applicable dates strictly contain the other's (e.g. an "all days" rule vs a
+ * "weekdays" rule sharing a timepoint), the **broader** rule owns the shared timepoint so its
+ * date set stays whole and the export emits one clean token instead of fragmenting across two
+ * (`ALL` + `ALL_DU`). We only override on true containment — for equal or partially-overlapping
+ * scopes the choice is genuinely ambiguous, so the primary schedule (more timepoints, then `_id`)
+ * wins, exactly as before.
+ *
+ * @returns Negative if `a` should sort before `b` (i.e. `a` owns the shared timepoint).
+ */
+export declare function compareGeneralManualOwnershipPriority(a: ManualRule, b: ManualRule): number;
+/**
+ * GTFS export attribution for one operational date.
+ *
+ * Unlike {@link computeActiveRules}, which returns the merged operating timepoint set,
+ * this returns per-timepoint contributions so the exporter can attach the correct
+ * `service_id` rows (`operating` and `base_off`).
+ *
+ * **Invariant (P5):** the set of `operating` timepoints should match
+ * `computeActiveRules(date, allRules, periods, holidays, options).timepoints`.
+ *
+ * @see SCENARIOS.md for scenario IDs (FR-*, ND-*, ER-*).
+ *
+ * - Normal days → {@link collectNormalDayContributionsReconciled}
+ * - Replacement days → {@link collectReplacementDayContributions}
+ */
+export declare function collectGtfsIncludeContributionsForDate(date: OperationalDate, allRules: ScheduleRule[], periods: YearPeriod[], holidays: Holiday[], options?: {
+    events?: Event[];
+}): GtfsIncludeContribution[];

package/dist/calendar/rules/export-attribution/index.js

@@ -0,0 +1,313 @@
+import { calendarKey, calendarWeekday } from '../../utils/index.js';
+import { Dates } from '../../../dates.js';
+import { hhmm } from '@tmlmobilidade/types';
+import { getTimepointsRemovedByEventRestriction } from '../calculation/filters.js';
+import { computeActiveRules } from '../calculation/index.js';
+import { findReplacementForDate, getActivePeriodId } from '../utils/date.js';
+import { shouldEmitReplacementOnForcedRetarget } from './canonical-registry.js';
+import { collectManualIncludesByRule, collectReplacementManualIncludesByRule } from './collectors.js';
+import { isForcedRetargetDay, resolveEffectiveReplacement } from './replacement.js';
+export * from './canonical-registry.js';
+export * from './collectors.js';
+export * from './replacement.js';
+export * from './trip-row-dates.js';
+export * from './types.js';
+/** Keeps event-linked manuals only when the event lists `date` (same filter as {@link computeActiveRules}). */
+function filterManualRulesForDate(manualRules, date, events) {
+    return manualRules.filter((rule) => {
+        if (!rule.event_id)
+            return true;
+        const event = events?.find(e => e._id === rule.event_id);
+        if (!event?.dates?.length)
+            return false;
+        return event.dates.includes(date);
+    });
+}
+/** Drops manuals whose `months` list does not include the date’s calendar month. */
+function filterManualRulesByMonth(manualRules, date) {
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const month = Number(key.slice(5, 7));
+    return manualRules.filter(rule => !rule.months?.length || rule.months.includes(month));
+}
+const ALL_WEEKDAYS = [1, 2, 3, 4, 5, 6, 7];
+const ALL_MONTHS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+function isSubsetOf(inner, outer) {
+    const set = new Set(outer);
+    return inner.every(x => set.has(x));
+}
+/**
+ * True when every date `inner` applies on is also covered by `outer`.
+ *
+ * A manual rule applies on date `D` iff `weekday(D) ∈ weekdays ∧ period(D) ∈ year_period_ids ∧
+ * month(D) ∈ months` (an empty list means "all"). So `inner`'s applicable dates ⊆ `outer`'s
+ * exactly when `outer`'s scope contains `inner`'s on every dimension. This is the sound,
+ * data-free realization of "every date applied by `inner` is also applied by `outer`".
+ */
+function scopeContains(outer, inner) {
+    const outerWeekdays = outer.weekdays?.length ? outer.weekdays : ALL_WEEKDAYS;
+    const innerWeekdays = inner.weekdays?.length ? inner.weekdays : ALL_WEEKDAYS;
+    if (!isSubsetOf(innerWeekdays, outerWeekdays))
+        return false;
+    const outerMonths = outer.months?.length ? outer.months : ALL_MONTHS;
+    const innerMonths = inner.months?.length ? inner.months : ALL_MONTHS;
+    if (!isSubsetOf(innerMonths, outerMonths))
+        return false;
+    // Empty year_period_ids = all periods (open-ended universe). An empty outer covers every
+    // period; an empty inner is only contained by an empty outer.
+    if (!outer.year_period_ids?.length)
+        return true;
+    if (!inner.year_period_ids?.length)
+        return false;
+    return isSubsetOf(inner.year_period_ids, outer.year_period_ids);
+}
+/**
+ * Ownership order for overlapping general manuals (ND-03).
+ *
+ * When one rule's applicable dates strictly contain the other's (e.g. an "all days" rule vs a
+ * "weekdays" rule sharing a timepoint), the **broader** rule owns the shared timepoint so its
+ * date set stays whole and the export emits one clean token instead of fragmenting across two
+ * (`ALL` + `ALL_DU`). We only override on true containment — for equal or partially-overlapping
+ * scopes the choice is genuinely ambiguous, so the primary schedule (more timepoints, then `_id`)
+ * wins, exactly as before.
+ *
+ * @returns Negative if `a` should sort before `b` (i.e. `a` owns the shared timepoint).
+ */
+export function compareGeneralManualOwnershipPriority(a, b) {
+    const aContainsB = scopeContains(a, b);
+    const bContainsA = scopeContains(b, a);
+    if (aContainsB && !bContainsA)
+        return -1; // a strictly broader → a owns
+    if (bContainsA && !aContainsB)
+        return 1; // b strictly broader → b owns
+    const aCount = a.timepoints?.length ?? 0;
+    const bCount = b.timepoints?.length ?? 0;
+    if (aCount !== bCount)
+        return bCount - aCount;
+    return (a._id ?? '').localeCompare(b._id ?? '');
+}
+/**
+ * Non-replacement days: assign each matching timepoint to one `operating` rule.
+ *
+ * Event-specific manuals claim first; general manuals follow {@link compareGeneralManualOwnershipPriority}.
+ * When two generals share a timepoint, only one `operating` row is emitted (ND-03).
+ * When an event manual displaces a general on the same timepoint, emits `base_off` (ND-02).
+ */
+function collectNormalDayContributions(monthFilteredManualRules, ctx) {
+    const contributions = [];
+    const claimedTimepoints = new Set();
+    const timepointOwners = new Map();
+    const matchingRules = collectManualIncludesByRule(monthFilteredManualRules, ctx);
+    const eventSpecificRules = matchingRules.filter(({ rule }) => !!rule.event_id);
+    const generalRules = matchingRules
+        .filter(({ rule }) => !rule.event_id)
+        .sort((a, b) => compareGeneralManualOwnershipPriority(a.rule, b.rule));
+    for (const { rule, timepoints } of eventSpecificRules) {
+        for (const rawTimepoint of timepoints) {
+            const timepoint = hhmm(rawTimepoint);
+            if (claimedTimepoints.has(timepoint))
+                continue;
+            claimedTimepoints.add(timepoint);
+            timepointOwners.set(timepoint, rule);
+            contributions.push({ kind: 'operating', rule, timepoint });
+        }
+    }
+    for (const { rule, timepoints } of generalRules) {
+        for (const rawTimepoint of timepoints) {
+            const timepoint = hhmm(rawTimepoint);
+            if (claimedTimepoints.has(timepoint)) {
+                const ownerRule = timepointOwners.get(timepoint);
+                if (!ownerRule)
+                    continue;
+                // ND-03: overlapping general manuals co-apply in the rules engine — one circulation,
+                // one operating row. base_off is only for event/replacement displacement (ND-02, FR-*).
+                if (!ownerRule.event_id && !rule.event_id)
+                    continue;
+                contributions.push({ excludeRule: ownerRule, kind: 'base_off', rule, timepoint });
+                continue;
+            }
+            claimedTimepoints.add(timepoint);
+            timepointOwners.set(timepoint, rule);
+            contributions.push({ kind: 'operating', rule, timepoint });
+        }
+    }
+    return contributions;
+}
+/** Rule that removed `timepoint` from the calendar operating set on this date (exclude or restriction). */
+function findDisplacementExcludeRule(date, timepoint, allRules, appliedRuleIds) {
+    const rulesById = new Map(allRules.map(rule => [rule._id, rule]));
+    for (const id of appliedRuleIds) {
+        const rule = rulesById.get(id);
+        if (rule?.kind === 'manual' && rule.operating_mode === 'exclude' && rule.timepoints?.includes(timepoint)) {
+            return rule;
+        }
+    }
+    for (const id of appliedRuleIds) {
+        const rule = rulesById.get(id);
+        if (rule?.kind !== 'event_restriction' || !rule.dates?.includes(date))
+            continue;
+        if (getTimepointsRemovedByEventRestriction(rule, [timepoint]).includes(timepoint)) {
+            return rule;
+        }
+    }
+    return undefined;
+}
+/**
+ * Normal days: reconcile calendar manuals with {@link computeActiveRules} (P5, ER-01).
+ *
+ * Calendar-only timepoints removed by event manual excludes or event restrictions become
+ * `base_off` pairs so the exporter emits `BASE-OFF-EVENT` instead of plain `BASE`.
+ */
+function collectNormalDayContributionsReconciled(date, allRules, monthFilteredManualRules, ctx, periods, holidays, events) {
+    const contributions = [];
+    const operating = computeActiveRules(date, allRules, periods, holidays, { events });
+    const operatingTimepoints = new Set(operating.timepoints.map(tp => hhmm(tp)));
+    const calendarContributions = collectNormalDayContributions(monthFilteredManualRules, ctx);
+    const calendarOperatingByTimepoint = new Map();
+    for (const contribution of calendarContributions) {
+        if (contribution.kind === 'base_off') {
+            contributions.push(contribution);
+            continue;
+        }
+        if (contribution.kind === 'operating') {
+            calendarOperatingByTimepoint.set(contribution.timepoint, contribution.rule);
+        }
+    }
+    const emittedOperating = new Set();
+    for (const [timepoint, ownerRule] of calendarOperatingByTimepoint) {
+        if (operatingTimepoints.has(timepoint)) {
+            contributions.push({ kind: 'operating', rule: ownerRule, timepoint });
+            emittedOperating.add(timepoint);
+            continue;
+        }
+        const excludeRule = findDisplacementExcludeRule(date, timepoint, allRules, operating.appliedRuleIds);
+        if (!excludeRule)
+            continue;
+        contributions.push({ excludeRule, kind: 'base_off', rule: ownerRule, timepoint });
+    }
+    const rulesById = new Map(allRules.map(rule => [rule._id, rule]));
+    for (const timepoint of operatingTimepoints) {
+        if (emittedOperating.has(timepoint))
+            continue;
+        const ownerRule = operating.appliedRuleIds
+            .map(id => rulesById.get(id))
+            .find((rule) => !!rule
+            && rule.kind === 'manual'
+            && rule.operating_mode === 'include'
+            && (rule.timepoints ?? []).includes(timepoint));
+        if (ownerRule) {
+            contributions.push({ kind: 'operating', rule: ownerRule, timepoint });
+        }
+    }
+    return contributions;
+}
+/**
+ * Replacement days: bind GTFS tokens using {@link computeActiveRules} as operating truth.
+ *
+ * **Forced retarget** — operating TPs on the replacement rule (+ `base_off` on calendar base owners);
+ * calendar-only TPs get `base_off` when absent from the operating set (FR-02, FR-03).
+ * Skips the replacement row when calendar manuals already cover the full operating set (FR-04).
+ *
+ * **Same_weekday** — `operating` rows on calendar manual owners (ND-03), one row per timepoint.
+ */
+function collectReplacementDayContributions(date, replacement, allRules, monthFilteredManualRules, periods, holidays, events) {
+    const contributions = [];
+    const effectiveReplacement = resolveEffectiveReplacement(date, replacement, holidays);
+    const operating = computeActiveRules(date, allRules, periods, holidays, { events });
+    const operatingTimepoints = new Set(operating.timepoints.map(tp => hhmm(tp)));
+    const replacementAsRule = allRules.find(r => r._id === replacement._id) ?? replacement;
+    const forcedRetarget = isForcedRetargetDay(date, effectiveReplacement, holidays);
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const calendarCtx = {
+        weekday: calendarWeekday(key, holidays),
+        yearPeriodId: getActivePeriodId(date, periods),
+    };
+    const calendarContributions = collectNormalDayContributions(monthFilteredManualRules, calendarCtx);
+    const calendarOperatingByTimepoint = new Map();
+    for (const contribution of calendarContributions) {
+        if (contribution.kind !== 'operating')
+            continue;
+        calendarOperatingByTimepoint.set(contribution.timepoint, contribution.rule);
+    }
+    if (forcedRetarget) {
+        const emitReplacement = shouldEmitReplacementOnForcedRetarget(operatingTimepoints, calendarOperatingByTimepoint);
+        for (const timepoint of operatingTimepoints) {
+            const ownerRule = calendarOperatingByTimepoint.get(timepoint);
+            if (emitReplacement) {
+                contributions.push({ kind: 'operating', rule: replacementAsRule, timepoint });
+                // Shared timepoint (FR-03): replacement runs on the event date; base is OFF, not plain.
+                if (ownerRule) {
+                    contributions.push({
+                        excludeRule: replacementAsRule,
+                        kind: 'base_off',
+                        rule: ownerRule,
+                        timepoint,
+                    });
+                }
+                continue;
+            }
+            if (ownerRule) {
+                contributions.push({ kind: 'operating', rule: ownerRule, timepoint });
+            }
+        }
+        // Weekday-owned timepoints that are not in the replacement operating set (e.g. 06:40
+        // when Carnival runs Saturday times from 06:45) → BASE-OFF-replacement on event dates.
+        for (const [timepoint, ownerRule] of calendarOperatingByTimepoint) {
+            if (operatingTimepoints.has(timepoint))
+                continue;
+            contributions.push({
+                excludeRule: replacementAsRule,
+                kind: 'base_off',
+                rule: ownerRule,
+                timepoint,
+            });
+        }
+    }
+    else {
+        // same_weekday (SW-01): one operating owner per timepoint (ND-03), not every rule that
+        // intersects the replacement — e.g. ALL_DU + ALL_DU-SAB both match but only ALL_DU owns 21:00.
+        for (const timepoint of operatingTimepoints) {
+            let ownerRule = calendarOperatingByTimepoint.get(timepoint);
+            if (!ownerRule) {
+                const candidates = collectReplacementManualIncludesByRule(effectiveReplacement, monthFilteredManualRules)
+                    .filter(({ timepoints }) => timepoints.some(tp => hhmm(tp) === timepoint))
+                    .sort((a, b) => compareGeneralManualOwnershipPriority(a.rule, b.rule));
+                ownerRule = candidates[0]?.rule;
+            }
+            if (ownerRule) {
+                contributions.push({ kind: 'operating', rule: ownerRule, timepoint });
+            }
+        }
+    }
+    return contributions;
+}
+/**
+ * GTFS export attribution for one operational date.
+ *
+ * Unlike {@link computeActiveRules}, which returns the merged operating timepoint set,
+ * this returns per-timepoint contributions so the exporter can attach the correct
+ * `service_id` rows (`operating` and `base_off`).
+ *
+ * **Invariant (P5):** the set of `operating` timepoints should match
+ * `computeActiveRules(date, allRules, periods, holidays, options).timepoints`.
+ *
+ * @see SCENARIOS.md for scenario IDs (FR-*, ND-*, ER-*).
+ *
+ * - Normal days → {@link collectNormalDayContributionsReconciled}
+ * - Replacement days → {@link collectReplacementDayContributions}
+ */
+export function collectGtfsIncludeContributionsForDate(date, allRules, periods, holidays, options) {
+    const manualRules = allRules.filter((r) => r.kind === 'manual');
+    const replacementRules = allRules.filter((r) => r.kind === 'event_replacement');
+    const filteredManualRules = filterManualRulesForDate(manualRules, date, options?.events);
+    const monthFilteredManualRules = filterManualRulesByMonth(filteredManualRules, date);
+    const replacement = findReplacementForDate(date, replacementRules);
+    if (replacement) {
+        return collectReplacementDayContributions(date, replacement, allRules, monthFilteredManualRules, periods, holidays, options?.events);
+    }
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const ctx = {
+        weekday: calendarWeekday(key, holidays),
+        yearPeriodId: getActivePeriodId(date, periods),
+    };
+    return collectNormalDayContributionsReconciled(date, allRules, monthFilteredManualRules, ctx, periods, holidays, options?.events);
+}

package/dist/calendar/rules/export-attribution/replacement.d.ts

@@ -0,0 +1,10 @@
+import type { EventReplacementRule, Holiday, OperationalDate } from '@tmlmobilidade/types';
+/**
+ * Resolves the effective replacement targets for a date, applying same_weekday semantics.
+ */
+export declare function resolveEffectiveReplacement(date: OperationalDate, replacement: EventReplacementRule, holidays: Holiday[]): EventReplacementRule;
+/**
+ * True when the calendar weekday is not among the replacement's target weekdays —
+ * the day is forcibly retargeted (e.g. Tuesday treated as Saturday for Carnival).
+ */
+export declare function isForcedRetargetDay(date: OperationalDate, effectiveReplacement: EventReplacementRule, holidays: Holiday[]): boolean;

package/dist/calendar/rules/export-attribution/replacement.js

@@ -0,0 +1,24 @@
+import { calendarKey, calendarWeekday } from '../../utils/index.js';
+import { Dates } from '../../../dates.js';
+/**
+ * Resolves the effective replacement targets for a date, applying same_weekday semantics.
+ */
+export function resolveEffectiveReplacement(date, replacement, holidays) {
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    if (replacement.same_weekday) {
+        return { ...replacement, weekdays: [calendarWeekday(key, holidays)] };
+    }
+    return replacement;
+}
+/**
+ * True when the calendar weekday is not among the replacement's target weekdays —
+ * the day is forcibly retargeted (e.g. Tuesday treated as Saturday for Carnival).
+ */
+export function isForcedRetargetDay(date, effectiveReplacement, holidays) {
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const calendarDay = calendarWeekday(key, holidays);
+    const targetWeekdays = effectiveReplacement.weekdays ?? [];
+    if (!targetWeekdays.length)
+        return false;
+    return !targetWeekdays.includes(calendarDay);
+}

package/dist/calendar/rules/export-attribution/trip-row-dates.d.ts

@@ -0,0 +1,38 @@
+import type { Event, Holiday, OperationalDate, ScheduleRule, YearPeriod } from '@tmlmobilidade/types';
+export type CanonicalDateCache = Map<string, Set<OperationalDate>>;
+export interface ExcludeScheduleSlice {
+    dates: Set<OperationalDate>;
+    rule: ScheduleRule;
+}
+export interface SplitByExcludeOverlapResult {
+    offOperationalDates: Set<OperationalDate>;
+    overlappingExcludeSchedules: ExcludeScheduleSlice[];
+    plainOperationalDates: Set<OperationalDate>;
+}
+/**
+ * Splits accumulated include dates into plain vs OFF buckets by **per-date** exclude overlap.
+ *
+ * Without this split, a single displacement day (e.g. Santo António, Véspera de Natal) marks the
+ * entire rule×timepoint schedule as OFF and forces canonical expansion for all dates — including
+ * same-weekday replacement days that should stay plain (SW-01, ND-04).
+ */
+export declare function splitOperationalDatesByExcludeOverlap(includeDates: Set<OperationalDate>, includeRuleId: string | undefined, excludeSchedules: ExcludeScheduleSlice[]): SplitByExcludeOverlapResult;
+export declare function resolveCanonicalDatesForRule(rule: ScheduleRule, accumulated: Set<OperationalDate>, cache: CanonicalDateCache, exportDates: readonly OperationalDate[], registryOptions: {
+    events: Event[];
+    holidays: Holiday[];
+    periods: YearPeriod[];
+}): Set<OperationalDate>;
+/**
+ * Resolves calendar membership for an OFF include row (canonical base minus canonical excludes).
+ *
+ * `allIncludeAccumulated` — union of all accumulated dates for this include rule at this
+ * timepoint (plain + off). Canonical expansion of the base rule can include dates the rule
+ * never actually accumulated on — e.g. Easter dates leak into a JUN_U2_SEM OFF row because
+ * Easter is within the same year-period, but the event_replacement redirected the rule away
+ * from that timepoint on Easter. Capping to accumulated dates prevents those phantoms.
+ */
+export declare function computeOffRowDates(includeRule: ScheduleRule, overlappingExcludeSchedules: ExcludeScheduleSlice[], canonicalCache: CanonicalDateCache, exportDates: readonly OperationalDate[], registryOptions: {
+    events: Event[];
+    holidays: Holiday[];
+    periods: YearPeriod[];
+}, offOperationalDates: Set<OperationalDate>, allIncludeAccumulated?: Set<OperationalDate>): Set<OperationalDate>;

package/dist/calendar/rules/export-attribution/trip-row-dates.js

@@ -0,0 +1,71 @@
+import { buildCanonicalRuleDates } from './canonical-registry.js';
+/**
+ * Splits accumulated include dates into plain vs OFF buckets by **per-date** exclude overlap.
+ *
+ * Without this split, a single displacement day (e.g. Santo António, Véspera de Natal) marks the
+ * entire rule×timepoint schedule as OFF and forces canonical expansion for all dates — including
+ * same-weekday replacement days that should stay plain (SW-01, ND-04).
+ */
+export function splitOperationalDatesByExcludeOverlap(includeDates, includeRuleId, excludeSchedules) {
+    const plainOperationalDates = new Set();
+    const offOperationalDates = new Set();
+    const overlappingById = new Map();
+    for (const date of includeDates) {
+        const overlapping = excludeSchedules.filter(ex => ex.rule._id !== includeRuleId && ex.dates.has(date));
+        if (overlapping.length === 0) {
+            plainOperationalDates.add(date);
+            continue;
+        }
+        offOperationalDates.add(date);
+        for (const ex of overlapping) {
+            const id = ex.rule._id ?? '';
+            if (!overlappingById.has(id))
+                overlappingById.set(id, ex);
+        }
+    }
+    return {
+        offOperationalDates,
+        overlappingExcludeSchedules: [...overlappingById.values()],
+        plainOperationalDates,
+    };
+}
+export function resolveCanonicalDatesForRule(rule, accumulated, cache, exportDates, registryOptions) {
+    if (rule.kind !== 'manual' && rule.kind !== 'event_replacement') {
+        return accumulated;
+    }
+    if (!cache.has(rule._id)) {
+        cache.set(rule._id, buildCanonicalRuleDates(rule, exportDates, registryOptions));
+    }
+    const canonical = cache.get(rule._id);
+    return canonical?.size ? canonical : accumulated;
+}
+/**
+ * Resolves calendar membership for an OFF include row (canonical base minus canonical excludes).
+ *
+ * `allIncludeAccumulated` — union of all accumulated dates for this include rule at this
+ * timepoint (plain + off). Canonical expansion of the base rule can include dates the rule
+ * never actually accumulated on — e.g. Easter dates leak into a JUN_U2_SEM OFF row because
+ * Easter is within the same year-period, but the event_replacement redirected the rule away
+ * from that timepoint on Easter. Capping to accumulated dates prevents those phantoms.
+ */
+export function computeOffRowDates(includeRule, overlappingExcludeSchedules, canonicalCache, exportDates, registryOptions, offOperationalDates, allIncludeAccumulated) {
+    // Defensive copy: resolveCanonicalDatesForRule returns the cached Set directly, and we
+    // mutate below. Without a copy, repeated calls for the same rule (different timepoints)
+    // would start from a previously-reduced canonical.
+    const resultingDates = new Set(resolveCanonicalDatesForRule(includeRule, offOperationalDates, canonicalCache, exportDates, registryOptions));
+    for (const excludeSchedule of overlappingExcludeSchedules) {
+        const excludeDates = resolveCanonicalDatesForRule(excludeSchedule.rule, excludeSchedule.dates, canonicalCache, exportDates, registryOptions);
+        for (const excludedDate of excludeDates) {
+            resultingDates.delete(excludedDate);
+        }
+    }
+    // Cap to dates the include rule actually accumulated. Dates in canonical but not accumulated
+    // were redirected away (e.g. by event_replacement) and must not appear in the OFF row.
+    if (allIncludeAccumulated) {
+        for (const date of resultingDates) {
+            if (!allIncludeAccumulated.has(date))
+                resultingDates.delete(date);
+        }
+    }
+    return resultingDates;
+}

package/dist/calendar/rules/export-attribution/types.d.ts

@@ -0,0 +1,17 @@
+import type { HHMM, ScheduleRule } from '@tmlmobilidade/types';
+/** How a rule binds to a timepoint in GTFS export. */
+export type GtfsIncludeContributionKind = 'base_off' | 'operating';
+/**
+ * One rule × timepoint binding for GTFS `trips.txt` / `calendar_dates.txt`.
+ *
+ * - `operating` — active include row for `rule` on `timepoint`.
+ * - `base_off` — `rule` stays in the calendar definition but is off on this date;
+ *   `excludeRule` is what displaces it (event manual or replacement).
+ */
+export interface GtfsIncludeContribution {
+    /** Present when `kind` is `base_off`: the rule that displaces `rule`. */
+    excludeRule?: ScheduleRule;
+    kind: GtfsIncludeContributionKind;
+    rule: ScheduleRule;
+    timepoint: HHMM;
+}

package/dist/calendar/rules/export-attribution/types.js

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

package/dist/calendar/rules/index.d.ts

@@ -1,5 +1,7 @@
+export * from './calculation/filters.js';
 export * from './calculation/index.js';
 export * from './calculation/types.js';
+export * from './export-attribution/index.js';
 export * from './formatting/parameter-summary.js';
 export * from './formatting/rule-summary.js';
 export * from './formatting/sort.js';

package/dist/calendar/rules/index.js

@@ -1,5 +1,7 @@
+export * from './calculation/filters.js';
 export * from './calculation/index.js';
 export * from './calculation/types.js';
+export * from './export-attribution/index.js';
 export * from './formatting/parameter-summary.js';
 export * from './formatting/rule-summary.js';
 export * from './formatting/sort.js';

package/dist/calendar/rules/merging/index.js

@@ -31,6 +31,7 @@ function buildEventDerivedRestriction(args) {
         lines_to_include: rule.lines_to_include,
         name: rule.name,
         start_time: rule.start_time,
+        timepoints: rule.timepoints,
     };
 }
 function buildEventDerivedReplacement(args) {

package/dist/calendar/rules/preview/computeRuleTimePoints.d.ts

@@ -5,7 +5,7 @@ import type { Event, Holiday, ScheduleRule, YearPeriod } from '@tmlmobilidade/ty
  *
  * - Manual include rules: return their timepoints directly
  * - Manual exclude rules: return their timepoints directly
- * - Event replacement rules: return timepoints that apply on the target weekdays
+ * - Event replacement rules: return operating timepoints on forced-retarget dates only
  * - Event restriction rules: return timepoints that are removed on the affected weekdays
  */
 export declare function computeRuleTimePoints(rule: ScheduleRule, allRules: ScheduleRule[], periods: YearPeriod[], holidays: Holiday[], options?: {

package/dist/calendar/rules/preview/computeRuleTimePoints.js

@@ -1,6 +1,7 @@
 import { calendarKey, calendarWeekday } from '../../utils/index.js';
 import { Dates } from '../../../dates.js';
 import { computeActiveRules } from '../calculation/index.js';
+import { isForcedRetargetDay, resolveEffectiveReplacement } from '../export-attribution/replacement.js';
 import { buildOperationalDateRange } from '../utils/date.js';
 // USED IN RulesScheduleView
 /**
@@ -9,7 +10,7 @@ import { buildOperationalDateRange } from '../utils/date.js';
  *
  * - Manual include rules: return their timepoints directly
  * - Manual exclude rules: return their timepoints directly
- * - Event replacement rules: return timepoints that apply on the target weekdays
+ * - Event replacement rules: return operating timepoints on forced-retarget dates only
  * - Event restriction rules: return timepoints that are removed on the affected weekdays
  */
 export function computeRuleTimePoints(rule, allRules, periods, holidays, options) {
@@ -32,21 +33,19 @@ export function computeRuleTimePoints(rule, allRules, periods, holidays, options
         const key = calendarKey(Dates.fromOperationalDate(opDate, 'Europe/Lisbon'));
         affectedWeekdays.add(calendarWeekday(key, holidays));
     }
-    // For replacement rules: return timepoints from the TARGET weekdays
+    // For replacement rules: operating schedule on dates forcibly retargeted (e.g. Tue → Sat)
     if (rule.kind === 'event_replacement') {
-        const addedTimepoints = new Set();
+        const labelTimepoints = new Set();
         for (const date of rule.dates ?? []) {
-            const withRule = computeActiveRules(date, allRules, periods, holidays, options);
-            const withoutRule = computeActiveRules(date, allRules.filter(r => r._id !== rule._id), periods, holidays, options);
-            const withSet = new Set(withRule.timepoints);
-            const withoutSet = new Set(withoutRule.timepoints);
-            for (const tp of withSet) {
-                if (!withoutSet.has(tp)) {
-                    addedTimepoints.add(tp);
-                }
+            const effectiveReplacement = resolveEffectiveReplacement(date, rule, holidays);
+            if (!isForcedRetargetDay(date, effectiveReplacement, holidays))
+                continue;
+            const operating = computeActiveRules(date, allRules, periods, holidays, options);
+            for (const tp of operating.timepoints) {
+                labelTimepoints.add(tp);
             }
         }
-        return addedTimepoints;
+        return labelTimepoints;
     }
     // For restriction rules: compute what was removed on affected weekdays
     // Generate a sample date range to check (1 year from now)

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from './lib/date-format.js';
 export * from './lib/time-slot.js';
 export * from './lib/timezone-identified.js';
 export * from './utils/index.js';
+export * from './vkm.js';

package/dist/index.js

@@ -5,3 +5,4 @@ export * from './lib/date-format.js';
 export * from './lib/time-slot.js';
 export * from './lib/timezone-identified.js';
 export * from './utils/index.js';
+export * from './vkm.js';

package/dist/vkm.d.ts

@@ -0,0 +1,11 @@
+import type { Agency, CalculateVkmDto, Event, Holiday, Pattern, VkmCalculationResult, YearPeriod } from '@tmlmobilidade/types';
+export interface CalculateAgencyVkmArgs {
+    agency: Agency;
+    events: Event[];
+    holidays: Holiday[];
+    patterns: Pattern[];
+    periods: YearPeriod[];
+    request: CalculateVkmDto;
+}
+export declare function getPatternExtensionMeters(pattern: Pattern, source: CalculateVkmDto['extension_source']): number;
+export declare function calculateAgencyVkm({ agency, events, holidays, patterns, periods, request }: CalculateAgencyVkmArgs): VkmCalculationResult;

package/dist/vkm.js

@@ -0,0 +1,177 @@
+import { buildOperationalDateRange } from './calendar/rules/utils/date.js';
+import { calendarWeekday } from './calendar/utils/index.js';
+import { Dates } from './dates.js';
+import { computeActiveRules } from './calendar/rules/calculation/index.js';
+import { resolvePatternRules } from './calendar/rules/merging/index.js';
+const UNASSIGNED_PERIOD_KEY = '__unassigned__';
+const UNASSIGNED_PERIOD_NAME = 'Sem período definido';
+function resolveDayTypeBucket(date, holidays) {
+    const weekday = calendarWeekday(Dates.fromOperationalDate(date, 'Europe/Lisbon'), holidays);
+    if (weekday === 6)
+        return '2';
+    if (weekday === 7)
+        return '3';
+    return '1';
+}
+function sortPeriodsByStartDate(periods) {
+    return [...periods].sort((left, right) => {
+        const leftStart = left.dates?.slice().sort()[0] ?? '99999999';
+        const rightStart = right.dates?.slice().sort()[0] ?? '99999999';
+        return leftStart.localeCompare(rightStart);
+    });
+}
+function createPeriodAccumulator(period, fallbackName = UNASSIGNED_PERIOD_NAME) {
+    return {
+        code: period?.code ?? null,
+        day_type_one: 0,
+        day_type_three: 0,
+        day_type_two: 0,
+        id: period?._id ?? null,
+        name: period?.name ?? fallbackName,
+        total: 0,
+    };
+}
+function createAccumulator(periods) {
+    const periodAccumulators = new Map();
+    for (const period of periods) {
+        periodAccumulators.set(period._id, createPeriodAccumulator(period));
+    }
+    return { day_type_one: 0, day_type_three: 0, day_type_two: 0, periods: periodAccumulators, total_from_distance: 0 };
+}
+function buildPeriodMetadata(operationalDates, periods) {
+    const operationalDateSet = new Set(operationalDates);
+    const periodIdByDate = new Map();
+    const relevantPeriods = [];
+    for (const period of sortPeriodsByStartDate(periods)) {
+        const relevantDates = (period.dates ?? []).filter(date => operationalDateSet.has(date));
+        if (!relevantDates.length)
+            continue;
+        relevantPeriods.push(period);
+        for (const date of relevantDates) {
+            if (!periodIdByDate.has(date))
+                periodIdByDate.set(date, period._id);
+        }
+    }
+    return { periodIdByDate, relevantPeriods };
+}
+function addDistanceToDayType(acc, distanceMeters, dayType) {
+    acc.total += distanceMeters;
+    if (dayType === '1')
+        acc.day_type_one += distanceMeters;
+    if (dayType === '2')
+        acc.day_type_two += distanceMeters;
+    if (dayType === '3')
+        acc.day_type_three += distanceMeters;
+}
+function addToAccumulator(accumulator, distanceMeters, dayType, periodId) {
+    accumulator.total_from_distance += distanceMeters;
+    if (dayType === '1')
+        accumulator.day_type_one += distanceMeters;
+    if (dayType === '2')
+        accumulator.day_type_two += distanceMeters;
+    if (dayType === '3')
+        accumulator.day_type_three += distanceMeters;
+    const key = periodId ?? UNASSIGNED_PERIOD_KEY;
+    const existing = accumulator.periods.get(key);
+    if (existing) {
+        addDistanceToDayType(existing, distanceMeters, dayType);
+        return;
+    }
+    const unassigned = createPeriodAccumulator(null);
+    addDistanceToDayType(unassigned, distanceMeters, dayType);
+    accumulator.periods.set(UNASSIGNED_PERIOD_KEY, unassigned);
+}
+function metersToKilometers(value) {
+    return value / 1000;
+}
+function buildPeriodResults(periods) {
+    return [...periods.entries()]
+        .filter(([key, period]) => key !== UNASSIGNED_PERIOD_KEY || period.total > 0)
+        .map(([, period]) => ({
+        code: period.code,
+        day_type_one: metersToKilometers(period.day_type_one),
+        day_type_three: metersToKilometers(period.day_type_three),
+        day_type_two: metersToKilometers(period.day_type_two),
+        id: period.id,
+        name: period.name,
+        total: metersToKilometers(period.total),
+    }));
+}
+function buildDayMetadata(operationalDates, holidays, periods) {
+    const { periodIdByDate, relevantPeriods } = buildPeriodMetadata(operationalDates, periods);
+    const metadataByDate = new Map();
+    for (const date of operationalDates) {
+        metadataByDate.set(date, {
+            dayType: resolveDayTypeBucket(date, holidays),
+            periodId: periodIdByDate.get(date) ?? null,
+        });
+    }
+    return { metadataByDate, relevantPeriods };
+}
+function resolveCalculationEndDate(request) {
+    const startDate = Dates.fromOperationalDate(request.start_date, 'Europe/Lisbon');
+    const endDate = request.calculation_method === 'rolling_year'
+        ? startDate.plus({ years: 1 })
+        : Dates.fromOperationalDate(request.end_date ?? request.start_date, 'Europe/Lisbon');
+    return { endDate, startDate };
+}
+function buildCalculationContext(request, holidays, periods) {
+    const { endDate, startDate } = resolveCalculationEndDate(request);
+    const operationalDates = buildOperationalDateRange(startDate.js_date, endDate.js_date);
+    const { metadataByDate, relevantPeriods } = buildDayMetadata(operationalDates, holidays, periods);
+    return { endDate, metadataByDate, operationalDates, relevantPeriods };
+}
+function buildCalculationInputs(agency, request, endDate) {
+    const totalVkmPerYear = agency.financials.vkm_per_month.reduce((sum, value) => sum + Number(value ?? 0), 0);
+    const pricePerKm = Number(agency.financials.price_per_km ?? 0);
+    return {
+        agency_id: agency._id,
+        agency_name: agency.name,
+        calculation_method: request.calculation_method,
+        end_date: endDate.operational_date,
+        price_per_km: pricePerKm,
+        start_date: request.start_date,
+        total_vkm_per_year: totalVkmPerYear,
+    };
+}
+export function getPatternExtensionMeters(pattern, source) {
+    if (source === 'stop_times') {
+        return (pattern.path ?? []).reduce((total, item) => total + Number(item.distance_delta ?? 0), 0);
+    }
+    return Number(pattern.shape?.extension ?? 0);
+}
+export function calculateAgencyVkm({ agency, events, holidays, patterns, periods, request }) {
+    const { endDate, metadataByDate, operationalDates, relevantPeriods } = buildCalculationContext(request, holidays, periods);
+    const accumulator = createAccumulator(relevantPeriods);
+    for (const pattern of patterns) {
+        const extensionMeters = getPatternExtensionMeters(pattern, request.extension_source);
+        if (!extensionMeters)
+            continue;
+        const mergedRules = resolvePatternRules(pattern, events);
+        if (!mergedRules.length)
+            continue;
+        for (const date of operationalDates) {
+            const activeRules = computeActiveRules(date, mergedRules, periods, holidays, { events });
+            const activeTripCount = activeRules.timepoints.length;
+            if (!activeTripCount)
+                continue;
+            const dayMetadata = metadataByDate.get(date);
+            if (!dayMetadata)
+                continue;
+            addToAccumulator(accumulator, extensionMeters * activeTripCount, dayMetadata.dayType, dayMetadata.periodId);
+        }
+    }
+    const totalDistanceKm = metersToKilometers(accumulator.total_from_distance);
+    const inputs = buildCalculationInputs(agency, request, endDate);
+    return {
+        day_type_one: metersToKilometers(accumulator.day_type_one),
+        day_type_three: metersToKilometers(accumulator.day_type_three),
+        day_type_two: metersToKilometers(accumulator.day_type_two),
+        inputs,
+        periods: buildPeriodResults(accumulator.periods),
+        total_from_distance: totalDistanceKm,
+        total_from_shape: 0,
+        total_in_euros: totalDistanceKm * inputs.price_per_km,
+        total_relative_to_contract: inputs.total_vkm_per_year ? totalDistanceKm / inputs.total_vkm_per_year : 0,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/dates",
-	"version": "20260612.214.31",
+	"version": "20260612.1126.8",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"
@@ -30,10 +30,11 @@
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"scripts": {
-		"build": "tsc && resolve-tspaths",
-		"lint": "eslint ./src/ && tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json && resolve-tspaths -p tsconfig.build.json",
+		"lint": "eslint ./src/ ./tests/ && tsc --noEmit",
 		"lint:fix": "eslint ./src/ --fix",
-		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+		"test": "tsx --test tests/*.test.ts",
+		"watch": "tsc-watch -p tsconfig.build.json --onSuccess 'resolve-tspaths -p tsconfig.build.json'"
 	},
 	"dependencies": {
 		"@tmlmobilidade/types": "*",
@@ -45,6 +46,7 @@
 		"@types/node": "25.9.3",
 		"resolve-tspaths": "0.8.23",
 		"tsc-watch": "7.2.0",
+		"tsx": "4.22.3",
 		"typescript": "6.0.3"
 	}
 }