stella-timeline-plugin 2.0.0

package/dist/src/core/runtime_guard.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTimelineReasonerOutput = validateTimelineReasonerOutput;
+const timeline_semantics_1 = require("../lib/timeline_semantics");
+const world_rhythm_1 = require("./world_rhythm");
+function factToParsedEpisode(fact) {
+    return {
+        timestamp: fact.timestamp,
+        location: fact.location,
+        action: fact.action,
+        emotionTags: fact.emotion_tags,
+        appearance: fact.appearance,
+        internalMonologue: fact.internal_monologue,
+        parseLevel: fact.parse_level,
+        confidence: fact.confidence,
+    };
+}
+function isValidGeneratedDraft(draft) {
+    if (!draft)
+        return false;
+    return Boolean((draft.timestamp === undefined || String(draft.timestamp).trim())
+        && String(draft.location || '').trim()
+        && String(draft.action || '').trim()
+        && Array.isArray(draft.emotionTags)
+        && draft.emotionTags.length > 0
+        && String(draft.appearance || '').trim()
+        && String(draft.internalMonologue || '').trim()
+        && Number.isFinite(Number(draft.confidence)));
+}
+function hasStructuredSceneSemantics(draft) {
+    return Boolean(draft.sceneSemantics
+        && (0, timeline_semantics_1.isActivityMode)(draft.sceneSemantics.activityMode)
+        && (0, timeline_semantics_1.isContinuityRelation)(draft.sceneSemantics.continuityRelation)
+        && String(draft.sceneSemantics.rationale || '').trim());
+}
+function hasStructuredAppearanceLogic(draft) {
+    return Boolean(draft.appearanceLogic
+        && (0, timeline_semantics_1.isAppearanceTransition)(draft.appearanceLogic.transition)
+        && (0, timeline_semantics_1.isOutfitMode)(draft.appearanceLogic.outfitMode)
+        && String(draft.appearanceLogic.changeReason || '').trim());
+}
+function hasPersonaConstraints(collector) {
+    return Boolean(collector.persona_context.should_constrain_generation
+        || collector.persona_context.soul.trim()
+        || collector.persona_context.memory.trim()
+        || collector.persona_context.identity.trim());
+}
+function validateTimelineReasonerOutput(collector, reasoner) {
+    if (reasoner.request_id !== collector.request_id) {
+        return {
+            ok: false,
+            outcome: 'blocked',
+            write_allowed: false,
+            block_reason: 'reasoner request_id mismatch',
+        };
+    }
+    if (reasoner.decision.action === 'reuse_existing_fact') {
+        const selectedFact = collector.candidate_facts.find((fact) => fact.fact_id === reasoner.decision.selected_fact_id);
+        if (!selectedFact) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner selected_fact_id not found in collector candidate_facts',
+            };
+        }
+        return {
+            ok: true,
+            outcome: 'reuse_existing_fact',
+            selected_fact: selectedFact,
+            selected_episode: factToParsedEpisode(selectedFact),
+            write_allowed: false,
+        };
+    }
+    if (reasoner.decision.action === 'generate_new_fact') {
+        if (collector.request.mode !== 'allow_generate') {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner requested generation during read_only mode',
+            };
+        }
+        if (!reasoner.decision.should_write_canon) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated a new fact without canon write permission',
+            };
+        }
+        if (!isValidGeneratedDraft(reasoner.generated_fact)) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated_fact payload is invalid',
+            };
+        }
+        if (!hasStructuredSceneSemantics(reasoner.generated_fact)) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated a new fact without structured scene semantics',
+            };
+        }
+        if (!hasStructuredAppearanceLogic(reasoner.generated_fact)) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated a new fact without structured appearance logic',
+            };
+        }
+        if (hasPersonaConstraints(collector) && reasoner.rationale.persona_basis.length === 0) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated a new fact without persona grounding',
+            };
+        }
+        if (hasPersonaConstraints(collector) && reasoner.rationale.constraint_basis.length === 0) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated a new fact without explicit persona constraints',
+            };
+        }
+        if (hasPersonaConstraints(collector) && !String(reasoner.generated_fact.reason || '').trim()) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated a new fact without explaining persona-consistent generation',
+            };
+        }
+        const worldRhythmCheck = (0, world_rhythm_1.validateGeneratedWorldRhythm)(reasoner.generated_fact);
+        if (!worldRhythmCheck.ok) {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: `reasoner generated_fact violates world rhythm: ${worldRhythmCheck.issues.join(' ')}`,
+            };
+        }
+        if (reasoner.generated_fact.appearanceLogic?.transition === 'change_required'
+            && reasoner.generated_fact.appearanceLogic.outfitMode === 'unknown') {
+            return {
+                ok: false,
+                outcome: 'blocked',
+                write_allowed: false,
+                block_reason: 'reasoner generated a required outfit change without a concrete outfit mode',
+            };
+        }
+        return {
+            ok: true,
+            outcome: 'generate_new_fact',
+            generated_fact: reasoner.generated_fact,
+            write_allowed: true,
+        };
+    }
+    return {
+        ok: true,
+        outcome: 'return_empty',
+        write_allowed: false,
+    };
+}

