argus-decision-mcp 1.0.0 → 1.3.0

package/dist/lib/ambient-due.js

@@ -0,0 +1,63 @@
+import { replayLedger } from './ledger-replay.js';
+import { duePremises, groupDuePremises, dueOpenQuestions } from './premises.js';
+import { surfacesFor, SURFACES, resolveResponseLocale } from './surfaces.js';
+/** Count from an already-replayed ledger (when the caller has one in hand). */
+export function ambientDueFromState(state) {
+    return {
+        contractsDue: state.overdue.length,
+        premiseFactsDue: groupDuePremises(duePremises(state)).length,
+        openQuestionsDue: dueOpenQuestions(state).length,
+    };
+}
+/** Count by replaying the ledger for `dir` as of `today`. */
+export function ambientDue(dir, today) {
+    return ambientDueFromState(replayLedger(dir, today));
+}
+/** True when nothing at all is due — the silence gate (restraint: zero renders
+ *  nothing, never an empty nag). */
+export function isSilent(due) {
+    return due.contractsDue === 0 && due.premiseFactsDue === 0 && due.openQuestionsDue === 0;
+}
+/**
+ * The user's own language, read from the LEDGER's user-authored text — the
+ * one deterministic voice source for surfaces that have no fresh input (the
+ * ambient tail, recall's textless views). Chain: the latest watch anchor, an
+ * overdue predicate, a due premise's decision, a due question, else ANY
+ * contract predicate (replay order = deterministic). Never env/Intl — an
+ * English user on a Korean machine must not get a Korean frame (experience
+ * loop caught exactly that).
+ */
+export function ledgerVoiceText(state) {
+    const anchors = [...state.watch.anchors.values()].sort((a, b) => (a.date < b.date ? 1 : -1));
+    return anchors[0]?.text
+        || state.overdue[0]?.text
+        || duePremises(state)[0]?.decision_text
+        || dueOpenQuestions(state)[0]?.text
+        || [...state.contracts.values()].find((c) => typeof c.predicate === 'string' && c.predicate)?.predicate;
+}
+/**
+ * The localized one-line ambient fact for a due count, or '' when silent.
+ * Leads with a space so it appends cleanly to the END of a tool's surface
+ * (M1 §1.3, §6: never obscure the result — the line is last, and it is a fact
+ * + the argus_check_in handle, never a directive).
+ * `state` (when the caller has one) lends the ledger's own voice — without it
+ * the tail fell back to config-or-EN and read "By the way — 2 to settle" to a
+ * user whose every decision is Korean (experience-loop worst-moment).
+ */
+export function ambientLine(dir, due, state) {
+    if (isSilent(due))
+        return '';
+    const voice = state ? ledgerVoiceText(state) : undefined;
+    const A = (voice ? SURFACES[resolveResponseLocale(dir, voice)] : surfacesFor(dir)).ambient;
+    const { contractsDue: c, premiseFactsDue: p, openQuestionsDue: q } = due;
+    // Fragment-composed so any subset of the three due kinds reads naturally in
+    // both locales (M3 adds a third kind — a fixed combo table would be 7 cases).
+    const frags = [];
+    if (c > 0)
+        frags.push(A.frag_contracts(c));
+    if (p > 0)
+        frags.push(A.frag_premises(p));
+    if (q > 0)
+        frags.push(A.frag_open_questions(q));
+    return A.wrap(frags);
+}

package/dist/lib/ambient-elicit.js

