@nomadamas/k-skill 0.9.1 → 0.10.0

package/skills/government-bond-analysis/references/methodology.md

@@ -0,0 +1,63 @@
+# 계산·검증 방법론
+
+## 데이터 정의
+
+- 출처: 한국은행 ECOS 통계표 `817Y002` 시장금리(일별)
+- 항목: 국고채 2년 `010195000`, 3년 `010200000`, 5년 `010200001`, 10년 `010210000`, 20년 `010220000`, 30년 `010230000`
+- 정책금리 갭: 한국은행 기준금리 `722Y001/0101000`
+- 단위: 연%
+- 결과의 성격: 공식 일별 통계. 실시간 체결가 또는 개별 지표채 호가가 아니다.
+
+## 날짜 정렬
+
+각 요청일 이전에서 여섯 만기 값이 모두 존재하는 가장 최근 날짜를 공통 관측일로 사용한다. 기본 최대 지연은 주말과 한국 장기 연휴를 포괄하는 7일이며 설정 가능 범위는 0~14일이다. 전일 비교는 달력상 전일이 아니라 최신 공통 관측일 직전의 공통 관측일을 사용한다. 현재와 비교 기준이 같은 공통 관측일로 귀결될 때도 변화 계산을 차단한다.
+
+대시보드는 최신 관측일, 직전 관측일, 7일 전 기준, 직전 월말 기준을 한 번에 계산한다. 분기말은 현재 분기의 직전 분기 말, 연초 대비는 전년도 마지막 공통 관측일을 기준으로 한다. 이벤트 비교는 이벤트 직전 마지막 공통 관측일과 이벤트 당일 또는 이후 첫 공통 관측일을 사용한다. 월 범위의 종료 월이 현재 진행 중이면 종료 기준일을 KST 오늘로 제한하고 최신 공통 관측일을 선택한다.
+
+## 원천 검증
+
+ECOS 응답마다 통계표 `817Y002`, 통계명 `1.3.2.1. 시장금리(일별)`, 항목코드·항목명, 단위 `연%`, 관측일 범위, 전체 건수와 실제 행 수를 확인한다. 원문 SHA-256은 evidence의 원문과 대조하고, 영수증의 건수·최초일·최종일은 정규화 관측치와 다시 대조한다. 캐시는 동일 만기·동일 조회 구간·168시간 이내인 경우에만 사용하며 캐시 봉투와 원문을 별도의 SHA-256으로 검증한다.
+
+사용자 CSV는 `USER_CSV`와 파일명으로 별도 표시한다. ECOS에서 직접 수집하지 않은 입력에 한국은행 공식 원천 링크나 ECOS 통계표 식별자를 부여하지 않는다. 실시간 원자료 검증 후 로컬 캐시 저장만 실패한 경우 정상 관측값을 버리지 않고 결과에 캐시 저장 경고를 남긴다.
+
+## 계산
+
+- 만기별 변화(bp) = `(현재 연% − 비교 연%) × 100`
+- 장단기 스프레드(bp) = `(장기 연% − 단기 연%) × 100`
+- 스프레드 변화(bp) = `현재 스프레드 − 비교 스프레드`
+- 정책금리 갭(bp) = `(국고채 3년 − 한국은행 기준금리) × 100`
+
+기본 구간은 5년−3년, 10년−5년, 10년−3년, 30년−10년이다. 최근 5·20거래일 모드는 만기별 시작·종료, 고점·저점, 순변화와 절대값 기준 최대 일간 변동을 계산한다.
+
+원자료로 계산한 뒤 출력 단계에서 표시 자릿수를 반올림한다.
+
+## 곡선 분류
+
+3년과 10년 변화 방향 및 10년−3년 스프레드 변화로 분류한다. 두 만기가 같은 폭으로 움직이면 평행 상승·하락으로 처리한다. 서로 반대 방향이면 혼합 움직임으로 표시하며 bull/bear 네 유형에 억지로 넣지 않는다.
+
+## 재현성 경계
+
+재현성이 뜻하는 것은 저장된 `evidence.mjson`을 같은 엔진 버전으로 처리했을 때 CSV·Markdown·HTML·상태 파일이 동일한 바이트로 생성된다는 것이다. 향후 ECOS 원자료가 수정되거나 신규 관측치가 추가되어도 새 조회 결과가 과거 실행과 같음을 보장하지 않는다.
+
+주요 일정도 저장된 공식 일정 증거를 재생할 때만 동일하게 나온다. 일정 증거에는 확인한 원문 일부, 원문 날짜 표현, 공식 URL과 확인 UTC를 남긴다. 엔진은 날짜·만기·출처 호스트·입찰표의 Auction Date 위치를 검증하지만, 원문 페이지가 이후 수정되었는지는 재생 시 자동으로 확인하지 않는다. 최신 일정을 말할 때는 공식 원문을 다시 열어 확인한다. 일정 확인 실패는 금리 분석 상태를 변경하지 않으며 `UNVERIFIED`로 표시한다.
+
+## 뉴스 evidence와 시장 배경
+
+뉴스는 helper가 상시 크롤링하지 않는다. 에이전트가 공개 검색 결과와 원문 페이지를 확인한 뒤 제목, HTTPS 링크, 게시 UTC, 짧은 의역, 관측 방향과 관계 분류만 `news-evidence.json`에 기록한다. 기사 본문 전체를 저장하거나 재배포하지 않는다.
+
+기사의 KST 게시일은 현재 공통 관측일과 같아야 한다. 3년과 10년 금리가 모두 상승하면 `higher`, 모두 하락하면 `lower`, 방향이 엇갈리면 `mixed`, 모두 보합이면 `flat`으로 정한다. 기사가 요인을 금리 움직임과 직접 연결한 경우에만 `explicit`으로 분류한다. 공식 발표나 같은 날의 관련 이벤트는 `contextual`이며 직접 원인 문장으로 사용하지 않는다.
+
+같은 날 연합인포맥스 마감 기사에서 직접 설명하고 방향이 일치하면 `HIGH`, 그 밖의 일치 기사 하나는 `LOW`, 서로 다른 호스트의 복수 근거가 일치하면 `MEDIUM`으로 표시한다. 관측 방향과 다른 기사는 삭제하지 않고 `excluded`로 남긴다. 뉴스의 상태와 실패는 ECOS 커브의 `READY/INCOMPLETE/BLOCKED` 판정을 바꾸지 않는다.
+
+각 기사 fingerprint는 정규화한 매체, 제목, URL, 게시시각, 유형, 방향, 관계, 요인과 근거 요약의 SHA-256이다. 이 fingerprint와 전체 `evidence.mjson` 및 manifest 해시를 함께 검증하므로 저장된 뉴스 코멘트도 replay에서 동일하게 생성된다.
+
+## 산출물 게이트
+
+스테이징 디렉터리에서 모든 파일을 만든 후 다음을 확인하고 최종 디렉터리로 이동한다.
+
+- evidence SHA-256과 manifest 일치
+- 각 산출물 SHA-256 일치
+- evidence 재계산 상태와 manifest 상태 일치
+- Markdown·CSV·HTML을 evidence에서 다시 렌더했을 때 동일
+- 출력에 `NaN` 또는 `undefined` 없음
+- 뉴스 사용 시 모든 채택·맥락·제외 출처와 fingerprint가 HTML·Markdown·상태 파일에 보존됨

