openwriter 0.14.0 → 0.16.0

package/dist/server/documents.js

@@ -9,11 +9,13 @@ import matter from 'gray-matter';
 import trash from 'trash';
 import { tiptapToMarkdownChecked, markdownToTiptap } from './markdown.js';
 import { parseMarkdownContent } from './compact.js';
-import { getDocument, getTitle, getFilePath, getIsTemp, getMetadata, save, cancelDebouncedSave, setActiveDocument, registerExternalDoc, unregisterExternalDoc, getExternalDocs, cacheActiveDocument, getCachedDocument, invalidateDocCache, removePendingCacheEntry, resetDocVersion, } from './state.js';
-import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, resolveDocPath, isExternalDoc, atomicWriteFileSync } from './helpers.js';
+import { getDocument, getTitle, getFilePath, getIsTemp, getMetadata, save, cancelDebouncedSave, setActiveDocument, registerExternalDoc, unregisterExternalDoc, getExternalDocs, cacheActiveDocument, getCachedDocument, invalidateDocCache, removePendingCacheEntry, resetDocVersion, markAsAgentStub, unmarkAgentStub, isAgentStub, } from './state.js';
+import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, resolveDocPath, isExternalDoc, atomicWriteFileSync, canonicalizePath } from './helpers.js';
 import { ensureDocId } from './versions.js';
-import { renameDocInAllWorkspaces, removeDocFromAllWorkspaces } from './workspaces.js';
-import { renameMark } from './marks.js';
+import { renameDocInAllWorkspaces, removeDocFromAllWorkspaces, listWorkspaces, getWorkspace } from './workspaces.js';
+import { collectAllFiles } from './workspace-tree.js';
+import { renameComments } from './comments.js';
+import { deleteOverlay, diagLog } from './pending-overlay.js';
 import { getDocId as getActiveDocId } from './state.js';
 function getDocOrderFile() { return join(getDataDir(), '_doc-order.json'); }
 /** Scan files for matching docId. Checks active doc first (free), then getDataDir(), then external docs. */