package/dist/src/core/timeline_reasoner_contract.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/core/trace.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeTraceId = makeTraceId;
+exports.buildTrace = buildTrace;
+function makeTraceId() {
+    return `timeline-${Date.now()}-${Math.floor(Math.random() * 100000)}`;
+}
+function buildTrace(input) {
+    return {
+        trace_id: makeTraceId(),
+        ts: new Date().toISOString(),
+        requested_range: input.requested_range,
+        actual_range: input.actual_range,
+        source_order: input.source_order,
+        source_summary: input.source_summary,
+        fingerprint: input.fingerprint,
+        appearance: input.appearance,
+        write: input.write,
+        decision: input.decision,
+        notes: input.notes,
+    };
+}

package/dist/src/core/world_rhythm.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorldRhythmSlot = buildWorldRhythmSlot;
+exports.buildTimelineWorldContext = buildTimelineWorldContext;
+exports.classifyWorldRhythmModes = classifyWorldRhythmModes;
+exports.validateGeneratedWorldRhythm = validateGeneratedWorldRhythm;
+const holidays_1 = require("../lib/holidays");
+const time_utils_1 = require("../lib/time-utils");
+function inferCountryFromOffset(offset) {
+    return offset === '+08:00' ? 'CN' : 'US';
+}
+function inferTimeBand(hour) {
+    if (hour <= 4)
+        return 'late_night';
+    if (hour <= 8)
+        return 'early_morning';
+    if (hour <= 11)
+        return 'morning_work';
+    if (hour <= 13)
+        return 'midday';
+    if (hour <= 16)
+        return 'afternoon';
+    if (hour <= 19)
+        return 'dinner_window';
+    if (hour <= 22)
+        return 'evening';
+    return 'late_evening';
+}
+function describeBand(timeBand, weekday, holidayKey) {
+    const notes = [];
+    const encouraged = new Set();
+    const discouraged = new Set();
+    const addEncouraged = (...modes) => modes.forEach((mode) => encouraged.add(mode));
+    const addDiscouraged = (...modes) => modes.forEach((mode) => discouraged.add(mode));
+    switch (timeBand) {
+        case 'late_night':
+            addEncouraged('sleep', 'rest', 'leisure');
+            addDiscouraged('breakfast', 'lunch', 'dinner', 'errands', 'work_or_study');
+            notes.push('Deep-night slots usually favor sleep, winding down, or very quiet activities.');
+            break;
+        case 'early_morning':
+            addEncouraged('wake_up', 'breakfast', 'commute', 'exercise', 'domestic');
+            addDiscouraged('nightlife');
+            notes.push('Early morning usually fits waking up, breakfast, commuting, or light exercise.');
+            break;
+        case 'morning_work':
+            addEncouraged('work_or_study', 'commute', 'errands');
+            addDiscouraged('sleep', 'nightlife');
+            notes.push('Late morning often fits work, study, focused errands, or commuting.');
+            break;
+        case 'midday':
+            addEncouraged('lunch', 'work_or_study', 'social', 'errands');
+            addDiscouraged('sleep', 'nightlife');
+            notes.push('Midday usually fits lunch, a work break, errands, or a short social moment.');
+            break;
+        case 'afternoon':
+            addEncouraged('work_or_study', 'errands', 'exercise', 'domestic');
+            addDiscouraged('sleep');
+            notes.push('Afternoon often fits work, study, chores, errands, or exercise.');
+            break;
+        case 'dinner_window':
+            addEncouraged('dinner', 'social', 'exercise', 'domestic', 'commute');
+            addDiscouraged('sleep');
+            notes.push('Early evening usually fits dinner, going out, exercise, or returning home.');
+            break;
+        case 'evening':
+            addEncouraged('social', 'leisure', 'domestic', 'rest');
+            addDiscouraged('breakfast');
+            notes.push('Evening often fits leisure, social time, domestic tasks, or gentle decompression.');
+            break;
+        case 'late_evening':
+            addEncouraged('rest', 'sleep', 'leisure');
+            addDiscouraged('breakfast', 'errands');
+            notes.push('Late evening usually fits winding down, resting, or going to sleep.');
+            break;
+    }
+    if (holidayKey) {
+        addEncouraged('social', 'leisure', 'domestic');
+        notes.push(`Public holiday context: ${holidayKey}. Social, family, celebration, travel, or relaxed home activities are more plausible.`);
+    }
+    else if (!weekday) {
+        addEncouraged('social', 'leisure', 'domestic', 'exercise');
+        notes.push('Weekend context: leisure, outings, exercise, social time, or slower domestic routines are especially plausible.');
+    }
+    else if (timeBand === 'morning_work' || timeBand === 'afternoon') {
+        addEncouraged('work_or_study');
+        notes.push('Workday daylight context: work, study, or purposeful errands are especially plausible.');
+    }
+    return {
+        encouraged_modes: [...encouraged],
+        discouraged_modes: [...discouraged],
+        notes,
+    };
+}
+function classifyDateKind(parts) {
+    const calendarDate = (0, time_utils_1.formatDate)(parts);
+    const holidayKey = (0, holidays_1.getHoliday)(calendarDate, inferCountryFromOffset(parts.offset));
+    const weekday = ![0, 6].includes((0, time_utils_1.dayOfWeek)(parts));
+    return {
+        weekday,
+        holiday_key: holidayKey,
+        day_kind: holidayKey ? 'holiday' : weekday ? 'workday' : 'weekend',
+    };
+}
+function buildWorldRhythmSlot(timestamp) {
+    const parts = (0, time_utils_1.parseTimestampParts)(timestamp);
+    if (!parts)
+        return null;
+    const calendarDate = (0, time_utils_1.formatDate)(parts);
+    const dateKind = classifyDateKind(parts);
+    const timeBand = inferTimeBand(parts.hour);
+    const bandDescription = describeBand(timeBand, dateKind.weekday, dateKind.holiday_key);
+    return {
+        timestamp_hint: timestamp,
+        calendar_date: calendarDate,
+        weekday: dateKind.weekday,
+        holiday_key: dateKind.holiday_key,
+        day_kind: dateKind.day_kind,
+        time_band: timeBand,
+        encouraged_modes: bandDescription.encouraged_modes,
+        discouraged_modes: bandDescription.discouraged_modes,
+        notes: bandDescription.notes,
+    };
+}
+function makeDateTimestamp(date, offset) {
+    return `${date}T12:00:00${offset || ''}`;
+}
+function buildTimelineWorldContext(window) {
+    const startParts = (0, time_utils_1.parseTimestampParts)(window.start);
+    const offset = startParts?.offset;
+    return {
+        target: window.target_timestamp_hint ? buildWorldRhythmSlot(window.target_timestamp_hint) : null,
+        range_calendar: window.calendar_dates.map((date) => buildWorldRhythmSlot(makeDateTimestamp(date, offset))).filter(Boolean),
+    };
+}
+function matched(text, patterns) {
+    return patterns.some((pattern) => pattern.test(text));
+}
+function classifyWorldRhythmModes(input) {
+    const text = [input.action || '', input.location || '', input.internalMonologue || ''].join(' ').toLowerCase();
+    const modes = new Set();
+    if (matched(text, [/\b(sleep|sleeping|asleep|bed|nap|napping|woke|wake up)\b/, /睡|睡觉|午睡|醒来|起床|床上/])) {
+        if (matched(text, [/\b(wake|woke|wake up)\b/, /醒来|起床/])) {
+            modes.add('wake_up');
+        }
+        else {
+            modes.add('sleep');
+        }
+    }
+    if (matched(text, [/\b(breakfast|coffee|morning meal)\b/, /早餐|早饭|咖啡/]))
+        modes.add('breakfast');
+    if (matched(text, [/\b(lunch|midday meal)\b/, /午饭|午餐/]))
+        modes.add('lunch');
+    if (matched(text, [/\b(dinner|bbq|supper)\b/, /晚饭|晚餐|烧烤/]))
+        modes.add('dinner');
+    if (matched(text, [/\b(work|working|study|studying|notes|desk|meeting|organizing)\b/, /工作|学习|整理|书房|会议|记录|待办/]))
+        modes.add('work_or_study');
+    if (matched(text, [/\b(commute|subway|bus|train|drive)\b/, /通勤|地铁|公交|开车|路上/]))
+        modes.add('commute');
+    if (matched(text, [/\b(exercise|gym|run|running|basketball|walk)\b/, /运动|健身|跑步|打球|散步/]))
+        modes.add('exercise');
+    if (matched(text, [/\b(friend|friends|party|date|chatting|hang out)\b/, /朋友|聚会|约会|聊天|一起/]))
+        modes.add('social');
+    if (matched(text, [/\b(movie|show|watching|reading|book|game|cafe)\b/, /看剧|电影|看书|书店|咖啡馆|发呆|放松/]))
+        modes.add('leisure');
+    if (matched(text, [/\b(rest|resting|relax|relaxing|quiet|settle)\b/, /休息|放松|安静|缓下来|歇一会/]))
+        modes.add('rest');
+    if (matched(text, [/\b(cooking|laundry|cleaning|home)\b/, /做饭|收拾|家务|在家/]))
+        modes.add('domestic');
+    if (matched(text, [/\b(errand|shopping|bank|grocery)\b/, /买东西|采购|办事|超市/]))
+        modes.add('errands');
+    if (matched(text, [/\b(bar|club|drinks|late-night)\b/, /酒吧|夜店|喝酒|夜生活/]))
+        modes.add('nightlife');
+    return [...modes];
+}
+function hourFromTimestamp(timestamp) {
+    const parts = (0, time_utils_1.parseTimestampParts)(timestamp);
+    return parts ? parts.hour : null;
+}
+function worldModesFromActivityMode(activityMode) {
+    switch (activityMode) {
+        case 'sleep':
+            return ['sleep'];
+        case 'bath':
+            return ['rest', 'domestic'];
+        case 'meal':
+            return [];
+        case 'work_or_study':
+            return ['work_or_study'];
+        case 'commute':
+            return ['commute'];
+        case 'exercise':
+            return ['exercise'];
+        case 'social':
+            return ['social'];
+        case 'shopping':
+            return ['errands', 'social'];
+        case 'leisure':
+            return ['leisure'];
+        case 'domestic':
+            return ['domestic'];
+        case 'errands':
+            return ['errands'];
+        case 'transition':
+            return ['commute'];
+        case 'rest':
+            return ['rest'];
+        default:
+            return [];
+    }
+}
+function validateGeneratedWorldRhythm(draft) {
+    if (!draft.timestamp) {
+        return { ok: true, matched_modes: [], issues: [] };
+    }
+    const slot = buildWorldRhythmSlot(draft.timestamp);
+    if (!slot) {
+        return { ok: true, matched_modes: [], issues: [] };
+    }
+    const semanticModes = draft.sceneSemantics
+        ? worldModesFromActivityMode(draft.sceneSemantics.activityMode)
+        : [];
+    const matchedModes = semanticModes.length > 0
+        ? semanticModes
+        : classifyWorldRhythmModes({
+            action: draft.action,
+            location: draft.location,
+            internalMonologue: draft.internalMonologue,
+        });
+    if (matchedModes.length === 0) {
+        return { ok: true, matched_modes: [], issues: [] };
+    }
+    const hour = hourFromTimestamp(draft.timestamp);
+    const issues = [];
+    if (matchedModes.includes('breakfast') && (hour === null || hour < 5 || hour > 10)) {
+        issues.push('Breakfast-like activity falls outside a plausible breakfast window.');
+    }
+    if (matchedModes.includes('lunch') && (hour === null || hour < 10 || hour > 15)) {
+        issues.push('Lunch-like activity falls outside a plausible lunch window.');
+    }
+    if (matchedModes.includes('dinner') && (hour === null || hour < 16 || hour > 22)) {
+        issues.push('Dinner-like activity falls outside a plausible dinner window.');
+    }
+    if (matchedModes.includes('sleep') && (hour === null || (hour >= 8 && hour < 21))) {
+        issues.push('Sleeping activity falls outside a plausible main sleep window.');
+    }
+    if (matchedModes.includes('work_or_study') && hour !== null && hour <= 4) {
+        issues.push('Work or study activity is implausibly late for a normal real-world routine.');
+    }
+    if (matchedModes.includes('nightlife') && hour !== null && hour < 18) {
+        issues.push('Nightlife activity falls outside a plausible nightlife window.');
+    }
+    return {
+        ok: issues.length === 0,
+        matched_modes: matchedModes,
+        issues,
+    };
+}

