@nathanvale/chatline 0.0.1

package/dist/ingest/link-replies-and-tapbacks.js

@@ -0,0 +1,381 @@
+/**
+ * Reply and tapback linking for NORMALIZE--T03
+ *
+ * Implements:
+ * AC01: Link replies using DB association_guid as primary method
+ * AC02: Apply heuristics for unlinked replies (timestamp proximity <30s, content patterns)
+ * AC03: Link tapbacks to parent message GUIDs (including part GUIDs)
+ * AC04: Handle ambiguous links with structured logging and tie counters
+ * AC05: Maintain parity with CSV linking rules from original analyzer
+ */
+const REPLY_WINDOW_SECONDS = 30; // AC02: <30s proximity threshold
+const REPLY_SEARCH_WINDOW_MINUTES = 5; // Expand to ±5 minutes if needed
+const TAPBACK_WINDOW_SECONDS = 30; // Tapbacks within 30s of parent
+/**
+ * AC01 + AC02: Link replies to their parent messages
+ *
+ * Primary: DB association_guid when present
+ * Fallback: Heuristics using timestamp and content matching
+ */
+export function linkRepliesToParents(messages, options = {}) {
+    const { trackAmbiguous = false, minConfidenceThreshold: _minConfidenceThreshold = 0.7, } = options;
+    // Build indices for fast lookup
+    const byGuid = new Map();
+    const byTimestamp = new Map();
+    messages.forEach((msg) => {
+        byGuid.set(msg.guid, msg);
+        // Use minute-based buckets for O(1) lookup in time window searches
+        const minuteBucket = new Date(msg.date).toISOString().slice(0, 16); // YYYY-MM-DDTHH:mm
+        if (!byTimestamp.has(minuteBucket)) {
+            byTimestamp.set(minuteBucket, []);
+        }
+        byTimestamp.get(minuteBucket).push(msg);
+    });
+    const ambiguousLinks = [];
+    const result = messages.map((msg) => {
+        // Only process text and media replies (not already linked)
+        if (msg.messageKind !== 'text' && msg.messageKind !== 'media') {
+            return msg;
+        }
+        // Skip if already has DB association
+        if (msg.replyingTo?.targetMessageGuid) {
+            return msg;
+        }
+        // Skip empty replies
+        if (!msg.text || msg.text.trim().length === 0) {
+            return msg;
+        }
+        // Try to link using heuristics
+        const candidates = findReplyParentCandidates(msg, messages, byGuid, byTimestamp);
+        if (candidates.length === 0) {
+            return msg;
+        }
+        // Sort by score (descending)
+        candidates.sort((a, b) => b.score - a.score);
+        const topCandidate = candidates[0];
+        if (!topCandidate) {
+            return msg; // Should never happen since we checked length > 0
+        }
+        const topScore = topCandidate.score;
+        // Check for ties
+        const tiedCandidates = candidates.filter((c) => c.score === topScore);
+        const isTie = tiedCandidates.length > 1;
+        if (isTie && trackAmbiguous) {
+            const firstTied = tiedCandidates[0];
+            if (firstTied) {
+                ambiguousLinks.push({
+                    messageGuid: msg.guid,
+                    selectedTarget: firstTied.message.guid,
+                    candidates: tiedCandidates,
+                    tieCount: tiedCandidates.length,
+                    confidenceScore: topScore,
+                });
+            }
+        }
+        // Link to best candidate
+        return {
+            ...msg,
+            replyingTo: {
+                ...msg.replyingTo,
+                targetMessageGuid: topCandidate.message.guid,
+            },
+        };
+    });
+    return trackAmbiguous ? { messages: result, ambiguousLinks } : result;
+}
+/**
+ * AC03: Link tapbacks to their parent messages
+ *
+ * Primary: DB association_guid when present
+ * Fallback: Heuristics preferring media messages
+ */
+export function linkTapbacksToParents(messages, options = {}) {
+    const { trackAmbiguous = false } = options;
+    // Build indices
+    const byGuid = new Map();
+    const byTimestamp = new Map();
+    messages.forEach((msg) => {
+        byGuid.set(msg.guid, msg);
+        // Use minute-based buckets for O(1) lookup in time window searches
+        const minuteBucket = new Date(msg.date).toISOString().slice(0, 16); // YYYY-MM-DDTHH:mm
+        if (!byTimestamp.has(minuteBucket)) {
+            byTimestamp.set(minuteBucket, []);
+        }
+        byTimestamp.get(minuteBucket).push(msg);
+    });
+    const ambiguousLinks = [];
+    const result = messages.map((msg) => {
+        // Only process tapback messages
+        if (msg.messageKind !== 'tapback') {
+            return msg;
+        }
+        // Skip if already has DB association
+        if (msg.tapback?.targetMessageGuid) {
+            return msg;
+        }
+        // Find parent for this tapback
+        const candidates = findTapbackParentCandidates(msg, messages, byGuid, byTimestamp);
+        if (candidates.length === 0) {
+            return msg;
+        }
+        // Sort by score
+        candidates.sort((a, b) => b.score - a.score);
+        const topCandidate = candidates[0];
+        if (!topCandidate) {
+            return msg; // Should never happen since we checked length > 0
+        }
+        const topScore = topCandidate.score;
+        // Check for ties
+        const tiedCandidates = candidates.filter((c) => c.score === topScore);
+        if (tiedCandidates.length > 1 && trackAmbiguous) {
+            const firstTied = tiedCandidates[0];
+            if (firstTied) {
+                ambiguousLinks.push({
+                    messageGuid: msg.guid,
+                    selectedTarget: firstTied.message.guid,
+                    candidates: tiedCandidates,
+                    tieCount: tiedCandidates.length,
+                    confidenceScore: topScore,
+                });
+            }
+        }
+        // Link to best candidate
+        if (!msg.tapback) {
+            return msg; // Shouldn't happen for tapback messages
+        }
+        return {
+            ...msg,
+            tapback: {
+                ...msg.tapback,
+                targetMessageGuid: topCandidate.message.guid,
+            },
+        };
+    });
+    return trackAmbiguous ? { messages: result, ambiguousLinks } : result;
+}
+/**
+ * AC04: Detect and report ambiguous links with confidence scores
+ */
+export function detectAmbiguousLinks(messages) {
+    const ambiguous = linkRepliesToParents(messages, {
+        trackAmbiguous: true,
+    });
+    const tapbackAmbiguous = linkTapbacksToParents(messages, {
+        trackAmbiguous: true,
+    });
+    const allAmbiguous = [
+        ...(ambiguous.ambiguousLinks || []),
+        ...(tapbackAmbiguous.ambiguousLinks || []),
+    ];
+    return {
+        tieCount: allAmbiguous.length,
+        ambiguousMessages: allAmbiguous.map((link) => ({
+            messageGuid: link.messageGuid,
+            selectedTarget: link.selectedTarget,
+            tieCount: link.tieCount,
+            topCandidates: link.candidates.map((c) => ({
+                guid: c.message.guid,
+                score: c.score,
+                reasons: c.reasons,
+            })),
+        })),
+    };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Get time bucket keys for a date within a window (for O(1) lookups)
+ */
+function getTimeBucketKeys(date, windowMinutes) {
+    const keys = [];
+    const baseTime = date.getTime();
+    // Generate bucket keys for the window before the date
+    for (let i = 0; i <= windowMinutes; i++) {
+        const bucketDate = new Date(baseTime - i * 60 * 1000);
+        keys.push(bucketDate.toISOString().slice(0, 16)); // YYYY-MM-DDTHH:mm (minute bucket)
+    }
+    return keys;
+}
+/**
+ * Find candidate parent messages for a reply
+ * Returns scored candidates
+ * Uses byTimestamp Map for O(1) bucket lookups instead of O(n) scan
+ */
+function findReplyParentCandidates(reply, _allMessages, _byGuid, byTimestamp) {
+    const replyDate = new Date(reply.date);
+    const replyTime = replyDate.getTime();
+    const candidates = [];
+    // Use replyTime for arithmetic operations (replyDate is Date object)
+    // Extract snippet from reply if present (CSV pattern: "➜ Replying to: \"<snippet>\"")
+    const snippetMatch = reply.text?.match(/(?:➜\s*Replying to:?\s+[«"]([^»"]+)[»"]|Replying to:?\s+[«"]([^»"]+)[»"])/);
+    const snippet = snippetMatch?.[1] || snippetMatch?.[2];
+    // Use time-bucketed lookup for O(1) average case per bucket
+    const bucketKeys = getTimeBucketKeys(replyDate, REPLY_SEARCH_WINDOW_MINUTES);
+    const seenGuids = new Set();
+    const potentialParents = [];
+    for (const key of bucketKeys) {
+        const bucketMessages = byTimestamp.get(key);
+        if (bucketMessages) {
+            for (const msg of bucketMessages) {
+                if (!seenGuids.has(msg.guid) &&
+                    msg.messageKind !== 'tapback' &&
+                    msg.messageKind !== 'notification' &&
+                    msg.guid !== reply.guid) {
+                    seenGuids.add(msg.guid);
+                    potentialParents.push(msg);
+                }
+            }
+        }
+    }
+    // Score each candidate
+    for (const candidate of potentialParents) {
+        if (!candidate.text && candidate.messageKind !== 'media') {
+            continue; // Skip messages without text or media
+        }
+        const candidateTime = new Date(candidate.date).getTime();
+        const timeDeltaMs = replyTime - candidateTime;
+        const timeDeltaSeconds = timeDeltaMs / 1000;
+        // Skip if too old (not within search window)
+        if (timeDeltaSeconds < 0 ||
+            timeDeltaSeconds > REPLY_SEARCH_WINDOW_MINUTES * 60) {
+            continue;
+        }
+        let score = 0;
+        const reasons = [];
+        // AC02: Timestamp proximity scoring
+        if (timeDeltaSeconds <= REPLY_WINDOW_SECONDS) {
+            score += 20;
+            reasons.push(`exact_second_match (Δ${timeDeltaSeconds.toFixed(1)}s)`);
+        }
+        // Snippet matching (AC05: CSV parity)
+        let hasContentMatch = false;
+        if (snippet && candidate.text) {
+            const normalizedText = candidate.text.toLowerCase();
+            const normalizedSnippet = snippet.toLowerCase();
+            if (normalizedText.startsWith(normalizedSnippet)) {
+                score += 100;
+                reasons.push('snippet_startswith');
+                hasContentMatch = true;
+            }
+            else if (normalizedText.includes(normalizedSnippet)) {
+                score += 50;
+                reasons.push('snippet_includes');
+                hasContentMatch = true;
+            }
+        }
+        // Media-implied replies (AC05: CSV parity)
+        if (candidate.messageKind === 'media') {
+            if (!snippet ||
+                reply.text?.toLowerCase().includes('photo') ||
+                reply.text?.toLowerCase().includes('image')) {
+                score += 80;
+                reasons.push('media_candidate');
+                hasContentMatch = true;
+                // Prefer lower timestamp_index (earlier part)
+                const indexMatch = candidate.guid.match(/p:(\d+)\//);
+                if (indexMatch?.[1]) {
+                    score += 10 - Number.parseInt(indexMatch[1], 10);
+                    reasons.push(`index_preference(${indexMatch[1]})`);
+                }
+            }
+        }
+        // Only extend beyond 30s window if there's strong content evidence
+        if (timeDeltaSeconds > REPLY_WINDOW_SECONDS && hasContentMatch) {
+            score -= timeDeltaSeconds / 100; // Mild penalty for distance
+            reasons.push(`extended_window (Δ${timeDeltaSeconds.toFixed(1)}s)`);
+        }
+        // Same sender preference
+        if (reply.handle && candidate.handle === reply.handle) {
+            score += 15;
+            reasons.push('same_sender');
+        }
+        // Same group/moment preference
+        if (reply.groupGuid && candidate.groupGuid === reply.groupGuid) {
+            score += 10;
+            reasons.push('same_group');
+        }
+        if (score > 0) {
+            candidates.push({ message: candidate, score, reasons });
+        }
+    }
+    // Sort all candidates: first by score (desc), then by time proximity (asc) for tiebreaking
+    candidates.sort((a, b) => {
+        // Primary: score (higher is better)
+        if (a.score !== b.score) {
+            return b.score - a.score;
+        }
+        // Tiebreaker: nearest prior message (lowest time delta)
+        const aDelta = replyTime - new Date(a.message.date).getTime();
+        const bDelta = replyTime - new Date(b.message.date).getTime();
+        return aDelta - bDelta;
+    });
+    return candidates;
+}
+/**
+ * Find candidate parent messages for a tapback
+ * Prefers media messages
+ * Uses byTimestamp Map for O(1) bucket lookups instead of O(n) scan
+ */
+function findTapbackParentCandidates(tapback, _allMessages, _byGuid, byTimestamp) {
+    const tapbackDate = new Date(tapback.date);
+    const tapbackTime = tapbackDate.getTime();
+    const candidates = [];
+    // Use time-bucketed lookup for O(1) average case per bucket
+    const bucketKeys = getTimeBucketKeys(tapbackDate, REPLY_SEARCH_WINDOW_MINUTES);
+    const seenGuids = new Set();
+    const potentialParents = [];
+    for (const key of bucketKeys) {
+        const bucketMessages = byTimestamp.get(key);
+        if (bucketMessages) {
+            for (const msg of bucketMessages) {
+                if (!seenGuids.has(msg.guid) &&
+                    msg.messageKind !== 'tapback' &&
+                    msg.messageKind !== 'notification' &&
+                    msg.guid !== tapback.guid) {
+                    seenGuids.add(msg.guid);
+                    potentialParents.push(msg);
+                }
+            }
+        }
+    }
+    // Score each candidate
+    for (const candidate of potentialParents) {
+        const candidateTime = new Date(candidate.date).getTime();
+        const timeDeltaSeconds = (tapbackTime - candidateTime) / 1000;
+        // Skip if too old or in future
+        if (timeDeltaSeconds < 0 ||
+            timeDeltaSeconds > REPLY_SEARCH_WINDOW_MINUTES * 60) {
+            continue;
+        }
+        let score = 0;
+        const reasons = [];
+        // Timestamp proximity
+        if (timeDeltaSeconds <= TAPBACK_WINDOW_SECONDS) {
+            score += 20;
+            reasons.push(`near_tap (Δ${timeDeltaSeconds.toFixed(1)}s)`);
+        }
+        else {
+            score -= timeDeltaSeconds;
+        }
+        // Media messages score higher (AC03: preferred targets)
+        if (candidate.messageKind === 'media') {
+            score += 80;
+            reasons.push('is_media');
+        }
+        else if (candidate.messageKind === 'text') {
+            score += 20;
+            reasons.push('is_text');
+        }
+        // Same group preference
+        if (tapback.groupGuid && candidate.groupGuid === tapback.groupGuid) {
+            score += 10;
+            reasons.push('same_group');
+        }
+        if (score > 0) {
+            candidates.push({ message: candidate, score, reasons });
+        }
+    }
+    return candidates;
+}
+//# sourceMappingURL=link-replies-and-tapbacks.js.map

package/dist/ingest/link-replies-and-tapbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-replies-and-tapbacks.js","sourceRoot":"","sources":["../../src/ingest/link-replies-and-tapbacks.ts"],"names":[],"mappings":"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"}

package/dist/normalize/date-converters.d.ts

@@ -0,0 +1,45 @@
+/**
+ * AC02: Convert Apple epoch (seconds since 2001-01-01 UTC) to ISO 8601 UTC string
+ * @param appleEpochSeconds - Seconds since 2001-01-01 00:00:00 UTC (may have fractional part)
+ * @returns ISO 8601 UTC string with Z suffix (e.g., "2001-01-01T00:00:00.000Z")
+ */
+export declare function convertAppleEpochToUTC(appleEpochSeconds: number): string;
+/**
+ * AC01 & AC03: Normalize CSV UTC timestamp to ISO 8601 with Z suffix
+ * Preserves timezone information and ensures consistent format
+ * @param csvDate - CSV timestamp (typically already UTC with Z suffix)
+ * @returns Normalized ISO 8601 UTC string with Z suffix
+ */
+export declare function normalizeCSVDate(csvDate: string): string;
+/**
+ * AC01: Validate date format is ISO 8601 UTC with Z suffix
+ * Strict validation rejects malformed dates and non-UTC timezones
+ * @param dateString - Date string to validate
+ * @returns Object with valid flag and optional error message
+ */
+export declare function validateDateFormat(dateString: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * AC04: Detect timezone drift between two timestamps
+ * Returns true if timestamps differ by more than a reasonable margin
+ * @param original - Original timestamp
+ * @param converted - Converted/processed timestamp
+ * @returns true if drift detected (timestamps differ significantly)
+ */
+export declare function detectTimezoneDrift(original: string, converted: string): boolean;
+/**
+ * AC04: End-to-end round-trip validation
+ * Validates that a date can be parsed, normalized, and validated without drift
+ * @param dateString - Input date string
+ * @returns Validation result with drift detection
+ */
+export declare function roundTripDateValidation(dateString: string): {
+    valid: boolean;
+    driftDetected: boolean;
+    input: string;
+    normalized: string;
+    error?: string;
+};
+//# sourceMappingURL=date-converters.d.ts.map

package/dist/normalize/date-converters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-converters.d.ts","sourceRoot":"","sources":["../../src/normalize/date-converters.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAOxE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG;IACvD,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACd,CAoEA;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GACf,OAAO,CAST;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG;IAC5D,KAAK,EAAE,OAAO,CAAA;IACd,aAAa,EAAE,OAAO,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd,CAwDA"}

package/dist/normalize/date-converters.js

@@ -0,0 +1,166 @@
+// src/normalize/date-converters.ts
+// Apple epoch and CSV UTC converters with end-to-end validation
+// Spec §13: Dates & Timezones, Risks & Mitigations
+/**
+ * Apple epoch constant: seconds since 2001-01-01 00:00:00 UTC
+ * Used by macOS for timestamps
+ */
+const APPLE_EPOCH_SECONDS = 978_307_200;
+/**
+ * AC02: Convert Apple epoch (seconds since 2001-01-01 UTC) to ISO 8601 UTC string
+ * @param appleEpochSeconds - Seconds since 2001-01-01 00:00:00 UTC (may have fractional part)
+ * @returns ISO 8601 UTC string with Z suffix (e.g., "2001-01-01T00:00:00.000Z")
+ */
+export function convertAppleEpochToUTC(appleEpochSeconds) {
+    // Convert Apple epoch seconds to Unix epoch milliseconds
+    const unixMs = (appleEpochSeconds + APPLE_EPOCH_SECONDS) * 1000;
+    // Create date and convert to ISO 8601 UTC
+    const date = new Date(unixMs);
+    return date.toISOString();
+}
+/**
+ * AC01 & AC03: Normalize CSV UTC timestamp to ISO 8601 with Z suffix
+ * Preserves timezone information and ensures consistent format
+ * @param csvDate - CSV timestamp (typically already UTC with Z suffix)
+ * @returns Normalized ISO 8601 UTC string with Z suffix
+ */
+export function normalizeCSVDate(csvDate) {
+    // Parse the CSV date string
+    const date = new Date(csvDate);
+    // Check if parse was successful
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`Invalid CSV date format: ${csvDate}`);
+    }
+    // Return ISO 8601 UTC string with Z suffix
+    return date.toISOString();
+}
+/**
+ * AC01: Validate date format is ISO 8601 UTC with Z suffix
+ * Strict validation rejects malformed dates and non-UTC timezones
+ * @param dateString - Date string to validate
+ * @returns Object with valid flag and optional error message
+ */
+export function validateDateFormat(dateString) {
+    // Check if empty or whitespace
+    if (!dateString || typeof dateString !== 'string' || !dateString.trim()) {
+        return { valid: false, error: 'Date string is empty or whitespace' };
+    }
+    // Check for Z suffix
+    if (!dateString.endsWith('Z')) {
+        return { valid: false, error: 'Date must end with Z suffix (UTC)' };
+    }
+    // Check for timezone offset (should not be present)
+    if (dateString.includes('+') || dateString.match(/-\d{2}:\d{2}$/)) {
+        return { valid: false, error: 'Date must be UTC only (no timezone offset)' };
+    }
+    // ISO 8601 requires T separator, not space
+    if (dateString.includes(' ')) {
+        return {
+            valid: false,
+            error: 'Date must use T separator (ISO 8601), not space',
+        };
+    }
+    // Strict ISO 8601 format check: YYYY-MM-DDTHH:mm:ss.sssZ
+    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+    if (!iso8601Regex.test(dateString)) {
+        return {
+            valid: false,
+            error: 'Date must match ISO 8601 format (YYYY-MM-DDTHH:mm:ss[.sss]Z)',
+        };
+    }
+    // Attempt to parse
+    const date = new Date(dateString);
+    if (Number.isNaN(date.getTime())) {
+        return { valid: false, error: 'Invalid ISO 8601 date format' };
+    }
+    // Validate the date is actually valid (e.g., Feb 29 in non-leap year)
+    // Re-stringify and compare to ensure components match
+    const isoString = date.toISOString();
+    // Extract components from original and reformed
+    const originalParts = dateString.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})/);
+    const reformedParts = isoString.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})/);
+    if (!originalParts || !reformedParts) {
+        return { valid: false, error: 'Failed to parse date components' };
+    }
+    // Check year, month, day, hour, minute, second match
+    // If they don't match, it means the date was invalid (like Feb 30)
+    for (let i = 1; i <= 6; i++) {
+        if (originalParts[i] !== reformedParts[i]) {
+            return {
+                valid: false,
+                error: `Invalid date values: component mismatch at index ${i}`,
+            };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * AC04: Detect timezone drift between two timestamps
+ * Returns true if timestamps differ by more than a reasonable margin
+ * @param original - Original timestamp
+ * @param converted - Converted/processed timestamp
+ * @returns true if drift detected (timestamps differ significantly)
+ */
+export function detectTimezoneDrift(original, converted) {
+    const origTime = new Date(original).getTime();
+    const convTime = new Date(converted).getTime();
+    // Allow 1 second tolerance for rounding/processing differences
+    const toleranceMs = 1000;
+    const diffMs = Math.abs(origTime - convTime);
+    return diffMs > toleranceMs;
+}
+/**
+ * AC04: End-to-end round-trip validation
+ * Validates that a date can be parsed, normalized, and validated without drift
+ * @param dateString - Input date string
+ * @returns Validation result with drift detection
+ */
+export function roundTripDateValidation(dateString) {
+    try {
+        // Step 1: Validate original format
+        const formatValidation = validateDateFormat(dateString);
+        if (!formatValidation.valid) {
+            const result = {
+                valid: false,
+                driftDetected: false,
+                input: dateString,
+                normalized: '',
+            };
+            if (formatValidation.error) {
+                result.error = formatValidation.error;
+            }
+            return result;
+        }
+        // Step 2: Normalize (re-parse to ensure consistent formatting)
+        const normalized = normalizeCSVDate(dateString);
+        // Step 3: Validate normalized format
+        const normalizedValidation = validateDateFormat(normalized);
+        if (!normalizedValidation.valid) {
+            return {
+                valid: false,
+                driftDetected: false,
+                input: dateString,
+                normalized,
+                error: `Normalized date failed validation: ${normalizedValidation.error}`,
+            };
+        }
+        // Step 4: Detect drift
+        const driftDetected = detectTimezoneDrift(dateString, normalized);
+        return {
+            valid: true,
+            driftDetected,
+            input: dateString,
+            normalized,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            driftDetected: false,
+            input: dateString,
+            normalized: '',
+            error: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+//# sourceMappingURL=date-converters.js.map

package/dist/normalize/date-converters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-converters.js","sourceRoot":"","sources":["../../src/normalize/date-converters.ts"],"names":[],"mappings":"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"}