@@ -123,6 +125,18 @@ export function listDocuments() {
                 ...(data.masterDocId ? { masterDocId: data.masterDocId } : {}),
                 ...(data.variantType ? { variantType: data.variantType } : {}),
                 ...(typeof data.autoAccept === 'boolean' ? { autoAccept: data.autoAccept } : {}),
+                // Tags ride along with the doc listing so the sidebar can populate its
+                // tag overlay from one HTTP round-trip instead of N. The server already
+                // has the parsed frontmatter in hand here; emitting tags is free.
+                ...(Array.isArray(data.tags) && data.tags.length > 0 ? { tags: data.tags } : {}),
+                // Enrichment fields — also free at this point since data is in hand.
+                // See brief 2026-05-18-frontmatter-enrichment-system.
+                ...(typeof data.logline === 'string' && data.logline ? { logline: data.logline } : {}),
+                ...(typeof data.domain === 'string' && data.domain ? { domain: data.domain } : {}),
+                ...(Array.isArray(data.concepts) && data.concepts.length > 0 ? { concepts: data.concepts } : {}),
+                ...(typeof data.docRole === 'string' && data.docRole ? { docRole: data.docRole } : {}),
+                ...(typeof data.status === 'string' && data.status ? { status: data.status } : {}),
+                ...(data.enrichmentStale === true ? { enrichmentStale: true } : {}),
             };
         }
         catch {
@@ -237,6 +251,211 @@ export function listArchivedDocuments() {
     files.sort((a, b) => new Date(b.archivedAt).getTime() - new Date(a.archivedAt).getTime());
     return files;
 }
+// ============================================================================
+// ENRICHMENT — list dirty docs + crawl + surfacing helpers
+// See brief 2026-05-18-frontmatter-enrichment-system.
+// ============================================================================
+/** One-line footer the high-frequency MCP discovery tools (list_documents,
+ *  list_workspaces, get_workspace_structure) append when dirty docs exist.
+ *  Constant pressure that doesn't require hook setup. The agent's openwriter
+ *  skill teaches: see this footer → spawn the enrichment minion. */
+export function enrichmentFooter() {
+    const count = listDirtyDocs().length;
+    if (count === 0)
+        return '';
+    return `\n\n⚠ ${count} doc${count === 1 ? '' : 's'} need enrichment — spawn the enrichment minion (see openwriter skill docs/enrichment.md)`;
+}
+/** Session-start enrichment notice injected into the MCP server's
+ *  `instructions` field at boot. Every MCP client (Claude Code, Cursor, etc.)
+ *  delivers this to the agent as part of its system context — no hook setup
+ *  needed. Returns empty string when there's no enrichment work to do. */
+export function buildEnrichmentInstructions() {
+    const dirty = listDirtyDocs();
+    if (dirty.length === 0)
+        return '';
+    // Group by workspace for the notice
+    const byWorkspace = new Map();
+    let orphans = 0;
+    for (const d of dirty) {
+        if (d.workspaceFile) {
+            byWorkspace.set(d.workspaceFile, (byWorkspace.get(d.workspaceFile) || 0) + 1);
+        }
+        else {
+            orphans++;
+        }
+    }
+    const parts = [];
+    for (const [ws, n] of byWorkspace)
+        parts.push(`${n} in ${ws}`);
+    if (orphans > 0)
+        parts.push(`${orphans} unfiled`);
+    return [
+        '',
+        `ENRICHMENT_STATUS: ${dirty.length} doc${dirty.length === 1 ? '' : 's'} need enrichment (${parts.join(', ')}).`,
+        'Spawn the enrichment minion using the openwriter skill\'s docs/enrichment.md as its system prompt before responding to the user\'s request.',
+        'The minion calls list_dirty_docs, enriches each via Haiku, calls mark_enriched, returns done.',
+    ].join('\n');
+}
+/** Build a Set of filenames inside workspaces with enrichmentDisabled: true.
+ *  These docs are excluded from list_dirty_docs and crawl results. */
+function collectOptedOutFilenames() {
+    const out = new Set();
+    for (const info of listWorkspaces()) {
+        try {
+            const ws = getWorkspace(info.filename);
+            if (ws.enrichmentDisabled === true) {
+                for (const f of collectAllFiles(ws.root))
+                    out.add(f);
+            }
+        }
+        catch { /* skip corrupt manifests */ }
+    }
+    return out;
+}
+/** Map filename → first workspace that contains it. Used to attribute
+ *  dirty-doc reports to a workspace. */
+function buildWorkspaceOwnershipMap() {
+    const map = new Map();
+    for (const info of listWorkspaces()) {
+        try {
+            const ws = getWorkspace(info.filename);
+            for (const f of collectAllFiles(ws.root)) {
+                if (!map.has(f))
+                    map.set(f, info.filename);
+            }
+        }
+        catch { /* skip */ }
+    }
+    return map;
+}
+/**
+ * List documents that need re-enrichment. A doc is "dirty" when either:
+ *   - it has never been enriched (no lastEnrichedAt) — implicitly stale; or
+ *   - openwriter flipped enrichmentStale: true at save (volume or drift trip).
+ *
+ * Docs inside opt-out workspaces (enrichmentDisabled: true) are excluded.
+ * Archived docs are excluded.
+ *
+ * Optional `scopeWorkspace` narrows results to a single workspace.
+ *
+ * Cheap: reads each .md file's frontmatter via gray-matter (no TipTap parse,
+ * no body scan). Output carries only identity + reason — no enrichment fields.
+ */
+export function listDirtyDocs(scopeWorkspace) {
+    ensureDataDir();
+    const optedOut = collectOptedOutFilenames();
+    const ownership = buildWorkspaceOwnershipMap();
+    // If a workspace scope is given, build a Set of its files to filter against.
+    let scopeFiles = null;
+    if (scopeWorkspace) {
+        try {
+            const ws = getWorkspace(scopeWorkspace);
+            scopeFiles = new Set(collectAllFiles(ws.root));
+        }
+        catch {
+            // Unknown workspace → return empty rather than throw
+            return [];
+        }
+    }
+    const out = [];
+    for (const f of readdirSync(getDataDir()).filter((f) => f.endsWith('.md'))) {
+        if (optedOut.has(f))
+            continue;
+        if (scopeFiles && !scopeFiles.has(f))
+            continue;
+        try {
+            const raw = readFileSync(join(getDataDir(), f), 'utf-8');
+            const { data } = matter(raw);
+            if (data.archivedAt)
+                continue; // archived docs don't participate
+            const explicitStale = data.enrichmentStale === true;
+            const implicitStale = !data.lastEnrichedAt;
+            if (!explicitStale && !implicitStale)
+                continue;
+            out.push({
+                docId: data.docId || '',
+                filename: f,
+                title: data.title || f.replace(/\.md$/, ''),
+                ...(ownership.get(f) ? { workspaceFile: ownership.get(f) } : {}),
+                reason: explicitStale ? 'stale_flag' : 'never_enriched',
+                ...(typeof data.lastEnrichedAt === 'string' ? { lastEnrichedAt: data.lastEnrichedAt } : {}),
+            });
+        }
+        catch { /* skip unreadable */ }
+    }
+    return out;
+}
+/**
+ * Bulk-read primitive for agents building working sets. Returns enriched
+ * fields per doc, filtered by criteria. No bodies, no nodes/graveyard, no
+ * pending overlay state.
+ *
+ * Filters compose with AND semantics — a doc must match every supplied
+ * criterion. Empty filter object returns every non-archived doc with its
+ * enrichment fields (whatever's present in frontmatter).
+ *
+ * Optimization: one disk pass, one gray-matter parse per file.
+ */
+export function crawlDocs(filter = {}) {
+    ensureDataDir();
+    // If a workspace scope is given, prebuild a set of its filenames.
+    let scopeFiles = null;
+    if (filter.workspaceFile) {
+        try {
+            const ws = getWorkspace(filter.workspaceFile);
+            scopeFiles = new Set(collectAllFiles(ws.root));
+        }
+        catch {
+            return [];
+        }
+    }
+    const out = [];
+    for (const f of readdirSync(getDataDir()).filter((f) => f.endsWith('.md'))) {
+        if (scopeFiles && !scopeFiles.has(f))
+            continue;
+        try {
+            const raw = readFileSync(join(getDataDir(), f), 'utf-8');
+            const { data, content } = matter(raw);
+            if (data.archivedAt)
+                continue;
+            // Apply filters
+            if (filter.domain && data.domain !== filter.domain)
+                continue;
+            if (filter.docRole && data.docRole !== filter.docRole)
+                continue;
+            if (filter.hasLogline === true && !data.logline)
+                continue;
+            if (filter.hasLogline === false && data.logline)
+                continue;
+            if (filter.tags && filter.tags.length > 0) {
+                const docTags = Array.isArray(data.tags) ? data.tags : [];
+                if (!filter.tags.every((t) => docTags.includes(t)))
+                    continue;
+            }
+            if (filter.concepts && filter.concepts.length > 0) {
+                const docConcepts = Array.isArray(data.concepts) ? data.concepts : [];
+                if (!filter.concepts.every((c) => docConcepts.includes(c)))
+                    continue;
+            }
+            const trimmed = content.trim();
+            out.push({
+                docId: data.docId || '',
+                filename: f,
+                title: data.title || f.replace(/\.md$/, ''),
+                wordCount: trimmed ? trimmed.split(/\s+/).length : 0,
+                ...(typeof data.logline === 'string' && data.logline ? { logline: data.logline } : {}),
+                ...(typeof data.domain === 'string' && data.domain ? { domain: data.domain } : {}),
+                ...(Array.isArray(data.tags) && data.tags.length > 0 ? { tags: data.tags } : {}),
+                ...(Array.isArray(data.concepts) && data.concepts.length > 0 ? { concepts: data.concepts } : {}),
+                ...(typeof data.docRole === 'string' && data.docRole ? { docRole: data.docRole } : {}),
+                ...(typeof data.status === 'string' && data.status ? { status: data.status } : {}),
+                ...(data.enrichmentStale === true ? { enrichmentStale: true } : {}),
+            });
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
 export function archiveDocument(filename) {
     ensureDataDir();
     const targetPath = resolveDocPath(filename);
@@ -380,15 +599,21 @@ export function searchDocuments(query, includeArchived = false) {
     return results;
 }
 export function switchDocument(filename) {
+    const tStart = performance.now();
+    const prevFilename = getActiveFilename();
     // No-op if already on this document — avoids save/reload cycle that can clear editor content
-    if (filename === getActiveFilename()) {
+    if (filename === prevFilename) {
+        diagLog(`[Switch] NOOP ${filename} (${(performance.now() - tStart).toFixed(1)}ms)`);
         return { document: getDocument(), title: getTitle(), filename };
     }
     // Cancel any pending debounced save, then save current doc immediately.
     cancelDebouncedSave();
+    const tSaveStart = performance.now();
     save();
+    const tSaveEnd = performance.now();
     // Cache current doc before switching (preserves node IDs)
     cacheActiveDocument();
+    const tCacheEnd = performance.now();
     // Reset version counter — new document starts a fresh version lineage
     resetDocVersion();
     // Read target from disk — markdownToTiptap rehydrates pending state
@@ -404,15 +629,22 @@ export function switchDocument(filename) {
     const cached = getCachedDocument(targetPath);
     if (cached) {
         setActiveDocument(cached.document, cached.title, targetPath, cached.isTemp, cached.lastModified, cached.metadata, cached.originalFrontmatter);
+        const tEnd = performance.now();
+        diagLog(`[Switch] ${prevFilename} → ${filename} CACHE-HIT total=${(tEnd - tStart).toFixed(1)}ms save=${(tSaveEnd - tSaveStart).toFixed(1)}ms cache=${(tCacheEnd - tSaveEnd).toFixed(1)}ms setActive=${(tEnd - tCacheEnd).toFixed(1)}ms`);
         return { document: getDocument(), title: getTitle(), filename };
     }
+    const tReadStart = performance.now();
     const raw = readFileSync(targetPath, 'utf-8');
+    const tReadEnd = performance.now();
     const parsed = markdownToTiptap(raw);
+    const tParseEnd = performance.now();
     const mtime = new Date(statSync(targetPath).mtimeMs);
     // Ensure docId exists on loaded doc metadata (lazy migration)
     ensureDocId(parsed.metadata);
     const baseName = targetPath.split(/[/\\]/).pop() || '';
     setActiveDocument(parsed.document, parsed.title, targetPath, baseName.startsWith(TEMP_PREFIX), mtime, parsed.metadata, parsed.rawFrontmatter);
+    const tEnd = performance.now();
+    diagLog(`[Switch] ${prevFilename} → ${filename} CACHE-MISS total=${(tEnd - tStart).toFixed(1)}ms save=${(tSaveEnd - tSaveStart).toFixed(1)}ms cache=${(tCacheEnd - tSaveEnd).toFixed(1)}ms read=${(tReadEnd - tReadStart).toFixed(1)}ms parse=${(tParseEnd - tReadEnd).toFixed(1)}ms setActive=${(tEnd - tParseEnd).toFixed(1)}ms`);
     return { document: getDocument(), title: getTitle(), filename };
 }
 export function createDocument(title, content, path) {
@@ -518,10 +750,17 @@ export function createDocumentFile(title, path, extraMeta) {
         filename = filePath.split(/[/\\]/).pop();
     }
     const newDoc = { type: 'doc', content: [{ type: 'paragraph', attrs: { id: generateNodeId() }, content: [] }] };
-    const metadata = { title: docTitle, docId: generateNodeId(), agentCreated: true, ...extraMeta };
+    // No `agentCreated: true` in metadata — stub status is in-memory only.
+    // adr: adr/agent-stub-model.md
+    const metadata = { title: docTitle, docId: generateNodeId(), ...extraMeta };
     const { markdown } = tiptapToMarkdownChecked(newDoc, docTitle, metadata);
     ensureDataDir();
     atomicWriteFileSync(filePath, markdown);
+    // Mark this filename as a fresh agent stub. Process-lifetime only — any
+    // accepted content via subsequent save graduates it out of the set, and a
+    // server restart naturally forgets stub status (a stub that survives a
+    // restart is by definition no longer fresh).
+    markAsAgentStub(filename);
     // Prepend to doc order so new docs appear at top and stay put after edits
     const order = readDocOrder();
     const fn = filePath.split(/[/\\]/).pop();
@@ -536,6 +775,9 @@ export async function deleteDocument(filename) {
     const targetPath = resolveDocPath(filename);
     // Invalidate cache for deleted doc
     invalidateDocCache(targetPath);
+    // Remove stub status for the deleted filename so a future recreate with
+    // the same name doesn't inherit the prior stub flag.
+    unmarkAgentStub(filename);
     // Unregister if external
     if (isExternalDoc(filename)) {
         unregisterExternalDoc(targetPath);
@@ -545,9 +787,25 @@ export async function deleteDocument(filename) {
         throw new Error('Cannot delete the only document');
     }
     const isDeletingActive = targetPath === getFilePath();
+    // Read docId BEFORE deleting the file so we can retire its overlay sidecar
+    // in lockstep. The sidecar's lifecycle is bound to the docId's existence in
+    // the workspace; delete retires the docId, archive does not.
+    // adr: adr/pending-overlay-model.md
+    let docIdToRetire = '';
+    if (existsSync(targetPath)) {
+        try {
+            const raw = readFileSync(targetPath, 'utf-8');
+            const { data } = matter(raw);
+            if (typeof data?.docId === 'string')
+                docIdToRetire = data.docId;
+        }
+        catch { /* best-effort */ }
+    }
     if (!isExternalDoc(filename) && existsSync(targetPath)) {
         await trash(targetPath);
     }
+    if (docIdToRetire)
+        deleteOverlay(docIdToRetire);
     if (isDeletingActive) {
         const remaining = readdirSync(getDataDir())
             .filter((f) => f.endsWith('.md'))
@@ -594,42 +852,49 @@ export function updateDocumentTitle(filename, newTitle) {
         setActiveDocument(getDocument(), newTitle, filePath, baseName.startsWith(TEMP_PREFIX), undefined, metadata);
     }
 }
-/** Open an existing file from any path. Saves current doc, registers as external, sets as active. */
+/** Open an existing file from any path. Saves current doc, registers as external, sets as active.
+ *
+ *  Canonicalizes the input path at the boundary so opening the same physical
+ *  file via different spellings (forward/back slash, drive-letter case,
+ *  symlink) hits the same doc identity — same cache slot, same watcher
+ *  subscription, same pending overlay.
+ *  adr: adr/path-canonicalization.md */
 export function openFile(fullPath) {
     if (!existsSync(fullPath)) {
         throw new Error(`File not found: ${fullPath}`);
     }
+    const canonPath = canonicalizePath(fullPath);
     // Cancel any pending debounced save, then save current doc immediately
     cancelDebouncedSave();
     save();
     // Cache current doc before switching
     cacheActiveDocument();
     // Register as external if not in getDataDir()
-    if (isExternalDoc(fullPath)) {
-        registerExternalDoc(fullPath);
+    if (isExternalDoc(canonPath)) {
+        registerExternalDoc(canonPath);
     }
     // Check cache first — preserves stable node IDs
-    const cached = getCachedDocument(fullPath);
+    const cached = getCachedDocument(canonPath);
     if (cached) {
-        setActiveDocument(cached.document, cached.title, fullPath, cached.isTemp, cached.lastModified, cached.metadata, cached.originalFrontmatter);
-        const filename = isExternalDoc(fullPath) ? fullPath : (fullPath.split(/[/\\]/).pop() || '');
+        setActiveDocument(cached.document, cached.title, canonPath, cached.isTemp, cached.lastModified, cached.metadata, cached.originalFrontmatter);
+        const filename = isExternalDoc(canonPath) ? canonPath : (canonPath.split(/[/\\]/).pop() || '');
         return { document: getDocument(), title: getTitle(), filename };
     }
-    const raw = readFileSync(fullPath, 'utf-8');
+    const raw = readFileSync(canonPath, 'utf-8');
     const parsed = markdownToTiptap(raw);
-    const mtime = new Date(statSync(fullPath).mtimeMs);
+    const mtime = new Date(statSync(canonPath).mtimeMs);
     ensureDocId(parsed.metadata);
     // Title fallback: use filename stem instead of "Untitled" for files without a title
     let title = parsed.title;
     if (title === 'Untitled') {
-        const stem = fullPath.split(/[/\\]/).pop()?.replace(/\.md$/i, '');
+        const stem = canonPath.split(/[/\\]/).pop()?.replace(/\.md$/i, '');
         if (stem)
             title = stem;
     }
-    const baseName = fullPath.split(/[/\\]/).pop() || '';
-    setActiveDocument(parsed.document, title, fullPath, baseName.startsWith(TEMP_PREFIX), mtime, parsed.metadata, parsed.rawFrontmatter);
+    const baseName = canonPath.split(/[/\\]/).pop() || '';
+    setActiveDocument(parsed.document, title, canonPath, baseName.startsWith(TEMP_PREFIX), mtime, parsed.metadata, parsed.rawFrontmatter);
     // Use full path as filename for external docs, basename for getDataDir() docs
-    const filename = isExternalDoc(fullPath) ? fullPath : baseName;
+    const filename = isExternalDoc(canonPath) ? canonPath : baseName;
     return { document: getDocument(), title: getTitle(), filename };
 }
 export function duplicateDocument(filename) {
@@ -695,10 +960,18 @@ export function promoteTempFile(newTitle) {
     // Invalidate old caches
     removePendingCacheEntry(oldFilename);
     invalidateDocCache(oldPath);
+    // Carry the agent-stub flag across the rename (if the doc was still a
+    // fresh stub when renamed — uncommon but possible). The Set is keyed by
+    // filename, so we must transfer the entry to the new key.
+    // adr: adr/agent-stub-model.md
+    if (isAgentStub(oldFilename)) {
+        unmarkAgentStub(oldFilename);
+        markAsAgentStub(newFilename);
+    }
     // Update workspace references
     renameDocInAllWorkspaces(oldFilename, newFilename, newTitle);
-    // Rename marks sidecar
-    renameMark(oldFilename, newFilename);
+    // Rename comments sidecar
+    renameComments(oldFilename, newFilename);
     return newFilename;
 }
 // ============================================================================

package/dist/server/enrichment.js

@@ -0,0 +1,114 @@
+/**
+ * Frontmatter enrichment staleness detection.
+ *
+ * The matcher already splits every block into sentences and hashes each one on
+ * every save (see node-fingerprint.ts). We reuse that machinery here — no new
+ * algorithm, no new splitter. Save-time staleness is a small tag-on after the
+ * matcher: harvest the current sentence-hash set + char count, compare against
+ * the at-enrichment baseline stored in frontmatter, set `enrichmentStale: true`
+ * when either threshold trips.
+ *
+ * Volume ratio captures growth and shrinkage symmetrically. Jaccard distance
+ * over the sentence-hash set captures rewrites at constant length. Either
+ * tripping flags the doc.
+ *
+ * OpenWriter owns "is this doc stale". The agent clears the flag via
+ * mark_enriched (Phase 4). Both sides read the same field, never compute it
+ * independently.
+ *
+ * See brief: 2026-05-18-frontmatter-enrichment-system.
+ */
+import { splitSentences, simpleHash } from './node-fingerprint.js';
+/** Volume-ratio threshold above which a doc is flagged stale by size delta. */
+export const DEFAULT_ENRICHMENT_VOLUME_THRESHOLD = 1.5;
+/** Jaccard-distance threshold above which a doc is flagged stale by drift. */
+export const DEFAULT_ENRICHMENT_DRIFT_THRESHOLD = 0.3;
+/**
+ * Flatten every block's per-sentence hashes into one sorted unique set.
+ * Sorted so the on-disk representation is stable across saves (no spurious
+ * frontmatter diffs from set-order drift). Unique so duplicate sentences
+ * in the same doc don't double-count in the Jaccard math.
+ */
+export function harvestSentenceHashes(blocks) {
+    const set = new Set();
+    for (const block of blocks) {
+        const sentences = splitSentences(block.text || '');
+        for (const s of sentences) {
+            set.add(simpleHash(s.text + s.terminator));
+        }
+    }
+    return Array.from(set).sort();
+}
+/** Total char count across all blocks' text — the volume signal. */
+export function harvestCharCount(blocks) {
+    let n = 0;
+    for (const b of blocks)
+        n += (b.text || '').length;
+    return n;
+}
+/**
+ * Symmetric size delta. Returns 1 when sizes match, grows toward infinity as
+ * they diverge in either direction. Handles zero-size docs safely.
+ */
+export function volumeRatio(current, baseline) {
+    if (current === 0 && baseline === 0)
+        return 1;
+    if (current === 0 || baseline === 0)
+        return Infinity;
+    return Math.max(current, baseline) / Math.min(current, baseline);
+}
+/**
+ * Jaccard distance over two sentence-hash sets. 0 = identical, 1 = disjoint.
+ * (union - intersection) / union. Empty-vs-empty returns 0.
+ */
+export function jaccardDistance(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    const setA = new Set(a);
+    const setB = new Set(b);
+    let intersection = 0;
+    for (const x of setA)
+        if (setB.has(x))
+            intersection++;
+    const union = setA.size + setB.size - intersection;
+    return union === 0 ? 0 : (union - intersection) / union;
+}
+/**
+ * Compute staleness for a single doc given current matcher-derived signals
+ * and the at-enrichment baseline stored in its frontmatter.
+ *
+ * Returns true when:
+ *   - the doc has never been enriched (no lastEnrichedAt) — brief: "absent flag = stale"
+ *   - volumeRatio trips its threshold
+ *   - Jaccard drift trips its threshold
+ *
+ * Thresholds: doc-level overrides first, then global defaults. Workspace-level
+ * overrides (per the brief) will be layered in when the surfacing handlers
+ * (Phase 6) get a workspace pointer — for now the doc carries no workspace
+ * reference in writeToDisk's scope.
+ */
+export function isEnrichmentStale(currentSentenceHashes, currentCharCount, metadata, workspaceOverrides) {
+    // Never enriched → stale by default. New docs land here.
+    if (!metadata.lastEnrichedAt)
+        return true;
+    const baselineHashes = Array.isArray(metadata.lastEnrichedSentences)
+        ? metadata.lastEnrichedSentences
+        : [];
+    const baselineChars = typeof metadata.lastEnrichedCharCount === 'number'
+        ? metadata.lastEnrichedCharCount
+        : 0;
+    const volTh = pickThreshold(metadata.enrichmentVolumeThreshold, workspaceOverrides?.volume, DEFAULT_ENRICHMENT_VOLUME_THRESHOLD);
+    const driftTh = pickThreshold(metadata.enrichmentDriftThreshold, workspaceOverrides?.drift, DEFAULT_ENRICHMENT_DRIFT_THRESHOLD);
+    if (volumeRatio(currentCharCount, baselineChars) >= volTh)
+        return true;
+    if (jaccardDistance(currentSentenceHashes, baselineHashes) >= driftTh)
+        return true;
+    return false;
+}
+function pickThreshold(docLevel, wsLevel, fallback) {
+    if (typeof docLevel === 'number' && docLevel > 0)
+        return docLevel;
+    if (typeof wsLevel === 'number' && wsLevel > 0)
+        return wsLevel;
+    return fallback;
+}

package/dist/server/helpers.js

@@ -2,7 +2,7 @@
  * Shared constants and utility functions for OpenWriter server.
  * Both state.ts and documents.ts import from here to avoid duplication.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync, rmSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync, rmSync, realpathSync } from 'fs';
 import { join, isAbsolute, basename, dirname, resolve, sep } from 'path';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
@@ -63,7 +63,36 @@ export function filePathForTitle(title) {
 export function tempFilePath() {
     return join(getDataDir(), `${TEMP_PREFIX}${randomUUID()}.md`);
 }
-// ---- Path resolution for external documents ----
+/**
+ * Produce one canonical representation per physical file. Idempotent:
+ * `canonicalizePath(canonicalizePath(p)) === canonicalizePath(p)`.
+ *
+ * On Windows: resolves separator direction (`/` vs `\`), drive-letter
+ * case (`c:` vs `C:`), 8.3 short names, and symlinks — whenever the
+ * file exists. `realpathSync.native` is the OS asking itself "what's
+ * the real path of this thing?", which is the only authoritative
+ * answer.
+ *
+ * On Unix: resolves symlinks and normalizes relative segments.
+ *
+ * Falls back to `path.resolve` (absolute path with platform separators)
+ * when the file doesn't exist yet. That's a weaker form — it won't
+ * catch drive-letter case mismatches on a path to a not-yet-created
+ * file — but every openwriter identity boundary hits an existing file,
+ * so the fallback is a safety net rather than a primary path.
+ *
+ * adr: adr/path-canonicalization.md
+ */
+export function canonicalizePath(p) {
+    if (!p)
+        return p;
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
 /** Resolve a filename to a full path. Basenames resolve to DATA_DIR; absolute paths pass through. */
 export function resolveDocPath(filename) {
     const dataDir = getDataDir();
@@ -78,13 +107,39 @@ export function resolveDocPath(filename) {
     }
     return resolved;
 }
-/** Returns true if filename is a full path (not a simple basename in DATA_DIR). */
+/**
+ * Canonicalize a doc identifier that might be a bare basename (internal
+ * doc) or an absolute path (external doc). Basenames pass through
+ * untouched; absolute paths route through `canonicalizePath`. Use this
+ * at WebSocket and HTTP boundaries where browser-sent identifiers can
+ * be either form and must compare equal against server-side
+ * `getActiveFilename()` regardless of how they were spelled.
+ *
+ * adr: adr/path-canonicalization.md
+ */
+export function canonicalizeIdentifier(id) {
+    if (!id)
+        return id;
+    return isAbsolute(id) ? canonicalizePath(id) : id;
+}
+/**
+ * Returns true if filename is a full path pointing outside DATA_DIR.
+ *
+ * Canonicalizes both sides of the comparison so that mixed separators,
+ * drive-letter case, and symlink-resolved variants of the same file all
+ * classify consistently. The pre-canonicalization version compared raw
+ * strings via `startsWith`, which let `C:/Users/.../data-dir/foo.md`
+ * be classified as external on Windows because `getDataDir()` returns
+ * `C:\Users\...\data-dir` (different separators).
+ *
+ * adr: adr/path-canonicalization.md
+ */
 export function isExternalDoc(filename) {
-    if (isAbsolute(filename) || /[/\\]/.test(filename)) {
-        const resolved = isAbsolute(filename) ? filename : filename;
-        return !resolved.startsWith(getDataDir());
-    }
-    return false;
+    if (!isAbsolute(filename) && !/[/\\]/.test(filename))
+        return false;
+    const canonFile = canonicalizePath(filename);
+    const canonDataDir = canonicalizePath(getDataDir());
+    return canonFile !== canonDataDir && !canonFile.startsWith(canonDataDir + sep);
 }
 /** Extract basename from a path, or return as-is if already a basename. */
 export function getDocBasename(filename) {