package/dist/src/lib/fingerprint.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeFingerprint = computeFingerprint;
+exports.checkReadOnlyHit = checkReadOnlyHit;
+const time_utils_1 = require("./time-utils");
+function normalize(s) {
+    return s.toLowerCase().replace(/[\s\p{P}]/gu, '');
+}
+function toTimeBucket(timestamp) {
+    const parts = (0, time_utils_1.parseTimestampParts)(timestamp);
+    if (parts) {
+        const hours = String(parts.hour).padStart(2, '0');
+        const minutes = parts.minute >= 30 ? '30' : '00';
+        return `${hours}:${minutes}`;
+    }
+    // Try to parse timestamp e.g. "2026-03-22 14:35:00" or other host-local date strings.
+    const dateObj = new Date(timestamp);
+    if (!isNaN(dateObj.getTime())) {
+        const hours = dateObj.getHours().toString().padStart(2, '0');
+        const minutes = dateObj.getMinutes() >= 30 ? '30' : '00';
+        return `${hours}:${minutes}`;
+    }
+    const timeMatch = timestamp.match(/(\d{2}):(\d{2})/);
+    if (!timeMatch) {
+        return 'unknown_time';
+    }
+    const hours = timeMatch[1];
+    const minutes = Number(timeMatch[2]) >= 30 ? '30' : '00';
+    return `${hours}:${minutes}`;
+}
+function computeFingerprint(date, location, action, timestamp) {
+    const bucket = toTimeBucket(timestamp);
+    return `${normalize(date)}|${normalize(location)}|${normalize(action)}|${bucket}`;
+}
+function checkReadOnlyHit(episodes, target) {
+    const targetFingerprint = computeFingerprint(target.date, target.location, target.action, target.timestamp);
+    for (const ep of episodes) {
+        const epDateMatch = ep.timestamp.match(/^(\d{4}-\d{2}-\d{2})/);
+        const epDate = epDateMatch ? epDateMatch[1] : target.date; // Use target date if unable to extract
+        const epFingerprint = computeFingerprint(epDate, ep.location, ep.action, ep.timestamp);
+        if (targetFingerprint === epFingerprint) {
+            return { hit: true, matchedEpisode: ep };
+        }
+    }
+    return { hit: false };
+}

