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/evidence.js CHANGED
@@ -52,11 +52,20 @@ import {
52
52
  import { dirname, join, resolve } from 'node:path'
53
53
 
54
54
  import { secrecyLevel } from './egress.js'
55
+ import { canonicalSourceType, describeSourcePointer } from './source.js'
55
56
 
56
57
  /** Quotes are verbatim evidence but capped, so a pack never carries a full body. */
57
58
  export const MAX_QUOTE_CHARS = 500
58
59
  export const MANIFEST_FORMAT = 'advisers-evidence-pack'
59
- export const MANIFEST_VERSION = 1
60
+ /**
61
+ * Evidence pack manifest version. v2 (0.4) adds byKind/notCheckedCount/
62
+ * verificationBasis and typed source rows (kind/type/resolution).
63
+ * lib/receipt-verify.js accepts v1 packs (strict legacy schema) and v2 packs
64
+ * (counts cross-checked against the entries).
65
+ */
66
+ export const MANIFEST_VERSION = 2
67
+ /** Manifest versions the offline receipt verifier accepts. */
68
+ export const EVIDENCE_PACK_VERSIONS = Object.freeze([1, 2])
60
69
  /**
61
70
  * Default cap for the "pack everything" path (0.2.0 performance audit P0-3).
62
71
  * A pack built from every row in a large ledger is slow and huge; callers must
@@ -534,103 +543,495 @@ function resolvePointerTurn(store, sessionId, turnId, quote) {
534
543
  return { source: { sessionId: normalizedSessionId, turnId, quote, turn: lookup.turn } }
535
544
  }
536
545
 
537
- function resolveSourceRefs(store, items) {
538
- const sources = []
539
- const missing = []
540
- const unverifiable = []
541
- for (const item of items) {
542
- if (!item || typeof item !== 'object' || Array.isArray(item)) {
543
- missing.push({ reason: 'invalid_source' })
544
- continue
545
- }
546
- if (isManualEvidence(item)) {
547
- unverifiable.push(manualEvidenceSource(item))
548
- continue
549
- }
550
- const quote = typeof item.quote === 'string' ? item.quote : ''
551
- const ref = typeof item.ref === 'string' ? item.ref : ''
552
- if (!ref) {
553
- missing.push({ quote, reason: 'no_ref' })
554
- continue
555
- }
556
- const parsed = parseSourceRef(ref)
557
- if (!parsed) {
558
- missing.push({ ref, quote, reason: 'unparseable_ref' })
559
- continue
560
- }
561
- const resolved = resolvePointerTurn(store, parsed.sessionId, parsed.turnId, quote)
562
- if (resolved.missing) {
563
- missing.push({ ref, ...resolved.missing })
564
- continue
546
+ // ---------------------------------------------------------------------------
547
+ // typed source resolution (Evidence 2.0, 0.4 subset)
548
+ //
549
+ // Four states (0.4 vocabulary):
550
+ // verified locally resolved AND the quote matched (build time)
551
+ // missing should have resolved but did not (turn/chunk/page/record
552
+ // gone, session mismatch, quote mismatch, unparseable ref)
553
+ // unverifiable cannot be locally verified by design (manual operator entry,
554
+ // mail body purged / never retained, web page never cached,
555
+ // tool result never stored)
556
+ // not_checked no local lookup capability was supplied for this run
557
+ //
558
+ // "verified" means "resolved against the local ledger when the pack was built".
559
+ // A receipt pack is offline, so receipt-verify cannot replay the turns; the pack
560
+ // therefore declares verificationBasis: 'build-time' and never claims external
561
+ // verification. Manual sources are unverifiable by construction and a pack that
562
+ // marks them verified must fail verification.
563
+ // ---------------------------------------------------------------------------
564
+
565
+ /** The four resolution states (also used by receipt-verify for pack v2). */
566
+ export const EVIDENCE_RESOLUTIONS = Object.freeze(['verified', 'missing', 'unverifiable', 'not_checked'])
567
+ /** Evidence taxonomy: how a source came into the ledger. */
568
+ export const EVIDENCE_KINDS = Object.freeze(['observed', 'derived', 'inferred', 'manual'])
569
+ /** What an offline pack can honestly claim: local build-time resolution only. */
570
+ export const VERIFICATION_BASIS = 'build-time'
571
+ export const VERIFICATION_BASES = Object.freeze(['build-time', 'offline-consistency-only'])
572
+
573
+ /** Ref schemes recognised without a `source` v2 object. */
574
+ const SOURCE_REF_SCHEMES = Object.freeze([
575
+ ['mail:', 'mail'],
576
+ ['imap:', 'mail'],
577
+ ['eml:', 'mail'],
578
+ ['kb_chunk:', 'kb_chunk'],
579
+ ['kb:', 'kb_chunk'],
580
+ ['kb_page:', 'kb_page'],
581
+ ['web:', 'web'],
582
+ ['tool:', 'tool'],
583
+ ['calendar:', 'calendar'],
584
+ ['transcript:', 'transcript'],
585
+ ['document:', 'document'],
586
+ ['ledger:', 'ledger'],
587
+ ['manual:', 'manual'],
588
+ ])
589
+
590
+ /** Source type implied by a ref scheme ('' when the scheme is unknown). */
591
+ export function sourceTypeFromRef(ref) {
592
+ if (typeof ref !== 'string') return ''
593
+ const text = ref.trim()
594
+ if (!text) return ''
595
+ const lower = text.toLowerCase()
596
+ if (lower.startsWith('http://') || lower.startsWith('https://')) return 'web'
597
+ for (const [prefix, type] of SOURCE_REF_SCHEMES) {
598
+ if (lower.startsWith(prefix)) return type
599
+ }
600
+ return ''
601
+ }
602
+
603
+ function trimmedText(value) {
604
+ return typeof value === 'string' ? value.trim() : ''
605
+ }
606
+
607
+ /**
608
+ * Kind of one evidence item: explicit kind wins, manual is forced, a
609
+ * `derivedFrom` list implies 'derived', everything else is 'observed'.
610
+ */
611
+ export function evidenceKindOf(item) {
612
+ if (!item || typeof item !== 'object' || Array.isArray(item)) return 'observed'
613
+ const explicit = trimmedText(item.kind)
614
+ if (EVIDENCE_KINDS.includes(explicit)) return explicit
615
+ if (isManualEvidence(item)) return 'manual'
616
+ if (Array.isArray(item.derivedFrom) && item.derivedFrom.length) return 'derived'
617
+ return 'observed'
618
+ }
619
+
620
+ /**
621
+ * Normalise an evidence item (legacy pointer, source v2 object, or a bare typed
622
+ * source) into the pointer description the resolvers consume.
623
+ *
624
+ * Priority: nested `source` v2 > legacy pointer fields. A source is never
625
+ * invented: a missing ref/typed pointer stays missing.
626
+ *
627
+ * @returns {{type: string, quote: string, ref?: string, messageId?: string,
628
+ * subject?: string, docId?: string, pageId?: string, chunkIndex?: number,
629
+ * url?: string, tool?: string, retained?: boolean, derivedFrom?: string[]}}
630
+ */
631
+ export function evidenceDescriptor(item) {
632
+ if (!item || typeof item !== 'object' || Array.isArray(item)) return null
633
+ const outer = describeSourcePointer(item) ?? { type: '' }
634
+ const nested = item.source && typeof item.source === 'object' && !Array.isArray(item.source) ? describeSourcePointer(item.source) : null
635
+ const pointer = { ...outer, ...(nested ?? {}) }
636
+ let type = canonicalSourceType(item.source && typeof item.source === 'object' ? item.source.type : undefined)
637
+ if (!type) type = canonicalSourceType(item.type)
638
+ if (!type) type = sourceTypeFromRef(pointer.ref)
639
+ if (!type && (outer.ref || item.sessionId || item.turnId)) type = 'conversation'
640
+ pointer.type = type || ''
641
+ if (typeof item.quote === 'string') pointer.quote = item.quote
642
+ else if (!(typeof pointer.quote === 'string' && pointer.quote)) pointer.quote = ''
643
+ const derived = Array.isArray(item.derivedFrom)
644
+ ? item.derivedFrom
645
+ : item.source && typeof item.source === 'object' && Array.isArray(item.source.derivedFrom)
646
+ ? item.source.derivedFrom
647
+ : null
648
+ if (derived) pointer.derivedFrom = derived
649
+ return pointer
650
+ }
651
+
652
+ function pickRow(value) {
653
+ if (Array.isArray(value)) {
654
+ if (!value.length) return { row: null }
655
+ if (value.length === 1) return { row: value[0] }
656
+ return { ambiguous: true }
657
+ }
658
+ return { row: value ?? null }
659
+ }
660
+
661
+ /**
662
+ * Optional local lookup capability. Stores that do not expose the method are
663
+ * "unavailable" (honest not_checked/unverifiable), never "missing".
664
+ */
665
+ function localLookup(store, methods, selector, direct) {
666
+ if (typeof direct === 'function') {
667
+ try {
668
+ return { status: 'ok', value: direct(selector) }
669
+ } catch {
670
+ return { status: 'error' }
565
671
  }
566
- sources.push(resolved.source)
567
672
  }
568
- return { sources, missing, unverifiable }
673
+ if (!store || typeof store !== 'object') return { status: 'unavailable' }
674
+ for (const method of methods) {
675
+ if (typeof store[method] !== 'function') continue
676
+ try {
677
+ return { status: 'ok', value: store[method](selector) }
678
+ } catch {
679
+ return { status: 'error' }
680
+ }
681
+ }
682
+ return { status: 'unavailable' }
683
+ }
684
+
685
+ function mailSelector(pointer) {
686
+ const selector = {}
687
+ if (pointer.messageId) selector.messageId = pointer.messageId
688
+ if (pointer.subject) selector.subject = pointer.subject
689
+ const ref = typeof pointer.ref === 'string' ? pointer.ref.trim() : ''
690
+ if (ref) {
691
+ selector.ref = ref
692
+ const mailRef = /^mail:(.+)$/i.exec(ref)
693
+ if (mailRef && !selector.messageId) selector.messageId = mailRef[1]
694
+ const imapRef = /^imap:([^:]*):([^:]*):([^:]*)$/i.exec(ref)
695
+ if (imapRef) {
696
+ selector.accountId = imapRef[1]
697
+ selector.uidvalidity = imapRef[2]
698
+ const uid = Number(imapRef[3])
699
+ if (Number.isInteger(uid)) selector.uid = uid
700
+ }
701
+ }
702
+ return selector
703
+ }
704
+
705
+ function rowBody(row) {
706
+ if (!row || typeof row !== 'object') return ''
707
+ for (const key of ['body_text', 'bodyText', 'text', 'body']) {
708
+ if (typeof row[key] === 'string') return row[key]
709
+ }
710
+ return ''
711
+ }
712
+
713
+ function resolveMail(ctx) {
714
+ const pointer = ctx.pointer
715
+ const base = {}
716
+ if (pointer.messageId) base.messageId = pointer.messageId
717
+ if (pointer.subject) base.subject = pointer.subject
718
+ if (pointer.ref) base.ref = pointer.ref
719
+ else if (pointer.messageId) base.ref = 'mail:' + pointer.messageId
720
+ const lookup = localLookup(ctx.store, ['getMailMessage', 'findMailMessage', 'lookupMailMessage'], mailSelector(pointer), ctx.lookup?.mail)
721
+ const retained = pointer.retained === true
722
+ if (lookup.status === 'unavailable') {
723
+ return retained
724
+ ? { resolution: 'not_checked', reason: 'mail_lookup_unavailable', extra: base }
725
+ : { resolution: 'unverifiable', reason: 'source_not_retained', extra: base }
726
+ }
727
+ if (lookup.status === 'error') return { resolution: 'missing', reason: 'lookup_failed' }
728
+ const picked = pickRow(lookup.value)
729
+ if (picked.ambiguous) return { resolution: 'missing', reason: 'ambiguous_source' }
730
+ const row = picked.row
731
+ const messageId = (row && (row.message_id ?? row.messageId)) || pointer.messageId || undefined
732
+ const subject = (row && row.subject) || pointer.subject || undefined
733
+ if (messageId) base.messageId = messageId
734
+ if (subject) base.subject = subject
735
+ if (pointer.ref) base.ref = pointer.ref
736
+ else if (messageId) base.ref = 'mail:' + messageId
737
+ if (!row) {
738
+ return retained
739
+ ? { resolution: 'missing', reason: 'message_not_found', extra: base }
740
+ : { resolution: 'unverifiable', reason: 'source_not_retained', extra: base }
741
+ }
742
+ if (row.purged_at || row.purgedAt || row.status === 'purged') {
743
+ return { resolution: 'unverifiable', reason: 'mail_body_purged', extra: { ...base, retained: false } }
744
+ }
745
+ const body = rowBody(row)
746
+ if (!body) {
747
+ return row.retained === false
748
+ ? { resolution: 'unverifiable', reason: 'source_not_retained', extra: { ...base, retained: false } }
749
+ : { resolution: 'unverifiable', reason: 'source_not_retained', extra: base }
750
+ }
751
+ if (ctx.quote && !body.normalize('NFC').includes(ctx.quote.normalize('NFC'))) {
752
+ return { resolution: 'missing', reason: 'quote_mismatch', extra: base }
753
+ }
754
+ return {
755
+ resolution: 'verified',
756
+ extra: {
757
+ ...base,
758
+ messageId,
759
+ subject,
760
+ retained: true,
761
+ quoteVerified: ctx.quote.length > 0,
762
+ sourceDigest: sha256Hex(body),
763
+ },
764
+ }
569
765
  }
570
766
 
767
+ function kbSelector(pointer) {
768
+ const selector = {}
769
+ if (pointer.docId) selector.docId = pointer.docId
770
+ if (pointer.pageId) selector.pageId = pointer.pageId
771
+ if (typeof pointer.chunkIndex === 'number') selector.chunkIndex = pointer.chunkIndex
772
+ if (pointer.ref) selector.ref = pointer.ref
773
+ const ref = typeof pointer.ref === 'string' ? pointer.ref.trim() : ''
774
+ const kbRef = /^kb:(.+?)(?:#(\d+))?$/i.exec(ref)
775
+ if (kbRef && !selector.docId) {
776
+ selector.docId = kbRef[1]
777
+ if (kbRef[2] !== undefined && selector.chunkIndex === undefined) selector.chunkIndex = Number(kbRef[2])
778
+ }
779
+ return selector
780
+ }
781
+
782
+ function resolveKbChunk(ctx) {
783
+ const unavailableExtra = {}
784
+ if (ctx.pointer.ref) unavailableExtra.ref = ctx.pointer.ref
785
+ if (ctx.pointer.docId) unavailableExtra.docId = ctx.pointer.docId
786
+ if (typeof ctx.pointer.chunkIndex === 'number') unavailableExtra.chunkIndex = ctx.pointer.chunkIndex
787
+ const lookup = localLookup(ctx.store, ['getKbChunk', 'findKbChunk', 'lookupKbChunk'], kbSelector(ctx.pointer), ctx.lookup?.kbChunk)
788
+ if (lookup.status === 'unavailable') return { resolution: 'not_checked', reason: 'kb_lookup_unavailable', extra: unavailableExtra }
789
+ if (lookup.status === 'error') return { resolution: 'missing', reason: 'lookup_failed' }
790
+ const picked = pickRow(lookup.value)
791
+ if (picked.ambiguous) return { resolution: 'missing', reason: 'ambiguous_source' }
792
+ const row = picked.row
793
+ const extra = {}
794
+ if (ctx.pointer.ref) extra.ref = ctx.pointer.ref
795
+ if (row && row.id) extra.chunkId = row.id
796
+ if (row && row.doc_id) extra.docId = row.doc_id
797
+ if (row && Number.isInteger(row.seq)) extra.chunkIndex = row.seq
798
+ else if (typeof ctx.pointer.chunkIndex === 'number') extra.chunkIndex = ctx.pointer.chunkIndex
799
+ if (!row) return { resolution: 'missing', reason: 'chunk_not_found', extra }
800
+ if (row.deleted_at || row.deletedAt || row.status === 'deleted') {
801
+ return { resolution: 'missing', reason: 'chunk_not_found', extra }
802
+ }
803
+ const text = rowBody(row)
804
+ if (!text) return { resolution: 'unverifiable', reason: 'source_not_retained', extra: { ...extra, retained: false } }
805
+ if (ctx.quote && !text.normalize('NFC').includes(ctx.quote.normalize('NFC'))) {
806
+ return { resolution: 'missing', reason: 'quote_mismatch', extra }
807
+ }
808
+ return { resolution: 'verified', extra: { ...extra, retained: true, quoteVerified: ctx.quote.length > 0, sourceDigest: sha256Hex(text) } }
809
+ }
810
+
811
+ function resolveKbPage(ctx) {
812
+ const unavailableExtra = {}
813
+ if (ctx.pointer.ref) unavailableExtra.ref = ctx.pointer.ref
814
+ if (ctx.pointer.pageId) unavailableExtra.pageId = ctx.pointer.pageId
815
+ const lookup = localLookup(ctx.store, ['getKbPage', 'findKbPage', 'lookupKbPage'], kbSelector(ctx.pointer), ctx.lookup?.kbPage)
816
+ if (lookup.status === 'unavailable') return { resolution: 'not_checked', reason: 'kb_lookup_unavailable', extra: unavailableExtra }
817
+ if (lookup.status === 'error') return { resolution: 'missing', reason: 'lookup_failed' }
818
+ const picked = pickRow(lookup.value)
819
+ if (picked.ambiguous) return { resolution: 'missing', reason: 'ambiguous_source' }
820
+ const row = picked.row
821
+ const extra = {}
822
+ if (ctx.pointer.ref) extra.ref = ctx.pointer.ref
823
+ if (ctx.pointer.pageId) extra.pageId = ctx.pointer.pageId
824
+ else if (row && row.id) extra.pageId = row.id
825
+ if (!row) return { resolution: 'missing', reason: 'page_not_found', extra }
826
+ if (row.deleted_at || row.deletedAt || row.status === 'deleted') {
827
+ return { resolution: 'missing', reason: 'page_not_found', extra }
828
+ }
829
+ const text = typeof row.markdown === 'string' ? row.markdown : typeof row.title === 'string' ? row.title : ''
830
+ if (!text) return { resolution: 'unverifiable', reason: 'source_not_retained', extra: { ...extra, retained: false } }
831
+ if (ctx.quote && !text.normalize('NFC').includes(ctx.quote.normalize('NFC'))) {
832
+ return { resolution: 'missing', reason: 'quote_mismatch', extra }
833
+ }
834
+ return { resolution: 'verified', extra: { ...extra, retained: true, quoteVerified: ctx.quote.length > 0, sourceDigest: sha256Hex(text) } }
835
+ }
836
+
837
+ function resolveLedger(ctx) {
838
+ const ref = typeof ctx.pointer.ref === 'string' ? ctx.pointer.ref.replace(/^ledger:/i, '') : ''
839
+ if (!ref) return { resolution: 'missing', reason: ctx.noPointerReason }
840
+ const found =
841
+ findCommitment(ctx.ledger, ref, ctx.index) ??
842
+ findFact(ctx.ledger, ref, ctx.index) ??
843
+ findPreference(ctx.ledger, ref, ctx.index)
844
+ if (!found) {
845
+ if (!ctx.ledger) return { resolution: 'not_checked', reason: 'ledger_unavailable', extra: { ref } }
846
+ return { resolution: 'missing', reason: 'record_not_found', extra: { ref } }
847
+ }
848
+ return { resolution: 'verified', extra: { ref, quoteVerified: false } }
849
+ }
850
+
851
+ function resolveConversation(ctx) {
852
+ const pointer = ctx.pointer
853
+ const ref = typeof pointer.ref === 'string' ? pointer.ref.trim() : ''
854
+ if (!ref) return { resolution: 'missing', reason: ctx.noPointerReason, extra: {} }
855
+ const parsed = parseSourceRef(ref)
856
+ if (!parsed) return { resolution: 'missing', reason: 'unparseable_ref', extra: { ref } }
857
+ const resolved = resolvePointerTurn(ctx.store, parsed.sessionId, parsed.turnId, ctx.quote)
858
+ if (resolved.missing) return { resolution: 'missing', reason: resolved.missing.reason, extra: { ...resolved.missing } }
859
+ return { resolution: 'verified', extra: { ...resolved.source, quoteVerified: ctx.quote.length > 0 } }
860
+ }
861
+
862
+ function unretainedResolver(reason) {
863
+ return (ctx) => ({ resolution: 'unverifiable', reason, extra: ctx.pointer.ref ? { ref: ctx.pointer.ref } : {} })
864
+ }
865
+
866
+ const SOURCE_RESOLVERS = Object.freeze({
867
+ conversation: resolveConversation,
868
+ mail: resolveMail,
869
+ kb_chunk: resolveKbChunk,
870
+ kb_page: resolveKbPage,
871
+ ledger: resolveLedger,
872
+ web: unretainedResolver('source_not_retained'),
873
+ tool: unretainedResolver('tool_result_not_retained'),
874
+ calendar: unretainedResolver('source_not_retained'),
875
+ transcript: unretainedResolver('source_not_retained'),
876
+ document: unretainedResolver('source_not_retained'),
877
+ })
878
+
571
879
  /**
572
- * Trace a commitment's evidence back to real turns.
880
+ * Resolve one evidence item to its four-state resolution.
573
881
  *
574
- * @returns {{ commitment: object|undefined,
575
- * sources: Array<{sessionId: string, turnId: string, quote: string, turn: object}>,
576
- * missing: Array<{sessionId?: string, turnId?: string, quote?: string, id?: string, reason: string}> }}
882
+ * Store capabilities (all optional; absence is honest not_checked/unverifiable,
883
+ * never missing): `getMailMessage/findMailMessage/lookupMailMessage`,
884
+ * `getKbChunk/findKbChunk/lookupKbChunk`, `getKbPage/findKbPage/lookupKbPage`.
885
+ * The mail/KB data lines wire these methods into the SqliteStore later; the
886
+ * resolver is the frozen interface.
887
+ *
888
+ * @param {object} store SqliteStore-like (conversation turns + optional typed lookups)
889
+ * @param {object} item stored evidence item
890
+ * @param {{ledger?: object, index?: object, noPointerReason?: string}} [options]
891
+ * @returns {{resolution: 'verified'|'missing'|'unverifiable'|'not_checked',
892
+ * kind: string, type: string, entry?: object, item?: object, reason?: string}}
577
893
  */
578
- export function evidenceForCommitment(store, ledger, commitmentId, index) {
579
- const commitment = findCommitment(ledger, commitmentId, index)
580
- if (!commitment) {
581
- return { schemaVersion: 2, commitment: undefined, sources: [], missing: [{ id: commitmentId, reason: 'commitment_not_found' }], unverifiable: [] }
894
+ export function resolveEvidenceSource(store, item, options = {}) {
895
+ if (!item || typeof item !== 'object' || Array.isArray(item)) {
896
+ return { resolution: 'missing', kind: 'observed', type: 'unknown', item: { reason: 'invalid_source', resolution: 'missing' } }
897
+ }
898
+ const pointer = evidenceDescriptor(item)
899
+ const kind = evidenceKindOf(item)
900
+ const quote = typeof pointer.quote === 'string' ? pointer.quote : ''
901
+ if (isManualEvidence(item) || pointer.type === 'manual') {
902
+ return { resolution: 'unverifiable', kind: 'manual', type: 'manual', item: manualEvidenceSource(item) }
903
+ }
904
+ const context = {
905
+ store,
906
+ ledger: options.ledger,
907
+ index: options.index,
908
+ lookup: options.lookup && typeof options.lookup === 'object' ? options.lookup : {},
909
+ noPointerReason: typeof options.noPointerReason === 'string' ? options.noPointerReason : 'no_ref',
910
+ pointer,
911
+ quote,
912
+ }
913
+ const resolver = SOURCE_RESOLVERS[pointer.type]
914
+ if (!resolver) {
915
+ const itemOut = { reason: context.noPointerReason, kind, type: pointer.type || 'unknown', resolution: 'missing' }
916
+ if (quote) itemOut.quote = quote
917
+ if (pointer.ref) itemOut.ref = pointer.ref
918
+ return { resolution: 'missing', kind, type: pointer.type || 'unknown', item: itemOut }
919
+ }
920
+ let result
921
+ try {
922
+ result = resolver(context)
923
+ } catch {
924
+ result = { resolution: 'missing', reason: 'lookup_failed', extra: {} }
925
+ }
926
+ const type = pointer.type || 'unknown'
927
+ if (result.resolution === 'verified') {
928
+ return {
929
+ resolution: 'verified',
930
+ kind,
931
+ type,
932
+ entry: { kind, type, resolution: 'verified', quote, quoteVerified: quote.length > 0, ...(result.extra ?? {}) },
933
+ }
582
934
  }
935
+ const itemOut = { reason: result.reason || 'unknown', kind, type, resolution: result.resolution, quoteVerified: false }
936
+ if (quote) itemOut.quote = quote
937
+ for (const key of ['ref', 'sessionId', 'turnId', 'messageId', 'subject', 'retained', 'docId', 'pageId', 'chunkIndex', 'url', 'tool', 'chunkId']) {
938
+ if (result.extra && result.extra[key] !== undefined) itemOut[key] = result.extra[key]
939
+ }
940
+ return { resolution: result.resolution, kind, type, item: itemOut }
941
+ }
942
+
943
+ /** Partition stored evidence items into the four resolution buckets. */
944
+ function resolveSourceItems(store, items, options) {
583
945
  const sources = []
584
946
  const missing = []
585
947
  const unverifiable = []
586
- const evidence = Array.isArray(commitment.evidence) ? commitment.evidence : []
587
- for (const item of evidence) {
588
- if (isManualEvidence(item)) {
589
- unverifiable.push(manualEvidenceSource(item))
590
- continue
591
- }
592
- const sessionId = typeof item?.sessionId === 'string' ? item.sessionId : ''
593
- const turnId = typeof item?.turnId === 'string' ? item.turnId : ''
594
- const quote = typeof item?.quote === 'string' ? item.quote : ''
595
- if (!sessionId || !turnId) {
596
- missing.push({
597
- sessionId: sessionId || undefined,
598
- turnId: turnId || undefined,
599
- quote,
600
- reason: 'invalid_evidence',
601
- })
602
- continue
603
- }
604
- const resolved = resolvePointerTurn(store, sessionId, turnId, quote)
605
- if (resolved.missing) {
606
- missing.push(resolved.missing)
607
- continue
948
+ const notChecked = []
949
+ for (const item of Array.isArray(items) ? items : []) {
950
+ const result = resolveEvidenceSource(store, item, options)
951
+ if (result.resolution === 'verified') sources.push(result.entry)
952
+ else if (result.resolution === 'unverifiable') unverifiable.push(result.item)
953
+ else if (result.resolution === 'not_checked') notChecked.push(result.item)
954
+ else missing.push(result.item)
955
+ }
956
+ return { sources, missing, unverifiable, notChecked }
957
+ }
958
+
959
+ function emptyByKind() {
960
+ const byKind = {}
961
+ for (const kind of EVIDENCE_KINDS) byKind[kind] = 0
962
+ return byKind
963
+ }
964
+
965
+ /**
966
+ * Tally the evidence taxonomy across every item of one traceback (sources,
967
+ * missing, unverifiable AND not_checked). Unknown kinds count as 'observed'.
968
+ * The pack verifier recomputes the same identity from the packed entries.
969
+ */
970
+ export function evidenceByKind(buckets) {
971
+ const byKind = emptyByKind()
972
+ for (const list of [buckets.sources, buckets.missing, buckets.unverifiable, buckets.notChecked]) {
973
+ for (const item of Array.isArray(list) ? list : []) {
974
+ const kind = EVIDENCE_KINDS.includes(item?.kind) ? item.kind : 'observed'
975
+ byKind[kind] += 1
608
976
  }
609
- sources.push(resolved.source)
610
977
  }
611
- return { schemaVersion: 2, commitment, sources, missing, unverifiable }
978
+ return byKind
979
+ }
980
+
981
+ /** Summary fields every traceback/pack shares (Evidence pack v2). */
982
+ export function evidenceResolutionSummary(buckets) {
983
+ const notChecked = Array.isArray(buckets.notChecked) ? buckets.notChecked : []
984
+ return {
985
+ byKind: evidenceByKind(buckets),
986
+ notCheckedCount: notChecked.length,
987
+ verificationBasis: VERIFICATION_BASIS,
988
+ }
989
+ }
990
+
991
+ /**
992
+ * Trace a commitment's evidence back to its sources.
993
+ *
994
+ * Commitment items have carried three shapes over time: `{sessionId,turnId,quote}`
995
+ * (conversation turn), `{quote,source}` (mail/KB import; no turn exists) and
996
+ * manual operator entries. All three now go through the same typed resolver.
997
+ *
998
+ * @returns {{ commitment: object|undefined, sources: object[], missing: object[],
999
+ * unverifiable: object[], notChecked: object[], byKind: object,
1000
+ * notCheckedCount: number, verificationBasis: string }}
1001
+ */
1002
+ export function evidenceForCommitment(store, ledger, commitmentId, index, options = {}) {
1003
+ const buckets = { sources: [], missing: [], unverifiable: [], notChecked: [] }
1004
+ const commitment = findCommitment(ledger, commitmentId, index)
1005
+ if (!commitment) {
1006
+ buckets.missing.push({ id: commitmentId, reason: 'commitment_not_found', kind: 'observed' })
1007
+ return { schemaVersion: 2, commitment: undefined, ...buckets, ...evidenceResolutionSummary(buckets) }
1008
+ }
1009
+ const resolved = resolveSourceItems(store, commitment.evidence, { ledger, index, lookup: options.lookup, noPointerReason: 'invalid_evidence' })
1010
+ return { schemaVersion: 2, commitment, ...resolved, ...evidenceResolutionSummary(resolved) }
612
1011
  }
613
1012
 
614
- /** Trace a fact's `SourceRef[]` (plus its primary `source`) back to turns. */
615
- export function evidenceForFact(store, ledger, factId, index) {
1013
+ /** Trace a fact's `SourceRef[]` (plus its primary `source`) back to its sources. */
1014
+ export function evidenceForFact(store, ledger, factId, index, options = {}) {
616
1015
  const fact = findFact(ledger, factId, index)
617
1016
  if (!fact) {
618
- return { schemaVersion: 2, fact: undefined, sources: [], missing: [{ id: factId, reason: 'fact_not_found' }], unverifiable: [] }
1017
+ const buckets = { sources: [], missing: [{ id: factId, reason: 'fact_not_found', kind: 'observed' }], unverifiable: [], notChecked: [] }
1018
+ return { schemaVersion: 2, fact: undefined, ...buckets, ...evidenceResolutionSummary(buckets) }
619
1019
  }
620
- const refs = collectSourceRefs(fact.evidence, primarySourceCandidates(fact.source))
621
- const resolved = resolveSourceRefs(store, refs)
622
- return { schemaVersion: 2, fact, sources: resolved.sources, missing: resolved.missing, unverifiable: resolved.unverifiable }
1020
+ const items = collectSourceRefs(fact.evidence, primarySourceCandidates(fact.source))
1021
+ const resolved = resolveSourceItems(store, items, { ledger, index, lookup: options.lookup, noPointerReason: 'no_ref' })
1022
+ return { schemaVersion: 2, fact, ...resolved, ...evidenceResolutionSummary(resolved) }
623
1023
  }
624
1024
 
625
- /** Trace a preference's `SourceRef[]` (plus its primary `source`) back to turns. */
626
- export function evidenceForPreference(store, ledger, preferenceId, index) {
1025
+ /** Trace a preference's `SourceRef[]` (plus its primary `source`) back to its sources. */
1026
+ export function evidenceForPreference(store, ledger, preferenceId, index, options = {}) {
627
1027
  const preference = findPreference(ledger, preferenceId, index)
628
1028
  if (!preference) {
629
- return { schemaVersion: 2, preference: undefined, sources: [], missing: [{ id: preferenceId, reason: 'preference_not_found' }], unverifiable: [] }
1029
+ const buckets = { sources: [], missing: [{ id: preferenceId, reason: 'preference_not_found', kind: 'observed' }], unverifiable: [], notChecked: [] }
1030
+ return { schemaVersion: 2, preference: undefined, ...buckets, ...evidenceResolutionSummary(buckets) }
630
1031
  }
631
- const refs = collectSourceRefs(preference.evidence, primarySourceCandidates(preference.source))
632
- const resolved = resolveSourceRefs(store, refs)
633
- return { schemaVersion: 2, preference, sources: resolved.sources, missing: resolved.missing, unverifiable: resolved.unverifiable }
1032
+ const items = collectSourceRefs(preference.evidence, primarySourceCandidates(preference.source))
1033
+ const resolved = resolveSourceItems(store, items, { ledger, index, lookup: options.lookup, noPointerReason: 'no_ref' })
1034
+ return { schemaVersion: 2, preference, ...resolved, ...evidenceResolutionSummary(resolved) }
634
1035
  }
635
1036
 
636
1037
  // ---------------------------------------------------------------------------
@@ -650,16 +1051,36 @@ function compareEntries(a, b) {
650
1051
  *
651
1052
  * @returns {string} canonical JSON text with a trailing newline
652
1053
  */
653
- export function manifestFor(entries, { createdAt } = {}) {
1054
+ function tallyCompacted(entries) {
1055
+ const byKind = emptyByKind()
1056
+ let notCheckedCount = 0
1057
+ for (const entry of entries) {
1058
+ for (const key of ['sources', 'missing', 'unverifiable', 'notChecked']) {
1059
+ const list = Array.isArray(entry[key]) ? entry[key] : []
1060
+ if (key === 'notChecked') notCheckedCount += list.length
1061
+ for (const item of list) {
1062
+ const kind = EVIDENCE_KINDS.includes(item?.kind) ? item.kind : 'observed'
1063
+ byKind[kind] += 1
1064
+ }
1065
+ }
1066
+ }
1067
+ return { byKind, notCheckedCount }
1068
+ }
1069
+
1070
+ export function manifestFor(entries, { createdAt, byKind, notCheckedCount, verificationBasis } = {}) {
654
1071
  const list = (Array.isArray(entries) ? entries : [])
655
1072
  .filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry))
656
1073
  .map((entry) => ({ ...entry }))
657
1074
  list.sort(compareEntries)
1075
+ const tallied = tallyCompacted(list)
658
1076
  return `${stableStringify({
659
1077
  format: MANIFEST_FORMAT,
660
1078
  version: MANIFEST_VERSION,
661
1079
  createdAt: isoDate(createdAt),
662
1080
  entryCount: list.length,
1081
+ byKind: byKind && typeof byKind === 'object' ? byKind : tallied.byKind,
1082
+ notCheckedCount: Number.isInteger(notCheckedCount) && notCheckedCount >= 0 ? notCheckedCount : tallied.notCheckedCount,
1083
+ verificationBasis: typeof verificationBasis === 'string' && VERIFICATION_BASES.includes(verificationBasis) ? verificationBasis : VERIFICATION_BASIS,
663
1084
  entries: list,
664
1085
  })}\n`
665
1086
  }
@@ -683,43 +1104,89 @@ function formatRef(sessionId, turnId) {
683
1104
  return parts.join('#')
684
1105
  }
685
1106
 
1107
+ const TYPED_SOURCE_FIELDS = Object.freeze(['ref', 'messageId', 'subject', 'docId', 'pageId', 'chunkIndex', 'url', 'tool', 'sourceDigest'])
1108
+
1109
+ /** Clamp a quote while keeping already-recorded truncation metadata (receipt re-compaction). */
1110
+ function clampStoredQuote(item) {
1111
+ const clamped = clampQuote(item?.quote)
1112
+ if (Number.isInteger(item?.quoteChars) && item.quoteChars >= clamped.quoteChars) {
1113
+ clamped.quoteChars = item.quoteChars
1114
+ clamped.truncated = item.truncated === true || item.quoteChars > MAX_QUOTE_CHARS
1115
+ }
1116
+ return clamped
1117
+ }
1118
+
686
1119
  function compactSource(source) {
687
- const clamped = clampQuote(source?.quote)
1120
+ const clamped = clampStoredQuote(source)
688
1121
  const entry = {
689
- sessionId: typeof source?.sessionId === 'string' ? source.sessionId : '',
690
- turnId: typeof source?.turnId === 'string' ? source.turnId : '',
1122
+ kind: EVIDENCE_KINDS.includes(source?.kind) ? source.kind : 'observed',
1123
+ type: typeof source?.type === 'string' && source.type ? source.type : 'conversation',
1124
+ resolution: 'verified',
1125
+ quoteVerified: source?.quoteVerified === true,
691
1126
  ...clamped,
692
1127
  }
1128
+ if (typeof source?.sessionId === 'string' && source.sessionId) entry.sessionId = source.sessionId
1129
+ if (typeof source?.turnId === 'string' && source.turnId) entry.turnId = source.turnId
693
1130
  // Turn sequence/role are provenance metadata, not body text.
694
1131
  if (Number.isInteger(source?.turn?.seq)) entry.turnSeq = source.turn.seq
695
1132
  if (typeof source?.turn?.role === 'string') entry.turnRole = source.turn.role
1133
+ for (const key of TYPED_SOURCE_FIELDS) {
1134
+ const value = source?.[key]
1135
+ if (typeof value === 'string' && value) entry[key] = value
1136
+ else if (Number.isInteger(value) && value >= 0) entry[key] = value
1137
+ }
1138
+ if (typeof source?.retained === 'boolean') entry.retained = source.retained
1139
+ if (Array.isArray(source?.derivedFrom) && source.derivedFrom.length) {
1140
+ entry.derivedFrom = source.derivedFrom.filter((item) => typeof item === 'string').slice(0, 20)
1141
+ }
696
1142
  return entry
697
1143
  }
698
1144
 
1145
+ const TYPED_ITEM_FIELDS = Object.freeze(['ref', 'sessionId', 'turnId', 'messageId', 'subject', 'docId', 'pageId', 'chunkIndex', 'url', 'tool', 'chunkId'])
1146
+
1147
+ function compactTypedItem(item, { resolution, fallbackReason }) {
1148
+ const out = {
1149
+ kind: EVIDENCE_KINDS.includes(item?.kind) ? item.kind : 'observed',
1150
+ type: typeof item?.type === 'string' && item.type ? item.type : 'unknown',
1151
+ resolution,
1152
+ reason: typeof item?.reason === 'string' && item.reason ? item.reason : fallbackReason,
1153
+ }
1154
+ const clamped = clampStoredQuote(item)
1155
+ Object.assign(out, clamped)
1156
+ for (const key of TYPED_ITEM_FIELDS) {
1157
+ const value = item?.[key]
1158
+ if (typeof value === 'string' && value) out[key] = value
1159
+ else if (Number.isInteger(value) && value >= 0) out[key] = value
1160
+ }
1161
+ if (typeof item?.retained === 'boolean') out.retained = item.retained
1162
+ return out
1163
+ }
1164
+
699
1165
  function compactMissing(item) {
700
1166
  const out = { reason: typeof item?.reason === 'string' ? item.reason : 'unknown' }
701
- for (const key of ['id', 'ref', 'sessionId', 'turnId']) {
1167
+ // Missing rows stay as small as the v1 shape: kind is only written when it is
1168
+ // not the default 'observed' (the verifier defaults it the same way), so a
1169
+ // 2000-row pack does not grow past the receipt manifest size limit.
1170
+ if (EVIDENCE_KINDS.includes(item?.kind) && item.kind !== 'observed') out.kind = item.kind
1171
+ for (const key of ['id', ...TYPED_ITEM_FIELDS]) {
702
1172
  if (typeof item?.[key] === 'string' && item[key]) out[key] = item[key]
703
1173
  }
704
- if (typeof item?.quote === 'string' && item.quote.length) Object.assign(out, clampQuote(item.quote))
1174
+ if (typeof item?.quote === 'string' && item.quote.length) Object.assign(out, clampStoredQuote(item))
705
1175
  return out
706
1176
  }
707
1177
 
708
1178
  function compactUnverifiable(item) {
709
- const out = {
710
- kind: MANUAL_SOURCE_KIND,
711
- type: MANUAL_SOURCE_KIND,
712
- resolution: MANUAL_RESOLUTION,
713
- reason: typeof item?.reason === 'string' && item.reason ? item.reason : MANUAL_REASON,
714
- }
715
- const clamped = clampQuote(item?.quote)
716
- Object.assign(out, clamped)
1179
+ const out = compactTypedItem(item, { resolution: MANUAL_RESOLUTION, fallbackReason: MANUAL_REASON })
717
1180
  for (const key of ['capturedAt', 'capturedBy', 'command']) {
718
1181
  if (typeof item?.[key] === 'string' && item[key]) out[key] = item[key]
719
1182
  }
720
1183
  return out
721
1184
  }
722
1185
 
1186
+ function compactNotChecked(item) {
1187
+ return compactTypedItem(item, { resolution: 'not_checked', fallbackReason: 'not_checked' })
1188
+ }
1189
+
723
1190
  function compactEntry(entry) {
724
1191
  const out = {
725
1192
  kind: typeof entry.kind === 'string' ? entry.kind : 'unknown',
@@ -733,6 +1200,9 @@ function compactEntry(entry) {
733
1200
  if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
734
1201
  out.unverifiable = entry.unverifiable.map(compactUnverifiable)
735
1202
  }
1203
+ if (Array.isArray(entry.notChecked) && entry.notChecked.length) {
1204
+ out.notChecked = entry.notChecked.map(compactNotChecked)
1205
+ }
736
1206
  return out
737
1207
  }
738
1208
 
@@ -801,19 +1271,23 @@ function normalizeRequestedIds(ids, ledger, index) {
801
1271
  return out
802
1272
  }
803
1273
 
804
- function buildReadme({ createdAt, entries, manifestDigest }) {
1274
+ function buildReadme({ createdAt, entries, manifestDigest, byKind, notCheckedCount }) {
805
1275
  const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
806
1276
  let sourceCount = 0
807
1277
  let missingCount = 0
808
1278
  let unverifiableCount = 0
1279
+ let manualCount = 0
809
1280
  let truncatedCount = 0
810
1281
  for (const entry of entries) {
811
1282
  counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
812
1283
  sourceCount += entry.sources.length
813
1284
  missingCount += entry.missing.length
814
1285
  unverifiableCount += (entry.unverifiable ?? []).length
1286
+ manualCount += (entry.unverifiable ?? []).filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
815
1287
  truncatedCount += entry.sources.filter((source) => source.truncated).length
816
1288
  }
1289
+ const notChecked = Number.isInteger(notCheckedCount) ? notCheckedCount : entries.reduce((sum, entry) => sum + (entry.notChecked ?? []).length, 0)
1290
+ const kinds = byKind && typeof byKind === 'object' ? byKind : tallyCompacted(entries).byKind
817
1291
  const lines = [
818
1292
  'Advisers evidence pack',
819
1293
  '======================',
@@ -821,7 +1295,10 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
821
1295
  'format: ' + MANIFEST_FORMAT + ' v' + MANIFEST_VERSION,
822
1296
  'created: ' + createdAt,
823
1297
  'entries: ' + entries.length + ' (commitment ' + counts.commitment + ', fact ' + counts.fact + ', preference ' + counts.preference + ', unknown ' + counts.unknown + ')',
824
- 'sources: ' + sourceCount + ' resolved, ' + missingCount + ' missing' + (unverifiableCount ? ', ' + unverifiableCount + ' operator-entered (not externally verified, not missing)' : ''),
1298
+ 'version: ' + MANIFEST_VERSION + ' (typed sources + byKind/notCheckedCount/verificationBasis)',
1299
+ 'sources: ' + sourceCount + ' verified at build time, ' + missingCount + ' missing' + (unverifiableCount ? ', ' + unverifiableCount + ' unverifiable' + (manualCount ? ' (' + manualCount + ' operator-entered)' : '') : '') + (notChecked ? ', ' + notChecked + ' not checked' : ''),
1300
+ 'by kind: observed ' + (kinds.observed ?? 0) + ', derived ' + (kinds.derived ?? 0) + ', inferred ' + (kinds.inferred ?? 0) + ', manual ' + (kinds.manual ?? 0),
1301
+ 'basis: ' + VERIFICATION_BASIS + ' — offline verification proves pack consistency only; it cannot replay turns or re-check web/tool sources',
825
1302
  `quotes: verbatim, at most ${MAX_QUOTE_CHARS} characters each; ${truncatedCount} truncated`,
826
1303
  '',
827
1304
  'Files',
@@ -847,7 +1324,13 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
847
1324
  `- ${entry.kind} ${entry.id} sources=${entry.sources.length} missing=${entry.missing.length}${manualCount ? ` manual=${manualCount}` : ''}${entry.found ? '' : ' (record not found)'}`,
848
1325
  )
849
1326
  for (const item of (entry.unverifiable ?? []).slice(0, README_REF_CAP)) {
850
- lines.push(` manual operator-entered (unverifiable): ${item.reason ?? MANUAL_REASON}`)
1327
+ lines.push(` unverifiable ${item.type ?? 'unknown'}: ${item.reason ?? MANUAL_REASON}`)
1328
+ }
1329
+ for (const item of (entry.notChecked ?? []).slice(0, README_REF_CAP)) {
1330
+ lines.push(` not checked ${item.type ?? 'unknown'}: ${item.reason ?? 'not_checked'}`)
1331
+ }
1332
+ if ((entry.notChecked ?? []).length > README_REF_CAP) {
1333
+ lines.push(` ... ${entry.notChecked.length - README_REF_CAP} more not checked`)
851
1334
  }
852
1335
  const refs = entry.sources.slice(0, README_REF_CAP)
853
1336
  for (const source of refs) {
@@ -905,6 +1388,11 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
905
1388
  * a record above `clearance`: omit it and count it (`exclude`, the bulk
906
1389
  * default), or throw `ProtectedEvidenceError` (`error`, used when the
907
1390
  * caller named the ids explicitly and must not get a silent partial pack).
1391
+ * @param {{mail?: Function, kbChunk?: Function, kbPage?: Function}} [options.lookups]
1392
+ * optional typed-source lookup seam for the mail/KB data lines, e.g.
1393
+ * `{mail: (selector) => getMailMessage(store, selector.messageId ?? selector.ref, {includeBody:true})}`.
1394
+ * Missing lookups are honest unverifiable/not_checked rows, never missing;
1395
+ * store methods of the same names are used when the seam is absent.
908
1396
  * @returns {{ files: Record<string, string>, summary: object }}
909
1397
  * files: `{ 'manifest.json': string, 'README.txt': string, 'SHA256SUMS': string }`
910
1398
  */
@@ -917,6 +1405,7 @@ export function buildEvidencePack({
917
1405
  all = false,
918
1406
  clearance = null,
919
1407
  protectedPolicy = 'exclude',
1408
+ lookups,
920
1409
  } = {}) {
921
1410
  if (!ledger || typeof ledger !== 'object') throw new TypeError('buildEvidencePack requires a ledger')
922
1411
  if (!store || typeof store !== 'object') throw new TypeError('buildEvidencePack requires a store')
@@ -964,7 +1453,7 @@ export function buildEvidencePack({
964
1453
  for (const id of requested.commitments) {
965
1454
  const commitment = findCommitment(ledger, id, index)
966
1455
  if (blockedByClearance('commitment', commitment)) continue
967
- const result = evidenceForCommitment(store, ledger, id, index)
1456
+ const result = evidenceForCommitment(store, ledger, id, index, { lookup: lookups })
968
1457
  entries.push({
969
1458
  kind: 'commitment',
970
1459
  id,
@@ -972,18 +1461,19 @@ export function buildEvidencePack({
972
1461
  sources: result.sources,
973
1462
  missing: result.missing,
974
1463
  unverifiable: result.unverifiable,
1464
+ notChecked: result.notChecked,
975
1465
  })
976
1466
  }
977
1467
  for (const id of requested.facts) {
978
1468
  const fact = findFact(ledger, id, index)
979
1469
  if (blockedByClearance('fact', fact)) continue
980
- const result = evidenceForFact(store, ledger, id, index)
981
- entries.push({ kind: 'fact', id, found: Boolean(result.fact), sources: result.sources, missing: result.missing, unverifiable: result.unverifiable })
1470
+ const result = evidenceForFact(store, ledger, id, index, { lookup: lookups })
1471
+ entries.push({ kind: 'fact', id, found: Boolean(result.fact), sources: result.sources, missing: result.missing, unverifiable: result.unverifiable, notChecked: result.notChecked })
982
1472
  }
983
1473
  for (const id of requested.preferences) {
984
1474
  const preference = findPreference(ledger, id, index)
985
1475
  if (blockedByClearance('preference', preference)) continue
986
- const result = evidenceForPreference(store, ledger, id, index)
1476
+ const result = evidenceForPreference(store, ledger, id, index, { lookup: lookups })
987
1477
  entries.push({
988
1478
  kind: 'preference',
989
1479
  id,
@@ -991,10 +1481,11 @@ export function buildEvidencePack({
991
1481
  sources: result.sources,
992
1482
  missing: result.missing,
993
1483
  unverifiable: result.unverifiable,
1484
+ notChecked: result.notChecked,
994
1485
  })
995
1486
  }
996
1487
  for (const id of requested.unknown) {
997
- entries.push({ kind: 'unknown', id, found: false, sources: [], missing: [{ id, reason: 'record_not_found' }] })
1488
+ entries.push({ kind: 'unknown', id, found: false, sources: [], missing: [{ id, reason: 'record_not_found', kind: 'observed' }] })
998
1489
  }
999
1490
  if (protectedIds.length) throw new ProtectedEvidenceError(protectedIds.length, clearanceValue)
1000
1491
 
@@ -1002,9 +1493,10 @@ export function buildEvidencePack({
1002
1493
  .map(compactEntry)
1003
1494
  .sort(compareEntries)
1004
1495
 
1005
- const manifestJson = manifestFor(compacted, { createdAt })
1496
+ const tallied = tallyCompacted(compacted)
1497
+ const manifestJson = manifestFor(compacted, { createdAt, byKind: tallied.byKind, notCheckedCount: tallied.notCheckedCount, verificationBasis: VERIFICATION_BASIS })
1006
1498
  const manifestDigest = sha256Hex(manifestJson)
1007
- const readme = buildReadme({ createdAt, entries: compacted, manifestDigest })
1499
+ const readme = buildReadme({ createdAt, entries: compacted, manifestDigest, byKind: tallied.byKind, notCheckedCount: tallied.notCheckedCount })
1008
1500
  const readmeDigest = sha256Hex(readme)
1009
1501
  const sums = [`${readmeDigest} README.txt`, `${manifestDigest} manifest.json`].join('\n') + '\n'
1010
1502
 
@@ -1013,14 +1505,16 @@ export function buildEvidencePack({
1013
1505
  let missingCount = 0
1014
1506
  let unverifiableCount = 0
1015
1507
  let operatorEnteredCount = 0
1508
+ let notCheckedCount = 0
1016
1509
  let truncatedCount = 0
1017
1510
  for (const entry of compacted) {
1018
1511
  counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
1019
1512
  sourceCount += entry.sources.length
1020
1513
  missingCount += entry.missing.length
1021
- const manual = entry.unverifiable ?? []
1022
- unverifiableCount += manual.length
1023
- operatorEnteredCount += manual.filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
1514
+ const unverifiable = entry.unverifiable ?? []
1515
+ unverifiableCount += unverifiable.length
1516
+ operatorEnteredCount += unverifiable.filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
1517
+ notCheckedCount += (entry.notChecked ?? []).length
1024
1518
  truncatedCount += entry.sources.filter((source) => source.truncated).length
1025
1519
  }
1026
1520
 
@@ -1040,6 +1534,9 @@ export function buildEvidencePack({
1040
1534
  missingCount,
1041
1535
  unverifiableCount,
1042
1536
  operatorEnteredCount,
1537
+ notCheckedCount,
1538
+ byKind: tallied.byKind,
1539
+ verificationBasis: VERIFICATION_BASIS,
1043
1540
  truncatedCount,
1044
1541
  // Additive (0.2.5 A-1): how many requested rows were withheld because
1045
1542
  // their own matter is protected. Counts only — never a title or quote.
@@ -1427,11 +1924,22 @@ function normalizeReceiptDeliveries(deliveries) {
1427
1924
  // --- evidence entries (re-sanitized: the receipt pack keeps references and
1428
1925
  // --- capped quotes only, never full turn bodies) ---------------------------
1429
1926
 
1927
+ function receiptIsTypedSource(source) {
1928
+ if (!source || typeof source !== 'object' || Array.isArray(source)) return false
1929
+ if (EVIDENCE_KINDS.includes(source.kind)) return true
1930
+ if (typeof source.type === 'string' && source.type && source.type !== 'conversation' && source.type !== 'unknown') return true
1931
+ // A source that never carried a session#turn pair is a typed source in v2
1932
+ // terms even when the caller forgot kind/type.
1933
+ return !('sessionId' in source) || !('turnId' in source)
1934
+ }
1935
+
1430
1936
  function receiptSource(source) {
1431
1937
  if (source && typeof source === 'object' && source.turn) return compactSource(source)
1432
1938
  if (!source || typeof source !== 'object' || Array.isArray(source)) {
1433
1939
  return { sessionId: '', turnId: '', quote: '', quoteChars: 0, truncated: false, quoteSha256: sha256Hex('') }
1434
1940
  }
1941
+ if (receiptIsTypedSource(source)) return compactSource(source)
1942
+ // v1 evidence shape: keep the historical receipt bytes exactly.
1435
1943
  const rawQuote = typeof source.quote === 'string' ? source.quote : ''
1436
1944
  const chars = Array.from(rawQuote)
1437
1945
  const quote = chars.length > MAX_QUOTE_CHARS ? chars.slice(0, MAX_QUOTE_CHARS).join('') : rawQuote
@@ -1453,7 +1961,7 @@ function receiptSource(source) {
1453
1961
  function receiptMissing(item) {
1454
1962
  if (!item || typeof item !== 'object' || Array.isArray(item)) return { reason: 'unknown' }
1455
1963
  const out = { reason: typeof item.reason === 'string' ? item.reason : 'unknown' }
1456
- for (const key of ['id', 'ref', 'sessionId', 'turnId']) {
1964
+ for (const key of ['id', 'kind', 'type', 'ref', 'sessionId', 'turnId', 'messageId', 'docId', 'pageId', 'url', 'tool']) {
1457
1965
  if (typeof item[key] === 'string' && item[key]) out[key] = item[key]
1458
1966
  }
1459
1967
  if (typeof item.quote === 'string' && item.quote.length) {
@@ -1469,6 +1977,15 @@ function receiptMissing(item) {
1469
1977
 
1470
1978
  function receiptUnverifiable(item) {
1471
1979
  if (!item || typeof item !== 'object' || Array.isArray(item)) return null
1980
+ const typed = EVIDENCE_KINDS.includes(item.kind) || (typeof item.type === 'string' && item.type && item.type !== MANUAL_SOURCE_KIND)
1981
+ if (typed) {
1982
+ const out = compactUnverifiable(item)
1983
+ for (const key of ['capturedAt', 'capturedBy', 'command']) {
1984
+ if (typeof item[key] === 'string' && item[key]) out[key] = item[key].slice(0, 120)
1985
+ }
1986
+ return out
1987
+ }
1988
+ // Legacy manual shape (v1 evidence): keep the historical receipt bytes.
1472
1989
  const out = {
1473
1990
  kind: MANUAL_SOURCE_KIND,
1474
1991
  type: MANUAL_SOURCE_KIND,
@@ -1482,6 +1999,11 @@ function receiptUnverifiable(item) {
1482
1999
  return out
1483
2000
  }
1484
2001
 
2002
+ function receiptNotChecked(item) {
2003
+ if (!item || typeof item !== 'object' || Array.isArray(item)) return null
2004
+ return compactNotChecked(item)
2005
+ }
2006
+
1485
2007
  function receiptEvidenceEntry(entry) {
1486
2008
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null
1487
2009
  const out = {
@@ -1494,11 +2016,14 @@ function receiptEvidenceEntry(entry) {
1494
2016
  if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
1495
2017
  out.unverifiable = entry.unverifiable.map(receiptUnverifiable).filter(Boolean)
1496
2018
  }
2019
+ if (Array.isArray(entry.notChecked) && entry.notChecked.length) {
2020
+ out.notChecked = entry.notChecked.map(receiptNotChecked).filter(Boolean)
2021
+ }
1497
2022
  return out
1498
2023
  }
1499
2024
 
1500
2025
  function normalizeReceiptEvidence(evidence) {
1501
- const meta = { format: MANIFEST_FORMAT, version: MANIFEST_VERSION }
2026
+ const meta = { format: MANIFEST_FORMAT, version: MANIFEST_VERSION, versionDeclared: false, verificationBasis: null }
1502
2027
  let list = []
1503
2028
  // Additive (0.2.5 A-1): the evidence pack reports how many requested rows it
1504
2029
  // withheld because their own matter is protected; the receipt summary carries
@@ -1520,7 +2045,11 @@ function normalizeReceiptEvidence(evidence) {
1520
2045
  } else if (typeof evidence === 'object') {
1521
2046
  if (evidence.summary && Array.isArray(evidence.summary.entries)) {
1522
2047
  if (typeof evidence.summary.format === 'string') meta.format = evidence.summary.format
1523
- if (Number.isInteger(evidence.summary.version)) meta.version = evidence.summary.version
2048
+ if (Number.isInteger(evidence.summary.version)) {
2049
+ meta.version = evidence.summary.version
2050
+ meta.versionDeclared = true
2051
+ }
2052
+ if (typeof evidence.summary.verificationBasis === 'string') meta.verificationBasis = evidence.summary.verificationBasis
1524
2053
  readProtectedExcluded(evidence.summary)
1525
2054
  list = evidence.summary.entries
1526
2055
  } else if (Array.isArray(evidence.entries)) {
@@ -1532,7 +2061,11 @@ function normalizeReceiptEvidence(evidence) {
1532
2061
  const parsed = JSON.parse(manifestText)
1533
2062
  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
1534
2063
  if (typeof parsed.format === 'string') meta.format = parsed.format
1535
- if (Number.isInteger(parsed.version)) meta.version = parsed.version
2064
+ if (Number.isInteger(parsed.version)) {
2065
+ meta.version = parsed.version
2066
+ meta.versionDeclared = true
2067
+ }
2068
+ if (typeof parsed.verificationBasis === 'string') meta.verificationBasis = parsed.verificationBasis
1536
2069
  list = Array.isArray(parsed.entries) ? parsed.entries : []
1537
2070
  }
1538
2071
  } catch {
@@ -1543,11 +2076,24 @@ function normalizeReceiptEvidence(evidence) {
1543
2076
  }
1544
2077
  const entries = list.map(receiptEvidenceEntry).filter(Boolean)
1545
2078
  entries.sort(compareEntries)
2079
+ if (!meta.versionDeclared) {
2080
+ // A caller passed raw v1-era entries (no version marker): keep claiming v1 so
2081
+ // the historical receipt shape and validation stay byte-compatible.
2082
+ const looksV1 = entries.some(
2083
+ (entry) =>
2084
+ entry.sources.some((source) => !('kind' in source)) ||
2085
+ entry.missing.some((item) => !('kind' in item)) ||
2086
+ (entry.unverifiable ?? []).some((item) => !('kind' in item)),
2087
+ )
2088
+ if (looksV1) meta.version = 1
2089
+ }
1546
2090
  const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
1547
2091
  let sourceCount = 0
1548
2092
  let missingCount = 0
1549
2093
  let unverifiableCount = 0
1550
2094
  let operatorEnteredCount = 0
2095
+ let notCheckedCount = 0
2096
+ const flat = { sources: [], missing: [], unverifiable: [], notChecked: [] }
1551
2097
  for (const entry of entries) {
1552
2098
  counts[entry.kind] = (counts[entry.kind] || 0) + 1
1553
2099
  sourceCount += entry.sources.length
@@ -1555,8 +2101,13 @@ function normalizeReceiptEvidence(evidence) {
1555
2101
  const manual = entry.unverifiable ?? []
1556
2102
  unverifiableCount += manual.length
1557
2103
  operatorEnteredCount += manual.filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
2104
+ notCheckedCount += (entry.notChecked ?? []).length
2105
+ flat.sources.push(...entry.sources)
2106
+ flat.missing.push(...entry.missing)
2107
+ flat.unverifiable.push(...manual)
2108
+ flat.notChecked.push(...(entry.notChecked ?? []))
1558
2109
  }
1559
- return {
2110
+ const base = {
1560
2111
  format: meta.format,
1561
2112
  version: meta.version,
1562
2113
  entryCount: entries.length,
@@ -1568,6 +2119,14 @@ function normalizeReceiptEvidence(evidence) {
1568
2119
  protectedExcluded,
1569
2120
  entries,
1570
2121
  }
2122
+ if (meta.version >= 2) {
2123
+ // Evidence pack v2: taxonomy + honest verification basis. v1 receipt packs
2124
+ // keep the exact historical evidence object (no new keys).
2125
+ base.notCheckedCount = notCheckedCount
2126
+ base.byKind = evidenceByKind(flat)
2127
+ base.verificationBasis = VERIFICATION_BASES.includes(meta.verificationBasis) ? meta.verificationBasis : VERIFICATION_BASIS
2128
+ }
2129
+ return base
1571
2130
  }
1572
2131
 
1573
2132
  // --- verify results ---------------------------------------------------------
@@ -2039,8 +2598,10 @@ function receiptDocxSpec(input) {
2039
2598
  heading: '证据摘要',
2040
2599
  paragraphs: [
2041
2600
  '证据条目:' + evidence.entryCount + '(commitment ' + evidence.counts.commitment + ' / fact ' + evidence.counts.fact + ' / preference ' + evidence.counts.preference + ' / unknown ' + evidence.counts.unknown + ')',
2042
- '已解析来源:' + evidence.sourceCount + ';缺失来源:' + evidence.missingCount,
2043
- ...(evidence.unverifiableCount ? ['未外部核验(操作者录入):' + evidence.unverifiableCount + ' 条(不是缺失;请勿当作已核验证据)'] : []),
2601
+ '构建时已核验来源:' + evidence.sourceCount + ';缺失来源:' + evidence.missingCount,
2602
+ ...(evidence.unverifiableCount ? ['不可本地核验:' + evidence.unverifiableCount + ' 条(manual/邮件正文未保留/网页未缓存;不是缺失;请勿当作已核验证据)'] : []),
2603
+ ...(evidence.notCheckedCount ? ['本次未核验(not_checked):' + evidence.notCheckedCount + ' 条'] : []),
2604
+ ...(evidence.verificationBasis ? ['核验基准:' + evidence.verificationBasis + '(离线校验只证明包内自洽,不能重放对话)'] : []),
2044
2605
  '完整证据条目(session#turn 引用与截断引用原话)见 manifest.json 的 evidence 字段。',
2045
2606
  ],
2046
2607
  })
@@ -2117,7 +2678,9 @@ function buildReceiptReadme(input) {
2117
2678
  'SHA256SUMS sha256 of every other file in this pack',
2118
2679
  '',
2119
2680
  'Evidence entries: ' + evidence.entryCount + ' (sources ' + evidence.sourceCount + ', missing ' + evidence.missingCount + ')',
2120
- ...(evidence.unverifiableCount ? ['unverifiable: ' + evidence.unverifiableCount + ' (operator-entered; not externally verified, NOT missing)'] : []),
2681
+ ...(evidence.unverifiableCount ? ['unverifiable: ' + evidence.unverifiableCount + ' (manual/mail-body-purged/web-not-cached; not externally verified, NOT missing)'] : []),
2682
+ ...(evidence.notCheckedCount ? ['not checked: ' + evidence.notCheckedCount + ' (no local lookup capability supplied for this run)'] : []),
2683
+ ...(evidence.verificationBasis ? ['verification basis: ' + evidence.verificationBasis + ' (offline verification proves pack consistency only; it cannot replay turns)'] : []),
2121
2684
  '(references and capped quotes only; see manifest.json evidence.entries)',
2122
2685
  '',
2123
2686
  'Verify (offline, no ~/.advisers database needed)',
@@ -2399,6 +2962,14 @@ export async function buildReceiptPack(options = {}) {
2399
2962
  unverifiableCount: evidence.unverifiableCount ?? 0,
2400
2963
  operatorEnteredCount: evidence.operatorEnteredCount ?? 0,
2401
2964
  protectedExcluded: Number.isInteger(evidence.protectedExcluded) ? evidence.protectedExcluded : 0,
2965
+ // Evidence pack v2 only; v1 callers keep the historical aggregate shape.
2966
+ ...(evidence.version >= 2
2967
+ ? {
2968
+ notCheckedCount: evidence.notCheckedCount ?? 0,
2969
+ byKind: evidence.byKind ?? emptyByKind(),
2970
+ verificationBasis: evidence.verificationBasis ?? VERIFICATION_BASIS,
2971
+ }
2972
+ : {}),
2402
2973
  },
2403
2974
  anchored: anchors.length > 0,
2404
2975
  fileMode: RECEIPT_FILE_MODE,
@@ -2487,7 +3058,8 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
2487
3058
  const sources = Array.isArray(entry.sources) ? entry.sources : []
2488
3059
  const missing = Array.isArray(entry.missing) ? entry.missing : []
2489
3060
  const unverifiable = Array.isArray(entry.unverifiable) ? entry.unverifiable : []
2490
- if (!sources.length && !missing.length && !unverifiable.length) {
3061
+ const notChecked = Array.isArray(entry.notChecked) ? entry.notChecked : []
3062
+ if (!sources.length && !missing.length && !unverifiable.length && !notChecked.length) {
2491
3063
  rows.push([kind, id, '', '', entry.found === false ? '记录不存在' : '无证据'])
2492
3064
  continue
2493
3065
  }
@@ -2510,12 +3082,24 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
2510
3082
  ])
2511
3083
  }
2512
3084
  for (const item of unverifiable) {
3085
+ const isManual = item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND
3086
+ rows.push([
3087
+ kind,
3088
+ id,
3089
+ item.ref || formatRef(item.sessionId, item.turnId) || '',
3090
+ clampQuote(item.quote).quote,
3091
+ isManual
3092
+ ? MANUAL_SOURCE_KIND + ': operator-entered (unverifiable, not missing)'
3093
+ : 'unverifiable: ' + (item.type ?? 'unknown') + ' (' + (item.reason ?? MANUAL_REASON) + ', not missing)',
3094
+ ])
3095
+ }
3096
+ for (const item of notChecked) {
2513
3097
  rows.push([
2514
3098
  kind,
2515
3099
  id,
2516
- '',
3100
+ item.ref || formatRef(item.sessionId, item.turnId) || '',
2517
3101
  clampQuote(item.quote).quote,
2518
- MANUAL_SOURCE_KIND + ': operator-entered (unverifiable, not missing)',
3102
+ 'not_checked: ' + (item.type ?? 'unknown') + ' (' + (item.reason ?? 'not_checked') + ')',
2519
3103
  ])
2520
3104
  }
2521
3105
  }