advisers 0.2.2 → 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.
Files changed (70) hide show
  1. package/LICENSE +0 -0
  2. package/NOTICE +0 -0
  3. package/README-zh.md +11 -7
  4. package/README.md +16 -8
  5. package/THIRD-PARTY-NOTICES.md +1 -1
  6. package/bin/advisers.js +6347 -542
  7. package/index.js +1 -1
  8. package/lib/agent.js +529 -80
  9. package/lib/attachments.js +0 -0
  10. package/lib/audit-anchor.js +683 -0
  11. package/lib/backup.js +1345 -0
  12. package/lib/capture.js +0 -0
  13. package/lib/context-window.js +0 -0
  14. package/lib/digest.js +0 -0
  15. package/lib/doc-review.js +0 -0
  16. package/lib/egress.js +0 -0
  17. package/lib/error-codes.js +1373 -0
  18. package/lib/evidence.js +352 -43
  19. package/lib/fs-safe.js +347 -0
  20. package/lib/ical.js +0 -0
  21. package/lib/imap.js +6 -2
  22. package/lib/importers.js +0 -0
  23. package/lib/learning.js +0 -0
  24. package/lib/ledger-read.js +608 -0
  25. package/lib/mcp-server.js +331 -50
  26. package/lib/model.js +73 -1
  27. package/lib/node-warning-filter.js +15 -0
  28. package/lib/notify.js +13 -3
  29. package/lib/nudge.js +0 -0
  30. package/lib/ocr.js +29 -9
  31. package/lib/pdf.js +0 -0
  32. package/lib/pet-brief-store.js +0 -0
  33. package/lib/pet-brief.js +126 -64
  34. package/lib/receipt-verify.js +213 -15
  35. package/lib/relative-date.js +0 -0
  36. package/lib/remind.js +91 -36
  37. package/lib/research.js +0 -0
  38. package/lib/review.js +0 -0
  39. package/lib/routine.js +0 -0
  40. package/lib/safety/classifier.js +55 -2
  41. package/lib/safety/explain.js +0 -0
  42. package/lib/safety/index.js +0 -0
  43. package/lib/safety/redact.js +0 -0
  44. package/lib/safety/rules.js +28 -0
  45. package/lib/scheduler.js +0 -0
  46. package/lib/source.js +0 -0
  47. package/lib/sqlite.js +2302 -55
  48. package/lib/sync.js +398 -71
  49. package/lib/text-safe.js +229 -0
  50. package/lib/timestamp.js +29 -9
  51. package/lib/tos/index.js +1 -1
  52. package/lib/tos/manifest.json +6 -6
  53. package/lib/tos/privacy.zh-CN.md +12 -9
  54. package/lib/tos/safety.zh-CN.md +4 -3
  55. package/lib/tos/summary.zh-CN.md +3 -3
  56. package/lib/tos/terms.zh-CN.md +8 -6
  57. package/lib/tui/color.js +164 -0
  58. package/lib/tui/index.js +33 -0
  59. package/lib/tui/json.js +124 -0
  60. package/lib/tui/labels.js +50 -0
  61. package/lib/tui/policy.js +108 -0
  62. package/lib/tui/render.js +371 -0
  63. package/lib/tui/sanitize.js +142 -0
  64. package/lib/tui/text-file.js +116 -0
  65. package/lib/tui/width.js +577 -0
  66. package/lib/ui.js +0 -0
  67. package/lib/undo.js +0 -0
  68. package/lib/untrusted.js +186 -0
  69. package/lib/vault.js +0 -0
  70. package/package.json +6 -5
package/lib/evidence.js CHANGED
@@ -19,8 +19,9 @@
19
19
  * directory offline.
20
20
  *
21
21
  * Constraints baked into the design:
22
- * - Offline: no network calls; imports only node:crypto/node:fs/node:path (plus
23
- * an optional in-process `advisers-office` build for the receipt DOCX).
22
+ * - Offline: no network calls; imports only node:crypto/node:fs/node:path, the
23
+ * pure sibling `./egress.js` secrecy scale, and an optional in-process
24
+ * `advisers-office` build for the receipt DOCX.
24
25
  * - No fabrication: an unknown turn, a session mismatch or an unparseable
25
26
  * `session#turn` ref goes to `missing`; nothing is guessed.
26
27
  * - No leaks: no absolute filesystem paths, no full turn/transcript bodies and
@@ -49,6 +50,8 @@ import {
49
50
  } from 'node:fs'
50
51
  import { dirname, join, resolve } from 'node:path'
51
52
 
53
+ import { secrecyLevel } from './egress.js'
54
+
52
55
  /** Quotes are verbatim evidence but capped, so a pack never carries a full body. */
53
56
  export const MAX_QUOTE_CHARS = 500
54
57
  export const MANIFEST_FORMAT = 'advisers-evidence-pack'
@@ -80,6 +83,23 @@ export class EvidencePackLimitError extends Error {
80
83
  }
81
84
  }
82
85
 
