advisers 0.2.1 → 0.2.3
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 +6 -4
- package/README.md +6 -6
- package/THIRD-PARTY-NOTICES.md +1 -1
- package/bin/advisers.js +3148 -369
- package/index.js +1 -1
- package/lib/agent.js +529 -80
- package/lib/evidence.js +150 -17
- package/lib/fs-safe.js +284 -0
- package/lib/mcp-server.js +46 -21
- package/lib/model.js +73 -1
- package/lib/ocr.js +29 -9
- package/lib/pet-brief.js +24 -25
- package/lib/safety/classifier.js +55 -2
- package/lib/safety/rules.js +28 -0
- package/lib/sqlite.js +1614 -129
- package/lib/sync.js +398 -71
- package/lib/timestamp.js +29 -9
- package/lib/untrusted.js +186 -0
- package/package.json +4 -4
package/lib/evidence.js
CHANGED
|
@@ -174,6 +174,52 @@ export function parseSourceRef(ref) {
|
|
|
174
174
|
return { sessionId, turnId }
|
|
175
175
|
}
|
|
176
176
|
|
|
177
|
+
/**
|
|
178
|
+
* 0.2.3 evidence discipline (B3): manual/operator-entered sources.
|
|
179
|
+
*
|
|
180
|
+
* A CLI operator can only state what they typed. Before 0.2.3 those rows were
|
|
181
|
+
* written as `{sessionId:'local', turnId:'cli'}`, i.e. a fake conversation
|
|
182
|
+
* pointer that every reader resolved as MISSING (turn_not_found). The honest
|
|
183
|
+
* shape is a typed manual source: it is unverifiable by construction, not
|
|
184
|
+
* missing. Legacy rows are mapped on read (never rewritten), so old packs and
|
|
185
|
+
* ledgers keep working without a migration.
|
|
186
|
+
*/
|
|
187
|
+
export const MANUAL_SOURCE_KIND = 'manual'
|
|
188
|
+
export const MANUAL_RESOLUTION = 'unverifiable'
|
|
189
|
+
export const MANUAL_REASON = 'operator_entered'
|
|
190
|
+
|
|
191
|
+
/** True for a new manual source, a legacy {sessionId:'local',turnId:'cli'} row, or an operator-marked item. */
|
|
192
|
+
export function isManualEvidence(item) {
|
|
193
|
+
if (!item || typeof item !== 'object' || Array.isArray(item)) return false
|
|
194
|
+
if (item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND) return true
|
|
195
|
+
if (item.source === 'operator') return true
|
|
196
|
+
// 0.2.2 forged CLI evidence: written by `commit add --quote` / `commit done`.
|
|
197
|
+
return item.sessionId === 'local' && item.turnId === 'cli'
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/**
|
|
201
|
+
* Render one manual source for evidence show / packs.
|
|
202
|
+
* The stored quote is always re-hashed locally; a stale or forged hash never wins.
|
|
203
|
+
*/
|
|
204
|
+
export function manualEvidenceSource(item) {
|
|
205
|
+
const clamped = clampQuote(typeof item?.quote === 'string' ? item.quote : '')
|
|
206
|
+
const entry = {
|
|
207
|
+
kind: MANUAL_SOURCE_KIND,
|
|
208
|
+
type: MANUAL_SOURCE_KIND,
|
|
209
|
+
source: 'operator',
|
|
210
|
+
quote: clamped.quote,
|
|
211
|
+
quoteChars: clamped.quoteChars,
|
|
212
|
+
truncated: clamped.truncated,
|
|
213
|
+
quoteSha256: clamped.quoteSha256,
|
|
214
|
+
resolution: MANUAL_RESOLUTION,
|
|
215
|
+
reason: MANUAL_REASON,
|
|
216
|
+
}
|
|
217
|
+
for (const key of ['capturedAt', 'capturedBy', 'command', 'cliVersion']) {
|
|
218
|
+
if (typeof item?.[key] === 'string' && item[key]) entry[key] = item[key]
|
|
219
|
+
}
|
|
220
|
+
return entry
|
|
221
|
+
}
|
|
222
|
+
|
|
177
223
|
function lookupTurn(store, sessionId, turnId) {
|
|
178
224
|
if (!store || typeof store !== 'object') return { turn: undefined, failed: false }
|
|
179
225
|
let failed = false
|
|
@@ -356,11 +402,16 @@ function collectSourceRefs(...lists) {
|
|
|
356
402
|
function resolveSourceRefs(store, items) {
|
|
357
403
|
const sources = []
|
|
358
404
|
const missing = []
|
|
405
|
+
const unverifiable = []
|
|
359
406
|
for (const item of items) {
|
|
360
407
|
if (!item || typeof item !== 'object' || Array.isArray(item)) {
|
|
361
408
|
missing.push({ reason: 'invalid_source' })
|
|
362
409
|
continue
|
|
363
410
|
}
|
|
411
|
+
if (isManualEvidence(item)) {
|
|
412
|
+
unverifiable.push(manualEvidenceSource(item))
|
|
413
|
+
continue
|
|
414
|
+
}
|
|
364
415
|
const quote = typeof item.quote === 'string' ? item.quote : ''
|
|
365
416
|
const ref = typeof item.ref === 'string' ? item.ref : ''
|
|
366
417
|
if (!ref) {
|
|
@@ -389,7 +440,7 @@ function resolveSourceRefs(store, items) {
|
|
|
389
440
|
}
|
|
390
441
|
sources.push({ sessionId: parsed.sessionId, turnId: parsed.turnId, quote, turn: lookup.turn })
|
|
391
442
|
}
|
|
392
|
-
return { sources, missing }
|
|
443
|
+
return { sources, missing, unverifiable }
|
|
393
444
|
}
|
|
394
445
|
|
|
395
446
|
/**
|
|
@@ -402,12 +453,17 @@ function resolveSourceRefs(store, items) {
|
|
|
402
453
|
export function evidenceForCommitment(store, ledger, commitmentId, index) {
|
|
403
454
|
const commitment = findCommitment(ledger, commitmentId, index)
|
|
404
455
|
if (!commitment) {
|
|
405
|
-
return { commitment: undefined, sources: [], missing: [{ id: commitmentId, reason: 'commitment_not_found' }] }
|
|
456
|
+
return { schemaVersion: 2, commitment: undefined, sources: [], missing: [{ id: commitmentId, reason: 'commitment_not_found' }], unverifiable: [] }
|
|
406
457
|
}
|
|
407
458
|
const sources = []
|
|
408
459
|
const missing = []
|
|
460
|
+
const unverifiable = []
|
|
409
461
|
const evidence = Array.isArray(commitment.evidence) ? commitment.evidence : []
|
|
410
462
|
for (const item of evidence) {
|
|
463
|
+
if (isManualEvidence(item)) {
|
|
464
|
+
unverifiable.push(manualEvidenceSource(item))
|
|
465
|
+
continue
|
|
466
|
+
}
|
|
411
467
|
const sessionId = typeof item?.sessionId === 'string' ? item.sessionId : ''
|
|
412
468
|
const turnId = typeof item?.turnId === 'string' ? item.turnId : ''
|
|
413
469
|
const quote = typeof item?.quote === 'string' ? item.quote : ''
|
|
@@ -431,29 +487,29 @@ export function evidenceForCommitment(store, ledger, commitmentId, index) {
|
|
|
431
487
|
}
|
|
432
488
|
sources.push({ sessionId, turnId, quote, turn: lookup.turn })
|
|
433
489
|
}
|
|
434
|
-
return { commitment, sources, missing }
|
|
490
|
+
return { schemaVersion: 2, commitment, sources, missing, unverifiable }
|
|
435
491
|
}
|
|
436
492
|
|
|
437
493
|
/** Trace a fact's `SourceRef[]` (plus its primary `source`) back to turns. */
|
|
438
494
|
export function evidenceForFact(store, ledger, factId, index) {
|
|
439
495
|
const fact = findFact(ledger, factId, index)
|
|
440
496
|
if (!fact) {
|
|
441
|
-
return { fact: undefined, sources: [], missing: [{ id: factId, reason: 'fact_not_found' }] }
|
|
497
|
+
return { schemaVersion: 2, fact: undefined, sources: [], missing: [{ id: factId, reason: 'fact_not_found' }], unverifiable: [] }
|
|
442
498
|
}
|
|
443
499
|
const refs = collectSourceRefs(fact.evidence, primarySourceCandidates(fact.source))
|
|
444
500
|
const resolved = resolveSourceRefs(store, refs)
|
|
445
|
-
return { fact, sources: resolved.sources, missing: resolved.missing }
|
|
501
|
+
return { schemaVersion: 2, fact, sources: resolved.sources, missing: resolved.missing, unverifiable: resolved.unverifiable }
|
|
446
502
|
}
|
|
447
503
|
|
|
448
504
|
/** Trace a preference's `SourceRef[]` (plus its primary `source`) back to turns. */
|
|
449
505
|
export function evidenceForPreference(store, ledger, preferenceId, index) {
|
|
450
506
|
const preference = findPreference(ledger, preferenceId, index)
|
|
451
507
|
if (!preference) {
|
|
452
|
-
return { preference: undefined, sources: [], missing: [{ id: preferenceId, reason: 'preference_not_found' }] }
|
|
508
|
+
return { schemaVersion: 2, preference: undefined, sources: [], missing: [{ id: preferenceId, reason: 'preference_not_found' }], unverifiable: [] }
|
|
453
509
|
}
|
|
454
510
|
const refs = collectSourceRefs(preference.evidence, primarySourceCandidates(preference.source))
|
|
455
511
|
const resolved = resolveSourceRefs(store, refs)
|
|
456
|
-
return { preference, sources: resolved.sources, missing: resolved.missing }
|
|
512
|
+
return { schemaVersion: 2, preference, sources: resolved.sources, missing: resolved.missing, unverifiable: resolved.unverifiable }
|
|
457
513
|
}
|
|
458
514
|
|
|
459
515
|
// ---------------------------------------------------------------------------
|
|
@@ -528,14 +584,35 @@ function compactMissing(item) {
|
|
|
528
584
|
return out
|
|
529
585
|
}
|
|
530
586
|
|
|
587
|
+
function compactUnverifiable(item) {
|
|
588
|
+
const out = {
|
|
589
|
+
kind: MANUAL_SOURCE_KIND,
|
|
590
|
+
type: MANUAL_SOURCE_KIND,
|
|
591
|
+
resolution: MANUAL_RESOLUTION,
|
|
592
|
+
reason: typeof item?.reason === 'string' && item.reason ? item.reason : MANUAL_REASON,
|
|
593
|
+
}
|
|
594
|
+
const clamped = clampQuote(item?.quote)
|
|
595
|
+
Object.assign(out, clamped)
|
|
596
|
+
for (const key of ['capturedAt', 'capturedBy', 'command']) {
|
|
597
|
+
if (typeof item?.[key] === 'string' && item[key]) out[key] = item[key]
|
|
598
|
+
}
|
|
599
|
+
return out
|
|
600
|
+
}
|
|
601
|
+
|
|
531
602
|
function compactEntry(entry) {
|
|
532
|
-
|
|
603
|
+
const out = {
|
|
533
604
|
kind: typeof entry.kind === 'string' ? entry.kind : 'unknown',
|
|
534
605
|
id: String(entry.id ?? ''),
|
|
535
606
|
found: Boolean(entry.found),
|
|
536
607
|
sources: (Array.isArray(entry.sources) ? entry.sources : []).map(compactSource),
|
|
537
608
|
missing: (Array.isArray(entry.missing) ? entry.missing : []).map(compactMissing),
|
|
538
609
|
}
|
|
610
|
+
// Additive (0.2.3 B3): operator-entered sources are unverifiable, not missing.
|
|
611
|
+
// Kept absent when empty so pre-0.2.3 pack bytes do not change.
|
|
612
|
+
if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
|
|
613
|
+
out.unverifiable = entry.unverifiable.map(compactUnverifiable)
|
|
614
|
+
}
|
|
615
|
+
return out
|
|
539
616
|
}
|
|
540
617
|
|
|
541
618
|
function inferKindFromId(id) {
|
|
@@ -607,21 +684,23 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
|
|
|
607
684
|
const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
|
|
608
685
|
let sourceCount = 0
|
|
609
686
|
let missingCount = 0
|
|
687
|
+
let unverifiableCount = 0
|
|
610
688
|
let truncatedCount = 0
|
|
611
689
|
for (const entry of entries) {
|
|
612
690
|
counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
|
|
613
691
|
sourceCount += entry.sources.length
|
|
614
692
|
missingCount += entry.missing.length
|
|
693
|
+
unverifiableCount += (entry.unverifiable ?? []).length
|
|
615
694
|
truncatedCount += entry.sources.filter((source) => source.truncated).length
|
|
616
695
|
}
|
|
617
696
|
const lines = [
|
|
618
697
|
'Advisers evidence pack',
|
|
619
698
|
'======================',
|
|
620
699
|
'',
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
700
|
+
'format: ' + MANIFEST_FORMAT + ' v' + MANIFEST_VERSION,
|
|
701
|
+
'created: ' + createdAt,
|
|
702
|
+
'entries: ' + entries.length + ' (commitment ' + counts.commitment + ', fact ' + counts.fact + ', preference ' + counts.preference + ', unknown ' + counts.unknown + ')',
|
|
703
|
+
'sources: ' + sourceCount + ' resolved, ' + missingCount + ' missing' + (unverifiableCount ? ', ' + unverifiableCount + ' operator-entered (not externally verified, not missing)' : ''),
|
|
625
704
|
`quotes: verbatim, at most ${MAX_QUOTE_CHARS} characters each; ${truncatedCount} truncated`,
|
|
626
705
|
'',
|
|
627
706
|
'Files',
|
|
@@ -642,9 +721,13 @@ function buildReadme({ createdAt, entries, manifestDigest }) {
|
|
|
642
721
|
if (!entries.length) lines.push('(no evidence requested)')
|
|
643
722
|
const shown = entries.slice(0, README_ENTRY_CAP)
|
|
644
723
|
for (const entry of shown) {
|
|
724
|
+
const manualCount = (entry.unverifiable ?? []).length
|
|
645
725
|
lines.push(
|
|
646
|
-
`- ${entry.kind} ${entry.id} sources=${entry.sources.length} missing=${entry.missing.length}${entry.found ? '' : ' (record not found)'}`,
|
|
726
|
+
`- ${entry.kind} ${entry.id} sources=${entry.sources.length} missing=${entry.missing.length}${manualCount ? ` manual=${manualCount}` : ''}${entry.found ? '' : ' (record not found)'}`,
|
|
647
727
|
)
|
|
728
|
+
for (const item of (entry.unverifiable ?? []).slice(0, README_REF_CAP)) {
|
|
729
|
+
lines.push(` manual operator-entered (unverifiable): ${item.reason ?? MANUAL_REASON}`)
|
|
730
|
+
}
|
|
648
731
|
const refs = entry.sources.slice(0, README_REF_CAP)
|
|
649
732
|
for (const source of refs) {
|
|
650
733
|
lines.push(` source ${formatRef(source.sessionId, source.turnId)}${source.truncated ? ' (quote truncated)' : ''}`)
|
|
@@ -730,11 +813,12 @@ export function buildEvidencePack({
|
|
|
730
813
|
found: Boolean(result.commitment),
|
|
731
814
|
sources: result.sources,
|
|
732
815
|
missing: result.missing,
|
|
816
|
+
unverifiable: result.unverifiable,
|
|
733
817
|
})
|
|
734
818
|
}
|
|
735
819
|
for (const id of requested.facts) {
|
|
736
820
|
const result = evidenceForFact(store, ledger, id, index)
|
|
737
|
-
entries.push({ kind: 'fact', id, found: Boolean(result.fact), sources: result.sources, missing: result.missing })
|
|
821
|
+
entries.push({ kind: 'fact', id, found: Boolean(result.fact), sources: result.sources, missing: result.missing, unverifiable: result.unverifiable })
|
|
738
822
|
}
|
|
739
823
|
for (const id of requested.preferences) {
|
|
740
824
|
const result = evidenceForPreference(store, ledger, id, index)
|
|
@@ -744,6 +828,7 @@ export function buildEvidencePack({
|
|
|
744
828
|
found: Boolean(result.preference),
|
|
745
829
|
sources: result.sources,
|
|
746
830
|
missing: result.missing,
|
|
831
|
+
unverifiable: result.unverifiable,
|
|
747
832
|
})
|
|
748
833
|
}
|
|
749
834
|
for (const id of requested.unknown) {
|
|
@@ -763,11 +848,16 @@ export function buildEvidencePack({
|
|
|
763
848
|
const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
|
|
764
849
|
let sourceCount = 0
|
|
765
850
|
let missingCount = 0
|
|
851
|
+
let unverifiableCount = 0
|
|
852
|
+
let operatorEnteredCount = 0
|
|
766
853
|
let truncatedCount = 0
|
|
767
854
|
for (const entry of compacted) {
|
|
768
855
|
counts[entry.kind] = (counts[entry.kind] ?? 0) + 1
|
|
769
856
|
sourceCount += entry.sources.length
|
|
770
857
|
missingCount += entry.missing.length
|
|
858
|
+
const manual = entry.unverifiable ?? []
|
|
859
|
+
unverifiableCount += manual.length
|
|
860
|
+
operatorEnteredCount += manual.filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
|
|
771
861
|
truncatedCount += entry.sources.filter((source) => source.truncated).length
|
|
772
862
|
}
|
|
773
863
|
|
|
@@ -785,6 +875,8 @@ export function buildEvidencePack({
|
|
|
785
875
|
counts,
|
|
786
876
|
sourceCount,
|
|
787
877
|
missingCount,
|
|
878
|
+
unverifiableCount,
|
|
879
|
+
operatorEnteredCount,
|
|
788
880
|
truncatedCount,
|
|
789
881
|
notFound: compacted.filter((entry) => !entry.found).map((entry) => entry.id),
|
|
790
882
|
fileHashes: { 'manifest.json': manifestDigest, 'README.txt': readmeDigest },
|
|
@@ -1131,15 +1223,34 @@ function receiptMissing(item) {
|
|
|
1131
1223
|
return out
|
|
1132
1224
|
}
|
|
1133
1225
|
|
|
1226
|
+
function receiptUnverifiable(item) {
|
|
1227
|
+
if (!item || typeof item !== 'object' || Array.isArray(item)) return null
|
|
1228
|
+
const out = {
|
|
1229
|
+
kind: MANUAL_SOURCE_KIND,
|
|
1230
|
+
type: MANUAL_SOURCE_KIND,
|
|
1231
|
+
resolution: MANUAL_RESOLUTION,
|
|
1232
|
+
reason: typeof item.reason === 'string' && item.reason ? item.reason : MANUAL_REASON,
|
|
1233
|
+
}
|
|
1234
|
+
Object.assign(out, clampQuote(item.quote))
|
|
1235
|
+
for (const key of ['capturedAt', 'capturedBy', 'command']) {
|
|
1236
|
+
if (typeof item[key] === 'string' && item[key]) out[key] = item[key].slice(0, 120)
|
|
1237
|
+
}
|
|
1238
|
+
return out
|
|
1239
|
+
}
|
|
1240
|
+
|
|
1134
1241
|
function receiptEvidenceEntry(entry) {
|
|
1135
1242
|
if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null
|
|
1136
|
-
|
|
1243
|
+
const out = {
|
|
1137
1244
|
kind: typeof entry.kind === 'string' ? entry.kind : 'unknown',
|
|
1138
1245
|
id: String(entry.id === undefined || entry.id === null ? '' : entry.id),
|
|
1139
1246
|
found: Boolean(entry.found),
|
|
1140
1247
|
sources: (Array.isArray(entry.sources) ? entry.sources : []).map(receiptSource),
|
|
1141
1248
|
missing: (Array.isArray(entry.missing) ? entry.missing : []).map(receiptMissing),
|
|
1142
1249
|
}
|
|
1250
|
+
if (Array.isArray(entry.unverifiable) && entry.unverifiable.length) {
|
|
1251
|
+
out.unverifiable = entry.unverifiable.map(receiptUnverifiable).filter(Boolean)
|
|
1252
|
+
}
|
|
1253
|
+
return out
|
|
1143
1254
|
}
|
|
1144
1255
|
|
|
1145
1256
|
function normalizeReceiptEvidence(evidence) {
|
|
@@ -1183,10 +1294,15 @@ function normalizeReceiptEvidence(evidence) {
|
|
|
1183
1294
|
const counts = { commitment: 0, fact: 0, preference: 0, unknown: 0 }
|
|
1184
1295
|
let sourceCount = 0
|
|
1185
1296
|
let missingCount = 0
|
|
1297
|
+
let unverifiableCount = 0
|
|
1298
|
+
let operatorEnteredCount = 0
|
|
1186
1299
|
for (const entry of entries) {
|
|
1187
1300
|
counts[entry.kind] = (counts[entry.kind] || 0) + 1
|
|
1188
1301
|
sourceCount += entry.sources.length
|
|
1189
1302
|
missingCount += entry.missing.length
|
|
1303
|
+
const manual = entry.unverifiable ?? []
|
|
1304
|
+
unverifiableCount += manual.length
|
|
1305
|
+
operatorEnteredCount += manual.filter((item) => item.kind === MANUAL_SOURCE_KIND || item.type === MANUAL_SOURCE_KIND).length
|
|
1190
1306
|
}
|
|
1191
1307
|
return {
|
|
1192
1308
|
format: meta.format,
|
|
@@ -1195,6 +1311,8 @@ function normalizeReceiptEvidence(evidence) {
|
|
|
1195
1311
|
counts,
|
|
1196
1312
|
sourceCount,
|
|
1197
1313
|
missingCount,
|
|
1314
|
+
unverifiableCount,
|
|
1315
|
+
operatorEnteredCount,
|
|
1198
1316
|
entries,
|
|
1199
1317
|
}
|
|
1200
1318
|
}
|
|
@@ -1564,6 +1682,7 @@ function receiptDocxSpec(input) {
|
|
|
1564
1682
|
paragraphs: [
|
|
1565
1683
|
'证据条目:' + evidence.entryCount + '(commitment ' + evidence.counts.commitment + ' / fact ' + evidence.counts.fact + ' / preference ' + evidence.counts.preference + ' / unknown ' + evidence.counts.unknown + ')',
|
|
1566
1684
|
'已解析来源:' + evidence.sourceCount + ';缺失来源:' + evidence.missingCount,
|
|
1685
|
+
...(evidence.unverifiableCount ? ['未外部核验(操作者录入):' + evidence.unverifiableCount + ' 条(不是缺失;请勿当作已核验证据)'] : []),
|
|
1567
1686
|
'完整证据条目(session#turn 引用与截断引用原话)见 manifest.json 的 evidence 字段。',
|
|
1568
1687
|
],
|
|
1569
1688
|
})
|
|
@@ -1637,6 +1756,7 @@ function buildReceiptReadme(input) {
|
|
|
1637
1756
|
'SHA256SUMS sha256 of every other file in this pack',
|
|
1638
1757
|
'',
|
|
1639
1758
|
'Evidence entries: ' + evidence.entryCount + ' (sources ' + evidence.sourceCount + ', missing ' + evidence.missingCount + ')',
|
|
1759
|
+
...(evidence.unverifiableCount ? ['unverifiable: ' + evidence.unverifiableCount + ' (operator-entered; not externally verified, NOT missing)'] : []),
|
|
1640
1760
|
'(references and capped quotes only; see manifest.json evidence.entries)',
|
|
1641
1761
|
'',
|
|
1642
1762
|
'Verify (offline, no ~/.advisers database needed)',
|
|
@@ -1877,6 +1997,8 @@ export async function buildReceiptPack(options = {}) {
|
|
|
1877
1997
|
counts: evidence.counts,
|
|
1878
1998
|
sourceCount: evidence.sourceCount,
|
|
1879
1999
|
missingCount: evidence.missingCount,
|
|
2000
|
+
unverifiableCount: evidence.unverifiableCount ?? 0,
|
|
2001
|
+
operatorEnteredCount: evidence.operatorEnteredCount ?? 0,
|
|
1880
2002
|
},
|
|
1881
2003
|
anchored: anchors.length > 0,
|
|
1882
2004
|
fileMode: RECEIPT_FILE_MODE,
|
|
@@ -1906,6 +2028,7 @@ function entryFromResult(result) {
|
|
|
1906
2028
|
found: true,
|
|
1907
2029
|
sources: Array.isArray(result.sources) ? result.sources : [],
|
|
1908
2030
|
missing: Array.isArray(result.missing) ? result.missing : [],
|
|
2031
|
+
unverifiable: Array.isArray(result.unverifiable) ? result.unverifiable : [],
|
|
1909
2032
|
}
|
|
1910
2033
|
}
|
|
1911
2034
|
|
|
@@ -1963,7 +2086,8 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
|
|
|
1963
2086
|
const id = String(entry.id ?? '')
|
|
1964
2087
|
const sources = Array.isArray(entry.sources) ? entry.sources : []
|
|
1965
2088
|
const missing = Array.isArray(entry.missing) ? entry.missing : []
|
|
1966
|
-
|
|
2089
|
+
const unverifiable = Array.isArray(entry.unverifiable) ? entry.unverifiable : []
|
|
2090
|
+
if (!sources.length && !missing.length && !unverifiable.length) {
|
|
1967
2091
|
rows.push([kind, id, '', '', entry.found === false ? '记录不存在' : '无证据'])
|
|
1968
2092
|
continue
|
|
1969
2093
|
}
|
|
@@ -1982,7 +2106,16 @@ export function toDocxRows(input, { maxRows = 200 } = {}) {
|
|
|
1982
2106
|
id,
|
|
1983
2107
|
item.ref || formatRef(item.sessionId, item.turnId) || String(item.id ?? ''),
|
|
1984
2108
|
clampQuote(item.quote).quote,
|
|
1985
|
-
|
|
2109
|
+
'missing: ' + (item.reason ?? 'unknown'),
|
|
2110
|
+
])
|
|
2111
|
+
}
|
|
2112
|
+
for (const item of unverifiable) {
|
|
2113
|
+
rows.push([
|
|
2114
|
+
kind,
|
|
2115
|
+
id,
|
|
2116
|
+
'',
|
|
2117
|
+
clampQuote(item.quote).quote,
|
|
2118
|
+
MANUAL_SOURCE_KIND + ': operator-entered (unverifiable, not missing)',
|
|
1986
2119
|
])
|
|
1987
2120
|
}
|
|
1988
2121
|
}
|
package/lib/fs-safe.js
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Crash-safe filesystem helpers (0.2.3 robustness Phase 0, robustness audit
|
|
3
|
+
* P1-2/P1-3/P1-7).
|
|
4
|
+
*
|
|
5
|
+
* Why this module exists: Node's fs.writeSync (and writeFileSync, which also
|
|
6
|
+
* issues a single write(2)) may write fewer bytes than requested. POSIX allows
|
|
7
|
+
* a short write on ENOSPC/EDQUOT, on signal interruption, and on network/quota
|
|
8
|
+
* filesystems; the 2026-11-17 robustness audit reproduced a 1 MB write into a
|
|
9
|
+
* nearly-full tmpfs returning 204800 bytes with no error, which used to install
|
|
10
|
+
* a truncated state.db.vault. A durable write therefore needs:
|
|
11
|
+
* 1. loop until every byte is written (zero/negative progress is EIO);
|
|
12
|
+
* 2. fsync the file before rename, fsync the directory after rename;
|
|
13
|
+
* 3. never leave a truncated target: write a same-directory temp file, verify
|
|
14
|
+
* its length, then atomically rename it into place; on any failure remove
|
|
15
|
+
* the temp file and rethrow (no 'best effort' success);
|
|
16
|
+
* 4. retry transient Windows/AV/OneDrive failures (EPERM/EBUSY/EACCES) with
|
|
17
|
+
* bounded exponential backoff instead of failing a user command once.
|
|
18
|
+
*
|
|
19
|
+
* This is a library-only module: it never imports node:sqlite and never writes
|
|
20
|
+
* to the user's home. Every function takes an optional `fs` implementation
|
|
21
|
+
* (default: node:fs), so tests can inject short writes and EPERM without root
|
|
22
|
+
* or a full disk (see test/fs-safe.test.js).
|
|
23
|
+
*
|
|
24
|
+
* bin/ integration contract (Wave 1):
|
|
25
|
+
* - vault seal: const tmp = writeAllToTempSync(out, bytes, { mode: 0o600 })
|
|
26
|
+
* ...verify by decrypting tmp...; commitTempFileSync(tmp, out)
|
|
27
|
+
* - pet-brief --out: atomicWriteFileSync(file, bytes)
|
|
28
|
+
* - backup/import: copyFileWithRetrySync(src, dst); fsyncFileSync(dst)
|
|
29
|
+
* - any rename/rm: renameWithRetrySync / rmWithRetrySync
|
|
30
|
+
* Also exported: tempPathForSync/tempPrefixForSync (so stale *.tmp-* scans can
|
|
31
|
+
* name the same scheme), describeFsError (ENOSPC/EACCES -> actionable text).
|
|
32
|
+
*/
|
|
33
|
+
import * as nodeFs from 'node:fs'
|
|
34
|
+
import { randomBytes } from 'node:crypto'
|
|
35
|
+
import { basename, dirname, join } from 'node:path'
|
|
36
|
+
|
|
37
|
+
/** errno values retried for transient filesystem contention (Windows AV/OneDrive). */
|
|
38
|
+
export const DEFAULT_RETRY_ERRNOS = Object.freeze(['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY', 'EAGAIN'])
|
|
39
|
+
/** Marker embedded in every temp file this module creates. */
|
|
40
|
+
export const TEMP_MARKER = '.tmp-'
|
|
41
|
+
const DEFAULT_TEMP_PREFIX = '.'
|
|
42
|
+
const MAX_BACKOFF_MS = 200
|
|
43
|
+
|
|
44
|
+
/** Synchronous sleep; used only between bounded retries. */
|
|
45
|
+
export function sleepSync(ms) {
|
|
46
|
+
if (!ms || ms <= 0) return
|
|
47
|
+
try {
|
|
48
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
|
|
49
|
+
} catch {
|
|
50
|
+
const end = Date.now() + ms
|
|
51
|
+
while (Date.now() < end) {}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Bounded exponential backoff: 10, 20, 40, 80, 160, 200, 200... ms. */
|
|
56
|
+
export function retryBackoffMs(attempt) {
|
|
57
|
+
return Math.min(MAX_BACKOFF_MS, 10 * 2 ** Math.max(0, attempt))
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function errnoOf(error) {
|
|
61
|
+
const code = error?.code ?? error?.errno
|
|
62
|
+
return typeof code === 'string' ? code : ''
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** True for transient errno values that a retry can legitimately fix. */
|
|
66
|
+
export function isRetryableFsError(error, errnos = DEFAULT_RETRY_ERRNOS) {
|
|
67
|
+
const allowed = errnos instanceof Set ? errnos : new Set(errnos)
|
|
68
|
+
const code = errnoOf(error)
|
|
69
|
+
if (code && allowed.has(code)) return true
|
|
70
|
+
const message = String(error?.message ?? error)
|
|
71
|
+
// libuv/windows sometimes surface EPERM/EBUSY in the message without a code
|
|
72
|
+
// (e.g. wrapped 'operation not permitted, rename ...'), so keep a narrow
|
|
73
|
+
// message fallback. ENOSPC must NOT be retried here.
|
|
74
|
+
return /operation not permitted|resource busy|permission denied/i.test(message) && /rename|unlink|rmdir|copyfile|fsync/i.test(message)
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Retry fn() when it throws a retryable fs error. fn receives the 0-based attempt.
|
|
79
|
+
* Non-retryable errors (ENOSPC, ENOENT, EIO, ...) are rethrown immediately.
|
|
80
|
+
*/
|
|
81
|
+
export function retryFsSync(fn, { retries = 5, errnos = DEFAULT_RETRY_ERRNOS, backoffMs = retryBackoffMs, sleep = sleepSync, onRetry } = {}) {
|
|
82
|
+
const allowed = errnos instanceof Set ? errnos : new Set(errnos)
|
|
83
|
+
let lastError
|
|
84
|
+
for (let attempt = 0; attempt <= Math.max(0, retries); attempt++) {
|
|
85
|
+
try {
|
|
86
|
+
return fn(attempt)
|
|
87
|
+
} catch (error) {
|
|
88
|
+
lastError = error
|
|
89
|
+
if (attempt >= retries || !isRetryableFsError(error, allowed)) throw error
|
|
90
|
+
try { onRetry?.(attempt, error) } catch {}
|
|
91
|
+
sleep(backoffMs(attempt))
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
throw lastError
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Write the whole buffer through fd, looping over short writes.
|
|
99
|
+
* Returns the number of bytes written (always buffer.length or throws).
|
|
100
|
+
* A 0/undefined/negative return is treated as EIO: reporting success after a
|
|
101
|
+
* short write is exactly the bug this helper exists to prevent.
|
|
102
|
+
*/
|
|
103
|
+
export function writeAllSync(fd, data, { fs = nodeFs } = {}) {
|
|
104
|
+
const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data)
|
|
105
|
+
let written = 0
|
|
106
|
+
while (written < buffer.length) {
|
|
107
|
+
const chunk = fs.writeSync(fd, buffer, written, buffer.length - written)
|
|
108
|
+
if (!Number.isFinite(chunk) || chunk <= 0) {
|
|
109
|
+
const error = new Error(`E_SHORT_WRITE: writeSync made no progress after ${written} of ${buffer.length} bytes; refusing to report a truncated write as success`)
|
|
110
|
+
error.code = 'E_SHORT_WRITE'
|
|
111
|
+
error.written = written
|
|
112
|
+
error.expected = buffer.length
|
|
113
|
+
throw error
|
|
114
|
+
}
|
|
115
|
+
written += chunk
|
|
116
|
+
}
|
|
117
|
+
return written
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** fsync a file descriptor or a path (opened read-only). */
|
|
121
|
+
export function fsyncFileSync(fileOrFd, { fs = nodeFs, retries = 5, errnos = DEFAULT_RETRY_ERRNOS, backoffMs = retryBackoffMs, sleep = sleepSync } = {}) {
|
|
122
|
+
if (typeof fileOrFd === 'number') {
|
|
123
|
+
return retryFsSync(() => fs.fsyncSync(fileOrFd), { retries, errnos, backoffMs, sleep })
|
|
124
|
+
}
|
|
125
|
+
return retryFsSync(() => {
|
|
126
|
+
const fd = fs.openSync(fileOrFd, 'r')
|
|
127
|
+
try { fs.fsyncSync(fd) } finally { try { fs.closeSync(fd) } catch {} }
|
|
128
|
+
}, { retries, errnos, backoffMs, sleep })
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* fsync a directory entry so a completed rename survives a crash. Windows
|
|
133
|
+
* returns EPERM for directory fsync (and FAT/network shares may not support it),
|
|
134
|
+
* so this is best-effort by contract: it returns a boolean, never throws.
|
|
135
|
+
*/
|
|
136
|
+
export function fsyncDirSync(dir, { fs = nodeFs } = {}) {
|
|
137
|
+
try {
|
|
138
|
+
const fd = fs.openSync(dir, 'r')
|
|
139
|
+
try { fs.fsyncSync(fd) } finally { try { fs.closeSync(fd) } catch {} }
|
|
140
|
+
return true
|
|
141
|
+
} catch {
|
|
142
|
+
return false
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** Same-directory temp path: hidden, pid+timestamp+random (unique per process). */
|
|
147
|
+
export function tempPathForSync(file) {
|
|
148
|
+
const unique = `${process.pid}-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`
|
|
149
|
+
return join(dirname(file), `${DEFAULT_TEMP_PREFIX}${basename(file)}${TEMP_MARKER}${unique}`)
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** Prefix shared by tempPathForSync paths (for stale-temp scans/cleanup). */
|
|
153
|
+
export function tempPrefixForSync(file) {
|
|
154
|
+
return join(dirname(file), `${DEFAULT_TEMP_PREFIX}${basename(file)}${TEMP_MARKER}`)
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** mkdir -p with retry; mode only applies to directories it creates. */
|
|
158
|
+
export function mkdirWithRetrySync(dir, { fs = nodeFs, mode = 0o700, recursive = true, retries = 3 } = {}) {
|
|
159
|
+
retryFsSync(() => fs.mkdirSync(dir, { recursive, mode }), { retries })
|
|
160
|
+
return dir
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** rename() with retry on transient EPERM/EBUSY/EACCES. */
|
|
164
|
+
export function renameWithRetrySync(from, to, { fs = nodeFs, retries = 5, errnos = DEFAULT_RETRY_ERRNOS, backoffMs = retryBackoffMs, sleep = sleepSync } = {}) {
|
|
165
|
+
retryFsSync(() => fs.renameSync(from, to), { retries, errnos, backoffMs, sleep })
|
|
166
|
+
return to
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** rm with retry; force:true so a missing target is not an error. */
|
|
170
|
+
export function rmWithRetrySync(target, { fs = nodeFs, retries = 3, force = true, errnos = DEFAULT_RETRY_ERRNOS, backoffMs = retryBackoffMs, sleep = sleepSync } = {}) {
|
|
171
|
+
try {
|
|
172
|
+
retryFsSync(() => fs.rmSync(target, { force }), { retries, errnos, backoffMs, sleep })
|
|
173
|
+
return true
|
|
174
|
+
} catch (error) {
|
|
175
|
+
if (force && errnoOf(error) === 'ENOENT') return false
|
|
176
|
+
throw error
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** copyFile with retry, then chmod 0600 unless disabled (backups hold plaintext). */
|
|
181
|
+
export function copyFileWithRetrySync(from, to, { fs = nodeFs, mode = 0o600, chmod = true, retries = 5, errnos = DEFAULT_RETRY_ERRNOS, backoffMs = retryBackoffMs, sleep = sleepSync } = {}) {
|
|
182
|
+
retryFsSync(() => fs.copyFileSync(from, to), { retries, errnos, backoffMs, sleep })
|
|
183
|
+
if (chmod && typeof fs.chmodSync === 'function') {
|
|
184
|
+
try { fs.chmodSync(to, mode) } catch {}
|
|
185
|
+
}
|
|
186
|
+
return to
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
function cleanupTemp(fs, tmp) {
|
|
190
|
+
try { fs.rmSync(tmp, { force: true }) } catch {}
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Write data to a fresh same-directory temp file, fsync it, verify its length,
|
|
195
|
+
* and return the temp path. The caller commits with commitTempFileSync() (and
|
|
196
|
+
* must call rmWithRetrySync(tmp) if it abandons the file after verification).
|
|
197
|
+
* On any failure the temp file is removed before the error is rethrown.
|
|
198
|
+
*/
|
|
199
|
+
export function writeAllToTempSync(file, data, { fs = nodeFs, mode = 0o600, fsync = true, retries = 5, tempPath, expectedBytes } = {}) {
|
|
200
|
+
const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data)
|
|
201
|
+
const expected = Number.isFinite(expectedBytes) ? expectedBytes : buffer.length
|
|
202
|
+
mkdirWithRetrySync(dirname(file), { fs })
|
|
203
|
+
const tmp = tempPath ?? tempPathForSync(file)
|
|
204
|
+
let fd = null
|
|
205
|
+
let created = false
|
|
206
|
+
try {
|
|
207
|
+
fd = fs.openSync(tmp, 'wx', mode)
|
|
208
|
+
created = true
|
|
209
|
+
writeAllSync(fd, buffer, { fs })
|
|
210
|
+
if (fsync) fsyncFileSync(fd, { fs, retries })
|
|
211
|
+
fs.closeSync(fd)
|
|
212
|
+
fd = null
|
|
213
|
+
if (typeof fs.chmodSync === 'function') { try { fs.chmodSync(tmp, mode) } catch {} }
|
|
214
|
+
const size = fs.statSync(tmp).size
|
|
215
|
+
if (size !== expected) {
|
|
216
|
+
const error = new Error(`E_SHORT_WRITE: wrote ${size} of ${expected} bytes to ${tmp}; refusing to commit a truncated file`)
|
|
217
|
+
error.code = 'E_SHORT_WRITE'
|
|
218
|
+
error.written = size
|
|
219
|
+
error.expected = expected
|
|
220
|
+
throw error
|
|
221
|
+
}
|
|
222
|
+
return tmp
|
|
223
|
+
} catch (error) {
|
|
224
|
+
if (fd !== null) { try { fs.closeSync(fd) } catch {} }
|
|
225
|
+
// Only remove the temp file when this call created it: a pre-existing file
|
|
226
|
+
// at the same path belongs to someone else and is never deleted.
|
|
227
|
+
if (created) cleanupTemp(fs, tmp)
|
|
228
|
+
throw error
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Atomically install a verified temp file at `file` (same directory, atomic
|
|
234
|
+
* rename). On failure the temp file is removed and the previous target is left
|
|
235
|
+
* untouched (rename is all-or-nothing).
|
|
236
|
+
*/
|
|
237
|
+
export function commitTempFileSync(tmp, file, { fs = nodeFs, mode = 0o600, retries = 5, errnos = DEFAULT_RETRY_ERRNOS, backoffMs = retryBackoffMs, sleep = sleepSync, fsyncDir = true } = {}) {
|
|
238
|
+
try {
|
|
239
|
+
renameWithRetrySync(tmp, file, { fs, retries, errnos, backoffMs, sleep })
|
|
240
|
+
if (typeof fs.chmodSync === 'function') { try { fs.chmodSync(file, mode) } catch {} }
|
|
241
|
+
if (fsyncDir) fsyncDirSync(dirname(file), { fs })
|
|
242
|
+
return file
|
|
243
|
+
} catch (error) {
|
|
244
|
+
cleanupTemp(fs, tmp)
|
|
245
|
+
throw error
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/**
|
|
250
|
+
* Durable atomic write of a whole file. This is the one-call API for bin/
|
|
251
|
+
* outputs that must never be installed truncated (vault seal, pet-brief --out,
|
|
252
|
+
* exports). Throws on ENOSPC/EIO/permission errors after removing the temp file.
|
|
253
|
+
*/
|
|
254
|
+
export function atomicWriteFileSync(file, data, { fs = nodeFs, mode = 0o600, fsync = true, retries = 5, verifyBytes = true } = {}) {
|
|
255
|
+
const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data)
|
|
256
|
+
const tmp = writeAllToTempSync(file, buffer, { fs, mode, fsync, retries, expectedBytes: verifyBytes ? buffer.length : undefined })
|
|
257
|
+
return commitTempFileSync(tmp, file, { fs, mode, retries })
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/** Human-actionable one-line explanation for a failed durable write. */
|
|
261
|
+
export function describeFsError(error, { action = 'writing', path = '', target = '' } = {}) {
|
|
262
|
+
const code = errnoOf(error)
|
|
263
|
+
const message = String(error?.message ?? error)
|
|
264
|
+
const where = target || path
|
|
265
|
+
if (/ENOSPC|EDQUOT/.test(code) || /no space left|disk quota exceeded/i.test(message)) {
|
|
266
|
+
return `E_NO_SPACE: not enough disk space while ${action}${where ? ` ${where}` : ''} (${code || 'ENOSPC'}); the temp file was removed and no truncated file was installed`
|
|
267
|
+
}
|
|
268
|
+
if (/EACCES|EPERM|EROFS/.test(code)) {
|
|
269
|
+
return `E_FS_PERMISSION: ${action}${where ? ` ${where}` : ''} was denied (${code}); check file/directory permissions, or close the program (antivirus/OneDrive/sync client) that may be holding it`
|
|
270
|
+
}
|
|
271
|
+
if (/EIO/.test(code)) return `E_IO: the filesystem reported an I/O error while ${action}${where ? ` ${where}` : ''}; the write was aborted and the temp file removed`
|
|
272
|
+
return `${action}${where ? ` ${where}` : ''} failed: ${message}`
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/** Wrap an fs error with the actionable message while preserving code/errno. */
|
|
276
|
+
export function wrapFsError(error, context = {}) {
|
|
277
|
+
const wrapped = new Error(describeFsError(error, context))
|
|
278
|
+
if (error?.code !== undefined) wrapped.code = error.code
|
|
279
|
+
if (error?.errno !== undefined) wrapped.errno = error.errno
|
|
280
|
+
wrapped.cause = error
|
|
281
|
+
return wrapped
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
export { nodeFs as defaultFs }
|