@tmlmobilidade/dates 20260612.214.31 → 20260612.1446.12

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,41 +1,46 @@
-import type { RuleApplication } from './types.js';
-import type { Event, Holiday, OperationalDate, ScheduleRule, YearPeriod } from '@tmlmobilidade/types';
+import type { DayContext, RuleApplication } from './types.js';
+import type { Event, EventReplacementRule, EventRestrictionRule, Holiday, ManualRule, OperationalDate, ScheduleRule, YearPeriod } from '@tmlmobilidade/types';
+export interface ComputeActiveRulesOptions {
+    dateContext?: ActiveRulesDateContext;
+    eventById?: Map<string, Event>;
+    events?: Event[];
+}
+export interface ActiveRulesDateContext extends DayContext {
+    key: string;
+}
+export interface SplitScheduleRules {
+    manualRules: ManualRule[];
+    replacementRules: EventReplacementRule[];
+    restrictionRules: EventRestrictionRule[];
+}
+export declare function buildActiveRulesEventIndex(events?: Event[]): Map<string, Event>;
+export declare function buildActiveRulesDateContext(date: OperationalDate, periods: YearPeriod[], holidays: Holiday[]): ActiveRulesDateContext;
+export declare function splitScheduleRules(rules: ScheduleRule[]): SplitScheduleRules;
 /**
- * Calculates which time points are active for each date in a range, based on scheduling rules.
- *
- * 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
+ * Operating schedule for one operational date: merged timepoints and applied rule IDs.
  *
- * 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
+ * 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
  *
- * @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
+ * 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
  *
- * @example
- * ```ts
- * const rules = [...]; // Manual, replacement, and restriction rules
- * const dates = ['2026-02-01', '2026-02-02', ...];
- * const periods = [...]; // YearPeriod definitions
+ * 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).
  *
- * 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[];
-}): RuleApplication;
+export declare function computeActiveRules(date: OperationalDate, rules: ScheduleRule[], periods: YearPeriod[], holidays: Holiday[], options?: ComputeActiveRulesOptions): RuleApplication;
+export declare function computeActiveRulesFromSplit(date: OperationalDate, rules: SplitScheduleRules, periods: YearPeriod[], holidays: Holiday[], options?: ComputeActiveRulesOptions): RuleApplication;
+export declare function computeActiveRuleCountFromSplit(date: OperationalDate, rules: SplitScheduleRules, periods: YearPeriod[], holidays: Holiday[], options?: ComputeActiveRulesOptions): number;

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

@@ -1,71 +1,140 @@
 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';
-/* * */
+import { getTimepointsRemovedByEventRestriction } from './filters.js';
+import { manualRuleMatchesContext, manualRuleMatchesReplacement } from './matchers.js';
+export function buildActiveRulesEventIndex(events = []) {
+    return new Map(events.map(event => [event._id, event]));
+}
+export function buildActiveRulesDateContext(date, periods, holidays) {
+    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    return {
+        key,
+        weekday: calendarWeekday(key, holidays),
+        yearPeriodId: getActivePeriodId(date, periods),
+    };
+}
+export function splitScheduleRules(rules) {
+    return {
+        manualRules: rules.filter((r) => r.kind === 'manual'),
+        replacementRules: rules.filter((r) => r.kind === 'event_replacement'),
+        restrictionRules: rules.filter((r) => r.kind === 'event_restriction'),
+    };
+}
+function resolveEventById(id, options) {
+    return options?.eventById?.get(id) ?? options?.events?.find(event => event._id === id);
+}
+function filterManualRulesByEventDate(manualRules, date, options) {
+    return manualRules.filter((rule) => {
+        if (!rule.event_id)
+            return true;
+        const event = resolveEventById(rule.event_id, options);
+        if (!event?.dates?.length)
+            return false;
+        return event.dates.includes(date);
+    });
+}
+function filterManualRulesByMonth(manualRules, month) {
+    return manualRules.filter(rule => !rule.months?.length || rule.months.includes(month));
+}
+function collectManualIncludeTimepoints(manualRules, ctx) {
+    const timepoints = new Set();
+    for (const rule of manualRules) {
+        if (rule.operating_mode !== 'include')
+            continue;
+        if (!manualRuleMatchesContext(rule, ctx))
+            continue;
+        for (const timepoint of rule.timepoints ?? [])
+            timepoints.add(timepoint);
+    }
+    return timepoints;
+}
+function collectReplacementManualIncludeTimepoints(replacement, manualRules) {
+    const timepoints = new Set();
+    for (const rule of manualRules) {
+        if (rule.operating_mode !== 'include')
+            continue;
+        if (!manualRuleMatchesReplacement(rule, replacement))
+            continue;
+        for (const timepoint of rule.timepoints)
+            timepoints.add(timepoint);
+    }
+    return timepoints;
+}
+function applyManualExcludeTimepoints(timepoints, manualRules, ctx) {
+    for (const rule of manualRules) {
+        if (rule.operating_mode !== 'exclude')
+            continue;
+        if (!manualRuleMatchesContext(rule, ctx))
+            continue;
+        for (const timepoint of rule.timepoints ?? [])
+            timepoints.delete(timepoint);
+    }
+}
+function applyReplacementManualExcludeTimepoints(timepoints, replacement, manualRules) {
+    for (const rule of manualRules) {
+        if (rule.operating_mode !== 'exclude')
+            continue;
+        if (!manualRuleMatchesReplacement(rule, replacement))
+            continue;
+        for (const timepoint of rule.timepoints)
+            timepoints.delete(timepoint);
+    }
+}
+function applyEventRestrictionTimepoints(date, timepoints, rules) {
+    for (const rule of rules) {
+        if (!rule.dates?.includes(date))
+            continue;
+        for (const timepoint of getTimepointsRemovedByEventRestriction(rule, timepoints)) {
+            timepoints.delete(timepoint);
+        }
+    }
+}
 /**
- * Calculates which time points are active for each date in a range, based on scheduling rules.
- *
- * 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
+ * Operating schedule for one operational date: merged timepoints and applied rule IDs.
  *
- * 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
+ * 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
  *
- * @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
+ * 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
  *
- * @example
- * ```ts
- * const rules = [...]; // Manual, replacement, and restriction rules
- * const dates = ['2026-02-01', '2026-02-02', ...];
- * const periods = [...]; // YearPeriod definitions
+ * 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).
  *
- * 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');
-    const restrictionRules = rules.filter(r => r.kind === 'event_restriction');
-    const replacementRules = rules.filter((r) => r.kind === 'event_replacement');
-    const filteredManualRules = manualRules.filter((rule) => {
-        if (!rule.event_id)
-            return true;
-        const event = options?.events?.find(e => e._id === rule.event_id);
-        if (!event?.dates?.length)
-            return false;
-        return event.dates.includes(date);
-    });
-    const key = calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const splitRules = splitScheduleRules(rules);
+    return computeActiveRulesFromSplit(date, splitRules, periods, holidays, options);
+}
+export function computeActiveRulesFromSplit(date, rules, periods, holidays, options) {
+    const { manualRules, replacementRules, restrictionRules } = rules;
+    const filteredManualRules = filterManualRulesByEventDate(manualRules, date, options);
+    const key = options?.dateContext?.key ?? calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
     // Filter out manual rules whose months list doesn't include the current month
     const month = Number(key.slice(5, 7));
-    const monthFilteredManualRules = filteredManualRules.filter(rule => !rule.months?.length || rule.months.includes(month));
+    const monthFilteredManualRules = filterManualRulesByMonth(filteredManualRules, month);
     const replacement = findReplacementForDate(date, replacementRules);
     // 1) Base timepoints
     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;
@@ -75,10 +144,7 @@ export function computeActiveRules(date, rules, periods, holidays, options) {
     }
     else {
         // Normal mode: day resolves to a single weekday + single yearPeriodId
-        const ctx = {
-            weekday: calendarWeekday(key, holidays),
-            yearPeriodId: getActivePeriodId(date, periods),
-        };
+        const ctx = options?.dateContext ?? buildActiveRulesDateContext(date, periods, holidays);
         const base = collectManualIncludes(monthFilteredManualRules, ctx);
         timepoints = base.timepoints;
         appliedRuleIds = base.appliedRuleIds;
@@ -92,4 +158,24 @@ export function computeActiveRules(date, rules, periods, holidays, options) {
     };
     return result;
 }
+export function computeActiveRuleCountFromSplit(date, rules, periods, holidays, options) {
+    const filteredManualRules = filterManualRulesByEventDate(rules.manualRules, date, options);
+    const key = options?.dateContext?.key ?? calendarKey(Dates.fromOperationalDate(date, 'Europe/Lisbon'));
+    const month = Number(key.slice(5, 7));
+    const monthFilteredManualRules = filterManualRulesByMonth(filteredManualRules, month);
+    const replacement = findReplacementForDate(date, rules.replacementRules);
+    let timepoints;
+    if (replacement) {
+        const effectiveReplacement = resolveEffectiveReplacement(date, replacement, holidays);
+        timepoints = collectReplacementManualIncludeTimepoints(effectiveReplacement, monthFilteredManualRules);
+        applyReplacementManualExcludeTimepoints(timepoints, effectiveReplacement, monthFilteredManualRules);
+    }
+    else {
+        const ctx = options?.dateContext ?? buildActiveRulesDateContext(date, periods, holidays);
+        timepoints = collectManualIncludeTimepoints(monthFilteredManualRules, ctx);
+        applyManualExcludeTimepoints(timepoints, monthFilteredManualRules, ctx);
+    }
+    applyEventRestrictionTimepoints(date, timepoints, rules.restrictionRules);
+    return timepoints.size;
+}
 /* * */

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[];