dsh-mindmark 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/store.js ADDED
@@ -0,0 +1,747 @@
1
+ // dsh-mindmark — durable store for user annotations.
2
+ //
3
+ // The document lives outside every workspace, under the Harness home, because
4
+ // annotations belong to a conversation rather than to one project:
5
+ //
6
+ // {
7
+ // "version": 2,
8
+ // "sessions": {
9
+ // "<sessionId>": {
10
+ // "mode": "brief" | "full", // optional; injection view mode
11
+ // "annotations": [Annotation],
12
+ // "messages": { "<messageKey>": { "text": "...", "turn": 3 } }
13
+ // }
14
+ // }
15
+ // }
16
+ //
17
+ // Writes are atomic (temp + rename with retry) and a copy of the previous good
18
+ // document is retained as `state.backup.json`. Loading never throws: a corrupt
19
+ // file is moved aside and treated as empty. Saving never throws either — a
20
+ // failed save is reported through the optional logger and the in-memory state
21
+ // stays usable, so the HTTP boundary can never emit an unhandled rejection.
22
+
23
+ import fs from 'node:fs'
24
+ import os from 'node:os'
25
+ import path from 'node:path'
26
+
27
+ export const STATE_VERSION = 2
28
+ export const MAX_ANNOTATIONS_PER_SESSION = 300
29
+ export const MAX_ID_LENGTH = 80
30
+ export const MAX_QUOTE_LENGTH = 2000
31
+ export const MAX_NOTE_LENGTH = 2000
32
+ export const MAX_CONTEXT_LENGTH = 80
33
+ export const MAX_ROOT_SELECTOR_LENGTH = 300
34
+ export const MAX_SESSION_ID_LENGTH = 200
35
+ export const MAX_MESSAGE_KEY_LENGTH = 200
36
+ export const MAX_MESSAGE_TEXT_LENGTH = 20000
37
+ export const ANNOTATION_STYLES = ['highlight', 'underline', 'strike', 'comment', 'rewrite']
38
+ /** Styles whose meaning needs the user's own words. */
39
+ export const NOTE_STYLES = ['comment', 'rewrite']
40
+ export const ANNOTATION_STATUSES = ['pending', 'resolved']
41
+ export const INJECTION_MODES = ['brief', 'full']
42
+ export const DEFAULT_MODE = 'brief'
43
+
44
+ /** Error carrying a stable, user-facing code for the HTTP boundary / tool. */
45
+ export class AnnotateInputError extends Error {
46
+ constructor(code, message) {
47
+ super(message)
48
+ this.name = 'AnnotateInputError'
49
+ this.code = code
50
+ }
51
+ }
52
+
53
+ /** Resolve `$DSH_HOME/annotations/state.json` (or `%USERPROFILE%\.dsh/...`). */
54
+ export function resolveStatePath(env = process.env) {
55
+ const home =
56
+ typeof env?.DSH_HOME === 'string' && env.DSH_HOME.trim() !== ''
57
+ ? env.DSH_HOME
58
+ : path.join(os.homedir(), '.dsh')
59
+ return path.join(home, 'annotations', 'state.json')
60
+ }
61
+
62
+ /** Empty-but-valid document. */
63
+ export function emptyState() {
64
+ return { version: STATE_VERSION, sessions: {} }
65
+ }
66
+
67
+ function truncate(value, max) {
68
+ return typeof value === 'string' ? value.slice(0, max) : ''
69
+ }
70
+
71
+ /** Server-side id for a record whose client omitted `id`. */
72
+ export function generateAnnotationId() {
73
+ return `ann_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
74
+ }
75
+
76
+ /**
77
+ * Validate a session id coming from the wire or from an Agent. Returns the id
78
+ * unchanged (session ids are opaque) and throws a user-facing InputError
79
+ * otherwise.
80
+ */
81
+ export function validateSessionId(sessionId) {
82
+ if (
83
+ typeof sessionId !== 'string' ||
84
+ sessionId.trim() === '' ||
85
+ sessionId.length > MAX_SESSION_ID_LENGTH
86
+ ) {
87
+ throw new AnnotateInputError('invalid-session-id', '会话 ID 无效。')
88
+ }
89
+ return sessionId
90
+ }
91
+
92
+ /** Validate an injection mode from the wire or the tool. */
93
+ export function validateMode(mode) {
94
+ if (!INJECTION_MODES.includes(mode)) {
95
+ throw new AnnotateInputError('invalid-mode', '模式必须是 brief(精简)或 full(完整)。')
96
+ }
97
+ return mode
98
+ }
99
+
100
+ function contextString(value, max) {
101
+ if (value === undefined || value === null) return ''
102
+ if (typeof value !== 'string') {
103
+ throw new AnnotateInputError('invalid-annotation-context', '标注上下文格式不正确。')
104
+ }
105
+ return truncate(value, max)
106
+ }
107
+
108
+ function optionalInteger(value) {
109
+ if (value === undefined || value === null || value === '') return undefined
110
+ const number = typeof value === 'number' ? value : Number(value)
111
+ if (!Number.isInteger(number) || number < 0) return undefined
112
+ return number
113
+ }
114
+
115
+ /**
116
+ * Normalize one incoming Annotation (wire format, client -> Host). Missing
117
+ * optional fields are filled in; anything shaped wrongly is rejected with a
118
+ * Chinese message so the route can answer 400.
119
+ */
120
+ export function validateAnnotationInput(raw) {
121
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
122
+ throw new AnnotateInputError('invalid-annotation', '标注格式不正确。')
123
+ }
124
+ if (!ANNOTATION_STYLES.includes(raw.style)) {
125
+ throw new AnnotateInputError(
126
+ 'invalid-annotation-style',
127
+ `标注类型必须是 ${ANNOTATION_STYLES.join('、')} 之一。`,
128
+ )
129
+ }
130
+ if (
131
+ typeof raw.quote !== 'string' ||
132
+ raw.quote.trim().length < 1 ||
133
+ raw.quote.trim().length > MAX_QUOTE_LENGTH
134
+ ) {
135
+ throw new AnnotateInputError(
136
+ 'invalid-annotation-quote',
137
+ `标注文本必须是 1–${MAX_QUOTE_LENGTH} 个字符的字符串。`,
138
+ )
139
+ }
140
+
141
+ let note = ''
142
+ if (raw.note !== undefined && raw.note !== null) {
143
+ if (typeof raw.note !== 'string') {
144
+ throw new AnnotateInputError('invalid-annotation-note', '批注内容必须是字符串。')
145
+ }
146
+ note = raw.note.trim().slice(0, MAX_NOTE_LENGTH)
147
+ }
148
+ if (NOTE_STYLES.includes(raw.style) && note === '') {
149
+ throw new AnnotateInputError(
150
+ 'missing-annotation-note',
151
+ raw.style === 'rewrite' ? '改写需要给出替换后的文字。' : '批注需要填写内容。',
152
+ )
153
+ }
154
+
155
+ let id
156
+ if (raw.id === undefined || raw.id === null || raw.id === '') {
157
+ id = generateAnnotationId()
158
+ } else if (typeof raw.id === 'string') {
159
+ id = raw.id.trim().slice(0, MAX_ID_LENGTH)
160
+ if (id === '') id = generateAnnotationId()
161
+ } else {
162
+ throw new AnnotateInputError('invalid-annotation-id', '标注 ID 必须是字符串。')
163
+ }
164
+
165
+ let createdAt
166
+ if (raw.createdAt === undefined || raw.createdAt === null) {
167
+ createdAt = new Date().toISOString()
168
+ } else if (typeof raw.createdAt === 'string' && raw.createdAt.trim() !== '') {
169
+ createdAt = raw.createdAt
170
+ } else {
171
+ throw new AnnotateInputError('invalid-annotation-created-at', '标注时间格式不正确。')
172
+ }
173
+
174
+ const messageKey = contextString(raw.messageKey, MAX_MESSAGE_KEY_LENGTH)
175
+ const messageStart = optionalInteger(raw.messageStart)
176
+ const messageEnd = optionalInteger(raw.messageEnd)
177
+ const anchored =
178
+ messageKey !== '' &&
179
+ messageStart !== undefined &&
180
+ messageEnd !== undefined &&
181
+ messageEnd > messageStart
182
+
183
+ // Keep harmless unknown fields from newer/older clients; the known fields win.
184
+ const record = {
185
+ ...raw,
186
+ id,
187
+ style: raw.style,
188
+ quote: raw.quote,
189
+ note,
190
+ prefix: contextString(raw.prefix, MAX_CONTEXT_LENGTH),
191
+ suffix: contextString(raw.suffix, MAX_CONTEXT_LENGTH),
192
+ rootSelector: contextString(raw.rootSelector, MAX_ROOT_SELECTOR_LENGTH),
193
+ messageKey: anchored ? messageKey : '',
194
+ createdAt,
195
+ status: 'pending',
196
+ injections: 0,
197
+ }
198
+ return withAnchor(record, anchored ? messageStart : undefined, anchored ? messageEnd : undefined, optionalInteger(raw.turn))
199
+ }
200
+
201
+ /** Set or drop the optional anchor fields so a record never carries `undefined` keys. */
202
+ function withAnchor(record, messageStart, messageEnd, turn) {
203
+ if (messageStart === undefined || messageEnd === undefined) {
204
+ delete record.messageStart
205
+ delete record.messageEnd
206
+ } else {
207
+ record.messageStart = messageStart
208
+ record.messageEnd = messageEnd
209
+ }
210
+ if (turn === undefined) delete record.turn
211
+ else record.turn = turn
212
+ return record
213
+ }
214
+
215
+ /**
216
+ * Normalize one incoming message capture `{ key, text, turn }` (the full text
217
+ * of the message an annotation belongs to). Returns null when it is unusable;
218
+ * a bad capture never fails the annotation itself.
219
+ */
220
+ export function validateMessageInput(raw) {
221
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
222
+ const key = typeof raw.key === 'string' ? raw.key.trim().slice(0, MAX_MESSAGE_KEY_LENGTH) : ''
223
+ if (key === '') return null
224
+ if (typeof raw.text !== 'string' || raw.text.length === 0 || raw.text.length > MAX_MESSAGE_TEXT_LENGTH) {
225
+ return null
226
+ }
227
+ const turn = optionalInteger(raw.turn)
228
+ return turn === undefined ? { key, text: raw.text } : { key, text: raw.text, turn }
229
+ }
230
+
231
+ /** Normalize one stored record. Returns null for a malformed entry. */
232
+ function normalizeStoredAnnotation(raw) {
233
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
234
+ if (typeof raw.id !== 'string' || raw.id.trim() === '') return null
235
+ if (!ANNOTATION_STYLES.includes(raw.style)) return null
236
+ if (typeof raw.quote !== 'string') return null
237
+ const quoteLength = raw.quote.trim().length
238
+ if (quoteLength < 1 || quoteLength > MAX_QUOTE_LENGTH) return null
239
+ if (typeof raw.createdAt !== 'string' || raw.createdAt.trim() === '') return null
240
+ const messageKey = truncate(raw.messageKey, MAX_MESSAGE_KEY_LENGTH)
241
+ const messageStart = optionalInteger(raw.messageStart)
242
+ const messageEnd = optionalInteger(raw.messageEnd)
243
+ const anchored =
244
+ messageKey !== '' && messageStart !== undefined && messageEnd !== undefined && messageEnd > messageStart
245
+ const injections = optionalInteger(raw.injections) ?? 0
246
+ const status = ANNOTATION_STATUSES.includes(raw.status) ? raw.status : 'pending'
247
+ const record = withAnchor({
248
+ ...raw,
249
+ id: truncate(raw.id.trim(), MAX_ID_LENGTH),
250
+ style: raw.style,
251
+ quote: raw.quote,
252
+ note: truncate(typeof raw.note === 'string' ? raw.note.trim() : '', MAX_NOTE_LENGTH),
253
+ prefix: truncate(raw.prefix, MAX_CONTEXT_LENGTH),
254
+ suffix: truncate(raw.suffix, MAX_CONTEXT_LENGTH),
255
+ rootSelector: truncate(raw.rootSelector, MAX_ROOT_SELECTOR_LENGTH),
256
+ messageKey: anchored ? messageKey : '',
257
+ createdAt: raw.createdAt,
258
+ status,
259
+ injections,
260
+ }, anchored ? messageStart : undefined, anchored ? messageEnd : undefined, optionalInteger(raw.turn))
261
+ if (status === 'resolved') {
262
+ record.resolvedAt = typeof raw.resolvedAt === 'string' ? raw.resolvedAt : raw.createdAt
263
+ record.resolvedBy = typeof raw.resolvedBy === 'string' ? raw.resolvedBy.slice(0, 20) : 'user'
264
+ } else {
265
+ delete record.resolvedAt
266
+ delete record.resolvedBy
267
+ }
268
+ if (record.lastInjectedTurn !== undefined && optionalInteger(record.lastInjectedTurn) === undefined) {
269
+ delete record.lastInjectedTurn
270
+ }
271
+ return record
272
+ }
273
+
274
+ function normalizeStoredMessages(raw, annotations) {
275
+ const messages = {}
276
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return messages
277
+ const referenced = new Set(annotations.map(item => item.messageKey).filter(key => key !== ''))
278
+ for (const [key, value] of Object.entries(raw)) {
279
+ if (!referenced.has(key)) continue
280
+ const message = validateMessageInput({ ...(value ?? {}), key })
281
+ if (message !== null) messages[key] = { text: message.text, ...(message.turn === undefined ? {} : { turn: message.turn }) }
282
+ }
283
+ return messages
284
+ }
285
+
286
+ /** Normalize one stored session. Returns null when it carries nothing worth keeping. */
287
+ function normalizeStoredSession(raw) {
288
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
289
+ const annotations = []
290
+ if (Array.isArray(raw.annotations)) {
291
+ for (const item of raw.annotations) {
292
+ const annotation = normalizeStoredAnnotation(item)
293
+ if (annotation !== null) annotations.push(annotation)
294
+ }
295
+ }
296
+ const mode = INJECTION_MODES.includes(raw.mode) && raw.mode !== DEFAULT_MODE ? raw.mode : undefined
297
+ if (annotations.length === 0 && mode === undefined) return null
298
+ const capped =
299
+ annotations.length > MAX_ANNOTATIONS_PER_SESSION
300
+ ? annotations.slice(-MAX_ANNOTATIONS_PER_SESSION)
301
+ : annotations
302
+ const session = { annotations: capped, messages: normalizeStoredMessages(raw.messages, capped) }
303
+ if (mode !== undefined) session.mode = mode
304
+ return session
305
+ }
306
+
307
+ /**
308
+ * Coerce an arbitrary parsed document into the safe in-memory shape. Never
309
+ * throws: garbage sections and malformed records are dropped, empty session
310
+ * keys are removed, and the per-session cap is re-applied.
311
+ */
312
+ export function normalizeState(raw) {
313
+ const state = emptyState()
314
+ try {
315
+ const sessions =
316
+ raw !== null &&
317
+ typeof raw === 'object' &&
318
+ !Array.isArray(raw) &&
319
+ raw.sessions !== null &&
320
+ typeof raw.sessions === 'object' &&
321
+ !Array.isArray(raw.sessions)
322
+ ? raw.sessions
323
+ : {}
324
+ for (const [sessionId, sessionRaw] of Object.entries(sessions)) {
325
+ if (
326
+ typeof sessionId !== 'string' ||
327
+ sessionId.trim() === '' ||
328
+ sessionId.length > MAX_SESSION_ID_LENGTH
329
+ ) {
330
+ continue
331
+ }
332
+ const session = normalizeStoredSession(sessionRaw)
333
+ if (session !== null) state.sessions[sessionId] = session
334
+ }
335
+ } catch {
336
+ // `normalizeState` never throws; a partially normalized document is fine.
337
+ }
338
+ return state
339
+ }
340
+
341
+ /** Drop session keys that carry nothing (no annotations and the default mode). */
342
+ function pruneEmptySessions(state) {
343
+ if (state === null || typeof state !== 'object' || Array.isArray(state)) return state
344
+ if (state.sessions === null || typeof state.sessions !== 'object' || Array.isArray(state.sessions)) {
345
+ state.sessions = {}
346
+ return state
347
+ }
348
+ for (const [sessionId, session] of Object.entries(state.sessions)) {
349
+ const empty =
350
+ session === null ||
351
+ typeof session !== 'object' ||
352
+ !Array.isArray(session.annotations) ||
353
+ session.annotations.length === 0
354
+ const defaultMode = session?.mode === undefined || session?.mode === DEFAULT_MODE
355
+ if (empty && defaultMode) {
356
+ delete state.sessions[sessionId]
357
+ } else if (empty) {
358
+ session.annotations = []
359
+ session.messages = {}
360
+ }
361
+ }
362
+ return state
363
+ }
364
+
365
+ function ensureDirectory(filePath) {
366
+ fs.mkdirSync(path.dirname(filePath), { recursive: true })
367
+ }
368
+
369
+ /**
370
+ * Load a document. A missing file means an empty document; a corrupt file is
371
+ * copied aside (`state.json.corrupt-<ts>`) instead of being silently
372
+ * overwritten. Never throws.
373
+ */
374
+ export function loadStateFile(filePath, { logger } = {}) {
375
+ try {
376
+ ensureDirectory(filePath)
377
+ } catch (error) {
378
+ logger?.warn?.(`dsh-mindmark: cannot create the annotation directory: ${String(error)}`)
379
+ return emptyState()
380
+ }
381
+ let raw
382
+ try {
383
+ raw = fs.readFileSync(filePath, 'utf8')
384
+ } catch (error) {
385
+ if (error?.code !== 'ENOENT') {
386
+ logger?.warn?.(`dsh-mindmark: cannot read ${filePath}: ${String(error)}`)
387
+ }
388
+ return emptyState()
389
+ }
390
+ try {
391
+ return normalizeState(JSON.parse(raw))
392
+ } catch (error) {
393
+ const backup = `${filePath}.corrupt-${Date.now()}`
394
+ try {
395
+ fs.copyFileSync(filePath, backup)
396
+ } catch {
397
+ // Best effort: the unreadable original remains in place.
398
+ }
399
+ logger?.warn?.(
400
+ `dsh-mindmark: annotation state was unreadable (${String(error)}); backup at ${backup}`,
401
+ )
402
+ return emptyState()
403
+ }
404
+ }
405
+
406
+ /** `state.json` -> `state.backup.json` (contract's name). */
407
+ export function backupPathFor(filePath) {
408
+ const base = path.basename(filePath)
409
+ const stem = base.toLowerCase().endsWith('.json') ? base.slice(0, -'.json'.length) : base
410
+ return path.join(path.dirname(filePath), `${stem}.backup.json`)
411
+ }
412
+
413
+ /** Windows can briefly lock the destination after an antivirus scan. */
414
+ function replaceWithRetry(temp, filePath) {
415
+ let lastError
416
+ for (let attempt = 0; attempt < 6; attempt += 1) {
417
+ try {
418
+ fs.renameSync(temp, filePath)
419
+ return
420
+ } catch (error) {
421
+ lastError = error
422
+ if (error?.code !== 'EPERM' && error?.code !== 'EBUSY' && error?.code !== 'EACCES') {
423
+ throw error
424
+ }
425
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 40 * (attempt + 1))
426
+ }
427
+ }
428
+ // A non-atomic copy is still preferable to losing the user's annotations.
429
+ fs.copyFileSync(temp, filePath)
430
+ fs.unlinkSync(temp)
431
+ if (!fs.existsSync(filePath)) throw lastError
432
+ }
433
+
434
+ /** Atomically replace the document, keeping one previous good copy. */
435
+ export function saveStateFile(filePath, state) {
436
+ ensureDirectory(filePath)
437
+ const document = pruneEmptySessions(
438
+ state !== null && typeof state === 'object' && !Array.isArray(state) ? state : emptyState(),
439
+ )
440
+ const json = `${JSON.stringify(document, null, 2)}\n`
441
+ const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`
442
+ fs.writeFileSync(temp, json, { encoding: 'utf8', mode: 0o600 })
443
+ try {
444
+ if (fs.existsSync(filePath)) {
445
+ try {
446
+ fs.copyFileSync(filePath, backupPathFor(filePath))
447
+ } catch {
448
+ // The next successful write can try the backup again.
449
+ }
450
+ }
451
+ replaceWithRetry(temp, filePath)
452
+ } finally {
453
+ try {
454
+ if (fs.existsSync(temp)) fs.unlinkSync(temp)
455
+ } catch {
456
+ // Leftover temp files are harmless.
457
+ }
458
+ }
459
+ }
460
+
461
+ function cleanIds(ids) {
462
+ return new Set((Array.isArray(ids) ? ids : []).filter(id => typeof id === 'string' && id.trim() !== ''))
463
+ }
464
+
465
+ /**
466
+ * Small synchronous store; the document is tiny and mutations are serialized.
467
+ * Save failures are logged but never thrown, so the HTTP handler and the tool
468
+ * keep working with the in-memory document.
469
+ */
470
+ export class AnnotationStore {
471
+ constructor(filePath, { logger, defaultMode } = {}) {
472
+ this.filePath = filePath ?? resolveStatePath()
473
+ this.logger = logger
474
+ this.defaultMode = INJECTION_MODES.includes(defaultMode) ? defaultMode : DEFAULT_MODE
475
+ this.state = loadStateFile(this.filePath, { logger })
476
+ this.lastSaveError = null
477
+ // Canonicalize what was loaded (and create the file early, best effort).
478
+ this.persist()
479
+ }
480
+
481
+ /** Session id -> safe session object, or undefined. */
482
+ sessionFor(sessionId) {
483
+ if (typeof sessionId !== 'string') return undefined
484
+ const session = this.state.sessions[sessionId]
485
+ if (
486
+ session === null ||
487
+ typeof session !== 'object' ||
488
+ !Array.isArray(session.annotations)
489
+ ) {
490
+ return undefined
491
+ }
492
+ if (session.messages === null || typeof session.messages !== 'object' || Array.isArray(session.messages)) {
493
+ session.messages = {}
494
+ }
495
+ return session
496
+ }
497
+
498
+ ensureSession(sessionId) {
499
+ const key = validateSessionId(sessionId)
500
+ let session = this.sessionFor(key)
501
+ if (session === undefined) {
502
+ session = { annotations: [], messages: {} }
503
+ this.state.sessions[key] = session
504
+ }
505
+ return session
506
+ }
507
+
508
+ /** Oldest first, always a fresh array. */
509
+ list(sessionId) {
510
+ const session = this.sessionFor(sessionId)
511
+ if (session === undefined) return []
512
+ return session.annotations.map(annotation => ({ ...annotation }))
513
+ }
514
+
515
+ /** Annotations still waiting for the model, oldest first. */
516
+ pending(sessionId) {
517
+ return this.list(sessionId).filter(annotation => annotation.status !== 'resolved')
518
+ }
519
+
520
+ /** The injection mode for one session (the configured default when unset). */
521
+ getMode(sessionId) {
522
+ const session = this.sessionFor(sessionId)
523
+ const mode = session?.mode
524
+ return INJECTION_MODES.includes(mode) ? mode : this.defaultMode
525
+ }
526
+
527
+ /** Record the injection mode for one session. */
528
+ setMode(sessionId, mode) {
529
+ const next = validateMode(mode)
530
+ const session = this.ensureSession(sessionId)
531
+ if (next === this.defaultMode) delete session.mode
532
+ else session.mode = next
533
+ this.persist()
534
+ return next
535
+ }
536
+
537
+ /** The captured full text of one message, or undefined. */
538
+ messageOf(sessionId, messageKey) {
539
+ const session = this.sessionFor(sessionId)
540
+ if (session === undefined || typeof messageKey !== 'string' || messageKey === '') return undefined
541
+ const message = session.messages[messageKey]
542
+ if (message === null || typeof message !== 'object' || typeof message.text !== 'string') return undefined
543
+ return { ...message }
544
+ }
545
+
546
+ /** Everything the injection builder needs for one session. */
547
+ snapshot(sessionId) {
548
+ const session = this.sessionFor(sessionId)
549
+ return {
550
+ mode: this.getMode(sessionId),
551
+ annotations: this.list(sessionId),
552
+ messages:
553
+ session === undefined
554
+ ? {}
555
+ : Object.fromEntries(Object.entries(session.messages).map(([key, value]) => [key, { ...value }])),
556
+ }
557
+ }
558
+
559
+ /**
560
+ * Append one annotation. An identical `(style, quote, prefix, suffix, note)`
561
+ * marks the same passage again: its `createdAt` is refreshed, it becomes
562
+ * pending again and moves to the end instead of being duplicated. The
563
+ * per-session cap drops the oldest. `message` optionally captures the full
564
+ * text of the message the annotation belongs to.
565
+ */
566
+ add(sessionId, annotation, message) {
567
+ const record = validateAnnotationInput(annotation)
568
+ const session = this.ensureSession(sessionId)
569
+ const capture = validateMessageInput(message)
570
+ if (capture !== null && record.messageKey === capture.key) {
571
+ session.messages[capture.key] = {
572
+ text: capture.text,
573
+ ...(capture.turn === undefined ? {} : { turn: capture.turn }),
574
+ }
575
+ if (record.turn === undefined && capture.turn !== undefined) record.turn = capture.turn
576
+ } else if (record.messageKey !== '' && session.messages[record.messageKey] === undefined) {
577
+ // Anchored to a message we never captured: keep the offsets harmless.
578
+ record.messageKey = ''
579
+ record.messageStart = undefined
580
+ record.messageEnd = undefined
581
+ }
582
+ const index = session.annotations.findIndex(
583
+ item =>
584
+ item.style === record.style &&
585
+ item.quote === record.quote &&
586
+ item.prefix === record.prefix &&
587
+ item.suffix === record.suffix &&
588
+ item.note === record.note,
589
+ )
590
+ let result
591
+ if (index >= 0) {
592
+ const existing = session.annotations[index]
593
+ const anchorSource = record.messageKey !== '' ? record : existing
594
+ const refreshed = withAnchor({
595
+ ...existing,
596
+ createdAt: record.createdAt,
597
+ status: 'pending',
598
+ injections: 0,
599
+ messageKey: anchorSource.messageKey ?? '',
600
+ }, anchorSource.messageStart, anchorSource.messageEnd, record.turn ?? existing.turn)
601
+ delete refreshed.resolvedAt
602
+ delete refreshed.resolvedBy
603
+ delete refreshed.lastInjectedTurn
604
+ session.annotations.splice(index, 1)
605
+ session.annotations.push(refreshed)
606
+ result = { annotation: { ...refreshed }, deduped: true }
607
+ } else {
608
+ session.annotations.push({ ...record })
609
+ if (session.annotations.length > MAX_ANNOTATIONS_PER_SESSION) {
610
+ session.annotations.splice(0, session.annotations.length - MAX_ANNOTATIONS_PER_SESSION)
611
+ }
612
+ result = { annotation: { ...record }, deduped: false }
613
+ }
614
+ this.pruneMessages(session)
615
+ this.persist()
616
+ return result
617
+ }
618
+
619
+ /** Drop captured messages no annotation references any more. */
620
+ pruneMessages(session) {
621
+ const referenced = new Set(session.annotations.map(item => item.messageKey).filter(key => key !== ''))
622
+ for (const key of Object.keys(session.messages)) {
623
+ if (!referenced.has(key)) delete session.messages[key]
624
+ }
625
+ }
626
+
627
+ /** Remove annotations by id. Returns how many were removed. */
628
+ remove(sessionId, ids) {
629
+ const session = this.sessionFor(sessionId)
630
+ if (session === undefined) return 0
631
+ const wanted = cleanIds(ids)
632
+ if (wanted.size === 0) return 0
633
+ const before = session.annotations.length
634
+ session.annotations = session.annotations.filter(item => !wanted.has(item.id))
635
+ const removed = before - session.annotations.length
636
+ if (removed > 0) {
637
+ this.pruneMessages(session)
638
+ this.persist()
639
+ }
640
+ return removed
641
+ }
642
+
643
+ /** Remove every annotation of one session (the mode is kept). Returns how many were removed. */
644
+ clear(sessionId) {
645
+ const session = this.sessionFor(sessionId)
646
+ if (session === undefined) return 0
647
+ const removed = session.annotations.length
648
+ session.annotations = []
649
+ session.messages = {}
650
+ if (removed > 0) this.persist()
651
+ return removed
652
+ }
653
+
654
+ /**
655
+ * Mark annotations as handled. `ids` undefined/empty means every pending
656
+ * annotation. `by` records who settled them: `model`, `user` or `cap`.
657
+ * Returns the ids that changed.
658
+ */
659
+ resolve(sessionId, ids, { by = 'user', at } = {}) {
660
+ const session = this.sessionFor(sessionId)
661
+ if (session === undefined) return []
662
+ const wanted = cleanIds(ids)
663
+ const stamp = typeof at === 'string' ? at : new Date().toISOString()
664
+ const changed = []
665
+ for (const item of session.annotations) {
666
+ if (item.status === 'resolved') continue
667
+ if (wanted.size > 0 && !wanted.has(item.id)) continue
668
+ item.status = 'resolved'
669
+ item.resolvedAt = stamp
670
+ item.resolvedBy = by
671
+ changed.push(item.id)
672
+ }
673
+ if (changed.length > 0) this.persist()
674
+ return changed
675
+ }
676
+
677
+ /**
678
+ * Put annotations back in front of the model. `ids` undefined/empty means
679
+ * every annotation. The injection counter restarts. Returns the ids that changed.
680
+ */
681
+ reopen(sessionId, ids) {
682
+ const session = this.sessionFor(sessionId)
683
+ if (session === undefined) return []
684
+ const wanted = cleanIds(ids)
685
+ const changed = []
686
+ for (const item of session.annotations) {
687
+ if (wanted.size > 0 && !wanted.has(item.id)) continue
688
+ if (item.status === 'pending' && item.injections === 0) continue
689
+ item.status = 'pending'
690
+ item.injections = 0
691
+ delete item.resolvedAt
692
+ delete item.resolvedBy
693
+ delete item.lastInjectedTurn
694
+ changed.push(item.id)
695
+ }
696
+ if (changed.length > 0) this.persist()
697
+ return changed
698
+ }
699
+
700
+ /**
701
+ * Count one injection for the given pending annotations and settle those
702
+ * that reached `cap` before this turn (`resolvedBy: 'cap'`).
703
+ * Returns `{ injected: ids, capped: ids }`; only `injected` were included.
704
+ */
705
+ markInjected(sessionId, ids, { turn, cap } = {}) {
706
+ const session = this.sessionFor(sessionId)
707
+ if (session === undefined) return { injected: [], capped: [] }
708
+ const wanted = cleanIds(ids)
709
+ const injected = []
710
+ const capped = []
711
+ const limit = Number.isInteger(cap) && cap > 0 ? cap : undefined
712
+ for (const item of session.annotations) {
713
+ if (item.status === 'resolved' || !wanted.has(item.id)) continue
714
+ if (limit !== undefined && item.injections >= limit) {
715
+ item.status = 'resolved'
716
+ item.resolvedAt = new Date().toISOString()
717
+ item.resolvedBy = 'cap'
718
+ capped.push(item.id)
719
+ continue
720
+ }
721
+ item.injections += 1
722
+ if (Number.isInteger(turn)) item.lastInjectedTurn = turn
723
+ injected.push(item.id)
724
+ }
725
+ if (injected.length > 0 || capped.length > 0) this.persist()
726
+ return { injected, capped }
727
+ }
728
+
729
+ /** Pending annotations that may still be injected under `cap`. */
730
+ injectable(sessionId, cap) {
731
+ const limit = Number.isInteger(cap) && cap > 0 ? cap : undefined
732
+ return this.pending(sessionId).filter(item => limit === undefined || item.injections < limit)
733
+ }
734
+
735
+ /** Save the document; failures are logged and recorded, never thrown. */
736
+ persist() {
737
+ try {
738
+ saveStateFile(this.filePath, this.state)
739
+ this.lastSaveError = null
740
+ return true
741
+ } catch (error) {
742
+ this.lastSaveError = error
743
+ this.logger?.warn?.(`dsh-mindmark: cannot save ${this.filePath}: ${String(error)}`)
744
+ return false
745
+ }
746
+ }
747
+ }