mixdog 0.9.4 → 0.9.6

package/src/runtime/channels/lib/scheduler.mjs

@@ -3,7 +3,7 @@ import { appendFile as _appendFile } from "fs";
 import { join, isAbsolute } from "path";
 import { tmpdir } from "os";
 import { randomUUID } from "crypto";
-import { DATA_DIR, DEFAULT_HOLIDAY_COUNTRY, isInQuietWindow } from "./config.mjs";
+import { DATA_DIR } from "./config.mjs";
 import { runScript as execScript, ensureNopluginDir } from "./executor.mjs";
 import { withFileLockSync } from "../../shared/atomic-file.mjs";
 import { makeAgentDispatch } from '../../agent/orchestrator/agent-runtime/agent-dispatch.mjs';
@@ -39,7 +39,6 @@ function logSchedule(msg) {
   if (!_schedLogTimer) _schedLogTimer = setTimeout(_flushScheduleLog, 2000);
 }
 
-import { isHoliday } from "./holidays.mjs";
 import { tryRead } from "./settings.mjs";
 // node-cron is an optional runtime dep. If the module isn't installed
 // (e.g. a fresh v0.6.190 where node_modules predates the package.json
@@ -104,7 +103,7 @@ function tzSnapshot(now, tz) {
 class Scheduler {
   nonInteractive;
   interactive;
-  channelsConfig;
+  channelId;
   promptsDir;
   tickTimer = null;
   lastFired = /* @__PURE__ */ new Map();
@@ -122,53 +121,16 @@ class Scheduler {
   // names skipped for today
   skippedTodayDate = "";
   // "YYYY-MM-DD" local date the skippedToday set belongs to
-  holidayCountry = null;
-  // ISO country code for holiday check
-  holidayChecked = "";
-  // "YYYY-MM-DD" last checked date
-  todayIsHoliday = false;
-  // cached result for today
-  quietSchedule = null;
-  // global quiet hours "HH:MM-HH:MM"
   cronJobs = /* @__PURE__ */ new Map();
   // name -> node-cron ScheduledTask for cron-expression entries
   //
-  // 0.1.62 wiring:
-  //   `topConfig` is the normalized top-level channels config from
-  //   loadConfig()/applyDefaults() — it carries `quiet`, `schedules`
-  //   at the top level. `channelsConfig` is still accepted separately
-  //   (channel metadata only, not quiet config) because resolveChannel()
-  //   needs the channel-label → platform-id map.
-  constructor(nonInteractive, interactive, channelsConfig, topConfig) {
+  // `channelId` is the single resolved main-channel id used when a schedule's
+  // `channel` flag is set (post-to-channel); absent flag → inject into session.
+  constructor(nonInteractive, interactive, channelId) {
     this.nonInteractive = nonInteractive.filter((s) => s.enabled !== false);
     this.interactive = interactive.filter((s) => s.enabled !== false);
-    this.channelsConfig = channelsConfig ?? null;
+    this.channelId = channelId ?? "";
     this.promptsDir = join(DATA_DIR, "prompts");
-    this._applyQuietConfig(topConfig);
-  }
-  /** Resolve quiet/schedules flags from the top-level config
-   *  (0.1.62 shape: `topConfig.quiet`, `topConfig.schedules`). Falls
-   *  through silently to defaults (empty schedule, holidays off,
-   *  respect flag default true) when topConfig is missing or malformed
-   *  — defensive, not legacy. */
-  _applyQuietConfig(topConfig) {
-    const cfg = (topConfig && typeof topConfig === "object") ? topConfig : null;
-    const quietSrc = cfg?.quiet ?? null;
-    const schedulesSrc = cfg?.schedules ?? null;
-    // Holidays: prefer an explicit ISO country code. Legacy boolean `true`
-    // from older setup UI builds is normalized to the local default country.
-    const hol = quietSrc?.holidays;
-    if (hol === true) {
-      this.holidayCountry = DEFAULT_HOLIDAY_COUNTRY;
-    } else if (typeof hol === "string" && hol) {
-      this.holidayCountry = hol.trim().toUpperCase();
-    } else {
-      this.holidayCountry = null;
-    }
-    // Quiet window string "HH:MM-HH:MM" from topConfig.quiet.schedule.
-    this.quietSchedule = quietSrc?.schedule ?? null;
-    // Opt-in flag: default true when unspecified, matching applyDefaults.
-    this.respectQuietSchedules = schedulesSrc?.respectQuiet !== false;
   }
   setInjectHandler(fn) {
     this.injectFn = fn;
@@ -372,8 +334,8 @@ ${Scheduler.INSTANCE_UUID}`;
       }
     }
   }
-  /** Fire path for a cron-triggered entry. Applies day/quiet/holiday
-   *  guards against the schedule's TZ (or local when absent). */
+  /** Fire path for a cron-triggered entry. Applies day guards against
+   *  the schedule's TZ (or local when absent). */
   async onCronFire(schedule, type) {
     const now = /* @__PURE__ */ new Date();
     const tz = schedule.timezone || null;
@@ -381,16 +343,6 @@ ${Scheduler.INSTANCE_UUID}`;
     const isWeekend = snap.dow === 0 || snap.dow === 6;
     const days = schedule.days ?? "daily";
     if (!this.matchesDays(days, snap.dow, isWeekend)) return;
-    if (this.holidayCountry) {
-      try {
-        const holiday = await isHoliday(this.tzDate(now, tz), this.holidayCountry);
-        if (holiday && (schedule.skipHolidays || days === "weekday")) {
-          logSchedule(`skipping "${schedule.name}" \u2014 public holiday\n`);
-          return;
-        }
-      } catch {}
-    }
-    if ((schedule.dnd || this.respectQuietSchedules) && this.isQuietHours(now, tz)) return;
     if (this.shouldSkip(schedule.name)) return;
     // Record lastFired only when the fire actually proceeds past
     // fireTimed's running/precondition guards (it resolves truthy on a
@@ -401,13 +353,6 @@ ${Scheduler.INSTANCE_UUID}`;
       (err) => process.stderr.write(`mixdog scheduler: ${schedule.name} failed: ${err}\n`)
     );
   }
-  /** Produce a Date whose calendar day matches the TZ-adjusted dateStr,
-   *  so holiday lookups by country work against the right day. */
-  tzDate(now, tz) {
-    if (!tz) return now;
-    const snap = tzSnapshot(now, tz);
-    return new Date(`${snap.dateStr}T12:00:00Z`);
-  }
   stop() {
     if (this.tickTimer) {
       clearInterval(this.tickTimer);
@@ -447,14 +392,11 @@ ${Scheduler.INSTANCE_UUID}`;
     } catch {}
     this.start();
   }
-  reloadConfig(nonInteractive, interactive, channelsConfig, topConfig, options = {}) {
+  reloadConfig(nonInteractive, interactive, channelId, options = {}) {
     this.nonInteractive = nonInteractive.filter((s) => s.enabled !== false);
     this.interactive = interactive.filter((s) => s.enabled !== false);
-    this.channelsConfig = channelsConfig ?? null;
+    this.channelId = channelId ?? "";
     this.promptsDir = join(DATA_DIR, "prompts");
-    this._applyQuietConfig(topConfig);
-    this.holidayChecked = "";
-    this.todayIsHoliday = false;
     if (this.deferred.size > 0 || this.skippedToday.size > 0) {
       process.stderr.write(`mixdog scheduler: reload clearing ${this.deferred.size} deferred, ${this.skippedToday.size} skipped
 `);
@@ -520,24 +462,9 @@ ${Scheduler.INSTANCE_UUID}`;
     );
   }
   async tickAsync() {
-    const now = /* @__PURE__ */ new Date();
-    const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
-    // All timed schedules are now handled exclusively by node-cron (registerCronJobs).
-    // tick() only drives the holiday cache refresh.
-    if (this.holidayCountry && this.holidayChecked !== dateStr) {
-      this.holidayChecked = dateStr;
-      try {
-        this.todayIsHoliday = await isHoliday(now, this.holidayCountry);
-        if (this.todayIsHoliday) {
-          process.stderr.write(`mixdog scheduler: today (${dateStr}) is a holiday \u2014 weekday schedules will be skipped
-`);
-        }
-      } catch (err) {
-        process.stderr.write(`mixdog scheduler: holiday check failed: ${err}
-`);
-        this.todayIsHoliday = false;
-      }
-    }
+    // All timed schedules are handled exclusively by node-cron
+    // (registerCronJobs). tick() no longer does any per-day work; the
+    // interval is kept for future cadence-driven work and lifecycle parity.
   }
   /** Day abbreviation → JS day number (0=Sun...6=Sat) */
   static DAY_ABBRS = {
@@ -557,18 +484,6 @@ ${Scheduler.INSTANCE_UUID}`;
     const dayList = days.split(",").map((d) => d.trim().toLowerCase());
     return dayList.some((d) => Scheduler.DAY_ABBRS[d] === dow);
   }
-  /** Check if current time is within global quiet hours (quiet.schedule).
-   *  tz optional — when set, HH:MM is evaluated in the given IANA zone.
-   *
-   *  Delegates to the shared, now TZ-aware isInQuietWindow(cfg, now, tz)
-   *  helper in lib/config.mjs. Holidays are passed as `false` here on
-   *  purpose: public-holiday skips for the scheduler are handled by the
-   *  separate holidayCountry / skipHolidays / days==="weekday" path in
-   *  onCronFire, so this quiet-window check stays schedule-window only —
-   *  identical to the prior local implementation. */
-  isQuietHours(now, tz) {
-    return isInQuietWindow({ schedule: this.quietSchedule, holidays: false }, now, tz);
-  }
   // ── Fire timed schedule ─────────────────────────────────────────────
   async fireTimed(schedule, type) {
     const execMode = schedule.exec ?? "prompt";
@@ -680,21 +595,20 @@ ${scriptResult}
     });
   }
   // ── Helpers ─────────────────────────────────────────────────────────
-  /** Resolve a channel label to its platform ID via channelsConfig, fallback to raw value */
-  resolveChannel(label) {
-    const entry = this.channelsConfig?.[label];
-    if (entry?.channelId) return entry.channelId;
-    // Misconfigured label: no channelsConfig entry, so we fall back to
-    // using the raw label as the channel id. Warn once per label so the
-    // misconfiguration is diagnosable without spamming stderr.
-    if (label != null) {
-      this._channelFallbackWarned ??= new Set();
-      if (!this._channelFallbackWarned.has(label)) {
-        this._channelFallbackWarned.add(label);
-        process.stderr.write(`mixdog scheduler: channel label "${label}" not found in channelsConfig — using it as a raw channel id\n`);
-      }
-    }
-    return label;
+  /**
+   * Map a schedule's `channel` flag to a target channel id. The flag is
+   * boolean-ish: any non-empty value except "false" (including legacy labels
+   * like "main") means "post to the main channel"; absent/false → "" (inject
+   * into the Lead session). No label resolution. A pure-digit / snowflake
+   * value is honored verbatim as an explicit id override (matches
+   * resolveWebhookChannelId in index.mjs).
+   */
+  resolveChannel(flag) {
+    if (flag == null) return "";
+    const v = String(flag).trim();
+    if (v === "" || v.toLowerCase() === "false") return "";
+    if (/^-?\d+$/.test(v)) return v;
+    return this.channelId ?? "";
   }
   /** Resolve prompt: try file first, fall back to inline text */
   resolvePrompt(schedule) {

package/src/runtime/channels/lib/webhook/deliveries.mjs

@@ -268,8 +268,9 @@ function appendDelivery(name, entry) {
 }
 // Dedup gate against a still-active claim or a successful prior delivery.
 // Only rows with status "received" (non-terminal claim) or "done"
-// (successful delivery) block a retry; terminal "failed" / "quiet-skip"
-// rows are NOT considered duplicates so a sender can legitimately
+// (successful delivery) block a retry; terminal "failed" rows (and any
+// other unknown/legacy terminal status) are NOT considered duplicates so
+// a sender can legitimately
 // redeliver the same id after a recoverable failure. Without this
 // scoping, every prior row would permanently dedup the id and stop
 // legit redelivery.

package/src/runtime/channels/lib/webhook.mjs

@@ -3,7 +3,6 @@ import { join } from "path";
 import { spawn, spawnSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { randomUUID } from "crypto";
-import { isInQuietWindow } from "./config.mjs";
 import { getWebhookAuthtoken } from "../../shared/config.mjs";
 import { readMarkdownDocument } from "../../shared/markdown-frontmatter.mjs";
 import { logWebhook } from "./webhook/log.mjs";
@@ -42,19 +41,8 @@ class WebhookServer {
   listenInFlight = false;
   noSecretWarned = false;
   ngrokProcess = null;
-  quiet = null;
-  // ctor accepts the TOP-LEVEL normalized config slice as the second arg:
-  //   new WebhookServer(config.webhook, { quiet: config.quiet })
-  constructor(config, topLevel) {
+  constructor(config) {
     this.config = config;
-    this._applyTopLevel(topLevel);
-  }
-  _applyTopLevel(src) {
-    this.quiet = null;
-    if (!src || typeof src !== "object") return;
-    if (src.quiet && typeof src.quiet === "object") {
-      this.quiet = src.quiet;
-    }
   }
   setEventPipeline(pipeline) {
     this.eventPipeline = pipeline;
@@ -241,7 +229,6 @@ class WebhookServer {
       const parsed = body ? JSON.parse(body) : {};
       const eventType = headers["x-github-event"] || null;
       const eventAction = parsed?.action || null;
-      if (this._maybeQuietSkip(name, eventType, eventAction, deliveryId, res)) return;
       // Invariant: skip self-generated GitHub issue_comment events. All
       // mixdog-authored issue comments are prefixed with "[mixdog "
       // (e.g. "[mixdog reviewer] ..."), so a comment.body starting with
@@ -341,32 +328,6 @@ class WebhookServer {
     }
     return true;
   }
-  // Quiet-hours skip: drop (do not queue) when webhook opt-in is on
-  // and current time falls inside the shared quiet window. Returns
-  // true when the request was answered with a 202 quiet-skip.
-  _maybeQuietSkip(name, eventType, eventAction, deliveryId, res) {
-    const webhookRespect = this.config?.respectQuiet === true;
-    const quietCfg = this.quiet
-      ? { schedule: this.quiet.schedule ?? null, holidays: this.quiet.holidays ?? false }
-      : null;
-    if (webhookRespect && quietCfg && isInQuietWindow(quietCfg, new Date())) {
-      logWebhook(`${name}: quiet-skip event=${eventType || "<none>"} action=${eventAction || "<none>"} (id=${deliveryId})`);
-      // Terminal delivery row: the `received` claim at the top of
-      // handleRequest must be resolved by a terminal status. Without
-      // it, deliveryExists() keeps the non-terminal row visible and
-      // dedupes every future retry of the same id forever.
-      appendDelivery(name, {
-        id: deliveryId,
-        status: "quiet-skip",
-        event: eventType,
-        action: eventAction,
-      });
-      res.writeHead(202, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ status: "quiet-skip", event: eventType, action: eventAction, id: deliveryId }));
-      return true;
-    }
-    return false;
-  }
   _listenWithRetry() {
     if (!this.server || this.listenInFlight) return;
     this.listenInFlight = true;
@@ -608,10 +569,8 @@ class WebhookServer {
     logWebhook("stopped (ngrok left running for reuse)");
     return closed;
   }
-  // reloadConfig(webhookCfg, topLevel, options?)
-  // `topLevel` mirrors the constructor: a top-level normalized config
-  // slice (typically `{ quiet }`).
-  async reloadConfig(config, topLevel, options = {}) {
+  // reloadConfig(webhookCfg, options?)
+  async reloadConfig(config, options = {}) {
     // Await server.close() before re-listen: server.close() is async and
     // releases the bound port only after the close callback fires. Calling
     // start() before that drains races the port and surfaces EADDRINUSE
@@ -619,7 +578,6 @@ class WebhookServer {
     // holds the port.
     await this.stop();
     this.config = config;
-    this._applyTopLevel(topLevel);
     if (options.autoStart !== false && config.enabled) this.start();
   }
   // ── Webhook handler ───────────────────────────────────────────────
@@ -633,14 +591,17 @@ class WebhookServer {
     // The signature gate (below) fails closed on any WEBHOOK.md
     // endpoint lacking a secret, so dropping `mode` does not weaken auth.
     // `instructions` carries the markdown body (the prompt) so callers read
-    // one file instead of a config.json + instructions.md pair.
-    const handler = { channel: null, role: "webhook-handler", model: null, instructions: "" };
+    // one file instead of a config.json + instructions.md pair. Frontmatter
+    // `name`/`description` (SKILL.md convention) are display-only: dir name
+    // stays the canonical identity/URL routing key, so `name` is ignored here.
+    const handler = { channel: null, role: "webhook-handler", model: null, description: "", instructions: "" };
     if (existsSync(mdPath)) {
       try {
         const { frontmatter, body } = readMarkdownDocument(readFileSync(mdPath, "utf8"));
         if (frontmatter.channel) handler.channel = frontmatter.channel;
         if (typeof frontmatter.role === "string" && frontmatter.role) handler.role = frontmatter.role;
         if (typeof frontmatter.model === "string" && frontmatter.model) handler.model = frontmatter.model;
+        handler.description = String(frontmatter.description || "");
         handler.instructions = String(body || "").trim();
       } catch {
       }

package/src/runtime/memory/index.mjs

@@ -78,6 +78,7 @@ import { readBody, sendJson, sendError, isLocalOrigin, normalizeCoreProjectId }
 import { scheduledCycle1Signature, scheduledCycle2Signature, scheduledCycle3Signature } from './lib/cycle-signatures.mjs'
 import { createTranscriptIngest } from './lib/transcript-ingest.mjs'
 import { createEmbeddingWarmup } from './lib/embedding-warmup.mjs'
+import { init as initKoMorph } from './lib/ko-morph.mjs'
 import { createCycleLlmAdapters } from './lib/cycle-llm-adapters.mjs'
 import { createCycleScheduler } from './lib/cycle-scheduler.mjs'
 import { createQueryHandlers } from './lib/query-handlers.mjs'
@@ -621,6 +622,14 @@ async function _initRuntime() {
   // Fire-and-forget on the embedding worker thread; never awaited so it does
   // not delay init() returning or the memory-ready signal.
   _embeddingWarmup.fireDeferred()
+  // Boot-edge Korean morph warmup. Same fire-and-forget style: lazy async init
+  // downloads+caches the Kiwi model once under DATA_DIR/kiwi-model/<version>,
+  // then builds the WASM analyzer. On any failure ko-morph stays null and
+  // buildFtsQuery keeps the websearch_to_tsquery fallback (never throws here).
+  // Skipped in secondary mode (query path lives on the primary).
+  if (!memorySecondaryMode()) {
+    initKoMorph(DATA_DIR, __mixdogMemoryLog).catch(() => {})
+  }
 }
 
 function _beginRuntimeInit() {

package/src/runtime/memory/lib/core-memory-store.mjs

@@ -30,7 +30,8 @@ const VALID_CAT = new Set([
 const SIM_RECALL = 0.65
 const CORE_DEDUP_TOP_K = 5
 
-export const CORE_SUMMARY_MAX = 120
+export const CORE_SUMMARY_MAX = 100
+export const CORE_ELEMENT_MAX = 40
 
 function trimOrNull(v) {
   if (v == null) return null
@@ -204,6 +205,9 @@ export async function addCore(dataDir, { element, summary, category }, projectId
   const el = trimOrNull(element)
   const sm = trimOrNull(summary) ?? el
   if (!el || !sm) throw new Error('add requires element and summary')
+  if (el.length > CORE_ELEMENT_MAX) {
+    throw new Error(`core element too long (${el.length} chars, max ${CORE_ELEMENT_MAX}) — element is a short key/title, not content.`)
+  }
   if (sm.length > CORE_SUMMARY_MAX) {
     throw new Error(`core summary too long (${sm.length} chars, max ${CORE_SUMMARY_MAX}) — core memory must be 1 fact in 1-2 sentences; procedures, multi-step, or code belong in recap or docs. Compress and retry.`)
   }

package/src/runtime/memory/lib/ko-morph.mjs

@@ -0,0 +1,195 @@
+// Korean morphological analysis for the recall FTS query path.
+//
+// Wraps kiwi-nlp (WASM). The npm package ships ONLY the WASM binary + JS glue,
+// NOT the language model — so the model archive is downloaded ONCE at boot from
+// the bab2min/Kiwi GitHub Release and cached under a gitignored data dir
+// (precedent: the embedding ONNX model is runtime-downloaded/cached the same
+// way). No per-query network. If download or WASM init fails, analyze() returns
+// null and the caller (buildFtsQuery) falls back to its prior websearch path.
+//
+// Lifecycle:
+//   init(dataDir)  — lazy, async, idempotent, safe to call fire-and-forget at
+//                    boot. Downloads+extracts model on first run, then builds
+//                    the Kiwi instance. Never throws (logs once, stays null).
+//   ready()        — true once the Kiwi instance is built.
+//   analyze(text)  — sync; returns TokenInfo[] or null when not ready.
+//   stems(text)    — sync; content-morpheme stems (NNG/NNP/VV/VA/XR/SL) or null.
+import fs from 'node:fs'
+import path from 'node:path'
+import zlib from 'node:zlib'
+
+// Pinned model release. The WASM package version (kiwi-nlp in package.json) and
+// this model version are independent; base model is format-stable across the
+// 0.2x line. Bump deliberately, never floating.
+// Model version MUST match the kiwi-nlp WASM version — a mismatched model
+// aborts the WASM at build() with an opaque numeric error. Pinned pair:
+// kiwi-nlp@0.21.0 (package.json) + model v0.21.0 KnLM. Deliberately NOT
+// 0.23.0: its base model ships CoNg (72MB, ~940MB RSS after build) vs
+// KnLM's 35MB download / ~560MB build peak, and recall stemming gains
+// nothing from the CoNg accuracy delta.
+export const KIWI_MODEL_VERSION = 'v0.21.0'
+const KIWI_MODEL_ASSET = `kiwi_model_${KIWI_MODEL_VERSION}_base.tgz`
+const KIWI_MODEL_URL = `https://github.com/bab2min/Kiwi/releases/download/${KIWI_MODEL_VERSION}/${KIWI_MODEL_ASSET}`
+
+// Model files KiwiBuilder.build({ modelFiles }) needs from the extracted
+// archive (v0.21.0 base layout: KnLM = sj.knlm + sj.morph).
+const REQUIRED_MODEL_FILES = [
+  'combiningRule.txt', 'default.dict', 'extract.mdl', 'sj.knlm', 'sj.morph',
+]
+// Optional files loaded when present (loadMultiDict / loadTypoDict defaults).
+const OPTIONAL_MODEL_FILES = ['multi.dict', 'skipbigram.mdl', 'typo.dict']
+
+// Content-morpheme POS tags whose stems are worth indexing against search_tsv.
+// NNG/NNP nouns, VV/VA predicate stems, XR root, SL foreign(latin) — matches
+// the brief. Endings/particles/josa are intentionally dropped.
+const CONTENT_TAGS = new Set(['NNG', 'NNP', 'VV', 'VA', 'XR', 'SL'])
+
+let _state = 'idle' // idle | loading | ready | failed
+let _initPromise = null
+let _kiwi = null
+let _log = () => {}
+let _initMs = 0
+
+export function isReady() { return _state === 'ready' && _kiwi != null }
+export function state() { return _state }
+export function initLatencyMs() { return _initMs }
+
+function modelDir(dataDir) {
+  return path.join(dataDir, 'kiwi-model', KIWI_MODEL_VERSION)
+}
+
+function hasAllRequired(dir) {
+  try {
+    return REQUIRED_MODEL_FILES.every(f => fs.existsSync(path.join(dir, f)))
+  } catch { return false }
+}
+
+// Minimal POSIX/ustar tar reader over an already-gunzipped buffer. Avoids a
+// node-tar dependency for a one-shot boot extraction. Handles regular files
+// (typeflag '0'/'\0') and the GNU/pax long-name records well enough for the
+// flat Kiwi model archive (all entries live under a single top-level dir).
+function extractTar(buf, destDir) {
+  let offset = 0
+  const written = []
+  while (offset + 512 <= buf.length) {
+    const header = buf.subarray(offset, offset + 512)
+    // Two consecutive zero blocks mark end of archive.
+    if (header.every(b => b === 0)) break
+    let name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '')
+    const sizeStr = header.subarray(124, 136).toString('utf8').replace(/\0.*$/, '').trim()
+    const size = parseInt(sizeStr, 8) || 0
+    const typeflag = String.fromCharCode(header[156]) || '0'
+    // ustar prefix (name continuation) at 345..500.
+    const prefix = header.subarray(345, 500).toString('utf8').replace(/\0.*$/, '')
+    if (prefix) name = `${prefix}/${name}`
+    offset += 512
+    const body = buf.subarray(offset, offset + size)
+    offset += Math.ceil(size / 512) * 512
+    if (typeflag !== '0' && typeflag !== '\0' && typeflag !== '') continue
+    // Flatten: take basename only; the archive nests files under one dir.
+    const base = name.split('/').filter(Boolean).pop()
+    if (!base) continue
+    fs.writeFileSync(path.join(destDir, base), body)
+    written.push(base)
+  }
+  return written
+}
+
+async function downloadAndExtractModel(dataDir) {
+  const dir = modelDir(dataDir)
+  if (hasAllRequired(dir)) return dir
+  fs.mkdirSync(dir, { recursive: true })
+  _log(`[memory-service] kiwi model missing — downloading ${KIWI_MODEL_ASSET} (~35MB) once\n`)
+  const res = await fetch(KIWI_MODEL_URL, { redirect: 'follow' })
+  if (!res.ok) throw new Error(`kiwi model download HTTP ${res.status}`)
+  const gz = Buffer.from(await res.arrayBuffer())
+  const tar = zlib.gunzipSync(gz)
+  extractTar(tar, dir)
+  if (!hasAllRequired(dir)) {
+    throw new Error(`kiwi model extract incomplete under ${dir}`)
+  }
+  return dir
+}
+
+function readModelFiles(dir) {
+  const modelFiles = {}
+  for (const f of REQUIRED_MODEL_FILES) {
+    modelFiles[f] = new Uint8Array(fs.readFileSync(path.join(dir, f)))
+  }
+  for (const f of OPTIONAL_MODEL_FILES) {
+    const p = path.join(dir, f)
+    if (fs.existsSync(p)) modelFiles[f] = new Uint8Array(fs.readFileSync(p))
+  }
+  return modelFiles
+}
+
+// Lazy, idempotent, never-throwing init. Fire-and-forget at boot.
+export async function init(dataDir, log = () => {}) {
+  if (_state === 'ready') return true
+  if (_initPromise) return _initPromise
+  _log = typeof log === 'function' ? log : (() => {})
+  _state = 'loading'
+  const t0 = Date.now()
+  _initPromise = (async () => {
+    // Resolve the WASM path from the installed package without hard-importing
+    // (keeps the whole feature optional if kiwi-nlp isn't installed).
+    // NOTE: must go through module resolution (import.meta.resolve) — a bare
+    // `new URL(spec, import.meta.url)` resolves relative to THIS file's
+    // directory, not node_modules.
+    const { KiwiBuilder } = await import('kiwi-nlp')
+    const wasmUrl = import.meta.resolve('kiwi-nlp/dist/kiwi-wasm.wasm')
+    const wasmPath = wasmUrl.startsWith('file:')
+      ? (await import('node:url')).fileURLToPath(wasmUrl)
+      : wasmUrl
+    const dir = await downloadAndExtractModel(dataDir)
+    const modelFiles = readModelFiles(dir)
+    const builder = await KiwiBuilder.create(wasmPath)
+    // modelType 'knlm' = fast KnLM (sj.knlm); loadMultiDict/loadTypoDict only
+    // engage if the optional files were present.
+    _kiwi = await builder.build({ modelFiles, modelType: 'knlm' })
+    _state = 'ready'
+    _initMs = Date.now() - t0
+    _log(`[memory-service] kiwi morph ready in ${_initMs}ms (model ${KIWI_MODEL_VERSION}, rss≈${Math.round(process.memoryUsage().rss / 1e6)}MB)\n`)
+    return true
+  })().catch(err => {
+    _state = 'failed'
+    _kiwi = null
+    _log(`[memory-service] kiwi morph init failed — recall stays lexical: ${err?.message || err}\n`)
+    return false
+  })
+  return _initPromise
+}
+
+// Sync morphological analysis. Returns TokenInfo[] or null when not ready.
+export function analyze(text) {
+  if (!isReady()) return null
+  const s = String(text ?? '')
+  if (!s) return null
+  try {
+    const r = _kiwi.analyze(s)
+    return Array.isArray(r?.tokens) ? r.tokens : null
+  } catch {
+    return null
+  }
+}
+
+// Content-morpheme stem forms for a Korean phrase. null when not ready.
+// "개선을" → ['개선']; "개선하고" → ['개선','하'] filtered to content tags.
+export function stems(text) {
+  const tokens = analyze(text)
+  if (!tokens) return null
+  const out = []
+  for (const t of tokens) {
+    if (!t || !CONTENT_TAGS.has(t.tag)) continue
+    const form = String(t.str || '').trim()
+    if (form.length >= 1) out.push(form)
+  }
+  return out
+}
+
+export function reset() {
+  _state = 'idle'
+  _initPromise = null
+  _kiwi = null
+  _initMs = 0
+}