noteconnection 1.8.0 → 1.9.0

package/dist/src/learning/vectorAccelerationAdapter.js

@@ -285,12 +285,21 @@ function parseExternalHttpRetryAfterMs(rawValue, nowMs = Date.now()) {
     }
     return Math.min(EXTERNAL_HTTP_RETRY_AFTER_MS_MAX, Math.floor(deltaMs));
 }
-async function waitForRetryDelay(ms) {
+async function waitForRetryDelay(ms, signal) {
+    signal?.throwIfAborted();
     if (!Number.isFinite(ms) || ms <= 0) {
         return;
     }
-    await new Promise((resolve) => {
-        setTimeout(resolve, ms);
+    await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
     });
 }
 function selectCandidatesFromExternalStub(input) {
@@ -483,6 +492,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
     return {
         id: EXTERNAL_HTTP_ADAPTER_ID,
         async syncIndex(input) {
+            input.signal?.throwIfAborted();
             const requestedRepresentationVersion = normalizeRepresentationVersion(input.representationVersion);
             const requestedEmbeddingModelId = normalizeEmbeddingModelId(input.embeddingModelId);
             const requestedEmbeddingDimension = normalizeEmbeddingDimension(input.embeddingDimension);
@@ -543,7 +553,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
                         tokenToAtomIds: Array.from(input.tokenToAtomIds.entries()),
                         signatureBuckets: Array.from(input.signatureBuckets.entries()),
                     }),
-                    signal: controller.signal,
+                    signal: input.signal ? AbortSignal.any([input.signal, controller.signal]) : controller.signal,
                 });
                 const connectorRequestId = normalizeExternalHttpRequestId(response?.headers?.get?.('x-request-id'), clientRequestId);
                 if (connectorRequestId) {
@@ -559,6 +569,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
                     throw new Error(indexSyncMessage);
                 }
                 const payload = await response.json();
+                input.signal?.throwIfAborted();
                 const responseRepresentationVersion = normalizeRepresentationVersion(payload?.representationVersion);
                 const responseEmbeddingModelId = normalizeEmbeddingModelId(payload?.embeddingModelId);
                 const responseEmbeddingDimension = normalizeEmbeddingDimension(payload?.embeddingDimension);
@@ -609,6 +620,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
                 };
             }
             catch (error) {
+                input.signal?.throwIfAborted();
                 syncFailureCount += 1;
                 indexSyncStatus = endpoint ? 'degraded' : 'unavailable';
                 indexSyncMessage = truncateMessage(error?.message || error, 240) || 'external_http_index_sync_failed';
@@ -624,6 +636,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
             }
         },
         async selectCandidates(input) {
+            input.signal?.throwIfAborted();
             selectionRequestCount += 1;
             const requestedRepresentationVersion = normalizeRepresentationVersion(input.representationVersion);
             const requestedEmbeddingModelId = normalizeEmbeddingModelId(input.embeddingModelId);
@@ -686,6 +699,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
             const totalAttempts = Math.max(1, maxRetries + 1);
             let lastError = null;
             for (let attemptIndex = 0; attemptIndex < totalAttempts; attemptIndex += 1) {
+                input.signal?.throwIfAborted();
                 const currentAttempt = attemptIndex + 1;
                 const clientRequestId = nextExternalHttpRequestId();
                 let connectorRequestId = '';
@@ -714,7 +728,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
                                 : undefined,
                             indexSignature: requestedIndexSignature || undefined,
                         }),
-                        signal: controller.signal,
+                        signal: input.signal ? AbortSignal.any([input.signal, controller.signal]) : controller.signal,
                     });
                     connectorRequestId = normalizeExternalHttpRequestId(response?.headers?.get?.('x-request-id'), clientRequestId);
                     if (connectorRequestId) {
@@ -739,6 +753,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
                         throw new Error(`external_http_status_${statusCode}:errorCode=${statusErrorCode}${retryAfterSegment}:requestId=${connectorRequestId || clientRequestId}`);
                     }
                     const payload = await response.json();
