advisers 0.3.2 → 0.4.1

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.
Files changed (44) hide show
  1. package/README-zh.md +13 -14
  2. package/README.md +37 -23
  3. package/THIRD-PARTY-NOTICES.md +1 -1
  4. package/bin/advisers.js +2302 -95
  5. package/index.js +1 -1
  6. package/lib/brief-archive.js +267 -0
  7. package/lib/client-pack.js +1016 -0
  8. package/lib/consent.js +390 -0
  9. package/lib/credentials.js +195 -0
  10. package/lib/error-codes.js +516 -7
  11. package/lib/evidence.js +697 -113
  12. package/lib/kb-extract.js +626 -0
  13. package/lib/kb-facts.js +429 -0
  14. package/lib/kb-pages.js +1084 -0
  15. package/lib/kb.js +1036 -0
  16. package/lib/mail-errors.js +46 -0
  17. package/lib/mail-extract.js +351 -0
  18. package/lib/mail-imap.js +446 -0
  19. package/lib/mail-import.js +176 -0
  20. package/lib/mail-parse.js +223 -0
  21. package/lib/mail-store.js +731 -0
  22. package/lib/mail.js +506 -0
  23. package/lib/mcp-server.js +196 -10
  24. package/lib/notify.js +265 -7
  25. package/lib/policy/decision.js +315 -0
  26. package/lib/policy/egress.js +268 -0
  27. package/lib/policy/errors.js +71 -0
  28. package/lib/policy/index.js +99 -0
  29. package/lib/policy/rules.js +468 -0
  30. package/lib/policy/surfaces.js +141 -0
  31. package/lib/receipt-verify.js +199 -19
  32. package/lib/receivables.js +1653 -0
  33. package/lib/scheduler.js +453 -9
  34. package/lib/shell.js +1406 -0
  35. package/lib/source.js +98 -3
  36. package/lib/sqlite.js +366 -49
  37. package/lib/tos/index.js +2 -2
  38. package/lib/tos/manifest.json +6 -6
  39. package/lib/tos/privacy.zh-CN.md +33 -20
  40. package/lib/tos/safety.zh-CN.md +7 -6
  41. package/lib/tos/summary.zh-CN.md +3 -2
  42. package/lib/tos/terms.zh-CN.md +31 -16
  43. package/lib/urgency.js +467 -0
  44. package/package.json +4 -4