@@ -0,0 +1,225 @@
+import fs from 'fs';
+import path from 'path';
+import { elicit, canElicit } from './elicit.js';
+import { replayLedger } from './ledger-replay.js';
+import { resolveToday } from './resolve-today.js';
+import { resolveResponseLocale } from './surfaces.js';
+import { resolveToolArgusDir } from './argus-dir.js';
+import { configPath } from './layout.js';
+import { atomicWriteJson } from './atomic-write.js';
+import { logError } from './log.js';
+import { sanitizeLine } from '../v2/sanitize.js';
+/**
+ * Out-of-band ambient elicitation — the MCP-side firing gate (창업자 컨셉
+ * 2026-07-15, 스파이크 spikes/ambient-elicit/ 가 프로토콜 층을 실증).
+ *
+ * The wire is bidirectional: `elicitation/create` is a server→client request
+ * and nothing ties it to an in-flight tool call. So after a tool call ends and
+ * the user goes back to their main work, THIS module may ask them the one due
+ * question — the wait becomes judgment time, no plugin required.
+ *
+ * Gate BEFORE form (spine mirror clause — don't judge WHETHER to intervene in
+ * the user's stead; default is restraint):
+ *
+ *   arm-time  — host declared elicitation? not already spent? then debounce:
+ *               each tool call re-arms one quiet-delay timer (fire only when
+ *               Argus goes quiet — mid-conversation is not the wait).
+ *   fire-time — EVERYTHING re-checked: capability, `ambient_mute: true` in
+ *               config.yaml (the SAME escape hatch as the due-note tail — one
+ *               mute, not two), cross-session cooldown (4h, state file), and
+ *               due recomputed from the ledger (zero due = silence).
+ *   budget    — at most ONE ask per server process (one question per sitting);
+ *               an argus_check_in call spends the budget (the user just saw
+ *               their dues — asking again in a minute is nagging, the same
+ *               principle as due-note's SKIP_TOOLS mark).
+ *   decline   — is an answer. Nothing written, budget stays spent, the state
+ *               file's cooldown keeps the next session from insta-re-asking.
+ *
+ * Form (spine §9.2): only the settlement outcome — the ONE spine-SAFE
+ * structured pick (reality, not a verdict; same enum as argus_settle's
+ * in-band elicit). Premise re-checks and open questions are deliberately NOT
+ * asked out-of-band in v1: their honest form is free text, and free text
+ * without conversational context invites fabricated-feeling answers. The
+ * recording brain is NOT duplicated: an accepted answer is fed to the real
+ * settle handler (injected via init), which runs every guard, receipt, and
+ * dual-write exactly as an in-band settle would. still_pending composes for
+ * free — the settle handler's own defer elicitation runs over the same
+ * out-of-band channel.
+ *
+ * Honest limits: real-host rendering of out-of-band pickers is per-host
+ * empirical (spike README table); an unanswered ask times out to null and is
+ * treated as a decline. Any internal failure is swallowed — an ambient extra
+ * must never tax the session it rides on.
+ */
+const COOLDOWN_MS = 4 * 60 * 60 * 1000; // 세션(연결)을 넘는 재발사 간격
+const DEFAULT_ASK_TIMEOUT_MS = 120_000; // 렌더 안 하는 호스트에서 조용히 접는 시한
+const DEFAULT_QUIET_MS = 45_000; // 마지막 툴 호출 뒤 이만큼 조용하면 발사
+function askTimeoutMs() {
+    const raw = Number(process.env['ARGUS_AMBIENT_ASK_TIMEOUT_MS']);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_ASK_TIMEOUT_MS;
+}
+let _settleHandler = null;
+let _serialize = (fn) => fn();
+let _timer = null;
+let _spent = false; // 프로세스당 질문 1개 — 한 자리에 한 질문
+let _inFlight = false;
+/** server.ts가 시동 시 배선한다. 미배선이면 arm은 완전 no-op (정직한 미연결). */
+export function initAmbientElicit(deps) {
+    _settleHandler = deps.settleHandler;
+    if (deps.serialize)
+        _serialize = deps.serialize;
+}
+/** 테스트 리셋 — 타이머·예산·배선을 모두 되돌린다. */
+export function resetAmbientElicit() {
+    if (_timer)
+        clearTimeout(_timer);
+    _timer = null;
+    _spent = false;
+    _inFlight = false;
+    _settleHandler = null;
+    _serialize = (fn) => fn();
+}
+function quietMs() {
+    const raw = Number(process.env['ARGUS_AMBIENT_DELAY_MS']);
+    return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_QUIET_MS;
+}
+function muted(dir) {
+    try {
+        return /^ambient_mute:\s*true\b/m.test(fs.readFileSync(configPath(dir), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+const statePath = (dir) => path.join(dir, 'ambient-elicit-state.json');
+function underCooldown(dir) {
+    try {
+        const st = JSON.parse(fs.readFileSync(statePath(dir), 'utf8'));
+        return typeof st.last_fired_at === 'number' && Date.now() - st.last_fired_at < COOLDOWN_MS;
+    }
+    catch {
+        return false; // 상태 부재·파손 = 이력 없음
+    }
+}
+function withTimeout(p, ms) {
+    return new Promise((res) => {
+        const t = setTimeout(() => res(null), ms);
+        t.unref?.();
+        p.then((v) => { clearTimeout(t); res(v); }, () => { clearTimeout(t); res(null); });
+    });
+}
+/**
+ * 디스패처가 매 툴 호출 뒤에 부른다 (fire-and-forget, 절대 던지지 않음).
+ * 타이머는 디바운스 — 새 호출이 오면 리셋되어, Argus가 조용해진 뒤에만 발사.
+ */
+export function armAmbientElicit(toolName, args) {
+    try {
+        if (!_settleHandler)
+            return; // 미배선 = no-op
+        if (toolName === 'argus_check_in') {
+            _spent = true;
+            return;
+        } // due를 방금 봤다 — 예산 소진
+        if (_spent || !canElicit())
+            return;
+        let dir;
+        try {
+            dir = resolveToolArgusDir(args['argus_dir']);
+        }
+        catch {
+            return;
+        }
+        const todayOverride = typeof args['today_override'] === 'string' ? args['today_override'] : undefined;
+        if (_timer)
+            clearTimeout(_timer);
+        _timer = setTimeout(() => { void fire(dir, todayOverride); }, quietMs());
+        _timer.unref?.();
+    }
+    catch { /* ambient는 절대 본 호출에 세금을 물리지 않는다 */ }
+}
+async function fire(dir, todayOverride) {
+    try {
+        if (_spent || _inFlight || !_settleHandler || !canElicit())
+            return;
+        if (muted(dir) || underCooldown(dir))
+            return;
+        const today = resolveToday({ override: todayOverride });
+        const state = replayLedger(dir, today);
+        const first = state.overdue[0];
+        if (!first)
+            return; // due 0건 = 침묵 (빈 질문은 표현 불가)
+        // 여기서부터는 시도 = 예산 소진. 상태 기록이 실패하면 발사하지 않는다 —
+        // 상한 없는 질문보다 한 번 거르는 쪽이 안전하다 (driver 훅과 같은 자세).
+        _spent = true;
+        _inFlight = true;
+        try {
+            await atomicWriteJson(statePath(dir), { last_fired_at: Date.now() });
+        }
+        catch {
+            return;
+        }
+        const ko = resolveResponseLocale(dir) === 'ko';
+        const text = sanitizeLine(first.text || first.id, 120);
+        // 물음 1 — 정산 outcome (spine-SAFE 구조 픽: 현실이지 평결이 아니다).
+        // 대화 맥락이 없는 사용자를 위해 그의 예측을 그대로 되비춘다 (우정 1조).
+        const picked = await withTimeout(elicit(ko
+            ? `Argus — 확인일이 지난 예측이 있어요: "${text}" (확인일 ${first.date}). 현실이 어떻게 답했나요? 지금 어려우면 닫아도 됩니다 — 다시 조르지 않아요.`
+            : `Argus — a prediction passed its check-by: "${text}" (due ${first.date}). What did reality do? Dismiss if now is a bad time — no re-asking.`, {
+            type: 'object',
+            required: ['outcome'],
+            properties: {
+                outcome: {
+                    type: 'string',
+                    enum: ['held', 'avoided', 'partial', 'still_pending', 'missed'],
+                    enumNames: ko
+                        ? ['그렇게 됐다 (held)', '피했다 (avoided)', '부분적으로 (partial)', '아직 불분명 (still pending)', '빗나갔다 (missed)']
+                        : ['It held', 'Avoided it', 'Partially', 'Still pending', 'Missed — my read was wrong'],
+                    description: ko ? '봉인한 예측에 현실이 어떻게 답했는지.' : 'What reality did to your sealed prediction.',
+                },
+            },
+        }), askTimeoutMs());
+        const outcome = picked?.['outcome'];
+        if (outcome !== 'held' && outcome !== 'avoided' && outcome !== 'partial' && outcome !== 'still_pending' && outcome !== 'missed') {
+            return; // 거절·시간초과·미렌더 = 답이다. 아무것도 쓰지 않는다.
+        }
+        // still_pending은 실제 settle 핸들러의 defer elicitation이 같은 채널로
+        // 이어서 묻는다 (두뇌 하나). 종결 outcome은 what_happened를 사용자의
+        // 말로 받아야만 기록한다 — 비면 기록하지 않는다 (날조 금지, 정직한 공백).
+        let whatHappened;
+        if (outcome !== 'still_pending') {
+            const wh = await withTimeout(elicit(ko
+                ? '실제로 무슨 일이 있었나요? 한 줄이면 됩니다 — 당신의 말 그대로 기록됩니다.'
+                : 'What actually happened, in one line? Recorded verbatim, in your words.', {
+                type: 'object',
+                required: ['what_happened'],
+                properties: {
+                    what_happened: {
+                        type: 'string', maxLength: 600,
+                        description: ko ? '당신의 말, 그대로.' : 'Your words, verbatim.',
+                    },
+                },
+            }), askTimeoutMs());
+            whatHappened = typeof wh?.['what_happened'] === 'string' ? wh['what_happened'].trim() : '';
+            if (!whatHappened)
+                return; // 현실 서술 없이는 종결 정산을 쓰지 않는다
+        }
+        // 기록은 실제 settle 핸들러로 — 가드·영수증·이중쓰기 전부 본 경로 그대로.
+        // 툴 호출 직렬화 사슬에 태워 원장 read-replay-append가 절대 끼어들지 않게.
+        const result = await _serialize(() => _settleHandler({
+            argus_dir: dir,
+            id: first.id,
+            outcome,
+            outcome_source: 'user_stated',
+            ...(whatHappened ? { what_happened: whatHappened } : {}),
+            ...(todayOverride ? { today_override: todayOverride } : {}),
+        }));
+        if (result.isError)
+            logError('[ambient-elicit] settle refused', result.structuredContent?.['error_code']);
+    }
+    catch (e) {
+        logError('[ambient-elicit] fire failed', e);
+    }
+    finally {
+        _inFlight = false;
+    }
+}

package/dist/lib/argus-dir.js

@@ -1,18 +1,23 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { boundMarkerPath } from './layout.js';
 /**
- * argus_dir resolution + precedence (blueprint §4.0 + addendum A/B).
+ * argus_dir resolution + precedence (blueprint §4.0 + addendum A/B; §9.7 O1).
  *
  * The `${workspaceFolder}` config variable only expands in VS Code — Claude
  * Code expands `${CLAUDE_PROJECT_DIR}`, others expand nothing. So env
  * interpolation is the LEAST reliable channel and must come last. Tools always
  * receive a per-call `argus_dir`, which works on every host, so that wins.
  *
- * Precedence:
- *   1. per-call `argus_dir` argument            (works on every host)
- *   2. last dir written to `.bound` by argus_init (read-side for Resources)
- *   3. ARGUS_DIR env                            (host-dependent interpolation)
+ * Precedence (tools and resources must tell the same storage story):
+ *   tools:     1. per-call `argus_dir`  2. ARGUS_DIR env  3. ~/.argus default
+ *   resources: (no per-call channel)   1. ARGUS_DIR env  2. ~/.argus default
+ *
+ * One deliberate asymmetry: an ARGUS_DIR that is SET but invalid makes a tool
+ * THROW (requireArgusDir) but makes a resource return null/unbound — resources
+ * can't error usefully, and silently reading a ledger the user didn't
+ * configure would be worse than degrading.
  */
 export class ArgusDirError extends Error {
     code = 'ARGUS_DIR_INVALID';
@@ -26,6 +31,14 @@ export function requireArgusDir(callArg) {
     if (typeof callArg !== 'string' || callArg.length === 0) {
         throw new ArgusDirError('argus_dir is required (absolute path to the .argus directory).');
     }
+    // An unexpanded config variable is the #1 Claude Desktop first-run failure:
+    // only Claude Code expands ${CLAUDE_PROJECT_DIR}, so Desktop passes the
+    // literal string through. Name the actual problem instead of "not absolute".
+    if (/\$\{[^}]*\}|%[A-Za-z_]+%/.test(callArg)) {
+        throw new ArgusDirError(`Your MCP host did not expand the variable in "${callArg}" (only some hosts interpolate env vars). ` +
+            'Replace it with an absolute path in your MCP config (e.g. "C:\\Users\\you\\.argus" or "/Users/you/.argus"), ' +
+            'or remove ARGUS_DIR entirely to use the default ~/.argus.');
+    }
     const resolved = path.resolve(callArg);
     if (!path.isAbsolute(callArg)) {
         throw new ArgusDirError('argus_dir must be an absolute path.');
@@ -48,7 +61,10 @@ export function resolveToolArgusDir(callArg) {
     const env = process.env['ARGUS_DIR'];
     if (typeof env === 'string' && env.length > 0)
         return requireArgusDir(env);
-    throw new ArgusDirError('No argus_dir given and ARGUS_DIR is not set. Pass an absolute argus_dir, or set "ARGUS_DIR" in your MCP config env (then you can omit it every call).');
+    // Zero-config default (blueprint §9.4 "첫 설치의 문"): a brand-new user on a
+    // host without env interpolation still gets a working home for their ledger.
+    // Per-call argus_dir and ARGUS_DIR both keep winning over this.
+    return path.join(os.homedir(), '.argus');
 }
 /** Record the bound dir so Resources (which get no args) can find it later. */
 export function writeBoundMarker(argusDir) {
@@ -61,6 +77,43 @@ export function writeBoundMarker(argusDir) {
     catch {
         /* non-critical */
     }
+    // Global registry (M2 fleet, §9.4): every init'd project dir also lands in
+    // ~/.argus/.bound so ONE check_in can report due items across all of a
+    // user's projects. Local paths only, stays on this machine, best-effort.
+    try {
+        const home = path.join(os.homedir(), '.argus');
+        fs.mkdirSync(home, { recursive: true });
+        const reg = path.join(home, '.bound');
+        let dirs = [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(reg, 'utf8'));
+            dirs = Array.isArray(parsed.bound) ? parsed.bound.filter((x) => typeof x === 'string') : [];
+        }
+        catch { /* fresh registry */ }
+        if (!dirs.includes(argusDir))
+            dirs.unshift(argusDir);
+        fs.writeFileSync(reg, JSON.stringify({ bound: dirs.slice(0, 16) }), 'utf8');
+    }
+    catch {
+        /* non-critical */
+    }
+}
+/** The cross-project registry (~/.argus/.bound) — existing dirs only. */
+export function readGlobalBoundList() {
+    try {
+        const reg = path.join(os.homedir(), '.argus', '.bound');
+        const parsed = JSON.parse(fs.readFileSync(reg, 'utf8'));
+        const dirs = Array.isArray(parsed.bound) ? parsed.bound.filter((x) => typeof x === 'string') : [];
+        return dirs.filter((d) => { try {
+            return fs.existsSync(d);
+        }
+        catch {
+            return false;
+        } });
+    }
+    catch {
+        return [];
+    }
 }
 function readBoundList(argusDir) {
     try {
@@ -74,12 +127,26 @@ function readBoundList(argusDir) {
 }
 /**
  * Resolve argus_dir for a Resource read (no per-call arg available).
- * Returns null (unbound) rather than throwing — the Resource degrades cleanly.
+ *
+ * Mirrors the tool chain minus the per-call arg: ARGUS_DIR env, else the same
+ * zero-config `~/.argus` default that tools write to — so a zero-config
+ * install's passive attention surface reads the SAME ledger its tools use.
+ * (§9.7 O1 방2. Previously env-only, which left every zero-config install's
+ * `argus://attention` permanently `{unbound}` while argus_predict happily
+ * wrote to ~/.argus — the return loop's front door was dark.)
+ *
+ * Stays null (unbound, cleanly degraded) ONLY when ARGUS_DIR is set but
+ * invalid — unexpanded `${...}`/`%...%` or a relative path. Falling back to
+ * ~/.argus in that case would silently read a different ledger than the one
+ * the user configured; unbound-with-hint is the resource's honest-failure
+ * form of the requireArgusDir throw.
  */
 export function resolveArgusDirForResource() {
     const env = process.env['ARGUS_DIR'];
-    if (typeof env === 'string' && env.length > 0 && path.isAbsolute(env)) {
+    if (typeof env === 'string' && env.length > 0) {
+        if (/\$\{[^}]*\}|%[A-Za-z_]+%/.test(env) || !path.isAbsolute(env))
+            return null;
         return path.resolve(env);
     }
-    return null;
+    return path.join(os.homedir(), '.argus');
 }

package/dist/lib/calendar.js

@@ -0,0 +1,75 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { calendarPath } from './layout.js';
+function ymdCompact(ymd) {
+    return ymd.replace(/-/g, '');
+}
+function addOneDay(ymd) {
+    const t = Date.parse(`${ymd}T00:00:00Z`);
+    if (Number.isNaN(t))
+        return ymd;
+    return new Date(t + 86_400_000).toISOString().slice(0, 10);
+}
+function escapeIcs(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/\r?\n/g, '\\n')
+        .replace(/,/g, '\\,')
+        .replace(/;/g, '\\;');
+}
+function foldLine(line) {
+    if (line.length <= 74)
+        return line;
+    const chunks = [];
+    let rest = line;
+    while (rest.length > 74) {
+        chunks.push(rest.slice(0, 74));
+        rest = rest.slice(74);
+    }
+    chunks.push(rest);
+    return chunks.map((chunk, i) => (i === 0 ? chunk : ` ${chunk}`)).join('\r\n');
+}
+export function renderReturnCalendarEvent(args) {
+    const start = ymdCompact(args.check_by);
+    const end = ymdCompact(addOneDay(args.check_by));
+    const stamp = args.created_at.replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+    const summary = `Argus return: ${args.predicate.slice(0, 80)}`;
+    const description = [
+        'An Argus prediction has reached its check date.',
+        `Predicate: ${args.predicate}`,
+        'Open your terminal and run argus_check_in, then argus_resolve if reality is clear.',
+    ].join('\n');
+    const lines = [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//Argus//Return Calendar//EN',
+        'CALSCALE:GREGORIAN',
+        'METHOD:PUBLISH',
+        'BEGIN:VEVENT',
+        `UID:${escapeIcs(args.id)}@argus.local`,
+        `DTSTAMP:${stamp}`,
+        `DTSTART;VALUE=DATE:${start}`,
+        `DTEND;VALUE=DATE:${end}`,
+        `SUMMARY:${escapeIcs(summary)}`,
+        `DESCRIPTION:${escapeIcs(description)}`,
+        'BEGIN:VALARM',
+        // DTSTART is local midnight of the check-by (an all-day event), so a POSITIVE
+        // offset lands on the morning OF the due date. `-PT9H` fired nine hours
+        // BEFORE midnight — 15:00 the previous afternoon — while the alarm text said
+        // "due today". This .ics is the only thing that brings a sealed bet back
+        // without an account, so it has to ring on the right day.
+        'TRIGGER;RELATED=START:PT9H',
+        'ACTION:DISPLAY',
+        `DESCRIPTION:${escapeIcs(summary)}`,
+        'END:VALARM',
+        'END:VEVENT',
+        'END:VCALENDAR',
+    ];
+    return `${lines.map(foldLine).join('\r\n')}\r\n`;
+}
+export async function writeReturnCalendarEvent(argusDir, args) {
+    const file = calendarPath(argusDir, args.id);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, renderReturnCalendarEvent(args), 'utf8');
+    return file;
+}

package/dist/lib/canonical-scales.js

@@ -0,0 +1,105 @@
+/**
+ * Canonical scales & units — the pre-rule normalization layer for M2 drift
+ * materiality (internal design notes §3, §10.4).
+ *
+ * Rules compare CANONICAL values, never raw labels. This module turns an ordinal
+ * label ("BBB", "Baa2", "Enterprise", "Maintenance") into a comparable number via
+ * a built-in ordinal map, and converts a few units into a common axis before the
+ * rule ever runs. When a label can't be placed on a known scale, this returns
+ * `null` — the caller routes that to `uncertain` (host-judgment lane), never a
+ * silent guess (§3.1, "규칙이 아니라 매번 모델 판정 = 스파인 위반").
+ *
+ * Alias normalization is the load-bearing win: Baa2 ≡ BBB, so a Moody's→S&P
+ * relabel is `unchanged`, not a manufactured downgrade (CAT-06).
+ */
+/** Normalize a label for lookup: trim, collapse spaces, lowercase. Ordinal maps
+ *  are keyed by this normalized form so "BBB ", "bbb", "BBB" all hit. */
+function normLabel(label) {
+    return label.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+// ── S&P / Moody's credit ratings (AAA=1 … D=22), with cross-agency aliases ──
+// The canonical axis is S&P notation; Moody's labels are aliases onto the same
+// rank so Baa2 ≡ BBB (CAT-06), A2 ≡ A, Ba1 ≡ BB+, etc.
+const SP_ORDER = [
+    'AAA', 'AA+', 'AA', 'AA-', 'A+', 'A', 'A-', 'BBB+', 'BBB', 'BBB-',
+    'BB+', 'BB', 'BB-', 'B+', 'B', 'B-', 'CCC+', 'CCC', 'CCC-', 'CC', 'C', 'D',
+];
+// Moody's, index-aligned to SP_ORDER above.
+const MOODYS_ORDER = [
+    'Aaa', 'Aa1', 'Aa2', 'Aa3', 'A1', 'A2', 'A3', 'Baa1', 'Baa2', 'Baa3',
+    'Ba1', 'Ba2', 'Ba3', 'B1', 'B2', 'B3', 'Caa1', 'Caa2', 'Caa3', 'Ca', 'C', 'DDD',
+];
+function buildCreditRanks() {
+    const r = {};
+    SP_ORDER.forEach((lbl, i) => {
+        r[normLabel(lbl)] = i + 1;
+        const m = MOODYS_ORDER[i];
+        if (m)
+            r[normLabel(m)] = i + 1; // alias onto the same rank
+    });
+    return r;
+}
+// ── LTS / lifecycle stages (Active=1 … EOL highest) ──
+const LTS_ORDER = ['Active', 'Maintenance', 'Security', 'Deprecated', 'EOL'];
+// ── Product tiers (Free=1 … Enterprise highest) ──
+const TIER_ORDER = ['Free', 'Trial', 'Starter', 'Pro', 'Business', 'Team', 'Enterprise'];
+// ── Generic quality letter grades (A=1 … F) ──
+const QUALITY_ORDER = ['A', 'B', 'C', 'D', 'E', 'F'];
+function buildOrdinal(order) {
+    const r = {};
+    order.forEach((lbl, i) => { r[normLabel(lbl)] = i + 1; });
+    return r;
+}
+/** Built-in scales, addressable by name from a premise's `scale` modifier. */
+export const BUILTIN_SCALES = {
+    sp_credit: { name: 'S&P/Moody\'s credit rating', kind: 'credit', ranks: buildCreditRanks() },
+    lts: { name: 'lifecycle stage', kind: 'lts', ranks: buildOrdinal(LTS_ORDER) },
+    tier: { name: 'product tier', kind: 'tier', ranks: buildOrdinal(TIER_ORDER) },
+    quality: { name: 'quality grade', kind: 'quality', ranks: buildOrdinal(QUALITY_ORDER) },
+};
+/**
+ * Map a label onto a named scale's ordinal rank. Returns null when the scale is
+ * unknown OR the label isn't on it — the caller routes null to `uncertain`
+ * (host-judgment lane), never a silent numeric guess (§3.1).
+ *
+ * A custom scale (user-provided ordered labels) can be passed inline via
+ * `customScales` so a premise isn't limited to the built-ins.
+ */
+export function normalizeLabel(scale, label, customScales) {
+    if (!scale)
+        return null;
+    const custom = customScales?.[scale];
+    if (custom) {
+        const ranks = Array.isArray(custom) ? buildOrdinal(custom) : custom.ranks;
+        const hit = ranks[normLabel(label)];
+        return typeof hit === 'number' ? hit : null;
+    }
+    const builtin = BUILTIN_SCALES[scale];
+    if (!builtin)
+        return null;
+    const hit = builtin.ranks[normLabel(label)];
+    return typeof hit === 'number' ? hit : null;
+}
+const UNIT_TABLE = {
+    // temperature: Kelvin ↔ Celsius (offset). Canonical = Celsius for delta axes.
+    k: { to: 'c', convert: (v) => v - 273.15 },
+    kelvin: { to: 'c', convert: (v) => v - 273.15 },
+    // fuel economy: mpg (US) → L/100km (reciprocal). Canonical = L/100km.
+    mpg: { to: 'l/100km', convert: (v) => (v === 0 ? Infinity : 235.215 / v) },
+    // percentage points and percent share a numeric magnitude; the AXIS (not the
+    // unit) disambiguates — handled by unit_axis, not here.
+};
+/**
+ * Convert a value from a source unit to its canonical unit. Returns null when the
+ * unit is unknown (caller keeps host_reported + low_confidence). When from===to
+ * or from is already canonical, returns the value unchanged.
+ */
+export function normalizeUnit(value, from) {
+    if (!from)
+        return null;
+    const key = from.trim().toLowerCase();
+    const conv = UNIT_TABLE[key];
+    if (!conv)
+        return { value, unit: key }; // unknown but not an error — pass through as-is unit-tagged
+    return { value: conv.convert(value), unit: conv.to };
+}