+                    input.signal?.throwIfAborted();
                     const mode = String(payload?.mode || '').trim().toLowerCase();
                     const normalizedMode = (mode === 'token_prefilter'
                         || mode === 'token_signature_prefilter') ? mode : 'full_scan';
@@ -858,6 +873,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
                     };
                 }
                 catch (error) {
+                    input.signal?.throwIfAborted();
                     lastError = error;
                     const transient = isExternalHttpTransientFailure(error);
                     const finalAttempt = currentAttempt >= totalAttempts;
@@ -897,7 +913,7 @@ function createVectorAccelerationAdapter(provider, options = {}) {
                                 + `requestId=${connectorRequestId || clientRequestId}`),
                             checkedAt: new Date().toISOString(),
                         });
-                        await waitForRetryDelay(effectiveBackoffDelay);
+                        await waitForRetryDelay(effectiveBackoffDelay, input.signal);
                         continue;
                     }
                     consecutiveFailures += 1;

package/dist/src/learning/vectorAccelerationAdapter.test.js

@@ -40,6 +40,36 @@ describe('vector acceleration adapter', () => {
         const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('local');
         expect(adapter).toBeUndefined();
     });
+    test.each(['syncIndex', 'selectCandidates'])('cancels %s HTTP without retry or circuit failure', async (operation) => {
+        const controller = new AbortController();
+        const cancelled = new Error('turn_cancelled');
+        const fetchMock = jest.fn((_url, init) => new Promise((_resolve, reject) => {
+            const signal = init.signal;
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+            controller.abort(cancelled);
+        }));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: { endpoint: 'http://127.0.0.1:18080', maxRetries: 3 },
+        });
+        const input = { ...baseSelectionInput, signal: controller.signal };
+        await expect(adapter[operation](input)).rejects.toBe(cancelled);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(JSON.parse(fetchMock.mock.calls[0][1].body)).not.toHaveProperty('signal');
+        expect(adapter.getHealth?.().consecutiveFailures).toBe(0);
+    });
+    test('cancels the connector retry delay before a second request', async () => {
+        const controller = new AbortController();
+        const cancelled = new Error('turn_cancelled');
+        globalThis.fetch = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: { endpoint: 'http://127.0.0.1:18080', maxRetries: 3, retryDelayMs: 1000 },
+        });
+        const result = Promise.resolve(adapter.selectCandidates({ ...baseSelectionInput, signal: controller.signal }));
+        setImmediate(() => controller.abort(cancelled));
+        await expect(result).rejects.toBe(cancelled);
+        expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    });
     test('external stub adapter selects token-based candidates for large corpus', async () => {
         const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_stub');
         expect(adapter).toBeDefined();

package/dist/src/learning/workspaceHydration.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveKnowledgeTargetLookupQueries = deriveKnowledgeTargetLookupQueries;
+exports.normalizeKnowledgeSourcePath = normalizeKnowledgeSourcePath;
+exports.buildKnowledgeSourceInventoryDiff = buildKnowledgeSourceInventoryDiff;
+exports.markdownPreviewMatchesTitleLikeQueries = markdownPreviewMatchesTitleLikeQueries;
+const path = __importStar(require("path"));
+function normalizeLookupQuery(value) {
+    return String(value || '')
+        .normalize('NFKC')
+        .replace(/[?？!！。.;；:,，]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .toLowerCase();
+}
+function stripDefinitionPredicate(value) {
+    return value
+        .replace(/^(?:what\s+is|what\s+are|define|explain|tell\s+me\s+about|what's)\s+/iu, '')
+        .replace(/^(?:什么是|何谓|解释(?:一下)?|介绍(?:一下)?|请(?:解释|介绍)(?:一下)?)\s*/u, '')
+        .trim();
+}
+/**
+ * Extracts bounded title-like variants from a user query. Compound prompts keep
+ * their first definition clause so a Chinese subject can resolve an English
+ * filename without scanning the whole corpus.
+ */
+function deriveKnowledgeTargetLookupQueries(query) {
+    const source = String(query || '').normalize('NFKC');
+    const candidates = new Set();
+    const add = (value) => {
+        const normalized = normalizeLookupQuery(value);
+        if (!normalized) {
+            return;
+        }
+        candidates.add(normalized);
+        const stripped = stripDefinitionPredicate(normalized);
+        if (stripped) {
+            candidates.add(stripped);
+            candidates.add(stripped.replace(/\s+/gu, ''));
+        }
+    };
+    add(source);
+    source.split(/[?？!！。.;；\n\r]+/gu).forEach(add);
+    const definitionSubject = source.match(/^(?:what\s+is|what\s+are|define|explain|tell\s+me\s+about|what's|什么是|何谓|解释(?:一下)?|介绍(?:一下)?|请(?:解释|介绍)(?:一下)?)\s*([^?？!！。.;；\n\r]+)/iu);
+    if (definitionSubject?.[1]) {
+        const subject = definitionSubject[1]
+            .replace(/\s+(?:我应该|应该|how\s+should|what\s+should).*$/iu, '')
+            .trim();
+        add(subject);
+    }
+    if (candidates.has('water glass') || candidates.has('waterglass')) {
+        candidates.add('water glass');
+        candidates.add('waterglass');
+        candidates.add('水玻璃');
+        candidates.add('水杯');
+    }
+    return Array.from(candidates.values()).filter(Boolean);
+}
+/**
+ * Produces the case-folded path key used only for inventory reconciliation.
+ * The original spelling is retained in diff output for diagnostics and ingest.
+ */
+function normalizeKnowledgeSourcePath(value) {
+    return String(value || '')
+        .normalize('NFKC')
+        .replace(/\\/g, '/')
+        .replace(/^\/+/, '')
+        .replace(/\/{2,}/g, '/')
+        .replace(/\/+$/g, '')
+        .toLowerCase();
+}
+function buildKnowledgeSourceInventoryDiff(params) {
+    const collect = (sourcePaths) => {
+        const byNormalizedPath = new Map();
+        sourcePaths.forEach((sourcePath) => {
+            const normalized = normalizeKnowledgeSourcePath(sourcePath);
+            if (normalized && !byNormalizedPath.has(normalized)) {
+                byNormalizedPath.set(normalized, sourcePath);
+            }
+        });
+        return byNormalizedPath;
+    };
+    const disk = collect(params.diskSourcePaths);
+    const indexed = collect(params.indexedSourcePaths);
+    const addedSourcePaths = Array.from(disk.entries())
+        .filter(([normalizedPath]) => !indexed.has(normalizedPath))
+        .map(([, sourcePath]) => sourcePath)
+        .sort((left, right) => normalizeKnowledgeSourcePath(left).localeCompare(normalizeKnowledgeSourcePath(right)));
+    const removedSourcePaths = Array.from(indexed.entries())
+        .filter(([normalizedPath]) => !disk.has(normalizedPath))
+        .map(([, sourcePath]) => sourcePath)
+        .sort((left, right) => normalizeKnowledgeSourcePath(left).localeCompare(normalizeKnowledgeSourcePath(right)));
+    return { addedSourcePaths, removedSourcePaths };
+}
+function normalizeTitleCandidate(value) {
+    return String(value || '')
+        .normalize('NFKC')
+        .replace(/[^\p{L}\p{N}\s_-]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .replace(/^(?:the|a|an)\s+/u, '')
+        .trim();
+}
+function collectPreviewTitleCandidates(sourcePath, preview) {
+    const candidates = new Set();
+    const basename = path.posix.basename(String(sourcePath || '').replace(/\\/g, '/'))
+        .replace(/\.[^.]+$/u, '');
+    if (basename) {
+        candidates.add(basename);
+    }
+    String(preview || '').split(/\r?\n/u).forEach((line) => {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return;
+        }
+        const heading = trimmed.match(/^#{1,6}\s+(.+?)\s*#*$/u);
+        if (heading?.[1]) {
+            candidates.add(heading[1]);
+            return;
+        }
+        if (candidates.size <= 1 && !/^```|^[-*+]\s|^\d+[.)]\s/u.test(trimmed)) {
+            candidates.add(trimmed);
+        }
+    });
+    return Array.from(candidates.values()).map(normalizeTitleCandidate).filter(Boolean);
+}
+function markdownPreviewMatchesTitleLikeQueries(input) {
+    const queries = Array.from(new Set(input.titleLikeQueries.map(normalizeTitleCandidate).filter((query) => query.length >= 2)));
+    if (queries.length <= 0) {
+        return false;
+    }
+    const candidates = collectPreviewTitleCandidates(input.sourcePath, input.preview);
+    return candidates.some((candidate) => queries.some((query) => candidate === query || candidate.includes(query)));
+}

package/dist/src/learning/workspaceHydration.test.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workspaceHydration_1 = require("./workspaceHydration");
+describe('workspaceHydration', () => {
+    test('detects source files that exist on disk but are absent from the indexed workspace', () => {
+        const diff = (0, workspaceHydration_1.buildKnowledgeSourceInventoryDiff)({
+            diskSourcePaths: [
+                'Knowledge_Base/waterglass/water glass.md',
+                'Knowledge_Base/waterglass/Amorphous ice.md',
+            ],
+            indexedSourcePaths: [
+                'knowledge_base\\waterglass\\water glass.md',
+            ],
+        });
+        expect(diff.addedSourcePaths).toEqual([
+            'Knowledge_Base/waterglass/Amorphous ice.md',
+        ]);
+        expect(diff.removedSourcePaths).toEqual([]);
+    });
+    test('matches a Chinese heading when the file basename uses the English concept name', () => {
+        expect((0, workspaceHydration_1.markdownPreviewMatchesTitleLikeQueries)({
+            sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+            preview: '## 非晶冰\n\n非晶冰（Amorphous ice）是水的一种固态形式。',
+            titleLikeQueries: ['非晶冰'],
+        })).toBe(true);
+    });
+    test('keeps the definition subject from a compound Chinese conversation query', () => {
+        expect((0, workspaceHydration_1.deriveKnowledgeTargetLookupQueries)('什么是非晶冰？我应该通过哪些知识点学习？')).toEqual(expect.arrayContaining(['非晶冰']));
+    });
+});

package/dist/src/license.policy.contract.test.js

@@ -44,6 +44,7 @@ describe('license policy contract', () => {
     const tauriCargoTomlPath = path.join(repoRoot, 'src-tauri', 'Cargo.toml');
     const licensePath = path.join(repoRoot, 'LICENSE');
     const readmePath = path.join(repoRoot, 'README.md');
+    const chineseReadmePath = path.join(repoRoot, 'README_zh.md');
     test('root package manifest is pinned to GPL-3.0-only', () => {
         const pkg = readJson(packageJsonPath);
         expect(pkg.license).toBe('GPL-3.0-only');
@@ -57,10 +58,14 @@ describe('license policy contract', () => {
         expect(license).toContain('GNU GENERAL PUBLIC LICENSE');
         expect(license).toContain('Version 3, 29 June 2007');
     });
-    test('README license section advertises GPL-3.0-only in both locales', () => {
+    test('README license sections advertise GPL-3.0-only in both locales', () => {
         const readme = fs.readFileSync(readmePath, 'utf8');
-        expect(readme).toContain('License / 开源许可');
-        expect(readme).toContain('GNU General Public License v3.0 (GPL-3.0-only)');
-        expect(readme).toContain('GNU General Public License v3.0（GPL-3.0-only）');
+        const chineseReadme = fs.readFileSync(chineseReadmePath, 'utf8');
+        expect(readme).toContain('## License');
+        expect(readme).toContain('GNU General Public License v3.0');
+        expect(readme).toContain('GPL-3.0-only');
+        expect(chineseReadme).toContain('## 开源许可');
+        expect(chineseReadme).toContain('GNU General Public License v3.0');
+        expect(chineseReadme).toContain('GPL-3.0-only');
     });
 });

package/dist/src/markdown/MarkdownGateway.js

@@ -697,6 +697,10 @@ class MarkdownGateway {
             candidates.push(path.join(path.dirname(process.execPath), binaryName));
             candidates.push(path.join(path.dirname(process.execPath), '..', 'Resources', binaryName));
         }
+        // Tauri removes the target triple from installed external binary names.
+        const installedBinaryName = process.platform === 'win32' ? 'markdown-worker.exe' : 'markdown-worker';
+        candidates.push(path.join(path.dirname(process.execPath), installedBinaryName));
+        candidates.push(path.join(path.dirname(process.execPath), '..', 'Resources', installedBinaryName));
         for (const candidate of candidates) {
             try {
                 if (!candidate) {

package/dist/src/markdown/MarkdownGateway.test.js

@@ -37,6 +37,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const MarkdownGateway_1 = require("./MarkdownGateway");
+const { resolveHostMarkdownWorkerBinaryName } = require('../../scripts/tauri-sidecar-utils');
 class TempDir {
     constructor(prefix) {
         this.path = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), `${prefix}-`));
@@ -192,4 +193,62 @@ describe('MarkdownGateway', () => {
             }
         }
     });
+    const testUnix = process.platform === 'win32' ? test.skip : test;
+    testUnix.each(['beside-server', 'Resources', 'explicit-override', 'build-filename'])('buildIndex discovers the %s worker and preserves lookup priority', async (location) => {
+        const installedDirectory = ctx.temp.mkdir('installed/bin');
+        const originalExecPath = process.execPath;
+        const originalWorkerPath = process.env.NOTE_CONNECTION_MARKDOWN_WORKER_PATH;
+        const writeWorker = (workerPath, anchorId) => {
+            fs.mkdirSync(path.dirname(workerPath), { recursive: true });
+            fs.writeFileSync(workerPath, `#!/usr/bin/env node
+const fs = require('fs');
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  const request = JSON.parse(input);
+  if (request.kind !== 'build_index') process.exit(1);
+  const content = fs.readFileSync(request.filePath);
+  const block = { id: 0, type: 'heading', startByte: 0, endByte: content.length, startLine: 1, endLine: 1, anchorId: ${JSON.stringify(anchorId)} };
+  process.stdout.write(JSON.stringify({ ok: true, index: { totalBytes: content.length, totalLines: 1, blocks: [block], anchors: [], wikiLinks: [] } }));
+});
+`, { mode: 0o755 });
+        };
+        try {
+            process.execPath = path.join(installedDirectory, 'server');
+            delete process.env.NOTE_CONNECTION_MARKDOWN_WORKER_PATH;
+            const installedWorker = location === 'Resources'
+                ? path.join(installedDirectory, '..', 'Resources', 'markdown-worker')
+                : path.join(installedDirectory, 'markdown-worker');
+            writeWorker(installedWorker, 'installed-worker');
+            if (location === 'explicit-override' || location === 'build-filename') {
+                writeWorker(path.join(ctx.projectRoot, 'src-tauri', 'bin', resolveHostMarkdownWorkerBinaryName()), 'build-worker');
+            }
+            if (location === 'explicit-override') {
+                const explicitWorker = path.join(ctx.temp.path, 'explicit-worker');
+                writeWorker(explicitWorker, 'explicit-worker');
+                process.env.NOTE_CONNECTION_MARKDOWN_WORKER_PATH = explicitWorker;
+            }
+            const filePath = ctx.temp.file(path.join('project', 'Knowledge_Base', 'installed.md'), '# Installed markdown worker');
+            const index = await ctx.gateway.buildIndex({ filePath }, {
+                markdownEngine: 'pulldown',
+                chunkBlockSize: 8,
+                prefetchBlocks: 2,
+                indexCacheTtlSec: 1800,
+                maxDocBytes: 32 * 1024 * 1024,
+            });
+            expect(index.engine).toBe('pulldown');
+            expect(index.fallbackReason).toBeUndefined();
+            const chunk = await ctx.gateway.getChunk({ indexId: index.indexId, startBlock: 0, blockCount: 1 });
+            const expectedAnchor = location === 'explicit-override' ? 'explicit-worker'
+                : location === 'build-filename' ? 'build-worker' : 'installed-worker';
+            expect(chunk.blocks[0].anchorId).toBe(expectedAnchor);
+        }
+        finally {
+            process.execPath = originalExecPath;
+            if (originalWorkerPath === undefined)
+                delete process.env.NOTE_CONNECTION_MARKDOWN_WORKER_PATH;
+            else
+                process.env.NOTE_CONNECTION_MARKDOWN_WORKER_PATH = originalWorkerPath;
+        }
+    });
 });

package/dist/src/middleware/SseResponseWriter.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseResponseWriter = void 0;
+/** Owns backpressure and the single terminal outcome of one HTTP event stream. */
+class SseResponseWriter {
+    constructor(destination, policy = {
+        maxBufferedBytes: 64 * 1024 * 1024 + 256 * 1024,
+        drainTimeoutMs: 15000,
+    }) {
+        this.destination = destination;
+        this.policy = policy;
+        this.pending = [];
+        this.queuedBytes = 0;
+        this.blocked = false;
+        this.finishing = false;
+        this.finished = false;
+        this.onDrain = () => {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+            this.blocked = false;
+            try {
+                while (this.pending.length && !this.blocked && !this.failure) {
+                    const frame = this.pending.shift();
+                    this.queuedBytes -= Buffer.byteLength(frame);
+                    this.send(frame);
+                }
+                if (this.finishing && !this.blocked && !this.failure)
+                    this.destination.end();
+            }
+            catch (error) {
+                this.fail(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        this.onError = (error) => { this.fail(error); };
+        this.onClose = () => {
+            if (!this.finished)
+                this.fail(new Error('sse_closed'));
+            this.cleanup();
+        };
+        this.onFinish = () => {
+            if (this.failure)
+                return;
+            this.finished = true;
+            this.cleanup();
+            this.resolveCompletion?.();
+        };
+        if (!Number.isFinite(policy.maxBufferedBytes) || policy.maxBufferedBytes < 1
+            || !Number.isFinite(policy.drainTimeoutMs) || policy.drainTimeoutMs < 1)
+            throw new TypeError('Invalid SSE delivery policy');
+        destination.on('drain', this.onDrain);
+        destination.on('error', this.onError);
+        destination.once('close', this.onClose);
+        destination.once('finish', this.onFinish);
+    }
+    get pendingBytes() { return this.failure || this.finished ? 0 : this.queuedBytes + this.destination.writableLength; }
+    write(frame) {
+        if (this.failure)
+            throw this.failure;
+        if (this.finishing || this.finished || this.destination.destroyed || this.destination.writableEnded)
+            throw new Error('sse_closed');
+        const bytes = Buffer.byteLength(frame);
+        if (this.pending.length >= 128 || this.pendingBytes + bytes > this.policy.maxBufferedBytes) {
+            this.fail(new Error('sse_buffer_limit'));
+            throw this.failure;
+        }
+        if (this.blocked) {
+            this.pending.push(frame);
+            this.queuedBytes += bytes;
+            return;
+        }
+        this.send(frame);
+    }
+    finish() {
+        if (this.failure)
+            return Promise.reject(this.failure);
+        if (this.finished)
+            return Promise.resolve();
+        if (this.completion)
+            return this.completion;
+        this.finishing = true;
+        this.completion = new Promise((resolve, reject) => {
+            this.resolveCompletion = resolve;
+            this.rejectCompletion = reject;
+        });
+        if (!this.blocked && this.pending.length === 0)
+            this.destination.end();
+        return this.completion;
+    }
+    send(frame) {
+        try {
+            if (!this.destination.write(frame)) {
+                this.blocked = true;
+                this.timer = setTimeout(() => this.fail(new Error('sse_drain_timeout')), this.policy.drainTimeoutMs);
+                this.timer.unref();
+            }
+        }
+        catch (error) {
+            this.fail(error instanceof Error ? error : new Error(String(error)));
+            throw this.failure;
+        }
+    }
+    fail(error) {
+        if (this.failure || this.finished)
+            return;
+        this.failure = error;
+        this.pending.length = 0;
+        this.queuedBytes = 0;
+        clearTimeout(this.timer);
+        this.destination.removeListener('drain', this.onDrain);
+        this.rejectCompletion?.(error);
+        // Preserve the error for finish(); destroy without an unhandled second error event.
+        this.destination.destroy();
+    }
+    cleanup() {
+        clearTimeout(this.timer);
+        this.destination.removeListener('drain', this.onDrain);
+        this.destination.removeListener('error', this.onError);
+        this.destination.removeListener('close', this.onClose);
+        this.destination.removeListener('finish', this.onFinish);
+    }
+}
+exports.SseResponseWriter = SseResponseWriter;

package/dist/src/middleware/SseResponseWriter.test.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stream_1 = require("stream");
+const SseResponseWriter_1 = require("./SseResponseWriter");
+describe('SSE delivery lifecycle', () => {
+    function slowDestination() {
+        const frames = [];
+        const callbacks = [];
+        const destination = new stream_1.Writable({ highWaterMark: 1, write(chunk, _encoding, callback) {
+                frames.push(chunk.toString());
+                callbacks.push(callback);
+            } });
+        return { destination, frames, callbacks };
+    }
+    test('waits for drain, preserves frame order and completes exactly once', async () => {
+        const { destination, frames, callbacks } = slowDestination();
+        const writer = new SseResponseWriter_1.SseResponseWriter(destination, { maxBufferedBytes: 64, drainTimeoutMs: 1000 });
+        const finish = jest.fn();
+        destination.on('finish', finish);
+        writer.write('first');
+        writer.write('second');
+        const completed = writer.finish();
+        expect(frames).toEqual(['first']);
+        callbacks.shift()();
+        expect(frames).toEqual(['first', 'second']);
+        callbacks.shift()();
+        await completed;
+        await writer.finish();
+        expect(finish).toHaveBeenCalledTimes(1);
+        expect(writer.pendingBytes).toBe(0);
+    });
+    test('bounds pending bytes and destroys an overproducing stream', async () => {
+        const { destination } = slowDestination();
+        const writer = new SseResponseWriter_1.SseResponseWriter(destination, { maxBufferedBytes: 8, drainTimeoutMs: 1000 });
+        writer.write('123456');
+        expect(() => writer.write('789')).toThrow('sse_buffer_limit');
+        expect(destination.destroyed).toBe(true);
+        await expect(writer.finish()).rejects.toThrow('sse_buffer_limit');
+    });
+    test.each(['close', 'error', 'timeout'])('settles %s while waiting for a slow client', async (cause) => {
+        const { destination } = slowDestination();
+        const writer = new SseResponseWriter_1.SseResponseWriter(destination, { maxBufferedBytes: 64, drainTimeoutMs: 10 });
+        writer.write('first');
+        writer.write('second');
+        const completed = writer.finish();
+        if (cause === 'close')
+            destination.destroy();
+        if (cause === 'error')
+            destination.destroy(new Error('socket_failure'));
+        await expect(completed).rejects.toThrow(cause === 'timeout' ? 'sse_drain_timeout' : cause === 'error' ? 'socket_failure' : 'sse_closed');
+        expect(writer.pendingBytes).toBe(0);
+        expect(destination.listenerCount('drain')).toBe(0);
+    });
+});