advisers 0.3.1 → 0.4.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 (48) hide show
  1. package/README-zh.md +13 -15
  2. package/README.md +32 -22
  3. package/THIRD-PARTY-NOTICES.md +1 -1
  4. package/bin/advisers.js +2769 -183
  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/customer-read.js +524 -0
  11. package/lib/error-codes.js +516 -7
  12. package/lib/evidence.js +928 -120
  13. package/lib/kb-extract.js +626 -0
  14. package/lib/kb-facts.js +429 -0
  15. package/lib/kb-pages.js +1084 -0
  16. package/lib/kb.js +1036 -0
  17. package/lib/ledger-read.js +109 -1
  18. package/lib/mail-errors.js +46 -0
  19. package/lib/mail-extract.js +351 -0
  20. package/lib/mail-imap.js +446 -0
  21. package/lib/mail-import.js +176 -0
  22. package/lib/mail-parse.js +223 -0
  23. package/lib/mail-store.js +731 -0
  24. package/lib/mail.js +506 -0
  25. package/lib/mcp-server.js +397 -11
  26. package/lib/notify.js +265 -7
  27. package/lib/policy/decision.js +315 -0
  28. package/lib/policy/egress.js +268 -0
  29. package/lib/policy/errors.js +71 -0
  30. package/lib/policy/index.js +99 -0
  31. package/lib/policy/rules.js +468 -0
  32. package/lib/policy/surfaces.js +141 -0
  33. package/lib/receipt-verify.js +283 -26
  34. package/lib/receivables.js +1653 -0
  35. package/lib/scheduler.js +453 -9
  36. package/lib/shell.js +1406 -0
  37. package/lib/source.js +98 -3
  38. package/lib/sqlite.js +501 -49
  39. package/lib/tos/index.js +2 -2
  40. package/lib/tos/manifest.json +6 -6
  41. package/lib/tos/privacy.zh-CN.md +33 -20
  42. package/lib/tos/safety.zh-CN.md +7 -6
  43. package/lib/tos/summary.zh-CN.md +3 -2
  44. package/lib/tos/terms.zh-CN.md +31 -16
  45. package/lib/tui/labels.js +1 -1
  46. package/lib/tui/render.js +1 -1
  47. package/lib/urgency.js +467 -0
  48. package/package.json +4 -4
package/lib/evidence.js CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * E3: evidence chain, evidence pack (v1) and delivery receipt pack (v1.1).
2
+ * E3: evidence chain, evidence pack (v1) and delivery receipt pack
3
+ * (v1.1 / manifest v2).
3
4
  *
4
5
  * Every ledger row that claims something about the world must point back to the
5
6
  * conversation turn it came from. This module walks those pointers (a turn is
@@ -51,11 +52,20 @@ import {
51
52
  import { dirname, join, resolve } from 'node:path'
52
53
 
53
54
  import { secrecyLevel } from './egress.js'
55
+ import { canonicalSourceType, describeSourcePointer } from './source.js'
54
56
 
55
57
  /** Quotes are verbatim evidence but capped, so a pack never carries a full body. */
56
58
  export const MAX_QUOTE_CHARS = 500
57
59
  export const MANIFEST_FORMAT = 'advisers-evidence-pack'
58
- 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])
59
69
  /**
60
70
  * Default cap for the "pack everything" path (0.2.0 performance audit P0-3).
61
71
  * A pack built from every row in a large ledger is slow and huge; callers must
@@ -533,103 +543,495 @@ function resolvePointerTurn(store, sessionId, turnId, quote) {
533
543
  return { source: { sessionId: normalizedSessionId, turnId, quote, turn: lookup.turn } }
534
544
  }
535
545
 
536
- function resolveSourceRefs(store, items) {
537
- const sources = []
538
- const missing = []
539
- const unverifiable = []
540
- for (const item of items) {
541
- if (!item || typeof item !== 'object' || Array.isArray(item)) {
542
- missing.push({ reason: 'invalid_source' })
543
- continue
544
- }
545
- if (isManualEvidence(item)) {
546
- unverifiable.push(manualEvidenceSource(item))
547
- continue
548
- }
549
- const quote = typeof item.quote === 'string' ? item.quote : ''
550
- const ref = typeof item.ref === 'string' ? item.ref : ''
551
- if (!ref) {
552
- missing.push({ quote, reason: 'no_ref' })
553
- 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' }
554
671
  }
555
- const parsed = parseSourceRef(ref)
556
- if (!parsed) {
557
- missing.push({ ref, quote, reason: 'unparseable_ref' })
558
- continue
672
+ }
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' }
559
680
  }
560
- const resolved = resolvePointerTurn(store, parsed.sessionId, parsed.turnId, quote)
561
- if (resolved.missing) {
562
- missing.push({ ref, ...resolved.missing })
563
- continue
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
564
700
  }
565
- sources.push(resolved.source)
566
701
  }
567
- return { sources, missing, unverifiable }
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
+ }
568
765
  }
569
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
+
570
879
  /**
571
- * Trace a commitment's evidence back to real turns.
880
+ * Resolve one evidence item to its four-state resolution.
881
+ *
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.
572
887
  *
573
- * @returns {{ commitment: object|undefined,
574
- * sources: Array<{sessionId: string, turnId: string, quote: string, turn: object}>,
575
- * missing: Array<{sessionId?: string, turnId?: string, quote?: string, id?: string, reason: string}> }}
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}}
576
893
  */
577
- export function evidenceForCommitment(store, ledger, commitmentId, index) {
578
- const commitment = findCommitment(ledger, commitmentId, index)
579
- if (!commitment) {
580
- 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,
581
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
+ }
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) {
582
945
  const sources = []
583
946
  const missing = []
584
947
  const unverifiable = []
585
- const evidence = Array.isArray(commitment.evidence) ? commitment.evidence : []
586
- for (const item of evidence) {
587
- if (isManualEvidence(item)) {
588
- unverifiable.push(manualEvidenceSource(item))
589
- continue
590
- }
591
- const sessionId = typeof item?.sessionId === 'string' ? item.sessionId : ''
592
- const turnId = typeof item?.turnId === 'string' ? item.turnId : ''
593
- const quote = typeof item?.quote === 'string' ? item.quote : ''
594
- if (!sessionId || !turnId) {
595
- missing.push({
596
- sessionId: sessionId || undefined,
597
- turnId: turnId || undefined,
598
- quote,
599
- reason: 'invalid_evidence',
600
- })
601
- continue
602
- }
603
- const resolved = resolvePointerTurn(store, sessionId, turnId, quote)
604
- if (resolved.missing) {
605
- missing.push(resolved.missing)
606
- 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
607
976
  }
608
- sources.push(resolved.source)
609
977
  }
610
- 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
+ }
611
989
  }
