@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/embed/cli.mjs

@@ -41,6 +41,83 @@ function logPath(homeDir = os.homedir()) {
   return path.join(runtimeDir(homeDir), LOG_FILE);
 }
 
+// ---------------------------------------------------------------------------
+// Log rotation
+//
+// The embed daemon writes its stdout/stderr to a single appended file. The
+// file descriptor is opened by the parent process at spawn time; the daemon
+// has no opportunity to reopen mid-flight. Rotation therefore happens at
+// each daemon spawn: if the existing log exceeds the size cap we shift
+// segments (.log → .log.1 → .log.2 → …) and drop the oldest, then the
+// spawn opens a fresh empty file.
+//
+// CONSTRUCT_EMBED_LOG_MAX_MB sets the rotation threshold (default 50 MB).
+// CONSTRUCT_EMBED_LOG_KEEP    sets retained segment count (default 3).
+// Worst-case disk footprint is (MAX_MB * (KEEP + 1)).
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_MB = 50;
+const DEFAULT_KEEP = 3;
+const HARD_CAP_MAX_MB = 500;     // refuse absurd configured values
+const HARD_CAP_KEEP = 20;
+
+function rotationConfig(env = process.env) {
+  const maxMbRaw = Number.parseInt(env.CONSTRUCT_EMBED_LOG_MAX_MB ?? '', 10);
+  const keepRaw = Number.parseInt(env.CONSTRUCT_EMBED_LOG_KEEP ?? '', 10);
+  const maxMb = Number.isFinite(maxMbRaw) && maxMbRaw > 0 ? Math.min(maxMbRaw, HARD_CAP_MAX_MB) : DEFAULT_MAX_MB;
+  const keep = Number.isFinite(keepRaw) && keepRaw >= 0 ? Math.min(keepRaw, HARD_CAP_KEEP) : DEFAULT_KEEP;
+  return { maxBytes: maxMb * 1024 * 1024, keep };
+}
+
+/**
+ * Rotate the embed daemon log if it exceeds the size cap. Exported for tests.
+ *
+ * @param {string} log        - Absolute path to the live log file
+ * @param {object} [env]      - Env object (default: process.env)
+ * @returns {{ rotated: boolean, sizeBytes: number, droppedSegment?: string }}
+ */
+export function rotateEmbedLogIfNeeded(log, env = process.env) {
+  let sizeBytes = 0;
+  try {
+    sizeBytes = fs.statSync(log).size;
+  } catch (err) {
+    if (err.code === 'ENOENT') return { rotated: false, sizeBytes: 0 };
+    process.stderr.write(`[cli.mjs] rotateEmbedLog stat: ${err.message}\n`);
+    return { rotated: false, sizeBytes: 0 };
+  }
+
+  const { maxBytes, keep } = rotationConfig(env);
+  if (sizeBytes <= maxBytes) return { rotated: false, sizeBytes };
+
+  // Shift segments oldest-first: .{keep} gets dropped, .{n} → .{n+1}, .log → .log.1
+  let droppedSegment;
+  try {
+    const oldest = `${log}.${keep}`;
+    if (keep === 0) {
+      // Retention of 0 means rotate-and-discard: the existing log is removed,
+      // no segment is kept.
+      fs.rmSync(log, { force: true });
+      droppedSegment = log;
+      return { rotated: true, sizeBytes, droppedSegment };
+    }
+    if (fs.existsSync(oldest)) {
+      fs.rmSync(oldest, { force: true });
+      droppedSegment = oldest;
+    }
+    for (let n = keep - 1; n >= 1; n--) {
+      const from = `${log}.${n}`;
+      const to = `${log}.${n + 1}`;
+      if (fs.existsSync(from)) fs.renameSync(from, to);
+    }
+    fs.renameSync(log, `${log}.1`);
+  } catch (err) {
+    process.stderr.write(`[cli.mjs] rotateEmbedLog: ${err.message}\n`);
+    return { rotated: false, sizeBytes };
+  }
+
+  return { rotated: true, sizeBytes, droppedSegment };
+}
+
 // ---------------------------------------------------------------------------
 // State helpers
 // ---------------------------------------------------------------------------