package/dist/src/lib/holidays.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * holidays.ts — Static public holiday lookup (CN + US, 2025–2027).
+ *
+ * Data sourced from Nager.Date API (global public holidays only).
+ * No network requests or file I/O at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHoliday = getHoliday;
+const STATIC_HOLIDAYS = {
+    // ── China 2025 ──────────────────────────────────────────────────
+    "2025-CN": [
+        { date: "2025-01-01", name: "New Year's Day" },
+        { date: "2025-01-29", name: "Chinese New Year (Spring Festival)" },
+        { date: "2025-05-01", name: "Labour Day" },
+        { date: "2025-05-31", name: "Dragon Boat Festival" },
+        { date: "2025-10-01", name: "National Day" },
+        { date: "2025-10-06", name: "Mid-Autumn Festival" },
+    ],
+    // ── China 2026 ──────────────────────────────────────────────────
+    "2026-CN": [
+        { date: "2026-01-01", name: "New Year's Day" },
+        { date: "2026-02-17", name: "Chinese New Year (Spring Festival)" },
+        { date: "2026-05-01", name: "Labour Day" },
+        { date: "2026-06-19", name: "Dragon Boat Festival" },
+        { date: "2026-09-25", name: "Mid-Autumn Festival" },
+        { date: "2026-10-01", name: "National Day" },
+    ],
+    // ── China 2027 ──────────────────────────────────────────────────
+    "2027-CN": [
+        { date: "2027-01-01", name: "New Year's Day" },
+        { date: "2027-02-06", name: "Chinese New Year (Spring Festival)" },
+        { date: "2027-05-01", name: "Labour Day" },
+        { date: "2027-06-09", name: "Dragon Boat Festival" },
+        { date: "2027-09-15", name: "Mid-Autumn Festival" },
+        { date: "2027-10-01", name: "National Day" },
+    ],
+    // ── United States 2025 ──────────────────────────────────────────
+    "2025-US": [
+        { date: "2025-01-01", name: "New Year's Day" },
+        { date: "2025-01-20", name: "Martin Luther King, Jr. Day" },
+        { date: "2025-02-17", name: "Presidents Day" },
+        { date: "2025-05-26", name: "Memorial Day" },
+        { date: "2025-06-19", name: "Juneteenth National Independence Day" },
+        { date: "2025-07-04", name: "Independence Day" },
+        { date: "2025-09-01", name: "Labour Day" },
+        { date: "2025-11-11", name: "Veterans Day" },
+        { date: "2025-11-27", name: "Thanksgiving Day" },
+        { date: "2025-12-25", name: "Christmas Day" },
+    ],
+    // ── United States 2026 ──────────────────────────────────────────
+    "2026-US": [
+        { date: "2026-01-01", name: "New Year's Day" },
+        { date: "2026-01-19", name: "Martin Luther King, Jr. Day" },
+        { date: "2026-02-16", name: "Presidents Day" },
+        { date: "2026-05-25", name: "Memorial Day" },
+        { date: "2026-06-19", name: "Juneteenth National Independence Day" },
+        { date: "2026-07-03", name: "Independence Day" },
+        { date: "2026-09-07", name: "Labour Day" },
+        { date: "2026-11-11", name: "Veterans Day" },
+        { date: "2026-11-26", name: "Thanksgiving Day" },
+        { date: "2026-12-25", name: "Christmas Day" },
+    ],
+    // ── United States 2027 ──────────────────────────────────────────
+    "2027-US": [
+        { date: "2027-01-01", name: "New Year's Day" },
+        { date: "2027-01-18", name: "Martin Luther King, Jr. Day" },
+        { date: "2027-02-15", name: "Presidents Day" },
+        { date: "2027-05-31", name: "Memorial Day" },
+        { date: "2027-06-18", name: "Juneteenth National Independence Day" },
+        { date: "2027-07-05", name: "Independence Day" },
+        { date: "2027-09-06", name: "Labour Day" },
+        { date: "2027-11-11", name: "Veterans Day" },
+        { date: "2027-11-25", name: "Thanksgiving Day" },
+        { date: "2027-12-24", name: "Christmas Day" },
+    ],
+};
+/**
+ * Returns the public holiday name for a given date and country, or null if none.
+ * Supported countries: CN, US (2025–2027).
+ * Falls back to null for unsupported years or countries.
+ */
+function getHoliday(dateStr, countryCode = 'CN') {
+    const dateMatch = dateStr.match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (!dateMatch)
+        return null;
+    const year = dateMatch[1];
+    const targetDate = `${year}-${dateMatch[2]}-${dateMatch[3]}`;
+    const key = `${year}-${countryCode}`;
+    const entries = STATIC_HOLIDAYS[key];
+    if (!entries)
+        return null;
+    const found = entries.find(h => h.date === targetDate);
+    return found ? found.name : null;
+}