612
990
 
613
- /** Trace a fact's `SourceRef[]` (plus its primary `source`) back to turns. */
614
- export function evidenceForFact(store, ledger, factId, index) {
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) }
1011
+ }
1012
+
1013
+ /** Trace a fact's `SourceRef[]` (plus its primary `source`) back to its sources. */
1014
+ export function evidenceForFact(store, ledger, factId, index, options = {}) {
615
1015
  const fact = findFact(ledger, factId, index)
616
1016
  if (!fact) {
617
- 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) }
618
1019
  }
619
- const refs = collectSourceRefs(fact.evidence, primarySourceCandidates(fact.source))
620
- const resolved = resolveSourceRefs(store, refs)
621
- 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) }
622
1023
  }
623
1024
 
624
- /** Trace a preference's `SourceRef[]` (plus its primary `source`) back to turns. */
625
- 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 = {}) {
626
1027
  const preference = findPreference(ledger, preferenceId, index)
627
1028
  if (!preference) {
628
- 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) }
629
1031
  }
630
- const refs = collectSourceRefs(preference.evidence, primarySourceCandidates(preference.source))
631
- const resolved = resolveSourceRefs(store, refs)
632
- 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) }
633
1035
  }
634
1036
 
635
1037
  // ---------------------------------------------------------------------------
@@ -649,16 +1051,36 @@ function compareEntries(a, b) {
649
1051
  *
650
1052
  * @returns {string} canonical JSON text with a trailing newline
651
1053
  */
652
- 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 } = {}) {
653
1071
  const list = (Array.isArray(entries) ? entries : [])
654
1072
  .filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry))
655
1073
  .map((entry) => ({ ...entry }))
656
1074
  list.sort(compareEntries)
1075
+ const tallied = tallyCompacted(list)
657
1076
  return `${stableStringify({
658
1077
  format: MANIFEST_FORMAT,
659
1078
  version: MANIFEST_VERSION,
660
1079
  createdAt: isoDate(createdAt),
661
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,
662
1084
  entries: list,
663
1085
  })}\n`
664
1086
  }
@@ -682,43 +1104,89 @@ function formatRef(sessionId, turnId) {
682
1104
  return parts.join('#')
683
1105
  }
684
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
+
685
1119
  function compactSource(source) {
686
- const clamped = clampQuote(source?.quote)
1120
+ const clamped = clampStoredQuote(source)
687
1121
  const entry = {
688
- sessionId: typeof source?.sessionId === 'string' ? source.sessionId : '',
689
- 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,
690
1126
  ...clamped,
691
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
692
1130
  // Turn sequence/role are provenance metadata, not body text.
693
1131
  if (Number.isInteger(source?.turn?.seq)) entry.turnSeq = source.turn.seq
694
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
+ }
695
1142
  return entry
696
1143
  }
697
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
+
698
1165
  function compactMissing(item) {
699
1166
  const out = { reason: typeof item?.reason === 'string' ? item.reason : 'unknown' }
700
- 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]) {
701
1172
  if (typeof item?.[key] === 'string' && item[key]) out[key] = item[key]
702
1173
  }
703
- 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))
704
1175
  return out
705
1176
  }
706
1177
 
707
1178
  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)
1179
+ const out = compactTypedItem(item, { resolution: MANUAL_RESOLUTION, fallbackReason: MANUAL_REASON })
716
1180
  for (const key of ['capturedAt', 'capturedBy', 'command']) {
717
1181
  if (typeof item?.[key] === 'string' && item[key]) out[key] = item[key]
718
1182
  }
719
1183
  return out
720
1184
  }
721
1185
 
