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.
- package/README-zh.md +13 -15
- package/README.md +32 -22
- package/THIRD-PARTY-NOTICES.md +1 -1
- package/bin/advisers.js +2769 -183
- package/index.js +1 -1
- package/lib/brief-archive.js +267 -0
- package/lib/client-pack.js +1016 -0
- package/lib/consent.js +390 -0
- package/lib/credentials.js +195 -0
- package/lib/customer-read.js +524 -0
- package/lib/error-codes.js +516 -7
- package/lib/evidence.js +928 -120
- package/lib/kb-extract.js +626 -0
- package/lib/kb-facts.js +429 -0
- package/lib/kb-pages.js +1084 -0
- package/lib/kb.js +1036 -0
- package/lib/ledger-read.js +109 -1
- package/lib/mail-errors.js +46 -0
- package/lib/mail-extract.js +351 -0
- package/lib/mail-imap.js +446 -0
- package/lib/mail-import.js +176 -0
- package/lib/mail-parse.js +223 -0
- package/lib/mail-store.js +731 -0
- package/lib/mail.js +506 -0
- package/lib/mcp-server.js +397 -11
- package/lib/notify.js +265 -7
- package/lib/policy/decision.js +315 -0
- package/lib/policy/egress.js +268 -0
- package/lib/policy/errors.js +71 -0
- package/lib/policy/index.js +99 -0
- package/lib/policy/rules.js +468 -0
- package/lib/policy/surfaces.js +141 -0
- package/lib/receipt-verify.js +283 -26
- package/lib/receivables.js +1653 -0
- package/lib/scheduler.js +453 -9
- package/lib/shell.js +1406 -0
- package/lib/source.js +98 -3
- package/lib/sqlite.js +501 -49
- package/lib/tos/index.js +2 -2
- package/lib/tos/manifest.json +6 -6
- package/lib/tos/privacy.zh-CN.md +33 -20
- package/lib/tos/safety.zh-CN.md +7 -6
- package/lib/tos/summary.zh-CN.md +3 -2
- package/lib/tos/terms.zh-CN.md +31 -16
- package/lib/tui/labels.js +1 -1
- package/lib/tui/render.js +1 -1
- package/lib/urgency.js +467 -0
- 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
|
|
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
|
-
|
|
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
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
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
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
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
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
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
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
574
|
-
*
|
|
575
|
-
*
|
|
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
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
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
|
|
586
|
-
for (const item of
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
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
|
|
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
|
-
/**
|
|
614
|
-
|
|
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
|
-
|
|
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
|
|
620
|
-
const resolved =
|
|
621
|
-
return { schemaVersion: 2, fact,
|
|
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
|
|
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
|
-
|
|
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
|
|
631
|
-
const resolved =
|
|
632
|
-
return { schemaVersion: 2, preference,
|
|
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
|
-
|
|
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 =
|
|
1120
|
+
const clamped = clampStoredQuote(source)
|
|
687
1121
|
const entry = {
|
|
688
|
-
|
|
689
|
-
|
|
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
|
-
|
|
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,
|
|
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
|
-
'
|
|
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(`
|
|
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
|
|
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
|
|
1021
|
-
unverifiableCount +=
|
|
1022
|
-
operatorEnteredCount +=
|
|
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
|
-
|
|
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))
|
|
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))
|
|
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
|
-
|
|
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
|
-
'
|
|
1860
|
-
...(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 + ' (
|
|
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.
|
|
2029
|
-
*
|
|
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
|
|
2035
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
3102
|
+
'not_checked: ' + (item.type ?? 'unknown') + ' (' + (item.reason ?? 'not_checked') + ')',
|
|
2295
3103
|
])
|
|
2296
3104
|
}
|
|
2297
3105
|
}
|