86
+ /**
87
+ * Raised (instead of silently omitting or leaking) when the caller explicitly
88
+ * selected evidence that belongs to a protected matter (matter.secrecy above the
89
+ * requested clearance). The message/count never contain a title, creditor,
90
+ * action or quote; only the number of blocked ids.
91
+ */
92
+ export class ProtectedEvidenceError extends Error {
93
+ constructor(count, clearance = 0) {
94
+ super(`refusing to export ${count} evidence item(s): their matter secrecy is above the clearance ${clearance}`)
95
+ this.name = 'ProtectedEvidenceError'
96
+ this.code = 'E_SECRECY_BLOCKED'
97
+ this.count = count
98
+ this.clearance = clearance
99
+ this.hint = 'Remove the protected ids from --ids, or lower the matter secrecy with a local command. Protected matters are excluded from packs by default.'
100
+ }
101
+ }
102
+
83
103
  /** Header for the optional DOCX table helper, kept next to the rows it describes. */
84
104
  export const DOCX_EVIDENCE_HEADERS = ['类型', '证据ID', '来源(session#turn)', '摘录', '状态']
85
105
 
@@ -174,6 +194,52 @@ export function parseSourceRef(ref) {
174
194
  return { sessionId, turnId }
175
195
  }
176
196
 