package/lib/mail.js ADDED
@@ -0,0 +1,506 @@
1
+ /**
2
+ * Public mail-entry API for Advisers 0.4.0 (bin integration calls these).
3
+ *
4
+ * Surfaces:
5
+ * mailAccountAdd/List/Show/Remove local account config (credentials live in
6
+ * lib/credentials.js, never in the DB)
7
+ * mailSync the ONLY IMAP network entry point
8
+ * mailList/mailShow local reads (body only with show --body)
9
+ * mailExtract local rules by default; model opt-in
10
+ * mailLink/mailDismiss manual review helpers
11
+ * mailPurge retention (30 days by default)
12
+ * mailImport offline .eml/.mbox fallback
13
+ *
14
+ * Invariants:
15
+ * - mailSync performs network I/O BEFORE opening the write transaction and
16
+ * then commits messages + UIDVALIDITY/UID cursor + run row in ONE
17
+ * BEGIN IMMEDIATE (lib/mail-store.js applyMailSyncBatch);
18
+ * - UIDVALIDITY changes never delete local rows: the cursor is marked
19
+ * needs_resync and E_IMAP_UIDVALIDITY asks for --full;
20
+ * - no function logs; errors are coded and never contain the password or the
21
+ * body; every write appends an audit row in the same transaction;
22
+ * - sync/extract never write to the ledger beyond mail tables + pending
23
+ * memory_candidates (never auto-accept).
24
+ */
25
+ import { hasImapCredential, listImapCredentialAccountIds, readImapCredential, removeImapCredential, saveImapCredential } from './credentials.js'
26
+ import { isMailError, mailError, MAIL_ERROR_CODES } from './mail-errors.js'
27
+ import { openMailImapSession } from './mail-imap.js'
28
+ import { parseMailMessage } from './mail-parse.js'
29
+ import { extractCandidatesWithModel, extractLocalCandidates, mailEvidenceSource, toMemoryCandidate } from './mail-extract.js'
30
+ import { importMailFiles } from './mail-import.js'
31
+ import * as mailDb from './mail-store.js'
32
+
33
+ export { MAIL_ERROR_CODES }
34
+ export const MAIL_MAX_MESSAGE_BYTES = mailDb.MAIL_MAX_MESSAGE_BYTES
35
+ export const MAIL_DEFAULT_RETENTION_DAYS = mailDb.MAIL_DEFAULT_RETENTION_DAYS
36
+ export const MAIL_LOCAL_ACCOUNT_ID = mailDb.MAIL_LOCAL_ACCOUNT_ID
37
+
38
+ function asDate(value) {
39
+ const date = value instanceof Date ? value : new Date(value ?? Date.now())
40
+ return Number.isFinite(date.getTime()) ? date : new Date()
41
+ }
42
+
43
+ function parseHeaderDate(value) {
44
+ if (!value) return null
45
+ const parsed = Date.parse(value)
46
+ return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null
47
+ }
48
+
49
+ function listActiveEntities(store, method) {
50
+ try {
51
+ if (typeof store?.[method] !== 'function') return []
52
+ return store[method]({ status: 'active', limit: 500 })
53
+ } catch { return [] }
54
+ }
55
+
56
+ /* ------------------------------------------------------------------ */
57
+ /* Accounts */
58
+ /* ------------------------------------------------------------------ */
59
+
60
+ /**
61
+ * Create one mail account. Optionally stores the IMAP credential atomically
62
+ * (options.credential = { user?, pass }); the password is never written to the
63
+ * ledger, argv or logs. `secure:false` / `tls:'none'` are rejected.
64
+ */
65
+ export function mailAccountAdd(store, config = {}, options = {}) {
66
+ mailDb.assertMailTables(store)
67
+ const now = asDate(options.now)
68
+ const prepared = mailDb.prepareMailAccount(config, { now, id: options.id })
69
+ const credential = options.credential ?? config.credential
70
+ let credentialSaved = false
71
+ if (credential !== undefined && credential !== null) {
72
+ if (typeof credential !== 'object' || typeof credential.pass !== 'string') {
73
+ throw mailError(MAIL_ERROR_CODES.CONFIG, 'credential must be an object with { user, pass }', 'pass the password from a TTY/app-password prompt or stdin, never from argv')
74
+ }
75
+ const user = credential.user == null ? prepared.username : String(credential.user)
76
+ if (user !== prepared.username) throw mailError(MAIL_ERROR_CODES.CONFIG, 'credential user must match the account username')
77
+ saveImapCredential(prepared.id, { user, pass: credential.pass }, { home: options.home, now })
78
+ credentialSaved = true
79
+ }
80
+ const audit = { actor: options.actor ?? 'local', action: 'mail.account.add', allowed: true, reason: prepared.id }
81
+ try {
82
+ store.mutate(() => mailDb.insertMailAccount(store, prepared), audit)
83
+ } catch (error) {
84
+ if (credentialSaved) { try { removeImapCredential(prepared.id, { home: options.home }) } catch {} }
85
+ throw error
86
+ }
87
+ return { ok: true, command: 'mail account add', account: { ...prepared, hasCredential: credentialSaved } }
88
+ }
89
+
90
+ export function mailAccountList(store, options = {}) {
91
+ mailDb.assertMailTables(store)
92
+ const accounts = mailDb.listMailAccounts(store, { includeRemoved: options.includeRemoved === true })
93
+ const credentialIds = new Set(listImapCredentialAccountIds({ home: options.home }))
94
+ const rows = accounts.map((account) => ({ ...account, hasCredential: credentialIds.has(account.id) }))
95
+ return { ok: true, command: 'mail account ls', accounts: rows, total: rows.length }
96
+ }
97
+
98
+ export function mailAccountShow(store, ref, options = {}) {
99
+ mailDb.assertMailTables(store)
100
+ const account = mailDb.getMailAccount(store, ref, { includeRemoved: options.includeRemoved === true })
101
+ return {
102
+ ok: true, command: 'mail account show',
103
+ account: { ...account, hasCredential: hasImapCredential(account.id, { home: options.home }) },
104
+ }
105
+ }
106
+
107
+ /**
108
+ * Remove one account: credential file + sync cursors + run history; local
109
+ * message rows are kept by default (they may back accepted evidence).
110
+ */
111
+ export function mailAccountRemove(store, ref, options = {}) {
112
+ mailDb.assertMailTables(store)
113
+ const now = asDate(options.now)
114
+ const account = mailDb.getMailAccount(store, ref)
115
+ let credentialRemoved = false
116
+ if (options.removeCredential !== false) credentialRemoved = removeImapCredential(account.id, { home: options.home })
117
+ const audit = { actor: options.actor ?? 'local', action: 'mail.account.remove', allowed: true, reason: account.id }
118
+ const outcome = store.mutate(
119
+ () => mailDb.removeMailAccountData(store, account.id, { purgeMessages: options.purgeMessages === true, now }),
120
+ audit,
121
+ )
122
+ return {
123
+ ok: true, command: 'mail account rm',
124
+ accountId: account.id,
125
+ removed: true,
126
+ credentialRemoved,
127
+ messagesDeleted: outcome.result.messagesDeleted,
128
+ }
129
+ }
130
+
131
+ /* ------------------------------------------------------------------ */
132
+ /* Sync */
133
+ /* ------------------------------------------------------------------ */
134
+
135
+ function syncResult(account, mailbox, extras) {
136
+ return { ok: true, command: 'mail sync', accountId: account.id, mailbox, ...extras }
137
+ }
138
+
139
+ /**
140
+ * Fetch new mail into the local ledger. Read-only IMAP (EXAMINE/FETCH); TLS
141
+ * only. Returns the frozen CLI JSON shape; dryRun writes nothing at all.
142
+ */
143
+ export async function mailSync(store, accountRef, options = {}) {
144
+ mailDb.assertMailTables(store)
145
+ const now = asDate(options.now)
146
+ const full = options.full === true
147
+ const dryRun = options.dryRun === true
148
+ const startedMs = Date.now()
149
+ const account = mailDb.getMailAccount(store, accountRef)
150
+ if (!['tls', 'starttls'].includes(account.tls)) {
151
+ throw mailError(MAIL_ERROR_CODES.CONFIG, 'account ' + account.name + ' is not an IMAP account', 'the local .eml import account cannot sync; add an IMAP account with implicit TLS')
152
+ }
153
+ const mailbox = options.mailbox == null ? account.mailbox : String(options.mailbox)
154
+ const cursor = mailDb.getMailCursor(store, account.id, mailbox)
155
+ if (cursor?.status === 'needs_resync' && !full) {
156
+ throw mailError(MAIL_ERROR_CODES.IMAP_UIDVALIDITY, 'mailbox ' + mailbox + ' needs a full rescan (UIDVALIDITY changed on an earlier sync)', 'run `advisers mail sync ' + account.name + ' --full`')
157
+ }
158
+ const credential = readImapCredential(account.id, { home: options.home })
159
+ if (!credential) {
160
+ throw mailError(MAIL_ERROR_CODES.CREDENTIALS_MISSING, 'no stored credential for mail account ' + account.name, 'run `advisers mail account add` again and provide the password through the TTY prompt or --pass-stdin')
161
+ }
162
+ const startedAt = now.toISOString()
163
+ const session = await openMailImapSession({
164
+ host: account.host,
165
+ port: account.port,
166
+ tls: account.tls,
167
+ user: credential.user || account.username,
168
+ pass: credential.pass,
169
+ connect: options.connect,
170
+ timeoutMs: options.timeoutMs,
171
+ idleTimeoutMs: options.idleTimeoutMs,
172
+ })
173
+ try {
174
+ const box = await session.examine(mailbox)
175
+ const observedValidity = box.uidValidity == null ? null : String(box.uidValidity)
176
+ const previousValidity = cursor?.uidvalidity ?? null
177
+ const validityChanged = Boolean(previousValidity && observedValidity && previousValidity !== observedValidity)
178
+ if (validityChanged && !full) {
179
+ if (!dryRun) {
180
+ const audit = { actor: options.actor ?? 'local', action: 'mail.sync.needs-resync', allowed: true, reason: account.id + ' ' + mailbox }
181
+ store.mutate(() => {
182
+ mailDb.markMailCursorNeedsResync(store, { accountId: account.id, mailbox, uidvalidity: observedValidity, uidnext: box.uidNext, now })
183
+ mailDb.updateMailAccount(store, account.id, { lastError: MAIL_ERROR_CODES.IMAP_UIDVALIDITY }, { now })
184
+ }, audit)
185
+ }
186
+ throw mailError(
187
+ MAIL_ERROR_CODES.IMAP_UIDVALIDITY,
188
+ 'mailbox ' + mailbox + ' UIDVALIDITY changed (' + previousValidity + ' -> ' + observedValidity + ')',
189
+ 'run `advisers mail sync ' + account.name + ' --full` to rescan; no local rows were deleted',
190
+ )
191
+ }
192
+ const sinceDays = Math.max(1, Math.min(3650, Number(options.sinceDays ?? account.retentionDays ?? 30) || 30))
193
+ let uids
194
+ if (cursor?.lastUid != null && !full) {
195
+ uids = await session.searchUidRange(Number(cursor.lastUid) + 1)
196
+ uids = uids.filter((uid) => uid > Number(cursor.lastUid))
197
+ } else {
198
+ uids = await session.searchSince(sinceDays)
199
+ }
200
+ const limit = Math.max(1, Math.min(mailDb.MAIL_MAX_SYNC_LIMIT, Number(options.limit) || mailDb.MAIL_DEFAULT_SYNC_LIMIT))
201
+ const selected = uids.slice(0, limit)
202
+ const fetched = await session.fetchMessages(selected, { maxMessageBytes: options.maxMessageBytes })
203
+ const rows = []
204
+ const failedUids = [...fetched.failedUids]
205
+ for (const message of fetched.messages) {
206
+ try {
207
+ const raw = message.oversize
208
+ ? (message.headerRaw ? message.headerRaw.toString('utf8') + '\n\n' : '')
209
+ : (message.raw ? message.raw.toString('utf8') : '')
210
+ const parsed = parseMailMessage(raw)
211
+ rows.push(mailDb.buildMailMessageRow({
212
+ accountId: account.id,
213
+ mailbox,
214
+ uid: message.uid,
215
+ uidvalidity: observedValidity,
216
+ sizeBytes: message.size,
217
+ receivedAt: startedAt,
218
+ sentAt: parseHeaderDate(parsed.date),
219
+ from: parsed.from,
220
+ subject: parsed.subject,
221
+ messageId: parsed.messageId,
222
+ text: message.oversize ? null : parsed.text,
223
+ attachments: parsed.attachments,
224
+ status: message.oversize ? 'oversize' : null,
225
+ now,
226
+ }))
227
+ } catch {
228
+ failedUids.push(message.uid)
229
+ }
230
+ }
231
+ if (dryRun) {
232
+ let duplicates = 0
233
+ for (const row of rows) if (mailDb.findMailMessageDuplicate(store, account.id, row)) duplicates += 1
234
+ return syncResult(account, mailbox, {
235
+ uidValidity: observedValidity ?? undefined,
236
+ fetched: selected.length, inserted: 0, skipped: duplicates, failed: failedUids.length,
237
+ duplicates, needsResync: false, dryRun: true, full, durationMs: Date.now() - startedMs,
238
+ })
239
+ }
240
+ const audit = { actor: options.actor ?? 'local', action: 'mail.sync', allowed: true, reason: '' }
241
+ const outcome = store.mutate(() => {
242
+ const applied = mailDb.applyMailSyncBatch(store, {
243
+ accountId: account.id,
244
+ mailbox,
245
+ uidvalidity: observedValidity,
246
+ messages: rows,
247
+ failedUids,
248
+ full,
249
+ uidnext: box.uidNext,
250
+ startedAt,
251
+ previousCursor: cursor,
252
+ now,
253
+ fetched: selected.length,
254
+ })
255
+ audit.reason = applied.inserted + ' inserted, ' + applied.skipped + ' skipped, ' + applied.failed + ' failed'
256
+ return applied
257
+ }, audit)
258
+ return syncResult(account, mailbox, {
259
+ uidValidity: observedValidity ?? undefined,
260
+ fetched: selected.length,
261
+ inserted: outcome.result.inserted,
262
+ skipped: outcome.result.skipped,
263
+ failed: outcome.result.failed,
264
+ duplicates: outcome.result.duplicates,
265
+ needsResync: false,
266
+ dryRun: false,
267
+ full,
268
+ durationMs: Date.now() - startedMs,
269
+ })
270
+ } catch (error) {
271
+ if (!dryRun && isMailError(error) && error.code !== MAIL_ERROR_CODES.IMAP_UIDVALIDITY) {
272
+ try { store.mutate(() => mailDb.updateMailAccount(store, account.id, { lastError: error.code }, { now })) } catch {}
273
+ }
274
+ throw error
275
+ } finally {
276
+ try { await session.logout() } catch {}
277
+ }
278
+ }
279
+
280
+ /* ------------------------------------------------------------------ */
281
+ /* Local reads */
282
+ /* ------------------------------------------------------------------ */
283
+
284
+ export function mailList(store, options = {}) {
285
+ mailDb.assertMailTables(store)
286
+ const accountId = options.account ? mailDb.getMailAccount(store, options.account).id : options.accountId
287
+ const sinceDays = options.sinceDays == null ? undefined : Number(options.sinceDays)
288
+ const result = mailDb.listMailMessages(store, {
289
+ accountId,
290
+ clientId: options.clientId,
291
+ projectId: options.projectId,
292
+ status: options.status,
293
+ retained: options.retained,
294
+ sinceDays,
295
+ limit: options.limit,
296
+ offset: options.offset,
297
+ now: options.now,
298
+ })
299
+ return { ok: true, command: 'mail ls', ...result }
300
+ }
301
+
302
+ export function mailShow(store, ref, options = {}) {
303
+ mailDb.assertMailTables(store)
304
+ const includeBody = options.body === true
305
+ const message = mailDb.getMailMessage(store, ref, { includeBody })
306
+ if (includeBody && message.bodyText == null) {
307
+ throw mailError(
308
+ MAIL_ERROR_CODES.NOT_RETAINED,
309
+ 'the body of ' + message.id + ' is not retained' + (message.purgedAt ? ' (purged ' + message.purgedAt + ')' : ' (metadata-only row)'),
310
+ 'metadata and body_sha256 are kept for evidence; re-sync the mailbox to read the body again',
311
+ )
312
+ }
313
+ return { ok: true, command: 'mail show', message }
314
+ }
315
+
316
+ /* ------------------------------------------------------------------ */
317
+ /* Review helpers */
318
+ /* ------------------------------------------------------------------ */
319
+
320
+ export function mailLink(store, ref, options = {}) {
321
+ mailDb.assertMailTables(store)
322
+ const now = asDate(options.now)
323
+ const message = mailDb.getMailMessage(store, ref)
324
+ const clientId = options.clientId == null ? (message.clientId ?? null) : String(options.clientId)
325
+ const projectId = options.projectId == null ? (message.projectId ?? null) : String(options.projectId)
326
+ const audit = { actor: options.actor ?? 'local', action: 'mail.link', allowed: true, reason: message.id }
327
+ const updated = store.mutate(() => mailDb.updateMailMessage(store, message.id, { clientId, projectId, status: 'linked' }, { now }), audit).result
328
+ return { ok: true, command: 'mail link', message: updated }
329
+ }
330
+
331
+ export function mailDismiss(store, ref, options = {}) {
332
+ mailDb.assertMailTables(store)
333
+ const now = asDate(options.now)
334
+ const message = mailDb.getMailMessage(store, ref)
335
+ const audit = { actor: options.actor ?? 'local', action: 'mail.dismiss', allowed: true, reason: message.id }
336
+ const updated = store.mutate(() => mailDb.updateMailMessage(store, message.id, { status: 'dismissed' }, { now }), audit).result
337
+ return { ok: true, command: 'mail dismiss', message: updated }
338
+ }
339
+
340
+ /* ------------------------------------------------------------------ */
341
+ /* Retention */
342
+ /* ------------------------------------------------------------------ */
343
+
344
+ /**
345
+ * Clear retained bodies older than each account's retention window (or
346
+ * --older-than). Messages with a pending candidate are skipped; metadata,
347
+ * body_sha256, dedupe key and evidence stay.
348
+ */
349
+ export function mailPurge(store, options = {}) {
350
+ mailDb.assertMailTables(store)
351
+ const now = asDate(options.now)
352
+ const accountId = options.account ? mailDb.getMailAccount(store, options.account).id : options.accountId
353
+ const plan = mailDb.planMailPurge(store, {
354
+ now,
355
+ olderThanDays: options.olderThanDays == null ? undefined : Number(options.olderThanDays),
356
+ accountId,
357
+ })
358
+ if (options.dryRun === true) {
359
+ return {
360
+ ok: true, command: 'mail purge', dryRun: true,
361
+ messagesPurged: 0, wouldPurge: plan.targets.length,
362
+ bytesFreed: 0, bytesWouldFree: plan.bytesFreed,
363
+ skippedPending: plan.skippedPending,
364
+ }
365
+ }
366
+ const audit = { actor: options.actor ?? 'local', action: 'mail.purge', allowed: true, reason: '' }
367
+ const purged = store.mutate(() => {
368
+ const count = mailDb.purgeMailBodies(store, plan.targets.map((target) => target.id), { now })
369
+ audit.reason = count + ' bodies purged, ' + plan.skippedPending + ' skipped (pending candidates)'
370
+ return count
371
+ }, audit)
372
+ return {
373
+ ok: true, command: 'mail purge', dryRun: false,
374
+ messagesPurged: purged.result,
375
+ bytesFreed: plan.bytesFreed,
376
+ skippedPending: plan.skippedPending,
377
+ }
378
+ }
379
+
380
+ /* ------------------------------------------------------------------ */
381
+ /* Extraction */
382
+ /* ------------------------------------------------------------------ */
383
+
384
+ function extractCandidateRecord(candidate, message, { matterId, now }) {
385
+ return toMemoryCandidate(candidate, { message, matterId, now })
386
+ }
387
+
388
+ /**
389
+ * Extract commitment candidates from locally retained mail.
390
+ * Default: pure local rules, zero network. Model mode is explicit opt-in
391
+ * (`model:true` + `confirmModel:true` + apiKey) and requires secrecy 0.
392
+ */
393
+ export async function mailExtract(store, options = {}) {
394
+ mailDb.assertMailTables(store)
395
+ const now = asDate(options.now)
396
+ const useModel = options.model === true
397
+ const mode = useModel ? 'model' : 'local'
398
+ if (useModel) {
399
+ if (options.confirmModel !== true) {
400
+ throw mailError(MAIL_ERROR_CODES.MODEL_DISABLED, 'model extraction requires explicit confirmation', 'the default --local path is offline and needs no key; pass --model --yes only after deciding the message text may be sent to your configured model provider')
401
+ }
402
+ if (!options.apiKey) throw mailError(MAIL_ERROR_CODES.MODEL_DISABLED, 'mail extract --model requires ADVISERS_API_KEY', 'run with --local (default) or configure a model key explicitly')
403
+ if (Number(options.secrecy) > 0) throw mailError(MAIL_ERROR_CODES.MODEL_DISABLED, 'model extraction is disabled for protected matters (secrecy > 0)', 'use the default local extraction or move the mail to an unprotected matter')
404
+ }
405
+ const account = options.account ? mailDb.getMailAccount(store, options.account) : undefined
406
+ const accountId = account?.id ?? options.accountId
407
+ const messages = mailDb.listMessagesForExtraction(store, {
408
+ accountId,
409
+ ids: options.ids,
410
+ all: options.all === true,
411
+ limit: options.limit,
412
+ now,
413
+ })
414
+ const matterId = options.matterId ?? account?.defaultMatterId
415
+ const clients = listActiveEntities(store, 'listClients')
416
+ const projects = listActiveEntities(store, 'listProjects')
417
+ const batches = []
418
+ let failed = 0
419
+ const failures = []
420
+ for (const message of messages) {
421
+ try {
422
+ if (useModel) {
423
+ const result = await extractCandidatesWithModel({
424
+ text: message.bodyText ?? '',
425
+ subject: message.subject,
426
+ from: message.from,
427
+ receivedAt: message.receivedAt,
428
+ apiKey: options.apiKey,
429
+ baseUrl: options.baseUrl,
430
+ model: options.modelName ?? options.modelId,
431
+ fetchImpl: options.fetchImpl,
432
+ safetyKey: options.safetyKey,
433
+ now,
434
+ })
435
+ batches.push({ message, candidates: result.candidates, safetyWarnings: result.safetyWarnings })
436
+ } else {
437
+ const result = extractLocalCandidates({
438
+ text: message.bodyText ?? '',
439
+ subject: message.subject,
440
+ from: message.from,
441
+ receivedAt: message.receivedAt,
442
+ clients,
443
+ projects,
444
+ now,
445
+ })
446
+ batches.push({ message, candidates: result.candidates })
447
+ }
448
+ } catch (error) {
449
+ // Safety blocks are a hard product stop: never swallow them into a
450
+ // per-message failure count.
451
+ if (error?.name === 'ContentSafetyError') throw error
452
+ failed += 1
453
+ failures.push({ messageId: message.id, code: error?.code ?? null })
454
+ }
455
+ }
456
+ const preview = []
457
+ for (const batch of batches) {
458
+ for (const candidate of batch.candidates) {
459
+ preview.push(extractCandidateRecord(candidate, batch.message, { matterId, now }))
460
+ }
461
+ }
462
+ const safetyWarnings = batches.flatMap((batch) => batch.safetyWarnings ?? [])
463
+ if (options.dryRun === true) {
464
+ return {
465
+ ok: true, command: 'mail extract', mode, dryRun: true,
466
+ scanned: messages.length, candidates: preview.map((candidate) => ({ ...candidate, preview: true })),
467
+ skipped: 0, failed, ...(failures.length ? { failures } : {}), ...(safetyWarnings.length ? { safetyWarnings } : {}),
468
+ }
469
+ }
470
+ const audit = { actor: options.actor ?? 'local', action: 'mail.extract.' + mode, allowed: true, reason: '' }
471
+ const created = []
472
+ store.mutate(() => {
473
+ for (const batch of batches) {
474
+ const ids = []
475
+ for (const candidate of batch.candidates) {
476
+ const record = extractCandidateRecord(candidate, batch.message, { matterId, now })
477
+ const row = store.proposeCandidate(record)
478
+ ids.push(row.id)
479
+ created.push({ ...row, mode })
480
+ }
481
+ const current = mailDb.getMailMessage(store, batch.message.id)
482
+ mailDb.updateMailMessage(store, batch.message.id, {
483
+ status: 'extracted',
484
+ candidateIds: [...(current.candidateIds ?? []), ...ids],
485
+ }, { now })
486
+ }
487
+ audit.reason = created.length + ' candidates from ' + messages.length + ' messages, ' + failed + ' failed'
488
+ }, audit)
489
+ return {
490
+ ok: true, command: 'mail extract', mode, dryRun: false,
491
+ scanned: messages.length, candidates: created, skipped: 0, failed,
492
+ ...(failures.length ? { failures } : {}), ...(safetyWarnings.length ? { safetyWarnings } : {}),
493
+ }
494
+ }
495
+
496
+ /* ------------------------------------------------------------------ */
497
+ /* Offline import */
498
+ /* ------------------------------------------------------------------ */
499
+
500
+ /** .eml/.mbox fallback import (no network, no credentials). */
501
+ export async function mailImport(store, options = {}, context = {}) {
502
+ return importMailFiles(store, options, context)
503
+ }
504
+
505
+ /** Evidence source for one stored message (used by tests/integration). */
506
+ export { mailEvidenceSource }