1186
+ function compactNotChecked(item) {
1187
+ return compactTypedItem(item, { resolution: 'not_checked', fallbackReason: 'not_checked' })
1188
+ }
1189
+
722
1190
  function compactEntry(entry) {
723
1191
  const out = {
724
1192
  kind: typeof entry.kind === 'string' ? entry.kind : 'unknown',
@@ -732,6 +1200,9 @@ function compactEntry(entry) {
732
1200
  if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
733
1201
  out.unverifiable = entry.unverifiable.map(compactUnverifiable)
734
1202
  }
1203
+ if (Array.isArray(entry.notChecked) && entry.notChecked.length) {
1204
+ out.notChecked = entry.notChecked.map(compactNotChecked)
1205
+ }
735
1206
  return out
736
1207
  }
737
1208
 
@@ -800,19 +1271,23 @@ function normalizeRequestedIds(ids, ledger, index) {
800
1271
  return out
801
1272
  }
802
1273
 
803
- function buildReadme({ createdAt, entries, manifestDigest }) {
1274
+ function buildReadme({ createdAt, entries, manifestDigest, byKind, notCheckedCount }) {
804
1275
  const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
805
1276
  let sourceCount = 0
806
1277
  let missingCount = 0
807
1278
  let unverifiableCount = 0
1279
+ let manualCount = 0
808
1280
  let truncatedCount = 0
809
1281
  for (const entry of entries) {
810
1282
  counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
811
1283
  sourceCount += entry.sources.length
812
1284
  missingCount += entry.missing.length
813
1285
  unverifiableCount += (entry.unverifiable ?? []).length
1286
+ manualCount += (entry.unverifiable ?? []).filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
814
1287
  truncatedCount += entry.sources.filter((source) => source.truncated).length
815
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
816
1291
  const lines = [
817
1292
  'Advisers evidence pack',
818
1293
  '======================',
@@ -820,7 +1295,10 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
820
1295
  'format: ' + MANIFEST_FORMAT + ' v' + MANIFEST_VERSION,
821
1296
  'created: ' + createdAt,
822
1297
  '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)' : ''),
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',
824
1302
  `quotes: verbatim, at most ${MAX_QUOTE_CHARS} characters each; ${truncatedCount} truncated`,
825
1303
  '',
826
1304
  'Files',
@@ -846,7 +1324,13 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
846
1324
  `- ${entry.kind} ${entry.id} sources=${entry.sources.length} missing=${entry.missing.length}${manualCount ? ` manual=${manualCount}` : ''}${entry.found ? '' : ' (record not found)'}`,
847
1325
  )
848
1326
  for (const item of (entry.unverifiable ?? []).slice(0, README_REF_CAP)) {
849
- 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`)
850
1334
  }
851
1335
  const refs = entry.sources.slice(0, README_REF_CAP)
852
1336
  for (const source of refs) {
@@ -904,6 +1388,11 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
904
1388
  * a record above `clearance`: omit it and count it (`exclude`, the bulk
905
1389
  * default), or throw `ProtectedEvidenceError` (`error`, used when the
906
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.
907
1396
  * @returns {{ files: Record<string, string>, summary: object }}
908
1397
  * files: `{ 'manifest.json': string, 'README.txt': string, 'SHA256SUMS': string }`
909
1398
  */
@@ -916,6 +1405,7 @@ export function buildEvidencePack({
916
1405
  all = false,
917
1406
  clearance = null,
918
1407
  protectedPolicy = 'exclude',
1408
+ lookups,
919
1409
  } = {}) {
920
1410
  if (!ledger || typeof ledger !== 'object') throw new TypeError('buildEvidencePack requires a ledger')
921
1411
  if (!store || typeof store !== 'object') throw new TypeError('buildEvidencePack requires a store')
@@ -963,7 +1453,7 @@ export function buildEvidencePack({
963
1453
  for (const id of requested.commitments) {
964
1454
  const commitment = findCommitment(ledger, id, index)
965
1455
  if (blockedByClearance('commitment', commitment)) continue
966
- const result = evidenceForCommitment(store, ledger, id, index)
1456
+ const result = evidenceForCommitment(store, ledger, id, index, { lookup: lookups })
967
1457
  entries.push({
968
1458
  kind: 'commitment',
969
1459
  id,
@@ -971,18 +1461,19 @@ export function buildEvidencePack({
971
1461
  sources: result.sources,
972
1462
  missing: result.missing,
973
1463
  unverifiable: result.unverifiable,
1464
+ notChecked: result.notChecked,
974
1465
  })
975
1466
  }
976
1467
  for (const id of requested.facts) {
977
1468
  const fact = findFact(ledger, id, index)
978
1469
  if (blockedByClearance('fact', fact)) continue
979
- const result = evidenceForFact(store, ledger, id, index)
980
- 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 })
981
1472
  }
982
1473
  for (const id of requested.preferences) {
983
1474
  const preference = findPreference(ledger, id, index)
984
1475
  if (blockedByClearance('preference', preference)) continue
985
- const result = evidenceForPreference(store, ledger, id, index)
1476
+ const result = evidenceForPreference(store, ledger, id, index, { lookup: lookups })
986
1477
  entries.push({
987
1478
  kind: 'preference',
988
1479
  id,
@@ -990,10 +1481,11 @@ export function buildEvidencePack({
990
1481
  sources: result.sources,
991
1482
  missing: result.missing,
992
1483
  unverifiable: result.unverifiable,
1484
+ notChecked: result.notChecked,
993
1485
  })
994
1486
  }
995
1487
  for (const id of requested.unknown) {
996
- 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' }] })
997
1489
  }
998
1490
  if (protectedIds.length) throw new ProtectedEvidenceError(protectedIds.length, clearanceValue)
999
1491
 
@@ -1001,9 +1493,10 @@ export function buildEvidencePack({
1001
1493
  .map(compactEntry)
1002
1494
  .sort(compareEntries)
1003
1495
 
1004
- 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 })
1005
1498
  const manifestDigest = sha256Hex(manifestJson)
1006
- const readme = buildReadme({ createdAt, entries: compacted, manifestDigest })
1499
+ const readme = buildReadme({ createdAt, entries: compacted, manifestDigest, byKind: tallied.byKind, notCheckedCount: tallied.notCheckedCount })
1007
1500
  const readmeDigest = sha256Hex(readme)
1008
1501
  const sums = [`${readmeDigest} README.txt`, `${manifestDigest} manifest.json`].join('\n') + '\n'
1009
1502
 
@@ -1012,14 +1505,16 @@ export function buildEvidencePack({
1012
1505
  let missingCount = 0
1013
1506
  let unverifiableCount = 0
1014
1507
  let operatorEnteredCount = 0
1508
+ let notCheckedCount = 0
1015
1509
  let truncatedCount = 0
1016
1510
  for (const entry of compacted) {
1017
1511
  counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
1018
1512
  sourceCount += entry.sources.length
1019
1513
  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
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
1023
1518
  truncatedCount += entry.sources.filter((source) => source.truncated).length
1024
1519
  }
1025
1520
 
@@ -1039,6 +1534,9 @@ export function buildEvidencePack({
1039
1534
  missingCount,
1040
1535
  unverifiableCount,
1041
1536
  operatorEnteredCount,
1537
+ notCheckedCount,
1538
+ byKind: tallied.byKind,
1539
+ verificationBasis: VERIFICATION_BASIS,
1042
1540
  truncatedCount,
1043
1541
  // Additive (0.2.5 A-1): how many requested rows were withheld because
1044
1542
  // their own matter is protected. Counts only — never a title or quote.
@@ -1141,7 +1639,7 @@ export function verifyPack(files) {
1141
1639
  }
1142
1640
 
1143
1641
  // ---------------------------------------------------------------------------
1144
- // delivery receipt pack v1.1
1642
+ // delivery receipt pack v1.1 / manifest v2
1145
1643
  //
1146
1644
  // Competitive report 21-w2-delivery-trust.md §2.2 and hardening
1147
1645
  // 13-gap-inventory.md P1-2: the evidence pack above is an evidence pack; a
@@ -1155,7 +1653,20 @@ export function verifyPack(files) {
1155
1653
  // ---------------------------------------------------------------------------
1156
1654
 
1157
1655
  export const RECEIPT_MANIFEST_FORMAT = 'advisers-delivery-receipt-pack'
1158
- export const RECEIPT_MANIFEST_VERSION = 1
1656
+ /**
1657
+ * Current manifest version written by buildReceiptPack. v2 adds the optional
1658
+ * top-level `subject` and the mandatory `scope`, plus optional row-level
1659
+ * lineage (`clientId`/`projectId`/`matterId`/`template`). v1 packs stay
1660
+ * verifiable: lib/receipt-verify.js accepts every version in
1661
+ * RECEIPT_MANIFEST_VERSIONS.
1662
+ */
1663
+ export const RECEIPT_MANIFEST_VERSION = 2
1664
+ /** Manifest versions the offline verifier accepts (v1 packs must keep verifying). */
1665
+ export const RECEIPT_MANIFEST_VERSIONS = Object.freeze([1, 2])
1666
+ /** Allowed manifest.subject.kind values (manifest v2). */
1667
+ export const RECEIPT_SUBJECT_KINDS = Object.freeze(['client', 'project', 'matter', 'none'])
1668
+ /** Allowed manifest.scope values (manifest v2). */
1669
+ export const RECEIPT_SCOPES = Object.freeze(['subject', 'local-all'])
1159
1670
  export const RECEIPT_SHA256SUMS_FILE = 'SHA256SUMS'
1160
1671
  /** Files every receipt pack must carry; SHA256SUMS covers all of them. */
1161
1672
  export const RECEIPT_REQUIRED_FILES = Object.freeze(['manifest.json', 'README.txt', 'receipt.docx'])
@@ -1292,6 +1803,65 @@ function normalizeDeliveryFile(file, deliveryId, fileIndex) {
1292
1803
  throw new TypeError('delivery ' + deliveryId + ' file #' + (fileIndex + 1) + ' must be a path string or an object')
1293
1804
  }
1294
1805
 
1806
+ // --- optional row-level lineage (manifest v2) --------------------------------
1807
+
1808
+ /**
1809
+ * Validate one optional delivery lineage id. Empty/null means "not recorded"
1810
+ * and keeps the v1 manifest shape (the key is not written at all).
1811
+ */
1812
+ function receiptLineageId(value, deliveryId, field) {
1813
+ if (value === undefined || value === null || value === '') return null
1814
+ if (typeof value !== 'string') {
1815
+ throw new TypeError('delivery ' + deliveryId + ' ' + field + ' must be a non-empty string')
1816
+ }
1817
+ const text = value.trim()
1818
+ if (!text) throw new TypeError('delivery ' + deliveryId + ' ' + field + ' must be a non-empty string')
1819
+ return text
1820
+ }
1821
+
1822
+ function receiptLineageString(value, deliveryId, field) {
1823
+ if (value === undefined || value === null || value === '') return null
1824
+ if (typeof value !== 'string' || !value.trim()) {
1825
+ throw new TypeError('delivery ' + deliveryId + ' ' + field + ' must be a non-empty string')
1826
+ }
1827
+ return value.trim()
1828
+ }
1829
+
1830
+ /**
1831
+ * Row-level template lineage: flat templateName/templateVersion/quoteNo/
1832
+ * dataSha256 inputs become one manifest.deliveries[].template object. Nothing is
1833
+ * written when the row carries none of them. name+version identify a template,
1834
+ * so a partial pair is rejected instead of silently recorded.
1835
+ */
1836
+ function receiptDeliveryTemplate(delivery, deliveryId) {
1837
+ const anyPresent = ['templateName', 'templateVersion', 'quoteNo', 'dataSha256'].some(
1838
+ (key) => delivery[key] !== undefined && delivery[key] !== null && delivery[key] !== '',
1839
+ )
1840
+ if (!anyPresent) return null
1841
+ const name = receiptLineageString(delivery.templateName, deliveryId, 'templateName')
1842
+ const version = receiptLineageString(delivery.templateVersion, deliveryId, 'templateVersion')
1843
+ if (name === null || version === null) {
1844
+ throw new TypeError(
1845
+ 'delivery ' + deliveryId + ' template lineage requires both templateName and templateVersion' +
1846
+ ' (quoteNo/dataSha256 are additional and optional)',
1847
+ )
1848
+ }
1849
+ const template = { name, version }
1850
+ const quoteNo = receiptLineageString(delivery.quoteNo, deliveryId, 'quoteNo')
1851
+ if (quoteNo !== null) template.quoteNo = quoteNo
1852
+ if (delivery.dataSha256 !== undefined && delivery.dataSha256 !== null && delivery.dataSha256 !== '') {
1853
+ if (typeof delivery.dataSha256 !== 'string') {
1854
+ throw new TypeError('delivery ' + deliveryId + ' dataSha256 must be 64 lowercase hex characters')
1855
+ }
1856
+ const dataSha256 = delivery.dataSha256.trim().toLowerCase()
1857
+ if (!isSha256Hex(dataSha256)) {
1858
+ throw new TypeError('delivery ' + deliveryId + ' dataSha256 must be 64 lowercase hex characters')
1859
+ }
1860
+ template.dataSha256 = dataSha256
1861
+ }
1862
+ return template
1863
+ }
1864
+
1295
1865
  function normalizeReceiptDeliveries(deliveries) {
1296
1866
  const input = Array.isArray(deliveries) ? deliveries : deliveries ? [deliveries] : []
1297
1867
  if (!input.length) {
@@ -1341,6 +1911,11 @@ function normalizeReceiptDeliveries(deliveries) {
1341
1911
  tool: receiptText(delivery.tool),
1342
1912
  createdAt: receiptDateText(delivery.createdAt !== undefined ? delivery.createdAt : delivery.created_at, null),
1343
1913
  validation,
1914
+ // Manifest v2 lineage: null means "not recorded" and is never written.
1915
+ clientId: receiptLineageId(delivery.clientId, id, 'clientId'),
1916
+ projectId: receiptLineageId(delivery.projectId, id, 'projectId'),
1917
+ matterId: receiptLineageId(delivery.matterId, id, 'matterId'),
1918
+ template: receiptDeliveryTemplate(delivery, id),
1344
1919
  files,
1345
1920
  }
1346
1921
  })
@@ -1349,11 +1924,22 @@ function normalizeReceiptDeliveries(deliveries) {
1349
1924
  // --- evidence entries (re-sanitized: the receipt pack keeps references and
1350
1925
  // --- capped quotes only, never full turn bodies) ---------------------------
1351
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
+
1352
1936
  function receiptSource(source) {
1353
1937
  if (source && typeof source === 'object' && source.turn) return compactSource(source)
1354
1938
  if (!source || typeof source !== 'object' || Array.isArray(source)) {
1355
1939
  return { sessionId: '', turnId: '', quote: '', quoteChars: 0, truncated: false, quoteSha256: sha256Hex('') }
1356
1940
  }
1941
+ if (receiptIsTypedSource(source)) return compactSource(source)
1942
+ // v1 evidence shape: keep the historical receipt bytes exactly.
1357
1943
  const rawQuote = typeof source.quote === 'string' ? source.quote : ''
1358
1944
  const chars = Array.from(rawQuote)
1359
1945
  const quote = chars.length > MAX_QUOTE_CHARS ? chars.slice(0, MAX_QUOTE_CHARS).join('') : rawQuote
@@ -1375,7 +1961,7 @@ function receiptSource(source) {
1375
1961
  function receiptMissing(item) {
1376
1962
  if (!item || typeof item !== 'object' || Array.isArray(item)) return { reason: 'unknown' }
1377
1963
  const out = { reason: typeof item.reason === 'string' ? item.reason : 'unknown' }
1378
- for (const key of ['id', 'ref', 'sessionId', 'turnId']) {
1964
+ for (const key of ['id', 'kind', 'type', 'ref', 'sessionId', 'turnId', 'messageId', 'docId', 'pageId', 'url', 'tool']) {
1379
1965
  if (typeof item[key] === 'string' && item[key]) out[key] = item[key]
1380
1966
  }
1381
1967
  if (typeof item.quote === 'string' && item.quote.length) {
@@ -1391,6 +1977,15 @@ function receiptMissing(item) {
1391
1977
 
1392
1978
  function receiptUnverifiable(item) {
1393
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.
1394
1989
  const out = {
1395
1990
  kind: MANUAL_SOURCE_KIND,
1396
1991
  type: MANUAL_SOURCE_KIND,
@@ -1404,6 +1999,11 @@ function receiptUnverifiable(item) {
1404
1999
  return out
1405
2000
  }
1406
2001
 
2002
+ function receiptNotChecked(item) {
2003
+ if (!item || typeof item !== 'object' || Array.isArray(item)) return null
2004
+ return compactNotChecked(item)
2005
+ }
2006
+
1407
2007
  function receiptEvidenceEntry(entry) {
1408
2008
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null
1409
2009
  const out = {
@@ -1416,11 +2016,14 @@ function receiptEvidenceEntry(entry) {
1416
2016
  if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
1417
2017
  out.unverifiable = entry.unverifiable.map(receiptUnverifiable).filter(Boolean)
1418
2018
  }
2019
+ if (Array.isArray(entry.notChecked) && entry.notChecked.length) {
2020
+ out.notChecked = entry.notChecked.map(receiptNotChecked).filter(Boolean)
2021
+ }
1419
2022
  return out
1420
2023
  }
1421
2024
 
1422
2025
  function normalizeReceiptEvidence(evidence) {
1423
- const meta = { format: MANIFEST_FORMAT, version: MANIFEST_VERSION }
2026
+ const meta = { format: MANIFEST_FORMAT, version: MANIFEST_VERSION, versionDeclared: false, verificationBasis: null }
1424
2027
  let list = []
1425
2028
  // Additive (0.2.5 A-1): the evidence pack reports how many requested rows it
1426
2029
  // withheld because their own matter is protected; the receipt summary carries
@@ -1442,7 +2045,11 @@ function normalizeReceiptEvidence(evidence) {
1442
2045
  } else if (typeof evidence === 'object') {
1443
2046
  if (evidence.summary && Array.isArray(evidence.summary.entries)) {
1444
2047
  if (typeof evidence.summary.format === 'string') meta.format = evidence.summary.format
1445
- 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
1446
2053
  readProtectedExcluded(evidence.summary)
1447
2054
  list = evidence.summary.entries
1448
2055
  } else if (Array.isArray(evidence.entries)) {
@@ -1454,7 +2061,11 @@ function normalizeReceiptEvidence(evidence) {
1454
2061
  const parsed = JSON.parse(manifestText)
1455
2062
  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
1456
2063
  if (typeof parsed.format === 'string') meta.format = parsed.format
1457
- 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
1458
2069
  list = Array.isArray(parsed.entries) ? parsed.entries : []
1459
2070
  }
1460
2071
  } catch {
@@ -1465,11 +2076,24 @@ function normalizeReceiptEvidence(evidence) {
1465
2076
  }
1466
2077
  const entries = list.map(receiptEvidenceEntry).filter(Boolean)
1467
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
+ }
1468
2090
  const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
1469
2091
  let sourceCount = 0
1470
2092
  let missingCount = 0
1471
2093
  let unverifiableCount = 0
1472
2094
  let operatorEnteredCount = 0
2095
+ let notCheckedCount = 0
2096
+ const flat = { sources: [], missing: [], unverifiable: [], notChecked: [] }
1473
2097
  for (const entry of entries) {
1474
2098
  counts[entry.kind] = (counts[entry.kind] || 0) + 1
1475
2099
  sourceCount += entry.sources.length
@@ -1477,8 +2101,13 @@ function normalizeReceiptEvidence(evidence) {
1477
2101
  const manual = entry.unverifiable ?? []
1478
2102
  unverifiableCount += manual.length
1479
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 ?? []))
1480
2109
  }
1481
- return {
2110
+ const base = {
1482
2111
  format: meta.format,
1483
2112
  version: meta.version,
1484
2113
  entryCount: entries.length,
@@ -1490,6 +2119,14 @@ function normalizeReceiptEvidence(evidence) {
1490
2119
  protectedExcluded,
1491
2120
  entries,
1492
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
1493
2130
  }
1494
2131
 
1495
2132
  // --- verify results ---------------------------------------------------------
@@ -1622,6 +2259,73 @@ function normalizeReceiptAnchors(anchors) {
1622
2259
  })
1623
2260
  }
1624
2261
 
2262
+ // --- subject / scope (manifest v2) ------------------------------------------
2263
+
2264
+ /**
2265
+ * Normalize the optional manifest.subject.
2266
+ *
2267
+ * `{kind:'client'|'project'|'matter', id?, name?}` needs at least one of
2268
+ * id/name; `{kind:'none'}` explicitly declares "no single subject" and must
2269
+ * not carry id/name. Unknown kinds, wrong types and empty strings fail closed
2270
+ * (returning `null` would silently drop a claim the caller asked to record).
2271
+ *
2272
+ * @returns {{kind: string, id?: string, name?: string}|null}
2273
+ */
2274
+ function normalizeReceiptSubject(subject) {
2275
+ if (subject === undefined || subject === null || subject === '') return null
2276
+ if (typeof subject !== 'object' || Array.isArray(subject)) {
2277
+ throw new TypeError('subject must be an object {kind, id?, name?}')
2278
+ }
2279
+ if (!RECEIPT_SUBJECT_KINDS.includes(subject.kind)) {
2280
+ throw new TypeError(
2281
+ 'subject.kind must be one of ' + RECEIPT_SUBJECT_KINDS.map((kind) => "'" + kind + "'").join(', '),
2282
+ )
2283
+ }
2284
+ const subjectField = (value, field) => {
2285
+ if (value === undefined || value === null || value === '') return null
2286
+ if (typeof value !== 'string' || !value.trim()) {
2287
+ throw new TypeError('subject.' + field + ' must be a non-empty string')
2288
+ }
2289
+ return value.trim()
2290
+ }
2291
+ const id = subjectField(subject.id, 'id')
2292
+ const name = subjectField(subject.name, 'name')
2293
+ if (subject.kind === 'none') {
2294
+ if (id !== null || name !== null) throw new TypeError("subject.kind 'none' must not carry id or name")
2295
+ return { kind: 'none' }
2296
+ }
2297
+ if (id === null && name === null) {
2298
+ throw new TypeError("subject.kind '" + subject.kind + "' requires subject.id or subject.name")
2299
+ }
2300
+ const out = { kind: subject.kind }
2301
+ if (id !== null) out.id = id
2302
+ if (name !== null) out.name = name
2303
+ return out
2304
+ }
2305
+
2306
+ /**
2307
+ * Normalize manifest scope (v2 mandatory field).
2308
+ *
2309
+ * Default: a subject with kind client/project/matter means 'subject'; no
2310
+ * subject (or `{kind:'none'}`) means 'local-all'. Contradictory explicit
2311
+ * combinations fail closed instead of producing a pack whose warning lies.
2312
+ */
2313
+ function normalizeReceiptScope(scope, subject) {
2314
+ if (scope === undefined || scope === null || scope === '') {
2315
+ return subject && subject.kind !== 'none' ? 'subject' : 'local-all'
2316
+ }
2317
+ if (scope !== 'subject' && scope !== 'local-all') {
2318
+ throw new TypeError("scope must be 'subject' or 'local-all'")
2319
+ }
2320
+ if (scope === 'subject' && (!subject || subject.kind === 'none')) {
2321
+ throw new TypeError("scope 'subject' requires a subject with kind 'client', 'project' or 'matter'")
2322
+ }
2323
+ if (scope === 'local-all' && subject && subject.kind !== 'none') {
2324
+ throw new TypeError("scope 'local-all' cannot carry a subject with kind 'client', 'project' or 'matter'")
2325
+ }
2326
+ return scope
2327
+ }
2328
+
1625
2329
  // --- minimal deterministic DOCX writer (fallback when advisers-office is not
1626
2330
  // --- installed; a DOCX is a ZIP with [Content_Types].xml + word/document.xml) ----
1627
2331
 
@@ -1790,6 +2494,39 @@ function receiptRecipientLabel(recipient) {
1790
2494
  return parts.length ? parts.join(' ') : 'recorded (see manifest.json)'
1791
2495
  }
1792
2496
 
2497
+ /** Human label for manifest.subject: "<kind> <name> (<id>)". */
2498
+ function receiptSubjectLabel(subject) {
2499
+ if (!subject) return 'none'
2500
+ const label = subject.name && subject.id ? subject.name + ' (' + subject.id + ')' : subject.name || subject.id || ''
2501
+ return (subject.kind + ' ' + label).trim()
2502
+ }
2503
+
2504
+ /**
2505
+ * The one place that turns scope + subject into the Chinese/English warning
2506
+ * printed by README.txt and receipt.docx. Keeping it here makes the two
2507
+ * documents unable to disagree about what the pack contains.
2508
+ */
2509
+ function receiptScopeLines(subject, scope) {
2510
+ if (scope === 'subject' && subject && subject.kind !== 'none') {
2511
+ const label = receiptSubjectLabel(subject)
2512
+ return {
2513
+ zh: '本包只含 ' + label + ' 的数据,全局 facts/preferences 默认不含。',
2514
+ en: 'This pack contains only the data of ' + label + '; global facts/preferences are not included by default.',
2515
+ }
2516
+ }
2517
+ return {
2518
+ zh: '本包含本机全部客户数据,勿直接发给第三方。',
2519
+ en: 'This pack contains all customer data on this machine; do not send it directly to a third party.',
2520
+ }
2521
+ }
2522
+
2523
+ function receiptScopeHeaderLine(subject, scope) {
2524
+ if (scope === 'subject' && subject && subject.kind !== 'none') {
2525
+ return 'subject (only ' + receiptSubjectLabel(subject) + '; global facts/preferences not included by default)'
2526
+ }
2527
+ return 'local-all (ALL customer data on this machine; do not send it to a third party)'
2528
+ }
2529
+
1793
2530
  function receiptDocxSpec(input) {
1794
2531
  const {
1795
2532
  createdAt,
@@ -1802,7 +2539,10 @@ function receiptDocxSpec(input) {
1802
2539
  anchors,
1803
2540
  deliveryFiles,
1804
2541
  receiptSha256,
2542
+ subject,
2543
+ scope,
1805
2544
  } = input
2545
+ const scopeLines = receiptScopeLines(subject, scope)
1806
2546
  const summary = [
1807
2547
  '包格式:' + RECEIPT_MANIFEST_FORMAT + ' v' + RECEIPT_MANIFEST_VERSION,
1808
2548
  '生成时间:' + createdAt,
@@ -1810,6 +2550,8 @@ function receiptDocxSpec(input) {
1810
2550
  '生成环境:Advisers ' + (generator.advisersVersion || 'unknown') + ' / Node ' + generator.nodeVersion + ' / ' + generator.platform,
1811
2551
  '模板:' + (generator.templateName ? generator.templateName + (generator.templateVersion ? '@' + generator.templateVersion : '') : '未记录'),
1812
2552
  '交付:' + deliveries.length + ' 项 / 文件 ' + deliveryFiles.length + ' 个',
2553
+ '数据范围:' + scopeLines.zh,
2554
+ 'Scope: ' + scopeLines.en,
1813
2555
  '校验结果:' + (verifyStatus === 'passed' ? '通过' : verifyStatus === 'failed' ? '未通过' : '未记录'),
1814
2556
  '时间锚:' + (anchors.length ? anchors.length + ' 条(外部锚,需按适配器另行验证)' : '未锚定(仅本地自证)'),
1815
2557
  ]
@@ -1856,8 +2598,10 @@ function receiptDocxSpec(input) {
1856
2598
  heading: '证据摘要',
1857
2599
  paragraphs: [
1858
2600
  '证据条目:' + evidence.entryCount + '(commitment ' + evidence.counts.commitment + ' / fact ' + evidence.counts.fact + ' / preference ' + evidence.counts.preference + ' / unknown ' + evidence.counts.unknown + ')',
1859
- '已解析来源:' + evidence.sourceCount + ';缺失来源:' + evidence.missingCount,
1860
- ...(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 + '(离线校验只证明包内自洽,不能重放对话)'] : []),
1861
2605
  '完整证据条目(session#turn 引用与截断引用原话)见 manifest.json 的 evidence 字段。',
1862
2606
  ],
1863
2607
  })
@@ -1890,7 +2634,8 @@ function buildReceiptSums(fileContents) {
1890
2634
  }
1891
2635
 
1892
2636
  function buildReceiptReadme(input) {
1893
- const { createdAt, generator, recipient, deliveries, evidence, verifyResults, verifyStatus, anchors, manifestDigest } = input
2637
+ const { createdAt, generator, recipient, deliveries, evidence, verifyResults, verifyStatus, anchors, manifestDigest, subject, scope } = input
2638
+ const scopeLines = receiptScopeLines(subject, scope)
1894
2639
  const lines = [
1895
2640
  'Advisers delivery receipt pack',
1896
2641
  '==============================',
@@ -1902,6 +2647,8 @@ function buildReceiptReadme(input) {
1902
2647
  'template: ' + (generator.templateName ? generator.templateName + (generator.templateVersion ? ' v' + generator.templateVersion : '') : 'not recorded'),
1903
2648
  'command: ' + (generator.command || 'not recorded'),
1904
2649
  'deliveries: ' + deliveries.length,
2650
+ 'subject: ' + (subject ? receiptSubjectLabel(subject) : 'none'),
2651
+ 'scope: ' + receiptScopeHeaderLine(subject, scope),
1905
2652
  'verification:' + ' ' + (verifyStatus === 'passed' ? 'passed' : verifyStatus === 'failed' ? 'FAILED' : 'not recorded') + (verifyResults.length ? ' (' + verifyResults.length + ' result(s))' : ''),
1906
2653
  'anchors: ' + (anchors.length ? anchors.length + ' external anchor(s) recorded' : 'NONE - this pack is not externally anchored (local self-attestation only)'),
1907
2654
  '',
@@ -1931,7 +2678,9 @@ function buildReceiptReadme(input) {
1931
2678
  'SHA256SUMS sha256 of every other file in this pack',
1932
2679
  '',
1933
2680
  'Evidence entries: ' + evidence.entryCount + ' (sources ' + evidence.sourceCount + ', missing ' + evidence.missingCount + ')',
1934
- ...(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)'] : []),
1935
2684
  '(references and capped quotes only; see manifest.json evidence.entries)',
1936
2685
  '',
1937
2686
  'Verify (offline, no ~/.advisers database needed)',
@@ -1944,6 +2693,11 @@ function buildReceiptReadme(input) {
1944
2693
  'pack can recompute them. When the anchors line above says NONE, the pack only',
1945
2694
  'proves internal consistency, not when or by whom it was produced.',
1946
2695
  '',
2696
+ 'Scope',
2697
+ '-----',
2698
+ scopeLines.zh,
2699
+ scopeLines.en,
2700
+ '',
1947
2701
  'Privacy and scope',
1948
2702
  '-----------------',
1949
2703
  '- Built locally; no network calls; verification does not open the ledger.',
@@ -2021,18 +2775,34 @@ function writeReceiptPackDir(targetDir, fileContents, { overwrite = false } = {}
2021
2775
  }
2022
2776
 
2023
2777
  /**
2024
- * Build a delivery receipt pack (v1.1).
2778
+ * Build a delivery receipt pack (manifest v2; v1.1 packs still verify offline).
2025
2779
  *
2026
2780
  * The manifest records the delivered files (relative path / size / SHA-256),
2027
2781
  * the generator environment, the verify results, optional recipient and
2028
- * timestamp anchors, and the evidence entries. receipt.docx is generated and
2029
- * both it and every delivered artifact are covered by SHA256SUMS, so
2782
+ * timestamp anchors, and the evidence entries. Manifest v2 adds the optional
2783
+ * `subject`, the mandatory `scope` ('subject' | 'local-all') and optional
2784
+ * row-level lineage. receipt.docx and README.txt both print the scope warning,
2785
+ * and both it and every delivered artifact are covered by SHA256SUMS, so
2030
2786
  * verifyReceiptPackDir can detect any edit or missing file offline.
2031
2787
  *
2788
+ * Backwards compatibility: callers that pass neither `subject` nor `scope`
2789
+ * (e.g. the 0.3.1 CLI) still get a valid pack, now version 2 with
2790
+ * scope 'local-all' and no subject key — the same manifest rows they got
2791
+ * before, plus the all-customer-data warning.
2792
+ *
2032
2793
  * @param {object} options
2033
2794
  * @param {Array|object} options.deliveries delivery record(s): {id, title, tool,
2034
- * createdAt, validation, files}. Each file is a path string, a
2035
- * {sourcePath} object, or a {content, name} object with embedded bytes.
2795
+ * createdAt, validation, files, clientId?, projectId?, matterId?,
2796
+ * templateName?, templateVersion?, quoteNo?, dataSha256?}. Each file is
2797
+ * a path string, a {sourcePath} object, or a {content, name} object with
2798
+ * embedded bytes. Lineage fields are written only when present; a partial
2799
+ * template identity (name without version) is rejected.
2800
+ * @param {{kind: 'client'|'project'|'matter'|'none', id?: string, name?: string}}
2801
+ * [options.subject] optional manifest.subject (v2). Written only when
2802
+ * passed; kind 'none' declares "no single subject" and forbids id/name.
2803
+ * @param {'subject'|'local-all'} [options.scope] pack scope (v2). Defaults to
2804
+ * 'subject' when a client/project/matter subject is given, otherwise
2805
+ * 'local-all'; contradictory combinations are rejected.
2036
2806
  * @param {object|Array|string} [options.evidence] buildEvidencePack output,
2037
2807
  * evidence entries, or an evidence manifest string.
2038
2808
  * @param {object|Array} [options.verifyResults] results with a boolean ok
@@ -2068,6 +2838,8 @@ export async function buildReceiptPack(options = {}) {
2068
2838
  const generator = normalizeReceiptGenerator(options.env)
2069
2839
  const recipient = normalizeReceiptRecipient(options.recipient)
2070
2840
  const anchors = normalizeReceiptAnchors(options.anchors)
2841
+ const subject = normalizeReceiptSubject(options.subject)
2842
+ const scope = normalizeReceiptScope(options.scope, subject)
2071
2843
  const deliveryFiles = []
2072
2844
  for (const delivery of deliveries) for (const file of delivery.files) deliveryFiles.push(file)
2073
2845
 
@@ -2086,6 +2858,8 @@ export async function buildReceiptPack(options = {}) {
2086
2858
  anchors,
2087
2859
  deliveryFiles,
2088
2860
  receiptSha256: 'see SHA256SUMS',
2861
+ subject,
2862
+ scope,
2089
2863
  })
2090
2864
  const receiptBytes =
2091
2865
  options.receiptDocx !== undefined
@@ -2120,12 +2894,20 @@ export async function buildReceiptPack(options = {}) {
2120
2894
  createdAt,
2121
2895
  generator,
2122
2896
  recipient,
2897
+ // v2: scope is always written, subject only when the caller supplied one.
2898
+ ...(subject ? { subject } : {}),
2899
+ scope,
2123
2900
  deliveries: deliveries.map((delivery) => ({
2124
2901
  id: delivery.id,
2125
2902
  title: delivery.title,
2126
2903
  tool: delivery.tool,
2127
2904
  createdAt: delivery.createdAt,
2128
2905
  validation: delivery.validation,
2906
+ // v2 lineage: absent keys keep the v1 row shape byte-clean.
2907
+ ...(delivery.clientId ? { clientId: delivery.clientId } : {}),
2908
+ ...(delivery.projectId ? { projectId: delivery.projectId } : {}),
2909
+ ...(delivery.matterId ? { matterId: delivery.matterId } : {}),
2910
+ ...(delivery.template ? { template: delivery.template } : {}),
2129
2911
  files: delivery.files.map((file) => ({ path: file.path, name: file.name, size: file.size, sha256: file.sha256 })),
2130
2912
  })),
2131
2913
  receipt: receiptFile,
@@ -2151,6 +2933,8 @@ export async function buildReceiptPack(options = {}) {
2151
2933
  verifyStatus,
2152
2934
  anchors,
2153
2935
  manifestDigest,
2936
+ subject,
2937
+ scope,
2154
2938
  })
2155
2939
  fileContents.set('README.txt', readme)
2156
2940
  // Everything except SHA256SUMS itself is covered by SHA256SUMS.
@@ -2162,6 +2946,9 @@ export async function buildReceiptPack(options = {}) {
2162
2946
  format: RECEIPT_MANIFEST_FORMAT,
2163
2947
  version: RECEIPT_MANIFEST_VERSION,
2164
2948
  createdAt,
2949
+ // v2: null (not undefined) so JSON callers see an explicit "no subject".
2950
+ subject: subject || null,
2951
+ scope,
2165
2952
  deliveryCount: deliveries.length,
2166
2953
  fileCount,
2167
2954
  verifyStatus,
@@ -2175,6 +2962,14 @@ export async function buildReceiptPack(options = {}) {
2175
2962
  unverifiableCount: evidence.unverifiableCount ?? 0,
2176
2963
  operatorEnteredCount: evidence.operatorEnteredCount ?? 0,
2177
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
+ : {}),
2178
2973
  },
2179
2974
  anchored: anchors.length > 0,
2180
2975
  fileMode: RECEIPT_FILE_MODE,
@@ -2263,7 +3058,8 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
2263
3058
  const sources = Array.isArray(entry.sources) ? entry.sources : []
2264
3059
  const missing = Array.isArray(entry.missing) ? entry.missing : []
2265
3060
  const unverifiable = Array.isArray(entry.unverifiable) ? entry.unverifiable : []
2266
- 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) {
2267
3063
  rows.push([kind, id, '', '', entry.found === false ? '记录不存在' : '无证据'])
2268
3064
  continue
2269
3065
  }
@@ -2286,12 +3082,24 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
2286
3082
  ])
2287
3083
  }
2288
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) {
2289
3097
  rows.push([
2290
3098
  kind,
2291
3099
  id,
2292
- '',
3100
+ item.ref || formatRef(item.sessionId, item.turnId) || '',
2293
3101
  clampQuote(item.quote).quote,
2294
- MANUAL_SOURCE_KIND + ': operator-entered (unverifiable, not missing)',
3102
+ 'not_checked: ' + (item.type ?? 'unknown') + ' (' + (item.reason ?? 'not_checked') + ')',
2295
3103
  ])
2296
3104
  }
2297
3105
  }