197
+ /**
198
+ * 0.2.3 evidence discipline (B3): manual/operator-entered sources.
199
+ *
200
+ * A CLI operator can only state what they typed. Before 0.2.3 those rows were
201
+ * written as `{sessionId:'local', turnId:'cli'}`, i.e. a fake conversation
202
+ * pointer that every reader resolved as MISSING (turn_not_found). The honest
203
+ * shape is a typed manual source: it is unverifiable by construction, not
204
+ * missing. Legacy rows are mapped on read (never rewritten), so old packs and
205
+ * ledgers keep working without a migration.
206
+ */
207
+ export const MANUAL_SOURCE_KIND = 'manual'
208
+ export const MANUAL_RESOLUTION = 'unverifiable'
209
+ export const MANUAL_REASON = 'operator_entered'
210
+
211
+ /** True for a new manual source, a legacy {sessionId:'local',turnId:'cli'} row, or an operator-marked item. */
212
+ export function isManualEvidence(item) {
213
+ if (!item || typeof item !== 'object' || Array.isArray(item)) return false
214
+ if (item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND) return true
215
+ if (item.source === 'operator') return true
216
+ // 0.2.2 forged CLI evidence: written by `commit add --quote` / `commit done`.
217
+ return item.sessionId === 'local' && item.turnId === 'cli'
218
+ }
219
+
220
+ /**
221
+ * Render one manual source for evidence show / packs.
222
+ * The stored quote is always re-hashed locally; a stale or forged hash never wins.
223
+ */
224
+ export function manualEvidenceSource(item) {
225
+ const clamped = clampQuote(typeof item?.quote === 'string' ? item.quote : '')
226
+ const entry = {
227
+ kind: MANUAL_SOURCE_KIND,
228
+ type: MANUAL_SOURCE_KIND,
229
+ source: 'operator',
230
+ quote: clamped.quote,
231
+ quoteChars: clamped.quoteChars,
232
+ truncated: clamped.truncated,
233
+ quoteSha256: clamped.quoteSha256,
234
+ resolution: MANUAL_RESOLUTION,
235
+ reason: MANUAL_REASON,
236
+ }
237
+ for (const key of ['capturedAt', 'capturedBy', 'command', 'cliVersion']) {
238
+ if (typeof item?.[key] === 'string' && item[key]) entry[key] = item[key]
239
+ }
240
+ return entry
241
+ }
242
+
177
243
  function lookupTurn(store, sessionId, turnId) {
178
244
  if (!store || typeof store !== 'object') return { turn: undefined, failed: false }
179
245
  let failed = false
@@ -200,6 +266,70 @@ function lookupTurn(store, sessionId, turnId) {
200
266
  return { turn: undefined, failed }
201
267
  }
202
268
 
269
+ // ---------------------------------------------------------------------------
270
+ // per-item secrecy (A-1 fix): a pack/read model may span many matters, so the
271
+ // clearance decision is made for every included record, never only for the
272
+ // active matter.
273
+ // ---------------------------------------------------------------------------
274
+
275
+ /**
276
+ * Matter id an evidence record belongs to.
277
+ *
278
+ * A commitment always carries `matterId`; a fact may (otherwise it is a global
279
+ * fact); a preference is matter-scoped only through
280
+ * `scope: { level: 'matter', value: <matterId> }`.
281
+ *
282
+ * @returns {string|undefined}
283
+ */
284
+ export function evidenceRecordMatterId(record, kind) {
285
+ if (!record || typeof record !== 'object' || Array.isArray(record)) return undefined
286
+ if (kind === 'preference') {
287
+ const scope = record.scope
288
+ if (!scope || typeof scope !== 'object' || Array.isArray(scope)) return undefined
289
+ if (scope.level !== 'matter') return undefined
290
+ return typeof scope.value === 'string' && scope.value ? scope.value : undefined
291
+ }
292
+ return typeof record.matterId === 'string' && record.matterId ? record.matterId : undefined
293
+ }
294
+
295
+ /**
296
+ * Secrecy level (0–3, same scale as `lib/egress.js`) of the matter a record
297
+ * belongs to.
298
+ *
299
+ * - no matter association -> 0 (a global record is not matter-protected);
300
+ * - a matter id the ledger cannot resolve -> Infinity, i.e. treated as
301
+ * protected. A clearance gate must fail closed; it never guesses a level for
302
+ * a row it cannot see.
303
+ *
304
+ * @returns {number} 0..3 or Infinity
305
+ */
306
+ export function evidenceRecordSecrecy(ledger, kind, record) {
307
+ const matterId = evidenceRecordMatterId(record, kind)
308
+ if (!matterId) return 0
309
+ let matter
310
+ try {
311
+ if (typeof ledger?.getMatter === 'function') matter = ledger.getMatter(matterId)
312
+ } catch {
313
+ matter = undefined
314
+ }
315
+ if (matter === undefined) {
316
+ try {
317
+ if (typeof ledger?.listMatters === 'function') matter = ledger.listMatters().find((row) => row?.id === matterId)
318
+ } catch {
319
+ matter = undefined
320
+ }
321
+ }
322
+ if (!matter) return Number.POSITIVE_INFINITY
323
+ return secrecyLevel(matter)
324
+ }
325
+
326
+ /** True when a record must stay out of an export/projection at `clearance`. */
327
+ export function isEvidenceRecordAboveClearance(ledger, kind, record, clearance = 0) {
328
+ const limit = Number(clearance)
329
+ if (!Number.isFinite(limit) || limit < 0) return true
330
+ return evidenceRecordSecrecy(ledger, kind, record) > limit
331
+ }
332
+
203
333
  // ---------------------------------------------------------------------------
204
334
  // ledger lookups
205
335
  // ---------------------------------------------------------------------------
@@ -353,14 +483,69 @@ function collectSourceRefs(...lists) {
353
483
  return out
354
484
  }
355
485
 
486
+ /** Writer sentinel for "this record came from a turn without a session id". */
487
+ const LEGACY_SESSION_ID = 'legacy'
488
+
489
+ /**
490
+ * A quote is verbatim evidence: it must occur in the turn body it claims to
491
+ * come from. NFC normalization only removes encoding differences; it never
492
+ * repairs, rewrites or fuzzy-matches a quote (no case/whitespace folding).
493
+ * An empty quote is the pre-0.2.3 "pointer only" shape and keeps its old
494
+ * semantics (the turn is still verified, the blank quote is not).
495
+ */
496
+ function quoteMatchesTurn(turn, quote) {
497
+ if (typeof quote !== 'string' || quote === '') return true
498
+ const content = typeof turn?.content === 'string' ? turn.content : ''
499
+ return content.normalize('NFC').includes(quote.normalize('NFC'))
500
+ }
501
+
502
+ /**
503
+ * Normalize the two known-bad pointer shapes writers produced before 0.2.5:
504
+ * - `sessionId === 'legacy'` (memory accept for a candidate with no session);
505
+ * - `sessionId === turnId` (lib/agent.js commitment_add passed the turn id as
506
+ * the session id).
507
+ * The turn store is authoritative for conversationId, so these resolve instead
508
+ * of reporting session_mismatch forever. Any other mismatch stays a mismatch:
509
+ * a real evidence pointer must name its own conversation.
510
+ *
511
+ * @returns {string|null} normalized session id, or null on a real mismatch
512
+ */
513
+ function normalizePointerSession(sessionId, turnId, turn) {
514
+ if (!turn || typeof turn.conversationId !== 'string') return sessionId
515
+ if (turn.conversationId === sessionId) return sessionId
516
+ const knownBadShape = sessionId === LEGACY_SESSION_ID || sessionId === turnId
517
+ return knownBadShape ? turn.conversationId : null
518
+ }
519
+
520
+ /** Resolve one pointer after the turn/quote checks; shared by both resolvers. */
521
+ function resolvePointerTurn(store, sessionId, turnId, quote) {
522
+ const lookup = lookupTurn(store, sessionId, turnId)
523
+ if (!lookup.turn) {
524
+ return { missing: { sessionId, turnId, quote, reason: lookup.failed ? 'lookup_failed' : 'turn_not_found' } }
525
+ }
526
+ const normalizedSessionId = normalizePointerSession(sessionId, turnId, lookup.turn)
527
+ if (normalizedSessionId === null) {
528
+ return { missing: { sessionId, turnId, quote, reason: 'session_mismatch' } }
529
+ }
530
+ if (!quoteMatchesTurn(lookup.turn, quote)) {
531
+ return { missing: { sessionId: normalizedSessionId, turnId, quote, reason: 'quote_mismatch' } }
532
+ }
533
+ return { source: { sessionId: normalizedSessionId, turnId, quote, turn: lookup.turn } }
534
+ }
535
+
356
536
  function resolveSourceRefs(store, items) {
357
537
  const sources = []
358
538
  const missing = []
539
+ const unverifiable = []
359
540
  for (const item of items) {
360
541
  if (!item || typeof item !== 'object' || Array.isArray(item)) {
361
542
  missing.push({ reason: 'invalid_source' })
362
543
  continue
363
544
  }
545
+ if (isManualEvidence(item)) {
546
+ unverifiable.push(manualEvidenceSource(item))
547
+ continue
548
+ }
364
549
  const quote = typeof item.quote === 'string' ? item.quote : ''
365
550
  const ref = typeof item.ref === 'string' ? item.ref : ''
366
551
  if (!ref) {
@@ -372,24 +557,14 @@ function resolveSourceRefs(store, items) {
372
557
  missing.push({ ref, quote, reason: 'unparseable_ref' })
373
558
  continue
374
559
  }
375
- const lookup = lookupTurn(store, parsed.sessionId, parsed.turnId)
376
- if (!lookup.turn) {
377
- missing.push({
378
- ref,
379
- quote,
380
- sessionId: parsed.sessionId,
381
- turnId: parsed.turnId,
382
- reason: lookup.failed ? 'lookup_failed' : 'turn_not_found',
383
- })
384
- continue
385
- }
386
- if (lookup.turn.conversationId !== parsed.sessionId) {
387
- missing.push({ ref, quote, sessionId: parsed.sessionId, turnId: parsed.turnId, reason: 'session_mismatch' })
560
+ const resolved = resolvePointerTurn(store, parsed.sessionId, parsed.turnId, quote)
561
+ if (resolved.missing) {
562
+ missing.push({ ref, ...resolved.missing })
388
563
  continue
389
564
  }
390
- sources.push({ sessionId: parsed.sessionId, turnId: parsed.turnId, quote, turn: lookup.turn })
565
+ sources.push(resolved.source)
391
566
  }
392
- return { sources, missing }
567
+ return { sources, missing, unverifiable }
393
568
  }
394
569
 
395
570
  /**
@@ -402,12 +577,17 @@ function resolveSourceRefs(store, items) {
402
577
  export function evidenceForCommitment(store, ledger, commitmentId, index) {
403
578
  const commitment = findCommitment(ledger, commitmentId, index)
404
579
  if (!commitment) {
405
- return { commitment: undefined, sources: [], missing: [{ id: commitmentId, reason: 'commitment_not_found' }] }
580
+ return { schemaVersion: 2, commitment: undefined, sources: [], missing: [{ id: commitmentId, reason: 'commitment_not_found' }], unverifiable: [] }
406
581
  }
407
582
  const sources = []
408
583
  const missing = []
584
+ const unverifiable = []
409
585
  const evidence = Array.isArray(commitment.evidence) ? commitment.evidence : []
410
586
  for (const item of evidence) {
587
+ if (isManualEvidence(item)) {
588
+ unverifiable.push(manualEvidenceSource(item))
589
+ continue
590
+ }
411
591
  const sessionId = typeof item?.sessionId === 'string' ? item.sessionId : ''
412
592
  const turnId = typeof item?.turnId === 'string' ? item.turnId : ''
413
593
  const quote = typeof item?.quote === 'string' ? item.quote : ''
@@ -420,40 +600,36 @@ export function evidenceForCommitment(store, ledger, commitmentId, index) {
420
600
  })
421
601
  continue
422
602
  }
423
- const lookup = lookupTurn(store, sessionId, turnId)
424
- if (!lookup.turn) {
425
- missing.push({ sessionId, turnId, quote, reason: lookup.failed ? 'lookup_failed' : 'turn_not_found' })
426
- continue
427
- }
428
- if (lookup.turn.conversationId !== sessionId) {
429
- missing.push({ sessionId, turnId, quote, reason: 'session_mismatch' })
603
+ const resolved = resolvePointerTurn(store, sessionId, turnId, quote)
604
+ if (resolved.missing) {
605
+ missing.push(resolved.missing)
430
606
  continue
431
607
  }
432
- sources.push({ sessionId, turnId, quote, turn: lookup.turn })
608
+ sources.push(resolved.source)
433
609
  }
434
- return { commitment, sources, missing }
610
+ return { schemaVersion: 2, commitment, sources, missing, unverifiable }
435
611
  }
436
612
 
437
613
  /** Trace a fact's `SourceRef[]` (plus its primary `source`) back to turns. */
438
614
  export function evidenceForFact(store, ledger, factId, index) {
439
615
  const fact = findFact(ledger, factId, index)
440
616
  if (!fact) {
441
- return { fact: undefined, sources: [], missing: [{ id: factId, reason: 'fact_not_found' }] }
617
+ return { schemaVersion: 2, fact: undefined, sources: [], missing: [{ id: factId, reason: 'fact_not_found' }], unverifiable: [] }
442
618
  }
443
619
  const refs = collectSourceRefs(fact.evidence, primarySourceCandidates(fact.source))
444
620
  const resolved = resolveSourceRefs(store, refs)
445
- return { fact, sources: resolved.sources, missing: resolved.missing }
621
+ return { schemaVersion: 2, fact, sources: resolved.sources, missing: resolved.missing, unverifiable: resolved.unverifiable }
446
622
  }
447
623
 
448
624
  /** Trace a preference's `SourceRef[]` (plus its primary `source`) back to turns. */
449
625
  export function evidenceForPreference(store, ledger, preferenceId, index) {
450
626
  const preference = findPreference(ledger, preferenceId, index)
451
627
  if (!preference) {
452
- return { preference: undefined, sources: [], missing: [{ id: preferenceId, reason: 'preference_not_found' }] }
628
+ return { schemaVersion: 2, preference: undefined, sources: [], missing: [{ id: preferenceId, reason: 'preference_not_found' }], unverifiable: [] }
453
629
  }
454
630
  const refs = collectSourceRefs(preference.evidence, primarySourceCandidates(preference.source))
455
631
  const resolved = resolveSourceRefs(store, refs)
456
- return { preference, sources: resolved.sources, missing: resolved.missing }
632
+ return { schemaVersion: 2, preference, sources: resolved.sources, missing: resolved.missing, unverifiable: resolved.unverifiable }
457
633
  }
458
634
 
459
635
  // ---------------------------------------------------------------------------
@@ -528,14 +704,35 @@ function compactMissing(item) {
528
704
  return out
529
705
  }
530
706
 
707
+ function compactUnverifiable(item) {
708
+ const out = {
709
+ kind: MANUAL_SOURCE_KIND,
710
+ type: MANUAL_SOURCE_KIND,
711
+ resolution: MANUAL_RESOLUTION,
712
+ reason: typeof item?.reason === 'string' && item.reason ? item.reason : MANUAL_REASON,
713
+ }
714
+ const clamped = clampQuote(item?.quote)
715
+ Object.assign(out, clamped)
716
+ for (const key of ['capturedAt', 'capturedBy', 'command']) {
717
+ if (typeof item?.[key] === 'string' && item[key]) out[key] = item[key]
718
+ }
719
+ return out
720
+ }
721
+
531
722
  function compactEntry(entry) {
532
- return {
723
+ const out = {
533
724
  kind: typeof entry.kind === 'string' ? entry.kind : 'unknown',
534
725
  id: String(entry.id ?? ''),
535
726
  found: Boolean(entry.found),
536
727
  sources: (Array.isArray(entry.sources) ? entry.sources : []).map(compactSource),
537
728
  missing: (Array.isArray(entry.missing) ? entry.missing : []).map(compactMissing),
538
729
  }
730
+ // Additive (0.2.3 B3): operator-entered sources are unverifiable, not missing.
731
+ // Kept absent when empty so pre-0.2.3 pack bytes do not change.
732
+ if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
733
+ out.unverifiable = entry.unverifiable.map(compactUnverifiable)
734
+ }
735
+ return out
539
736
  }
540
737
 
541
738
  function inferKindFromId(id) {
@@ -607,21 +804,23 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
607
804
  const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
608
805
  let sourceCount = 0
609
806
  let missingCount = 0
807
+ let unverifiableCount = 0
610
808
  let truncatedCount = 0
611
809
  for (const entry of entries) {
612
810
  counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
613
811
  sourceCount += entry.sources.length
614
812
  missingCount += entry.missing.length
813
+ unverifiableCount += (entry.unverifiable ?? []).length
615
814
  truncatedCount += entry.sources.filter((source) => source.truncated).length
616
815
  }
617
816
  const lines = [
618
817
  'Advisers evidence pack',
619
818
  '======================',
620
819
  '',
621
- `format: ${MANIFEST_FORMAT} v${MANIFEST_VERSION}`,
622
- `created: ${createdAt}`,
623
- `entries: ${entries.length} (commitment ${counts.commitment}, fact ${counts.fact}, preference ${counts.preference}, unknown ${counts.unknown})`,
624
- `sources: ${sourceCount} resolved, ${missingCount} missing`,
820
+ 'format: ' + MANIFEST_FORMAT + ' v' + MANIFEST_VERSION,
821
+ 'created: ' + createdAt,
822
+ 'entries: ' + entries.length + ' (commitment ' + counts.commitment + ', fact ' + counts.fact + ', preference ' + counts.preference + ', unknown ' + counts.unknown + ')',
823
+ 'sources: ' + sourceCount + ' resolved, ' + missingCount + ' missing' + (unverifiableCount ? ', ' + unverifiableCount + ' operator-entered (not externally verified, not missing)' : ''),
625
824
  `quotes: verbatim, at most ${MAX_QUOTE_CHARS} characters each; ${truncatedCount} truncated`,
626
825
  '',
627
826
  'Files',
@@ -642,9 +841,13 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
642
841
  if (!entries.length) lines.push('(no evidence requested)')
643
842
  const shown = entries.slice(0, README_ENTRY_CAP)
644
843
  for (const entry of shown) {
844
+ const manualCount = (entry.unverifiable ?? []).length
645
845
  lines.push(
646
- `- ${entry.kind} ${entry.id} sources=${entry.sources.length} missing=${entry.missing.length}${entry.found ? '' : ' (record not found)'}`,
846
+ `- ${entry.kind} ${entry.id} sources=${entry.sources.length} missing=${entry.missing.length}${manualCount ? ` manual=${manualCount}` : ''}${entry.found ? '' : ' (record not found)'}`,
647
847
  )
848
+ for (const item of (entry.unverifiable ?? []).slice(0, README_REF_CAP)) {
849
+ lines.push(` manual operator-entered (unverifiable): ${item.reason ?? MANUAL_REASON}`)
850
+ }
648
851
  const refs = entry.sources.slice(0, README_REF_CAP)
649
852
  for (const source of refs) {
650
853
  lines.push(` source ${formatRef(source.sessionId, source.turnId)}${source.truncated ? ' (quote truncated)' : ''}`)
@@ -693,6 +896,14 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
693
896
  * @param {number} [options.limit=DEFAULT_MAX_EVIDENCE_ENTRIES] max entries before
694
897
  * `EvidencePackLimitError` (Infinity disables the cap).
695
898
  * @param {boolean} [options.all=false] explicit "build the whole pack" opt-in.
899
+ * @param {number|null} [options.clearance=null] per-item secrecy gate: when a
900
+ * number, every requested record is checked against its OWN matter's
901
+ * secrecy (0–3, see lib/egress.js). `null` keeps the pre-0.2.5 library
902
+ * behavior (no filtering); CLI pack/receipt pass 0.
903
+ * @param {'exclude'|'error'} [options.protectedPolicy='exclude'] what to do with
904
+ * a record above `clearance`: omit it and count it (`exclude`, the bulk
905
+ * default), or throw `ProtectedEvidenceError` (`error`, used when the
906
+ * caller named the ids explicitly and must not get a silent partial pack).
696
907
  * @returns {{ files: Record<string, string>, summary: object }}
697
908
  * files: `{ 'manifest.json': string, 'README.txt': string, 'SHA256SUMS': string }`
698
909
  */
@@ -703,6 +914,8 @@ export function buildEvidencePack({
703
914
  now = new Date(),
704
915
  limit = DEFAULT_MAX_EVIDENCE_ENTRIES,
705
916
  all = false,
917
+ clearance = null,
918
+ protectedPolicy = 'exclude',
706
919
  } = {}) {
707
920
  if (!ledger || typeof ledger !== 'object') throw new TypeError('buildEvidencePack requires a ledger')
708
921
  if (!store || typeof store !== 'object') throw new TypeError('buildEvidencePack requires a store')
@@ -711,18 +924,45 @@ export function buildEvidencePack({
711
924
  if (!(effectiveLimit === Infinity || (Number.isInteger(effectiveLimit) && effectiveLimit >= 0))) {
712
925
  throw new TypeError('buildEvidencePack limit must be a non-negative integer or Infinity')
713
926
  }
927
+ const clearanceValue = clearance === undefined || clearance === null ? null : Number(clearance)
928
+ if (clearanceValue !== null && (!Number.isFinite(clearanceValue) || clearanceValue < 0)) {
929
+ throw new TypeError('buildEvidencePack clearance must be a non-negative number or null')
930
+ }
931
+ if (protectedPolicy !== 'exclude' && protectedPolicy !== 'error') {
932
+ throw new TypeError("buildEvidencePack protectedPolicy must be 'exclude' or 'error'")
933
+ }
714
934
  const requestedAny = ids !== undefined && ids !== null && !(Array.isArray(ids) && ids.length === 0)
715
935
  // Build the lookup index once; every evidenceFor* call below then costs O(1)
716
936
  // instead of re-scanning listFacts()/listCommitments() (P0-3: 80k pack went
717
- // from 113.75s to linear time).
718
- const index = requestedAny ? createEvidenceIndex(ledger) : undefined
937
+ // from 113.75s to linear time). The per-item secrecy check reads the same
938
+ // records, so it shares the index.
939
+ const index = requestedAny || clearanceValue !== null ? createEvidenceIndex(ledger) : undefined
719
940
  const requested = normalizeRequestedIds(ids, ledger, index)
720
941
  const requestedCount =
721
942
  requested.commitments.length + requested.facts.length + requested.preferences.length + requested.unknown.length
722
943
  if (requestedCount > effectiveLimit) throw new EvidencePackLimitError(requestedCount, effectiveLimit)
723
944
  const entries = []
945
+ const protectedIds = []
946
+ let protectedExcluded = 0
947
+ /**
948
+ * A-1 (0.2.5): a pack materializes every requested ledger row, so the
949
+ * clearance gate must judge each row by the secrecy of ITS OWN matter — the
950
+ * old "active matter only" check let a secrecy=3 matter leak into a pack built
951
+ * while another matter was active. With `error` (the CLI's explicit --ids
952
+ * path) the whole pack fails closed; with `exclude` (the default/bulk path)
953
+ * the row is omitted and only a count is reported.
954
+ */
955
+ const blockedByClearance = (kind, record) => {
956
+ if (clearanceValue === null || !record) return false
957
+ if (!isEvidenceRecordAboveClearance(ledger, kind, record, clearanceValue)) return false
958
+ if (protectedPolicy === 'error') protectedIds.push(String(record.id ?? ''))
959
+ else protectedExcluded += 1
960
+ return true
961
+ }
724
962
 
725
963
  for (const id of requested.commitments) {
964
+ const commitment = findCommitment(ledger, id, index)
965
+ if (blockedByClearance('commitment', commitment)) continue
726
966
  const result = evidenceForCommitment(store, ledger, id, index)
727
967
  entries.push({
728
968
  kind: 'commitment',
@@ -730,13 +970,18 @@ export function buildEvidencePack({
730
970
  found: Boolean(result.commitment),
731
971
  sources: result.sources,
732
972
  missing: result.missing,
973
+ unverifiable: result.unverifiable,
733
974
  })
734
975
  }
735
976
  for (const id of requested.facts) {
977
+ const fact = findFact(ledger, id, index)
978
+ if (blockedByClearance('fact', fact)) continue
736
979
  const result = evidenceForFact(store, ledger, id, index)
737
- entries.push({ kind: 'fact', id, found: Boolean(result.fact), sources: result.sources, missing: result.missing })
980
+ entries.push({ kind: 'fact', id, found: Boolean(result.fact), sources: result.sources, missing: result.missing, unverifiable: result.unverifiable })
738
981
  }
739
982
  for (const id of requested.preferences) {
983
+ const preference = findPreference(ledger, id, index)
984
+ if (blockedByClearance('preference', preference)) continue
740
985
  const result = evidenceForPreference(store, ledger, id, index)
741
986
  entries.push({
742
987
  kind: 'preference',
@@ -744,11 +989,13 @@ export function buildEvidencePack({
744
989
  found: Boolean(result.preference),
745
990
  sources: result.sources,
746
991
  missing: result.missing,
992
+ unverifiable: result.unverifiable,
747
993
  })
748
994
  }
749
995
  for (const id of requested.unknown) {
750
996
  entries.push({ kind: 'unknown', id, found: false, sources: [], missing: [{ id, reason: 'record_not_found' }] })
751
997
  }
998
+ if (protectedIds.length) throw new ProtectedEvidenceError(protectedIds.length, clearanceValue)
752
999
 
753
1000
  const compacted = entries
754
1001
  .map(compactEntry)
@@ -763,11 +1010,16 @@ export function buildEvidencePack({
763
1010
  const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
764
1011
  let sourceCount = 0
765
1012
  let missingCount = 0
1013
+ let unverifiableCount = 0
1014
+ let operatorEnteredCount = 0
766
1015
  let truncatedCount = 0
767
1016
  for (const entry of compacted) {
768
1017
  counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
769
1018
  sourceCount += entry.sources.length
770
1019
  missingCount += entry.missing.length
1020
+ const manual = entry.unverifiable ?? []
1021
+ unverifiableCount += manual.length
1022
+ operatorEnteredCount += manual.filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
771
1023
  truncatedCount += entry.sources.filter((source) => source.truncated).length
772
1024
  }
773
1025
 
@@ -785,7 +1037,13 @@ export function buildEvidencePack({
785
1037
  counts,
786
1038
  sourceCount,
787
1039
  missingCount,
1040
+ unverifiableCount,
1041
+ operatorEnteredCount,
788
1042
  truncatedCount,
1043
+ // Additive (0.2.5 A-1): how many requested rows were withheld because
1044
+ // their own matter is protected. Counts only — never a title or quote.
1045
+ protectedExcluded,
1046
+ clearance: clearanceValue,
789
1047
  notFound: compacted.filter((entry) => !entry.found).map((entry) => entry.id),
790
1048
  fileHashes: { 'manifest.json': manifestDigest, 'README.txt': readmeDigest },
791
1049
  entries: compacted,
@@ -1131,20 +1389,46 @@ function receiptMissing(item) {
1131
1389
  return out
1132
1390
  }
1133
1391
 
1392
+ function receiptUnverifiable(item) {
1393
+ if (!item || typeof item !== 'object' || Array.isArray(item)) return null
1394
+ const out = {
1395
+ kind: MANUAL_SOURCE_KIND,
1396
+ type: MANUAL_SOURCE_KIND,
1397
+ resolution: MANUAL_RESOLUTION,
1398
+ reason: typeof item.reason === 'string' && item.reason ? item.reason : MANUAL_REASON,
1399
+ }
1400
+ Object.assign(out, clampQuote(item.quote))
1401
+ for (const key of ['capturedAt', 'capturedBy', 'command']) {
1402
+ if (typeof item[key] === 'string' && item[key]) out[key] = item[key].slice(0, 120)
1403
+ }
1404
+ return out
1405
+ }
1406
+
1134
1407
  function receiptEvidenceEntry(entry) {
1135
1408
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null
1136
- return {
1409
+ const out = {
1137
1410
  kind: typeof entry.kind === 'string' ? entry.kind : 'unknown',
1138
1411
  id: String(entry.id === undefined || entry.id === null ? '' : entry.id),
1139
1412
  found: Boolean(entry.found),
1140
1413
  sources: (Array.isArray(entry.sources) ? entry.sources : []).map(receiptSource),
1141
1414
  missing: (Array.isArray(entry.missing) ? entry.missing : []).map(receiptMissing),
1142
1415
  }
1416
+ if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
1417
+ out.unverifiable = entry.unverifiable.map(receiptUnverifiable).filter(Boolean)
1418
+ }
1419
+ return out
1143
1420
  }
1144
1421
 
1145
1422
  function normalizeReceiptEvidence(evidence) {
1146
1423
  const meta = { format: MANIFEST_FORMAT, version: MANIFEST_VERSION }
1147
1424
  let list = []
1425
+ // Additive (0.2.5 A-1): the evidence pack reports how many requested rows it
1426
+ // withheld because their own matter is protected; the receipt summary carries
1427
+ // the same count (never a title/creditor/action/quote).
1428
+ let protectedExcluded = 0
1429
+ const readProtectedExcluded = (summary) => {
1430
+ if (summary && Number.isInteger(summary.protectedExcluded) && summary.protectedExcluded >= 0) protectedExcluded = summary.protectedExcluded
1431
+ }
1148
1432
  if (evidence === undefined || evidence === null) {
1149
1433
  list = []
1150
1434
  } else if (typeof evidence === 'string') {
@@ -1159,6 +1443,7 @@ function normalizeReceiptEvidence(evidence) {
1159
1443
  if (evidence.summary && Array.isArray(evidence.summary.entries)) {
1160
1444
  if (typeof evidence.summary.format === 'string') meta.format = evidence.summary.format
1161
1445
  if (Number.isInteger(evidence.summary.version)) meta.version = evidence.summary.version
1446
+ readProtectedExcluded(evidence.summary)
1162
1447
  list = evidence.summary.entries
1163
1448
  } else if (Array.isArray(evidence.entries)) {
1164
1449
  list = evidence.entries
@@ -1183,10 +1468,15 @@ function normalizeReceiptEvidence(evidence) {
1183
1468
  const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
1184
1469
  let sourceCount = 0
1185
1470
  let missingCount = 0
1471
+ let unverifiableCount = 0
1472
+ let operatorEnteredCount = 0
1186
1473
  for (const entry of entries) {
1187
1474
  counts[entry.kind] = (counts[entry.kind] || 0) + 1
1188
1475
  sourceCount += entry.sources.length
1189
1476
  missingCount += entry.missing.length
1477
+ const manual = entry.unverifiable ?? []
1478
+ unverifiableCount += manual.length
1479
+ operatorEnteredCount += manual.filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
1190
1480
  }
1191
1481
  return {
1192
1482
  format: meta.format,
@@ -1195,6 +1485,9 @@ function normalizeReceiptEvidence(evidence) {
1195
1485
  counts,
1196
1486
  sourceCount,
1197
1487
  missingCount,
1488
+ unverifiableCount,
1489
+ operatorEnteredCount,
1490
+ protectedExcluded,
1198
1491
  entries,
1199
1492
  }
1200
1493
  }
@@ -1564,6 +1857,7 @@ function receiptDocxSpec(input) {
1564
1857
  paragraphs: [
1565
1858
  '证据条目:' + evidence.entryCount + '(commitment ' + evidence.counts.commitment + ' / fact ' + evidence.counts.fact + ' / preference ' + evidence.counts.preference + ' / unknown ' + evidence.counts.unknown + ')',
1566
1859
  '已解析来源:' + evidence.sourceCount + ';缺失来源:' + evidence.missingCount,
1860
+ ...(evidence.unverifiableCount ? ['未外部核验(操作者录入):' + evidence.unverifiableCount + ' 条(不是缺失;请勿当作已核验证据)'] : []),
1567
1861
  '完整证据条目(session#turn 引用与截断引用原话)见 manifest.json 的 evidence 字段。',
1568
1862
  ],
1569
1863
  })
@@ -1637,6 +1931,7 @@ function buildReceiptReadme(input) {
1637
1931
  'SHA256SUMS sha256 of every other file in this pack',
1638
1932
  '',
1639
1933
  'Evidence entries: ' + evidence.entryCount + ' (sources ' + evidence.sourceCount + ', missing ' + evidence.missingCount + ')',
1934
+ ...(evidence.unverifiableCount ? ['unverifiable: ' + evidence.unverifiableCount + ' (operator-entered; not externally verified, NOT missing)'] : []),
1640
1935
  '(references and capped quotes only; see manifest.json evidence.entries)',
1641
1936
  '',
1642
1937
  'Verify (offline, no ~/.advisers database needed)',
@@ -1877,6 +2172,9 @@ export async function buildReceiptPack(options = {}) {
1877
2172
  counts: evidence.counts,
1878
2173
  sourceCount: evidence.sourceCount,
1879
2174
  missingCount: evidence.missingCount,
2175
+ unverifiableCount: evidence.unverifiableCount ?? 0,
2176
+ operatorEnteredCount: evidence.operatorEnteredCount ?? 0,
2177
+ protectedExcluded: Number.isInteger(evidence.protectedExcluded) ? evidence.protectedExcluded : 0,
1880
2178
  },
1881
2179
  anchored: anchors.length > 0,
1882
2180
  fileMode: RECEIPT_FILE_MODE,
@@ -1906,6 +2204,7 @@ function entryFromResult(result) {
1906
2204
  found: true,
1907
2205
  sources: Array.isArray(result.sources) ? result.sources : [],
1908
2206
  missing: Array.isArray(result.missing) ? result.missing : [],
2207
+ unverifiable: Array.isArray(result.unverifiable) ? result.unverifiable : [],
1909
2208
  }
1910
2209
  }
1911
2210
 
@@ -1963,7 +2262,8 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
1963
2262
  const id = String(entry.id ?? '')
1964
2263
  const sources = Array.isArray(entry.sources) ? entry.sources : []
1965
2264
  const missing = Array.isArray(entry.missing) ? entry.missing : []
1966
- if (!sources.length && !missing.length) {
2265
+ const unverifiable = Array.isArray(entry.unverifiable) ? entry.unverifiable : []
2266
+ if (!sources.length && !missing.length && !unverifiable.length) {
1967
2267
  rows.push([kind, id, '', '', entry.found === false ? '记录不存在' : '无证据'])
1968
2268
  continue
1969
2269
  }
@@ -1982,7 +2282,16 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
1982
2282
  id,
1983
2283
  item.ref || formatRef(item.sessionId, item.turnId) || String(item.id ?? ''),
1984
2284
  clampQuote(item.quote).quote,
1985
- `missing: ${item.reason ?? 'unknown'}`,
2285
+ 'missing: ' + (item.reason ?? 'unknown'),
2286
+ ])
2287
+ }
2288
+ for (const item of unverifiable) {
2289
+ rows.push([
2290
+ kind,
2291
+ id,
2292
+ '',
2293
+ clampQuote(item.quote).quote,
2294
+ MANUAL_SOURCE_KIND + ': operator-entered (unverifiable, not missing)',
1986
2295
  ])
1987
2296
  }
1988
2297
  }