package/dist/src/lib/inherit-appearance.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAppearance = resolveAppearance;
+function resolveAppearance(dayEpisodes, defaultAppearance, appearanceLogic) {
+    const latestKnownEpisode = [...dayEpisodes]
+        .reverse()
+        .find((episode) => episode.appearance && episode.appearance !== 'unknown');
+    const latestKnownAppearance = latestKnownEpisode?.appearance;
+    const transition = appearanceLogic?.transition || 'unknown';
+    const outfitMode = appearanceLogic?.outfitMode || 'unknown';
+    const changeReason = appearanceLogic?.changeReason || 'unspecified';
+    if (transition === 'change_required') {
+        return {
+            appearance: defaultAppearance,
+            overridden: true,
+            reason: latestKnownAppearance
+                ? 'explicit appearance transition required by generated scene semantics'
+                : 'explicit appearance transition required and no prior same-day appearance was available',
+            sourceEpisodeTimestamp: latestKnownEpisode?.timestamp,
+            transition,
+            outfitMode,
+            changeReason,
+        };
+    }
+    if (latestKnownAppearance) {
+        return {
+            appearance: latestKnownAppearance,
+            overridden: false,
+            reason: transition === 'change_allowed'
+                ? 'kept the latest known same-day appearance because no forced outfit change was required'
+                : 'inherited from latest known same-day appearance',
+            sourceEpisodeTimestamp: latestKnownEpisode?.timestamp,
+            transition,
+            outfitMode,
+            changeReason,
+        };
+    }
+    return {
+        appearance: defaultAppearance,
+        overridden: true,
+        reason: 'no prior same-day appearance found; kept the LLM-provided appearance',
+        transition,
+        outfitMode,
+        changeReason,
+    };
+}