package/skills/government-bond-analysis/scripts/cli.mjs

@@ -0,0 +1,268 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { collect, collectWindows, pointWindows, rangeWindows } from './collect.mjs';
+import { ENGINE, PACKET_VERSION, TENOR_META, TENORS, analyze, bp, classify, csvRead, date, days, kstToday, sha256, shift } from './core.mjs';
+import { collectPolicyRate, dashboard, eventQueryWindows, monthComparisonDates, onOrAfter, onOrBefore, previousMonthEnd, previousQuarterEnd, previousYearEnd, trend } from './modes.mjs';
+import { analyzeNews, newsRead, newsTemplate } from './news.mjs';
+import { writeArtifacts } from './render.mjs';
+import { analyzeDual, DUAL_ENGINE, dualChat, dualSummary, writeDualArtifacts } from './dual.mjs';
+import { collectUst } from './ust.mjs';
+import { readSchedule } from './schedule.mjs';
+function args(argv) {
+    const out = {}, allowed = new Set(['as-of', 'base', 'from-month', 'to-month', 'preset', 'event-date', 'lookback-sessions', 'out', 'input', 'replay', 'news-evidence', 'news-template', 'schedule-evidence', 'cache-dir', 'max-lag', 'no-cache', 'text', 'json', 'help', 'market']);
+    for (let i = 0; i < argv.length; i++) {
+        const x = argv[i];
+        if (!x.startsWith('--'))
+            throw Error(`Unknown argument: ${x}`);
+        const k = x.slice(2);
+        if (!allowed.has(k))
+            throw Error(`Unknown option: --${k}`);
+        if (Object.hasOwn(out, k))
+            throw Error(`Duplicate option: --${k}`);
+        if (['no-cache', 'text', 'json', 'help'].includes(k))
+            out[k] = true;
+        else {
+            const v = argv[++i];
+            if (!v || v.startsWith('--'))
+                throw Error(`Missing value: --${k}`);
+            out[k] = v;
+        }
+    }
+    return out;
+}
+const usage = `Usage:
+  node scripts/cli.mjs [--as-of YYYY-MM-DD] [--base YYYY-MM-DD] [--max-lag 0..14] [--text]
+  node scripts/cli.mjs --from-month YYYY-MM --to-month YYYY-MM [--text]
+  node scripts/cli.mjs --preset today|dashboard|previous-session|previous-week|previous-month-end|previous-quarter-end|year-start|policy-gap [--as-of YYYY-MM-DD] [--text]
+  node scripts/cli.mjs --event-date YYYY-MM-DD [--text]
+  node scripts/cli.mjs --lookback-sessions 5|20 [--as-of YYYY-MM-DD] [--text]
+  node scripts/cli.mjs --input FILE.csv --as-of YYYY-MM-DD --base YYYY-MM-DD [--text]
+  node scripts/cli.mjs --base YYYY-MM-DD --as-of YYYY-MM-DD --news-evidence FILE.mjson [--out DIR]
+  node scripts/cli.mjs --news-template YYYY-MM-DD
+  node scripts/cli.mjs --replay evidence.mjson [--text]
+  node scripts/cli.mjs --market both [--as-of YYYY-MM-DD] [--base YYYY-MM-DD] [--schedule-evidence FILE.mjson] [--json|--out DIR]
+  node scripts/cli.mjs --market both --replay evidence.mjson [--out DIR]
+  Add --out DIR only when a persistent HTML/CSV/evidence report bundle is requested.
+`;
+function summary(p, a, news) {
+    return { result: a.status, requested: { base: p.base, asOf: p.asOf }, observed: { base: a.previous.actual, asOf: a.current.actual }, unit: 'annual percent; changes/spreads in bp', rates: TENORS.map((tenor, i) => ({ tenor: `${tenor}Y`, base: a.previous.values?.[i] ?? null, asOf: a.current.values?.[i] ?? null, changeBp: a.changes?.[i] ?? null })), spreads: a.spreads, movement: a.movement, notes: a.notes, news: news.status === 'DISABLED' ? null : { status: news.status, confidence: news.confidence, curveDirection: news.curveDirection, commentary: news.commentary, notes: news.notes, sources: [...news.eligible.map(x => ({ disposition: 'eligible', ...x })), ...news.context.map(x => ({ disposition: 'context', ...x })), ...news.excluded.map(x => ({ disposition: 'excluded', ...x }))].map(x => ({ disposition: x.disposition, publisher: x.publisher, title: x.title, url: x.url, publishedAt: x.publishedAt, sourceFingerprint: x.sourceFingerprint })) }, sources: p.receipts.map(r => ({ tenor: `${r.tenor}Y`, provider: r.sourceId, statCode: r.statCode, itemCode: r.itemCode, unit: r.unit, cycle: r.cycle, retrievedAt: r.retrievedAt, status: r.status, sourceUrl: r.sourceUrl, rawSha256: r.rawSha256 })) };
+}
+function textSummary(p, a, news) {
+    const lines = [`상태: ${a.status}`, `요청일: ${p.base} → ${p.asOf}`, `관측일: ${a.previous.actual ?? '없음'} → ${a.current.actual ?? '없음'}`];
+    if (a.changes && a.previous.values && a.current.values) {
+        TENORS.forEach((t, i) => lines.push(`${t}년: ${a.previous.values[i].toFixed(3)}% → ${a.current.values[i].toFixed(3)}% (${a.changes[i] >= 0 ? '+' : ''}${a.changes[i].toFixed(2)}bp)`));
+        for (const s of a.spreads)
+            lines.push(`${s.name}: ${s.previous?.toFixed(2)}bp → ${s.current?.toFixed(2)}bp (${(s.change ?? 0) >= 0 ? '+' : ''}${s.change?.toFixed(2)}bp)`);
+        lines.push(`곡선 판정: ${a.movement}`);
+    }
+    if (a.notes.length)
+        lines.push(...a.notes.map(n => `주의: ${n}`));
+    if (news.status !== 'DISABLED') {
+        lines.push(`뉴스 근거: ${news.status}${news.confidence ? ` / ${news.confidence}` : ''}`, ...news.commentary, ...news.notes.map(n => `주의: ${n}`));
+        for (const source of [...news.eligible, ...news.context, ...news.excluded])
+            lines.push(`기사: ${source.publisher} · ${source.title} · ${source.url}`);
+        lines.push('뉴스 코멘트는 출처가 전한 시장 해석이며 ECOS 수치만으로 인과를 확정하지 않습니다.');
+    }
+    lines.push(`출처: ${[...new Set(p.receipts.map(r => r.sourceUrl || r.sourceId))].join(', ')}`);
+    return lines.join('\n');
+}
+function snapshotLines(label, s) { const lines = [`${label}: ${s.actual ?? '없음'}`]; if (s.values)
+    lines.push(TENORS.map(t => `${t}Y ${s.values[`${t}Y`].toFixed(3)}%`).join(' · ')); return lines; }
+function dashboardText(d) {
+    const lines = [`상태: ${d.result}`, ...snapshotLines('현재 관측일', d.current)];
+    for (const [label, key] of [['전일', 'previousSession'], ['1주', 'weekAgo'], ['전월말', 'previousMonthEnd']]) {
+        const ref = d.references[key];
+        lines.push(`${label} 기준: ${ref.actual ?? '없음'}`);
+        if (ref.values)
+            lines.push(d.changes[key].map(x => `${x.tenor} ${x.changeBp >= 0 ? '+' : ''}${x.changeBp?.toFixed(2)}bp`).join(' · '));
+    }
+    lines.push(`스프레드: ${Object.entries(d.spreads).map(([k, v]) => `${k} ${v?.toFixed(2) ?? '없음'}bp`).join(' · ')}`);
+    if (d.policyRate)
+        lines.push(`기준금리: ${d.policyRate.value.toFixed(2)}% (${d.policyRate.date}) · 3Y-기준금리 ${d.policyGap3YBp?.toFixed(2)}bp`);
+    if (d.notes.length)
+        lines.push(...d.notes.map(n => `주의: ${n}`));
+    lines.push('출처: https://ecos.bok.or.kr/');
+    return lines.join('\n');
+}
+function trendText(t) { const lines = [`상태: ${t.result}`, `기간: ${t.from ?? '없음'} → ${t.to ?? '없음'} (${t.actualSessions}/${t.requestedSessions}거래일)`]; for (const s of t.stats)
+    lines.push(`${s.tenor}: ${s.start.toFixed(3)}% → ${s.end.toFixed(3)}% (${s.netChangeBp >= 0 ? '+' : ''}${s.netChangeBp.toFixed(2)}bp), 고점 ${s.high.toFixed(3)}%, 저점 ${s.low.toFixed(3)}%, 최대 일변동 ${s.largestDailyMoveBp >= 0 ? '+' : ''}${s.largestDailyMoveBp.toFixed(2)}bp (${s.largestDailyMoveDate})`); if (t.notes.length)
+    lines.push(...t.notes.map(n => `주의: ${n}`)); lines.push('출처: https://ecos.bok.or.kr/'); return lines.join('\n'); }
+function comparison(current, reference, mode) { const changes = TENORS.map(t => ({ tenor: `${t}Y`, base: reference.values?.[`${t}Y`] ?? null, current: current.values?.[`${t}Y`] ?? null, changeBp: current.values && reference.values ? Math.round((current.values[`${t}Y`] - reference.values[`${t}Y`]) * 100 * 1e8) / 1e8 : null })), c3 = changes.find(x => x.tenor === '3Y')?.changeBp, c10 = changes.find(x => x.tenor === '10Y')?.changeBp; return { result: current.values && reference.values && current.actual !== reference.actual ? 'READY' : current.values || reference.values ? 'INCOMPLETE' : 'BLOCKED', mode, current, reference, changes, movement: c3 !== null && c3 !== undefined && c10 !== null && c10 !== undefined ? classify(c3, c10) : '판정 불가', source: 'https://ecos.bok.or.kr/' }; }
+function snapshotSpreads(s) { const spread = (long, short) => s.values ? bp(s.values[long], s.values[short]) : null; return { '5Y-3Y': spread('5Y', '3Y'), '10Y-5Y': spread('10Y', '5Y'), '10Y-3Y': spread('10Y', '3Y'), '30Y-10Y': spread('30Y', '10Y') }; }
+async function main() {
+    const a = args(process.argv.slice(2));
+    if (a.help) {
+        console.log(usage);
+        return;
+    }
+    const market = typeof a.market === 'string' ? a.market : 'kr';
+    if (!['kr', 'both'].includes(market))
+        throw Error('--market must be kr or both');
+    if (a.text === true && a.json === true)
+        throw Error('--text and --json are mutually exclusive');
+    if (market === 'kr' && a.json === true)
+        throw Error('--json is only needed with --market both; Korean mode already defaults to JSON');
+    if (typeof a['news-template'] === 'string') {
+        if (Object.keys(a).some(k => k !== 'news-template'))
+            throw Error('--news-template cannot be combined with other options');
+        console.log(newsTemplate(date(a['news-template']), new Date().toISOString()));
+        return;
+    }
+    const hasMonth = typeof a['from-month'] === 'string' || typeof a['to-month'] === 'string';
+    const hasInput = typeof a.input === 'string', hasReplay = typeof a.replay === 'string';
+    if (hasInput && hasReplay)
+        throw Error('--input and --replay are mutually exclusive');
+    if (hasMonth && (typeof a['from-month'] !== 'string' || typeof a['to-month'] !== 'string'))
+        throw Error('--from-month and --to-month must be used together');
+    if (hasMonth && (typeof a.base === 'string' || typeof a['as-of'] === 'string'))
+        throw Error('Month range cannot be combined with --base/--as-of');
+    if (hasInput && (hasMonth || typeof a.base !== 'string' || typeof a['as-of'] !== 'string'))
+        throw Error('--input requires explicit --base and --as-of and cannot use month range');
+    if (hasReplay && Object.keys(a).some(k => !['replay', 'out', 'text', 'json', 'market'].includes(k)))
+        throw Error('--replay accepts only --market, --out, --text and --json');
+    const monthDates = hasMonth ? monthComparisonDates(a['from-month'], a['to-month'], kstToday()) : null;
+    const asOf = monthDates?.asOf ?? (typeof a['as-of'] === 'string' ? date(a['as-of']) : kstToday());
+    const base = monthDates?.base ?? (typeof a.base === 'string' ? date(a.base) : shift(asOf, -7));
+    const maxLag = typeof a['max-lag'] === 'string' ? Number(a['max-lag']) : 7;
+    if (!Number.isInteger(maxLag) || maxLag < 0 || maxLag > 14)
+        throw Error('--max-lag must be an integer from 0 to 14');
+    const cacheDir = resolve(typeof a['cache-dir'] === 'string' ? a['cache-dir'] : join(homedir(), '.cache', 'k-skill', 'korean-interest-rate-analysis')), useCache = a['no-cache'] !== true;
+    if (market === 'both') {
+        if (Object.keys(a).some(k => !['market', 'base', 'as-of', 'from-month', 'to-month', 'max-lag', 'out', 'replay', 'schedule-evidence', 'cache-dir', 'no-cache', 'text', 'json'].includes(k)))
+            throw Error('--market both supports dates, schedule evidence, cache, replay, --text, --json and --out only');
+        let dual;
+        if (hasReplay) {
+            const evidencePath = resolve(a.replay), raw = await readFile(evidencePath, 'utf8');
+            if (raw.length > 100_000_000)
+                throw Error('Dual replay evidence exceeds 100 MB');
+            try {
+                const manifest = JSON.parse(await readFile(join(dirname(evidencePath), 'manifest.mjson'), 'utf8'));
+                if (manifest.evidenceSha256 !== sha256(raw))
+                    throw Error('Dual replay evidence hash differs from manifest');
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+            }
+            dual = JSON.parse(raw);
+        }
+        else {
+            if (asOf > kstToday())
+                throw Error('Live collection cannot use a future KST as-of date');
+            if (base >= asOf || days(asOf, base) > 366)
+                throw Error(base >= asOf ? 'Base must precede as-of' : 'Comparison window must be 366 days or less');
+            const [kr, us] = await Promise.all([collect(base, asOf, maxLag, cacheDir, useCache), collectUst(base, asOf, maxLag, cacheDir, useCache)]);
+            const schedule = typeof a['schedule-evidence'] === 'string' ? readSchedule(await readFile(resolve(a['schedule-evidence']), 'utf8'), asOf) : undefined;
+            dual = { version: 1, engine: DUAL_ENGINE, ktb: { version: PACKET_VERSION, engine: ENGINE, asOf, base, maxLag, ...kr, label: '한·미 국채 금리 분석 · KTB' }, ust: us, ...(schedule ? { schedule } : {}) };
+        }
+        const result = analyzeDual(dual);
+        if (typeof a.out === 'string') {
+            const out = resolve(a.out);
+            await writeDualArtifacts(out, dual);
+            console.log(JSON.stringify({ result: result.status, out, files: ['report.html', 'brief.md', 'market-table.csv', 'evidence.mjson', 'status.mjson', 'manifest.mjson'] }, null, 2));
+        }
+        else if (a.json === true)
+            console.log(JSON.stringify(dualSummary(dual, result), null, 2));
+        else
+            console.log(dualChat(dual, result));
+        if (result.status !== 'READY')
+            process.exitCode = 2;
+        return;
+    }
+    const preset = typeof a.preset === 'string' ? a.preset : null, eventDate = typeof a['event-date'] === 'string' ? date(a['event-date']) : null, lookback = typeof a['lookback-sessions'] === 'string' ? Number(a['lookback-sessions']) : null;
+    if ((preset !== null || lookback !== null || eventDate !== null) && (typeof a.input === 'string' || typeof a.replay === 'string' || typeof a.out === 'string' || typeof a['news-evidence'] === 'string' || hasMonth || typeof a.base === 'string'))
+        throw Error('Preset/trend/event modes accept only date anchor, --max-lag, --cache-dir, --no-cache and --text');
+    if ([preset !== null, lookback !== null, eventDate !== null].filter(Boolean).length > 1)
+        throw Error('--preset, --lookback-sessions and --event-date are mutually exclusive');
+    if (!hasReplay && (base >= asOf || days(asOf, base) > 366))
+        throw Error(base >= asOf ? 'Base must precede as-of' : 'Comparison window must be 366 days or less');
+    if (preset !== null || lookback !== null || eventDate !== null) {
+        if (asOf > kstToday())
+            throw Error('Live collection cannot use a future KST as-of date');
+        let output;
+        if (eventDate !== null) {
+            const data = await collectWindows(eventQueryWindows(eventDate, kstToday(), maxLag), cacheDir, useCache), before = onOrBefore(data.observations, shift(eventDate, -1), maxLag), after = onOrAfter(data.observations, eventDate, maxLag);
+            output = { ...comparison(after, before, 'event'), eventDate };
+            console.log(JSON.stringify(output, null, 2));
+        }
+        else if (lookback !== null) {
+            if (![5, 20].includes(lookback))
+                throw Error('--lookback-sessions must be 5 or 20');
+            const from = shift(asOf, lookback === 20 ? -45 : -16), data = await collectWindows(rangeWindows(from, asOf), cacheDir, useCache);
+            output = trend(data.observations, lookback);
+            console.log(a.text === true ? trendText(output) : JSON.stringify(output, null, 2));
+        }
+        else if (preset === 'today') {
+            const data = await collectWindows(pointWindows([asOf], maxLag), cacheDir, useCache), current = onOrBefore(data.observations, asOf, maxLag);
+            output = { result: current.values ? 'READY' : 'BLOCKED', mode: 'today', current, spreads: snapshotSpreads(current), source: 'https://ecos.bok.or.kr/' };
+            console.log(JSON.stringify(output, null, 2));
+        }
+        else if (preset === 'policy-gap') {
+            const data = await collectWindows(pointWindows([asOf], maxLag), cacheDir, useCache), current = onOrBefore(data.observations, asOf, maxLag), policyRate = await collectPolicyRate(asOf, cacheDir, useCache), current3 = current.values?.['3Y'] ?? null, policyGap3YBp = current3 !== null && policyRate ? bp(current3, policyRate.value) : null, notes = [current.reason, !policyRate ? '기준금리 확보 실패: 정책금리 갭 제외' : null].filter((x) => !!x);
+            output = { result: current.values && policyRate ? 'READY' : current.values ? 'INCOMPLETE' : 'BLOCKED', mode: 'policy-gap', current, policyRate, policyGap3YBp, notes, source: 'https://ecos.bok.or.kr/' };
+            console.log(JSON.stringify(output, null, 2));
+        }
+        else if (preset === 'dashboard' || preset === 'previous-session') {
+            const windows = [...rangeWindows(shift(asOf, -(maxLag + 7)), asOf), ...pointWindows([shift(asOf, -7), previousMonthEnd(asOf)], maxLag)], data = await collectWindows(windows, cacheDir, useCache), policy = preset === 'dashboard' ? await collectPolicyRate(asOf, cacheDir, useCache) : null, d = dashboard(asOf, data.observations, maxLag, policy);
+            output = preset === 'dashboard' ? d : comparison(d.current, d.references.previousSession, 'previous-session');
+            console.log(a.text === true && preset === 'dashboard' ? dashboardText(d) : JSON.stringify(output, null, 2));
+        }
+        else {
+            const refs = { 'previous-week': shift(asOf, -7), 'previous-month-end': previousMonthEnd(asOf), 'previous-quarter-end': previousQuarterEnd(asOf), 'year-start': previousYearEnd(asOf) };
+            const referenceDate = refs[preset ?? ''];
+            if (!referenceDate)
+                throw Error(`Unknown preset: ${preset}`);
+            const data = await collectWindows(pointWindows([asOf, referenceDate], maxLag), cacheDir, useCache), current = onOrBefore(data.observations, asOf, maxLag), reference = onOrBefore(data.observations, referenceDate, maxLag);
+            output = comparison(current, reference, preset);
+            console.log(JSON.stringify(output, null, 2));
+        }
+        const result = output.result;
+        if (result !== 'READY')
+            process.exitCode = 2;
+        return;
+    }
+    let p;
+    if (typeof a.replay === 'string') {
+        const evidencePath = resolve(a.replay), raw = await readFile(evidencePath, 'utf8');
+        if (raw.length > 100_000_000)
+            throw Error('Replay evidence exceeds 100 MB character limit');
+        try {
+            const m = JSON.parse(await readFile(join(dirname(evidencePath), 'manifest.mjson'), 'utf8'));
+            if (m.evidenceSha256 && m.evidenceSha256 !== sha256(raw))
+                throw Error('Replay evidence hash differs from manifest');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        p = JSON.parse(raw);
+        if (p.version !== PACKET_VERSION || p.engine !== ENGINE)
+            throw Error('Unsupported evidence packet');
+    }
+    else if (typeof a.input === 'string') {
+        const inputPath = resolve(a.input), raw = await readFile(inputPath, 'utf8'), observations = csvRead(raw), now = new Date().toISOString();
+        const receipts = TENORS.map(tenor => { const rows = observations.filter(r => r.tenor === tenor), meta = TENOR_META[tenor]; return { tenor, sourceId: `사용자 제공 CSV: ${basename(inputPath)}`, sourceUrl: '', statCode: 'USER_CSV', itemCode: meta.itemCode, itemName: meta.itemName, unit: '연%', cycle: 'D', retrievedAt: now, status: 'input', raw: [raw], rawSha256: [sha256(raw)], count: rows.length, first: rows[0]?.date ?? null, last: rows.at(-1)?.date ?? null, windows: [] }; });
+        p = { version: PACKET_VERSION, engine: ENGINE, asOf, base, maxLag, observations, receipts, label: '한국 금리 동향 분석' };
+    }
+    else {
+        if (asOf > kstToday())
+            throw Error('Live collection cannot use a future KST as-of date');
+        const result = await collect(base, asOf, maxLag, cacheDir, useCache);
+        p = { version: PACKET_VERSION, engine: ENGINE, asOf, base, maxLag, ...result, label: '한국 금리 동향 분석' };
+    }
+    if (typeof a['news-evidence'] === 'string') {
+        const raw = await readFile(resolve(a['news-evidence']), 'utf8');
+        p = { ...p, newsEvidence: newsRead(raw) };
+    }
+    const analysis = analyze(p), news = analyzeNews(p.newsEvidence, analysis);
+    if (typeof a.out === 'string') {
+        const out = resolve(a.out), manifest = await writeArtifacts(out, p);
+        console.log(JSON.stringify({ result: manifest.status, out, files: [...Object.keys(manifest.files), 'manifest.mjson'] }, null, 2));
+    }
+    else
+        console.log(a.text === true ? textSummary(p, analysis, news) : JSON.stringify(summary(p, analysis, news), null, 2));
+    if (analysis.status !== 'READY')
+        process.exitCode = 2;
+}
+main().catch(e => { const message = e instanceof Error ? e.message : String(e); console.error(JSON.stringify({ result: 'error', message }, null, 2)); process.exitCode = 1; });

package/skills/government-bond-analysis/scripts/collect.mjs

@@ -0,0 +1,171 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { SOURCE_ID, SOURCE_URL, TENORS, TENOR_META, date, days, normalize, parseEcos, sha256, shift } from './core.mjs';
+class Fatal extends Error {
+}
+class RequestFailure extends Error {
+    attempts;
+    constructor(message, attempts) {
+        super(message);
+        this.attempts = attempts;
+    }
+}
+const transient = (status) => [408, 425, 429].includes(status) || status >= 500;
+export async function request(url, get = fetch, pause = ms => new Promise(r => setTimeout(r, ms)), validate) {
+    let last = 'unknown error';
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+            const res = await get(url, { signal: AbortSignal.timeout(10000), headers: { accept: 'application/json' } });
+            if (!res.ok) {
+                if (!transient(res.status))
+                    throw new Fatal(`HTTP ${res.status}`);
+                throw Error(`HTTP ${res.status}`);
+            }
+            const text = await res.text();
+            if (text.length > 2_000_000)
+                throw new Fatal('Response too large');
+            JSON.parse(text);
+            validate?.(text);
+            return { text, attempts: attempt };
+        }
+        catch (e) {
+            last = e instanceof Error ? e.message : String(e);
+            if (e instanceof Fatal)
+                throw new RequestFailure(last, attempt);
+            if (attempt === 3)
+                throw new RequestFailure(`${last} after 3 attempts`, attempt);
+            await pause(300 * 2 ** (attempt - 1));
+        }
+    }
+    throw Error(last);
+}
+export const parse = parseEcos;
+export function pointWindows(points, maxLag) {
+    const unique = new Map();
+    if (!Number.isInteger(maxLag) || maxLag < 0 || maxLag > 14)
+        throw Error('maxLag must be 0..14 calendar days');
+    for (const point of points) {
+        date(point);
+        for (const window of rangeWindows(shift(point, -maxLag), point))
+            unique.set(`${window.from}/${window.to}`, window);
+    }
+    return [...unique.values()].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+}
+export function rangeWindows(from, to) {
+    date(from);
+    date(to);
+    if (from > to)
+        throw Error('Invalid collection range');
+    const result = [];
+    for (let start = from; start <= to; start = shift(start, 10)) {
+        const end = shift(start, 9) < to ? shift(start, 9) : to;
+        result.push({ from: start, to: end });
+    }
+    return result;
+}
+async function atomic(path, content) { const temp = `${path}.${randomUUID()}.tmp`; try {
+    await writeFile(temp, content);
+    await rename(temp, path);
+}
+catch (e) {
+    await rm(temp, { force: true });
+    throw e;
+} }
+const cacheName = (tenor, from, to) => `${tenor}-${from}-${to}.mjson`;
+export async function collect(base, asOf, maxLag, cacheDir, useCache = true, get = fetch, now = new Date(), maxCacheAgeHours = 168) {
+    date(base);
+    date(asOf);
+    if (!Number.isInteger(maxLag) || maxLag < 0 || maxLag > 14)
+        throw Error('maxLag must be 0..14 calendar days');
+    if (base >= asOf)
+        throw Error('Base must precede as-of');
+    if (days(asOf, base) > 366)
+        throw Error('Comparison window must be 366 days or less');
+    return collectWindows(pointWindows([base, asOf], maxLag), cacheDir, useCache, get, now, maxCacheAgeHours);
+}
+export async function collectWindows(inputSegments, cacheDir, useCache = true, get = fetch, now = new Date(), maxCacheAgeHours = 168) {
+    if (!Array.isArray(inputSegments) || !inputSegments.length)
+        throw Error('At least one query window is required');
+    if (typeof cacheDir !== 'string' || !cacheDir.trim())
+        throw Error('cacheDir must be a non-empty path');
+    if (!Number.isFinite(now.getTime()))
+        throw Error('Invalid collection clock');
+    if (!Number.isFinite(maxCacheAgeHours) || maxCacheAgeHours < 0)
+        throw Error('maxCacheAgeHours must be non-negative');
+    const unique = new Map();
+    for (const segment of inputSegments) {
+        if (!segment || typeof segment.from !== 'string' || typeof segment.to !== 'string')
+            throw Error('Invalid query window');
+        date(segment.from);
+        date(segment.to);
+        if (segment.from > segment.to || daysBetween(segment.from, segment.to) > 10)
+            throw Error('Query windows must contain 1..10 calendar days');
+        unique.set(`${segment.from}/${segment.to}`, segment);
+    }
+    const retrievedAt = now.toISOString(), segments = [...unique.values()].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+    if (useCache)
+        await mkdir(cacheDir, { recursive: true });
+    const parts = await Promise.all(TENORS.map(async (tenor) => {
+        const observations = [];
+        const raw = [];
+        const rawSha256 = [];
+        const windowReceipts = [];
+        const errors = [];
+        for (const segment of segments) {
+            const file = join(cacheDir, cacheName(tenor, segment.from, segment.to));
+            let liveError = '', liveAttempts = 0;
+            try {
+                const key = process.env.KSKILL_BOK_ECOS_API_KEY || 'sample', meta = TENOR_META[tenor];
+                const url = `https://ecos.bok.or.kr/api/StatisticSearch/${encodeURIComponent(key)}/json/kr/1/10/817Y002/D/${segment.from.replaceAll('-', '')}/${segment.to.replaceAll('-', '')}/${meta.itemCode}`;
+                const result = await request(url, get, undefined, text => { parse(text, tenor, segment.from, segment.to); });
+                liveAttempts = result.attempts;
+                const rows = parse(result.text, tenor, segment.from, segment.to), digest = sha256(result.text);
+                const data = { version: 1, storedAt: retrievedAt, tenor, ...segment, raw: result.text, rawSha256: digest };
+                let cacheError;
+                if (useCache)
+                    try {
+                        await atomic(file, JSON.stringify({ data, digest: sha256(JSON.stringify(data)) }));
+                    }
+                    catch (e) {
+                        cacheError = `cache write failed (${e instanceof Error ? e.message : String(e)})`;
+                    }
+                observations.push(...rows);
+                raw.push(result.text);
+                rawSha256.push(digest);
+                windowReceipts.push({ ...segment, status: 'live', attempts: result.attempts, ...(cacheError ? { error: cacheError } : {}) });
+                continue;
+            }
+            catch (e) {
+                liveError = e instanceof Error ? e.message : String(e);
+                liveAttempts = e instanceof RequestFailure ? e.attempts : Math.max(liveAttempts, 1);
+            }
+            if (useCache)
+                try {
+                    const envelope = JSON.parse(await readFile(file, 'utf8')), data = envelope.data;
+                    const age = (now.getTime() - Date.parse(data?.storedAt)) / 3600000;
+                    if (!data || envelope.digest !== sha256(JSON.stringify(data)) || data.version !== 1 || data.tenor !== tenor || data.from !== segment.from || data.to !== segment.to || data.rawSha256 !== sha256(data.raw) || !Number.isFinite(age) || age < 0 || age > maxCacheAgeHours)
+                        throw Error('cache identity, hash, or age check failed');
+                    const rows = parse(data.raw, tenor, segment.from, segment.to);
+                    observations.push(...rows);
+                    raw.push(data.raw);
+                    rawSha256.push(data.rawSha256);
+                    windowReceipts.push({ ...segment, status: 'cache', attempts: liveAttempts, cacheAgeHours: Math.round(age * 100) / 100, error: liveError });
+                    continue;
+                }
+                catch (e) {
+                    errors.push(`${segment.from}..${segment.to}: ${liveError}; cache rejected (${e instanceof Error ? e.message : String(e)})`);
+                }
+            else
+                errors.push(`${segment.from}..${segment.to}: ${liveError}`);
+            windowReceipts.push({ ...segment, status: 'failed', attempts: liveAttempts, error: liveError });
+        }
+        const rows = normalize(observations), modes = new Set(windowReceipts.map(w => w.status));
+        const status = rows.length === 0 && modes.has('failed') ? 'failed' : modes.size === 1 ? (modes.has('live') ? 'live' : modes.has('cache') ? 'cache' : 'failed') : 'mixed';
+        const meta = TENOR_META[tenor];
+        const receipt = { tenor, sourceId: SOURCE_ID, sourceUrl: SOURCE_URL, statCode: '817Y002', itemCode: meta.itemCode, itemName: meta.itemName, unit: '연%', cycle: 'D', retrievedAt, status, raw, rawSha256, count: rows.length, first: rows[0]?.date ?? null, last: rows.at(-1)?.date ?? null, windows: windowReceipts, ...(errors.length ? { error: errors.join(' | ') } : {}) };
+        return { observations: rows, receipt };
+    }));
+    return { observations: normalize(parts.flatMap(p => p.observations)), receipts: parts.map(p => p.receipt) };
+}
+function daysBetween(from, to) { return Math.round((Date.parse(to) - Date.parse(from)) / 86400000) + 1; }