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/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
- return {
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
- `format: ${MANIFEST_FORMAT} v${MANIFEST_VERSION}`,
622
- `created: ${createdAt}`,
623
- `entries: ${entries.length} (commitment ${counts.commitment}, fact ${counts.fact}, preference ${counts.preference}, unknown ${counts.unknown})`,
624
- `sources: ${sourceCount} resolved, ${missingCount} missing`,
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
- return {
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
- if (!sources.length && !missing.length) {
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
- `missing: ${item.reason ?? 'unknown'}`,
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 }