@@ -140,6 +217,7 @@ export async function autoStartEmbedIfNeeded(env = process.env, rootDir, homeDir
     const workerPath = path.join(resolvedRoot, 'lib', 'embed', 'worker.mjs');
     const log = logPath(homeDir);
     fs.mkdirSync(path.dirname(log), { recursive: true });
+    rotateEmbedLogIfNeeded(log, env);
     const fd = fs.openSync(log, 'a');
 
     const child = spawn(process.execPath, [workerPath], {
@@ -149,7 +227,18 @@ export async function autoStartEmbedIfNeeded(env = process.env, rootDir, homeDir
     });
     child.unref();
 
-    writeState({ pid: child.pid, configPath: 'auto', startedAt: new Date().toISOString() }, homeDir);
+    let resolvedRootDir = homeDir;
+    try {
+      const { resolveRootDir } = await import('./daemon.mjs');
+      resolvedRootDir = resolveRootDir(env, process.cwd());
+    } catch { /* fall back to homeDir */ }
+
+    writeState({
+      pid: child.pid,
+      configPath: 'auto',
+      startedAt: new Date().toISOString(),
+      rootDir: resolvedRootDir,
+    }, homeDir);
     return { started: true, pid: child.pid };
   } catch (err) {
     return { started: false, reason: `spawn_failed: ${err.message}` };
@@ -196,6 +285,7 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPat
   const workerArgs = configPath ? [workerPath, '--config', configPath] : [workerPath];
   const log = logPath(homeDir);
   fs.mkdirSync(path.dirname(log), { recursive: true });
+  rotateEmbedLogIfNeeded(log, process.env);
   const fd = fs.openSync(log, 'a');
 
   const child = spawn(process.execPath, workerArgs, {
@@ -206,7 +296,21 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPat
   fs.closeSync(fd);
   child.unref();
 
-  writeState({ pid: child.pid, configPath: configPath ?? 'auto', startedAt: new Date().toISOString() }, homeDir);
+  // Resolve rootDir using the same precedence the spawned worker will so the
+  // operator can see which inbox is being watched via `construct embed status`.
+
+  let resolvedRootDir = homeDir;
+  try {
+    const { resolveRootDir } = await import('./daemon.mjs');
+    resolvedRootDir = resolveRootDir(process.env, process.cwd());
+  } catch { /* fall back to homeDir */ }
+
+  writeState({
+    pid: child.pid,
+    configPath: configPath ?? 'auto',
+    startedAt: new Date().toISOString(),
+    rootDir: resolvedRootDir,
+  }, homeDir);
 
   // Brief liveness check — detects immediate crashes (e.g. missing module, bad config path)
   await new Promise(r => setTimeout(r, _livenessCheckMs));
@@ -245,15 +349,32 @@ function cmdEmbedStop(_args, { homeDir = os.homedir() } = {}) {
 // Subcommand: status
 // ---------------------------------------------------------------------------
 
-function cmdEmbedStatus(_args, { homeDir = os.homedir() } = {}) {
+async function cmdEmbedStatus(_args, { homeDir = os.homedir() } = {}) {
   const state = readRunningState(homeDir);
   if (!state) {
     process.stdout.write('embed daemon: stopped\n');
     return;
   }
+
+  // Re-resolve rootDir using the same precedence the daemon would so the
+  // operator sees which inbox is actually being watched (CX_DATA_DIR override,
+  // walked-up project root, or homedir fallback).
+
+  let rootDir = state.rootDir;
+  if (!rootDir) {
+    try {
+      const { resolveRootDir } = await import('./daemon.mjs');
+      rootDir = resolveRootDir(process.env, process.cwd());
+    } catch {
+      rootDir = homeDir;
+    }
+  }
+
   process.stdout.write(`embed daemon: running\n`);
   process.stdout.write(`  pid:        ${state.pid}\n`);
   process.stdout.write(`  config:     ${state.configPath}\n`);
+  process.stdout.write(`  rootDir:    ${rootDir}\n`);
+  process.stdout.write(`  inbox:      ${path.join(rootDir, '.cx', 'inbox')}\n`);
   process.stdout.write(`  started at: ${state.startedAt}\n`);
   process.stdout.write(`  log:        ${logPath(homeDir)}\n`);
 }

package/lib/embed/daemon.mjs

@@ -26,7 +26,7 @@
 
 import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 import { loadEmbedConfig } from './config.mjs';
 import { Scheduler } from './scheduler.mjs';
@@ -109,8 +109,44 @@ async function resolveLLMKey(varName, env) {
 
 // ─── Root dir resolution ─────────────────────────────────────────────────────
 
-function resolveRootDir(env = process.env) {
-  return (env.CX_DATA_DIR ?? '').trim() || homedir();
+// Cap upward search so a daemon launched from deep in the filesystem cannot
+// fan out to thousands of stat() calls in pathological layouts.
+
+const PROJECT_WALKUP_MAX = 10;
+
+/**
+ * Walk up from `startDir` looking for a directory that contains `.cx/context.md`.
+ * Returns the project root path, or null if nothing is found within the cap.
+ * Exported for unit tests.
+ */
+export function findProjectRoot(startDir, { maxLevels = PROJECT_WALKUP_MAX } = {}) {
+  if (!startDir || typeof startDir !== 'string') return null;
+  let current = startDir;
+  for (let i = 0; i <= maxLevels; i++) {
+    try {
+      if (existsSync(join(current, '.cx', 'context.md'))) return current;
+    } catch { /* skip unreadable dir */ }
+    const parent = dirname(current);
+    if (!parent || parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+
+/**
+ * Resolve the daemon's rootDir.
+ *
+ * Precedence:
+ *   1. `CX_DATA_DIR` env override (operator authority)
+ *   2. Project root discovered by walking up from `cwd` looking for `.cx/context.md`
+ *   3. `homedir()` fallback
+ */
+export function resolveRootDir(env = process.env, cwd = process.cwd()) {
+  const override = (env.CX_DATA_DIR ?? '').trim();
+  if (override) return override;
+  const projectRoot = findProjectRoot(cwd);
+  if (projectRoot) return projectRoot;
+  return homedir();
 }
 
 function resolveWorkspaceDir(env = process.env) {
@@ -708,7 +744,10 @@ this.#scheduler.register(
       async () => {
         const result = await this.#inboxWatcher.poll();
         if (result.processed.length) {
-          process.stderr.write(`[embed] Inbox: ingested ${result.processed.length} file(s) from [${result.dirs.join(', ')}]\n`);
+          const { getRebrand } = await import('../profiles/rebrand.mjs');
+          const { signalNoun } = getRebrand(this.#rootDir);
+          const noun = result.processed.length === 1 ? signalNoun : `${signalNoun}s`;
+          process.stderr.write(`[embed] Classified ${result.processed.length} ${noun} from [${result.dirs.join(', ')}]\n`);
           addObservation(this.#rootDir, {
             role: 'construct',
             category: 'insight',

package/lib/embed/docs-lifecycle.mjs

@@ -64,7 +64,7 @@ export function detectDocGaps(target, opts = {}) {
   const gaps = [];
 
   if (target.access === 'remote') {
-    // Remote-only targets: can't inspect filesystem, skip for now
+    // Remote-only targets have no local filesystem to inspect; gap detection requires the local docs tree.
     return gaps;
   }
 

package/lib/embed/inbox.mjs

@@ -21,14 +21,16 @@
  *   // result: { processed: [...], skipped: number, errors: [...] }
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
-import { isExtractableDocumentPath } from '../document-extract.mjs';
+import { homedir } from 'node:os';
+import { isExtractableDocumentPath, AUDIO_VIDEO_EXTS } from '../document-extract.mjs';
 import { ingestDocuments } from '../document-ingest.mjs';
 import { addObservation } from '../observation-store.mjs';
 import { inferKnowledgeTarget, knowledgeDirForCategory } from '../knowledge/layout.mjs';
 import { docLaneDir, suggestDocsLaneForFile } from '../docs-routing.mjs';
 import { shouldCreateCx } from '../project-detection.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 import { prepareIntakeForIngestedFile } from '../intake/prepare.mjs';
 import { loadIntakeConfig, INTAKE_DEFAULT_MAX_DEPTH } from '../intake/intake-config.mjs';
 
@@ -38,6 +40,37 @@ const DOCS_INTAKE_SUBDIR = 'docs/intake';
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB hard cap
 const STALE_STATE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
+// ─── Extraction-warning helpers ───────────────────────────────────────────────
+
+function extractionWarningsLog() {
+  return join(homedir(), '.cx', 'intake', 'extraction-warnings.jsonl');
+}
+
+function needsAsrDir() {
+  return join(homedir(), '.cx', 'intake', 'needs-asr');
+}
+
+function writeExtractionWarning({ sourcePath, droppedInfo }) {
+  if (!droppedInfo?.length) return;
+  const logPath = extractionWarningsLog();
+  try {
+    mkdirSync(join(homedir(), '.cx', 'intake'), { recursive: true });
+    const line = JSON.stringify({ ts: new Date().toISOString(), sourcePath, droppedInfo }) + '\n';
+    appendFileSync(logPath, line);
+  } catch { /* non-fatal */ }
+}
+
+function writeAsrPacket({ sourcePath, extension, errorMessage }) {
+  try {
+    const dir = needsAsrDir();
+    mkdirSync(dir, { recursive: true });
+    const id = `asr-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const packet = { id, ts: new Date().toISOString(), sourcePath, extension, error: errorMessage };
+    writeFileSync(join(dir, `${id}.json`), JSON.stringify(packet, null, 2));
+    return id;
+  } catch { return null; }
+}
+
 function nextAvailablePath(targetPath) {
   if (!existsSync(targetPath)) return targetPath;
   const dot = targetPath.lastIndexOf('.');
@@ -90,6 +123,7 @@ function writeState(rootDir, state) {
   
   // Only create .cx directories if this is an initialized project
   if (shouldCreateCx(rootDir)) {
+    ensureCxDir(rootDir);
     mkdirSync(join(rootDir, '.cx', 'runtime'), { recursive: true });
     writeFileSync(p, JSON.stringify(state, null, 2) + '\n');
   }
@@ -304,6 +338,10 @@ export class InboxWatcher {
               if (contentIdx !== -1) extractedText = md.slice(contentIdx + 20).trim();
             } catch (err) { process.stderr.write('[inbox.mjs] read-extracted-text: ' + (err?.message ?? String(err)) + '\n'); }
 
+            // Write extraction warnings JSONL for any dropped structured content.
+            const droppedInfo = fileResult.droppedInfo ?? [];
+            writeExtractionWarning({ sourcePath: candidate.path, droppedInfo });
+
             recordInboxObservation(this.#rootDir, {
               sourcePath: candidate.path,
               outputPath: fileResult.outputPath,
@@ -331,6 +369,7 @@ export class InboxWatcher {
                   outputPath: fileResult.outputPath,
                   characters: fileResult.characters,
                   knowledgeSubdir,
+                  droppedInfo,
                 },
                 env: this.#env,
               });
@@ -345,7 +384,15 @@ export class InboxWatcher {
             processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId });
           }
         } catch (err) {
-          errors.push({ path: candidate.path, error: err.message });
+          // Audio/video files cannot be text-extracted without ASR. Route to
+          // the needs-asr queue so the signal is preserved for later processing.
+          if (err.code === 'ASR_REQUIRED') {
+            const asrId = writeAsrPacket({ sourcePath: candidate.path, extension: err.extension, errorMessage: err.message });
+            state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), needsAsr: true, asrId };
+            processed.push({ path: candidate.path, needsAsr: true, asrId });
+          } else {
+            errors.push({ path: candidate.path, error: err.message });
+          }
         }
       }
     }

package/lib/embed/role-framing.mjs

@@ -12,7 +12,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const REGISTRY_PATH = join(__dirname, '..', '..', 'agents', 'registry.json');
+const REGISTRY_PATH = join(__dirname, '..', '..', 'specialists', 'registry.json');
 
 let _registryCache = null;
 
@@ -22,7 +22,7 @@ function loadRegistry() {
     _registryCache = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
   } catch (err) {
     process.stderr.write('[role-framing.mjs] loadRegistry: ' + (err?.message ?? String(err)) + '\n');
-    _registryCache = { agents: [] };
+    _registryCache = { specialists: [] };
   }
   return _registryCache;
 }
@@ -35,7 +35,7 @@ function loadRegistry() {
 export function getOrientation(roleName) {
   if (!roleName) return null;
   const registry = loadRegistry();
-  const agent = (registry.agents ?? []).find((a) => a.name === roleName);
+  const agent = (registry.specialists ?? []).find((a) => a.name === roleName);
   return agent?.embedOrientation ?? null;
 }
 

package/lib/embed/scheduler.mjs

@@ -4,24 +4,30 @@
  * Lightweight alternative to a full cron library — runs tasks at fixed
  * intervals, tracks last-run times, and supports graceful shutdown.
  * Zero external deps.
+ *
+ * One-shot startup jobs MUST set `repeat: false`. With `repeat: true`
+ * (the default) and `intervalMs: 0`, the timer fires on every event-loop
+ * tick — the bug that filled embed-daemon.log to 34 GB before this option
+ * was added.
  */
 
 export class Scheduler {
-  #tasks = new Map();   // id → { fn, intervalMs, lastRun, timer, label }
+  #tasks = new Map();   // id → { fn, intervalMs, lastRun, timer, label, repeat }
   #running = false;
 
   /**
    * Register a task. Returns the task id.
    * @param {string} label       - Human-readable name for logging
-   * @param {number} intervalMs  - How often to run (ms)
+   * @param {number} intervalMs  - How often to run (ms); ignored when repeat is false
    * @param {Function} fn        - Async function to call; receives { label, lastRun }
    * @param {object} [opts]
    * @param {boolean} [opts.runImmediately=false] - Run once before first interval fires
    * @param {boolean} [opts.unref=false]           - Call timer.unref() so this task does not keep the event loop alive (use in tests)
+   * @param {boolean} [opts.repeat=true]           - When false, the task is one-shot: it runs once (immediately if runImmediately, otherwise after intervalMs) and never re-arms. Required for startup jobs that pass intervalMs: 0.
    */
-  register(label, intervalMs, fn, { runImmediately = false, unref = false } = {}) {
+  register(label, intervalMs, fn, { runImmediately = false, unref = false, repeat = true } = {}) {
     const id = `${label}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    const task = { label, intervalMs, fn, lastRun: null, timer: null, runImmediately, unref };
+    const task = { label, intervalMs, fn, lastRun: null, timer: null, runImmediately, unref, repeat };
     this.#tasks.set(id, task);
 
     if (this.#running) {
@@ -50,6 +56,7 @@ export class Scheduler {
     for (const task of this.#tasks.values()) {
       if (task.timer) {
         clearInterval(task.timer);
+        clearTimeout(task.timer);
         task.timer = null;
       }
     }
@@ -60,7 +67,10 @@ export class Scheduler {
    */
   unregister(id) {
     const task = this.#tasks.get(id);
-    if (task?.timer) clearInterval(task.timer);
+    if (task?.timer) {
+      clearInterval(task.timer);
+      clearTimeout(task.timer);
+    }
     this.#tasks.delete(id);
   }
 
@@ -74,6 +84,7 @@ export class Scheduler {
       intervalMs: t.intervalMs,
       lastRun: t.lastRun,
       active: Boolean(t.timer),
+      repeat: t.repeat,
     }));
   }
 
@@ -83,6 +94,23 @@ export class Scheduler {
         process.stderr.write(`[scheduler] ${task.label} error: ${err.message}\n`);
       });
     }
+
+    // One-shot jobs do not re-arm. When runImmediately is true, the task has
+    // already executed and no further scheduling is needed. When false, a
+    // single setTimeout fires once at intervalMs.
+    if (!task.repeat) {
+      if (!runImmediately) {
+        task.timer = setTimeout(() => {
+          task.timer = null;
+          this.#runTask(task).catch((err) => {
+            process.stderr.write(`[scheduler] ${task.label} error: ${err.message}\n`);
+          });
+        }, task.intervalMs);
+        if (task.unref && task.timer.unref) task.timer.unref();
+      }
+      return;
+    }
+
     task.timer = setInterval(() => {
       this.#runTask(task).catch((err) => {
         process.stderr.write(`[scheduler] ${task.label} error: ${err.message}\n`);

package/lib/env-config.mjs

@@ -97,11 +97,17 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
     for (const key of Object.keys(env)) {
       if (ENV_SHADOW_IGNORE.has(key)) continue;
       if (!ENV_SHADOW_WARN.has(key)) continue;
+      // Only warn when process.env has a non-empty competing value.
+      // An empty-string env var (e.g. Claude for Desktop clears ANTHROPIC_API_KEY
+      // so its internal auth is used instead) is not a real conflict — config.env wins
+      // silently and no user action is needed.
+      if (!env[key]) continue;
       if (key in fileEnv && fileEnv[key] !== env[key]) {
         process.stderr.write(
-          `[construct] WARNING: process.env.${key} (${env[key].slice(0, 6)}…) shadows ` +
-          `config.env value (${fileEnv[key].slice(0, 6)}…). ` +
-          `Unset the shell variable or update ~/.construct/config.env.\n`,
+          `[construct] WARNING: process.env.${key} (${env[key].slice(0, 6)}…) ` +
+          `differs from config.env value (${fileEnv[key].slice(0, 6)}…). ` +
+          `config.env will be used. To silence: unset the shell variable or ` +
+          `update ~/.construct/config.env to match.\n`,
         );
       }
     }

package/lib/evaluator-optimizer.mjs

@@ -95,9 +95,8 @@ export async function evaluateDocument({ content, docType, evaluatorFn = null })
     return await evaluatorFn({ content, docType, rubric });
   }
   
-  // Default: deterministic rubric-based evaluation
-  // In production, this would call an LLM evaluator
-  // For now, we use structural checks as a proxy
+  // Default path: deterministic structural-rubric evaluation.
+  // Consumers wanting LLM-graded evaluation supply `evaluatorFn` (handled above).
   
   const scores = [];
   const feedback = [];

package/lib/extractors/calendar.mjs

@@ -0,0 +1,173 @@
+/**
+ * lib/extractors/calendar.mjs — RFC 5545 iCalendar (.ics) structured extraction.
+ *
+ * Parses VCALENDAR / VEVENT blocks without external dependencies. Handles
+ * multi-line property continuation (lines starting with whitespace), extracts
+ * SUMMARY, DTSTART, DTEND, ORGANIZER, ATTENDEE, DESCRIPTION, LOCATION, and
+ * preserves RRULE as a raw string for recurring events.
+ *
+ * Returns the universal { text, structured, droppedInfo } envelope where
+ * structured = { events: [{ summary, dtstart, dtend, organizer,
+ *                           attendees: [], description, location, rrule }] }.
+ */
+import { readFileSync } from 'node:fs';
+import { makeEnvelope, makeDropInfo } from './shared/drop-info.mjs';
+
+// ─── RFC 5545 helpers ─────────────────────────────────────────────────────────
+
+// Unfold continuation lines (RFC 5545 §3.1 — a line beginning with SPACE or TAB
+// is a continuation of the previous property line).
+function unfoldLines(raw) {
+  return raw.replace(/\r\n/g, '\n').replace(/\n[ \t]/g, '');
+}
+
+// Split a property line into its name, params object, and value.
+// e.g. "DTSTART;TZID=America/New_York:20240101T090000" → name=DTSTART, params={TZID:...}, value=...
+function parseProperty(line) {
+  const colonIdx = line.indexOf(':');
+  if (colonIdx === -1) return { name: line.toUpperCase(), params: {}, value: '' };
+  const nameAndParams = line.slice(0, colonIdx);
+  const value = line.slice(colonIdx + 1).trim();
+  const parts = nameAndParams.split(';');
+  const name = (parts[0] || '').toUpperCase().trim();
+  const params = {};
+  for (const part of parts.slice(1)) {
+    const eqIdx = part.indexOf('=');
+    if (eqIdx === -1) continue;
+    params[part.slice(0, eqIdx).toUpperCase()] = part.slice(eqIdx + 1);
+  }
+  return { name, params, value };
+}
+
+// Extract a human-readable name from an ORGANIZER or ATTENDEE value.
+// Tries the CN param first, then strips mailto: prefix.
+function extractName(value, params) {
+  if (params.CN) return params.CN.replace(/^["']|["']$/g, '');
+  return value.replace(/^mailto:/i, '');
+}
+
+// Parse an iCal date/datetime string into an ISO string. Tolerant of both
+// date-only (YYYYMMDD) and datetime (YYYYMMDDTHHMMSS[Z]) forms.
+function parseIcalDate(value) {
+  if (!value) return null;
+  const v = value.replace('Z', '').trim();
+  if (v.length === 8) {
+    // Date-only: YYYYMMDD
+    return `${v.slice(0, 4)}-${v.slice(4, 6)}-${v.slice(6, 8)}`;
+  }
+  if (v.length >= 15 && v[8] === 'T') {
+    // Datetime: YYYYMMDDTHHMMSS
+    return `${v.slice(0, 4)}-${v.slice(4, 6)}-${v.slice(6, 8)}T${v.slice(9, 11)}:${v.slice(11, 13)}:${v.slice(13, 15)}${value.endsWith('Z') ? 'Z' : ''}`;
+  }
+  return value;
+}
+
+// ─── VEVENT block parser ──────────────────────────────────────────────────────
+
+function parseVEvent(lines) {
+  const event = {
+    summary: null,
+    dtstart: null,
+    dtend: null,
+    organizer: null,
+    attendees: [],
+    description: null,
+    location: null,
+    rrule: null,
+  };
+
+  for (const line of lines) {
+    if (!line.includes(':')) continue;
+    const { name, params, value } = parseProperty(line);
+    switch (name) {
+      case 'SUMMARY':     event.summary = value; break;
+      case 'DTSTART':     event.dtstart = parseIcalDate(value); break;
+      case 'DTEND':       event.dtend   = parseIcalDate(value); break;
+      case 'DTDUE':       event.dtend   = event.dtend ?? parseIcalDate(value); break;
+      case 'ORGANIZER':   event.organizer = extractName(value, params); break;
+      case 'ATTENDEE':    event.attendees.push(extractName(value, params)); break;
+      case 'DESCRIPTION': event.description = value.replace(/\\n/g, '\n').replace(/\\,/g, ','); break;
+      case 'LOCATION':    event.location = value; break;
+      case 'RRULE':       event.rrule = value; break;
+    }
+  }
+  return event;
+}
+
+// ─── VCALENDAR parser ─────────────────────────────────────────────────────────
+
+function parseIcs(raw) {
+  const unfolded = unfoldLines(raw);
+  const lines = unfolded.split('\n').map((l) => l.trim()).filter(Boolean);
+
+  if (!lines.some((l) => l === 'BEGIN:VCALENDAR')) {
+    return makeEnvelope({
+      text: raw.replace(/\r\n/g, '\n').trim(),
+      structured: null,
+      droppedInfo: [makeDropInfo({ kind: 'attachment', count: 1, reason: 'No BEGIN:VCALENDAR found; treating as plain text', recoverable: false })],
+    });
+  }
+
+  const events = [];
+  let inEvent = false;
+  let eventLines = [];
+  let droppedTodosVjournals = 0;
+  let inOther = false;
+
+  for (const line of lines) {
+    if (line === 'BEGIN:VEVENT') {
+      inEvent = true;
+      eventLines = [];
+    } else if (line === 'END:VEVENT') {
+      events.push(parseVEvent(eventLines));
+      inEvent = false;
+    } else if (line === 'BEGIN:VTODO' || line === 'BEGIN:VJOURNAL') {
+      inOther = true;
+      droppedTodosVjournals++;
+    } else if (line === 'END:VTODO' || line === 'END:VJOURNAL') {
+      inOther = false;
+    } else if (inEvent) {
+      eventLines.push(line);
+    }
+  }
+
+  const droppedInfo = [];
+  if (droppedTodosVjournals > 0) {
+    droppedInfo.push(makeDropInfo({
+      kind: 'attachment',
+      count: droppedTodosVjournals,
+      reason: 'VTODO and VJOURNAL components omitted (only VEVENT extracted)',
+      recoverable: false,
+    }));
+  }
+
+  // Build text representation
+  const textParts = events.map((e) => {
+    const parts = [];
+    if (e.summary) parts.push(`Event: ${e.summary}`);
+    if (e.dtstart) parts.push(`Start: ${e.dtstart}`);
+    if (e.dtend)   parts.push(`End: ${e.dtend}`);
+    if (e.organizer) parts.push(`Organizer: ${e.organizer}`);
+    if (e.attendees.length) parts.push(`Attendees: ${e.attendees.join(', ')}`);
+    if (e.location) parts.push(`Location: ${e.location}`);
+    if (e.description) parts.push(`\n${e.description}`);
+    return parts.join('\n');
+  });
+
+  return makeEnvelope({
+    text: textParts.join('\n\n').trim(),
+    structured: { events },
+    droppedInfo,
+  });
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Extract structured calendar data from a .ics file path.
+ * Returns the universal { text, structured, droppedInfo } envelope.
+ */
+export function extractCalendar(filePath) {
+  const raw = readFileSync(filePath, 'utf8');
+  return parseIcs(raw);
+}