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/kb-facts.js
ADDED
|
@@ -0,0 +1,429 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fact time travel (0.4.0, read-only; no migration).
|
|
3
|
+
*
|
|
4
|
+
* The facts table already stores valid_from / valid_to / supersedes /
|
|
5
|
+
* superseded_by / deleted_at; this module is the read side that 0.3.2 only had
|
|
6
|
+
* partially. Three time concepts are kept distinct:
|
|
7
|
+
* - validFrom/validTo: when the fact was true in the world (the as-of axis);
|
|
8
|
+
* - recordedAt: when the ledger learned it;
|
|
9
|
+
* - expiredAt: when the system noticed it stopped being current (never used for
|
|
10
|
+
* as-of selection, only displayed).
|
|
11
|
+
*
|
|
12
|
+
* as-of semantics (45 section 3.7): at instant t a fact applies when
|
|
13
|
+
* effectiveFrom = validFrom ?? recordedAt <= t
|
|
14
|
+
* and (validTo is null or t < validTo)
|
|
15
|
+
* status is deliberately NOT filtered: a superseded fact was true in the past.
|
|
16
|
+
* Deleted facts are excluded unless includeDeleted, and then only facts whose
|
|
17
|
+
* deletedAt is after t are kept. For one (subject, predicate, matter) group the
|
|
18
|
+
* row with the largest effectiveFrom wins; ties fall back to recordedAt and id.
|
|
19
|
+
* A date-only --at is the start of that Asia/Shanghai calendar day converted to
|
|
20
|
+
* a UTC instant (never a UTC day slice).
|
|
21
|
+
*
|
|
22
|
+
* Pure read module: no writes, no model, no network, no console output.
|
|
23
|
+
*/
|
|
24
|
+
import { entityError } from './sqlite.js'
|
|
25
|
+
import { stripBidiControls, stripControlChars, stripTerminalSequences } from './text-safe.js'
|
|
26
|
+
|
|
27
|
+
export const FACT_AS_OF_LIMIT = 200
|
|
28
|
+
export const FACT_AS_OF_LIMIT_MAX = 500
|
|
29
|
+
export const FACT_EVIDENCE_QUOTE_MAX = 200
|
|
30
|
+
export const FACT_HISTORY_MAX = 500
|
|
31
|
+
|
|
32
|
+
const SHANGHAI_OFFSET_MS = 8 * 3600_000
|
|
33
|
+
const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/
|
|
34
|
+
const LOCAL_TIME_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?$/
|
|
35
|
+
|
|
36
|
+
/* -------------------------------------------------------------------------- */
|
|
37
|
+
/* helpers */
|
|
38
|
+
/* -------------------------------------------------------------------------- */
|
|
39
|
+
|
|
40
|
+
function assertStore(store) {
|
|
41
|
+
if (!store || !store.db || typeof store.db.prepare !== 'function' || typeof store.read !== 'function') {
|
|
42
|
+
throw new TypeError('kb-facts requires an opened SqliteStore')
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function sanitizeQuote(value) {
|
|
47
|
+
const text = stripControlChars(stripBidiControls(stripTerminalSequences(String(value ?? ''))), { keepNewlines: false, keepTabs: false, replacement: ' ' })
|
|
48
|
+
.replace(/\s+/gu, ' ').trim()
|
|
49
|
+
const chars = Array.from(text)
|
|
50
|
+
return chars.length <= FACT_EVIDENCE_QUOTE_MAX ? text : chars.slice(0, FACT_EVIDENCE_QUOTE_MAX).join('')
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function parseJson(value) {
|
|
54
|
+
if (value === undefined || value === null) return undefined
|
|
55
|
+
try { return typeof value === 'string' ? JSON.parse(value) : value } catch { return undefined }
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function parseEvidence(value) {
|
|
59
|
+
const parsed = parseJson(value)
|
|
60
|
+
if (!Array.isArray(parsed)) return []
|
|
61
|
+
const out = []
|
|
62
|
+
for (const item of parsed) {
|
|
63
|
+
if (!item || typeof item !== 'object') continue
|
|
64
|
+
const quote = item.quote === undefined || item.quote === null ? null : sanitizeQuote(item.quote)
|
|
65
|
+
const ref = item.ref === undefined || item.ref === null
|
|
66
|
+
? (item.sessionId ? String(item.sessionId) + '#' + String(item.turnId ?? '') : null)
|
|
67
|
+
: String(item.ref)
|
|
68
|
+
const source = item.source && typeof item.source === 'object' ? item.source : null
|
|
69
|
+
if (!quote && !ref) continue
|
|
70
|
+
out.push({
|
|
71
|
+
...(quote ? { quote } : {}),
|
|
72
|
+
...(ref ? { ref } : {}),
|
|
73
|
+
...(source ? { source } : {}),
|
|
74
|
+
})
|
|
75
|
+
if (out.length >= 10) break
|
|
76
|
+
}
|
|
77
|
+
return out
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function mapFact(row) {
|
|
81
|
+
if (!row) return null
|
|
82
|
+
return {
|
|
83
|
+
id: String(row.id),
|
|
84
|
+
...(row.matter_id === null || row.matter_id === undefined ? {} : { matterId: String(row.matter_id) }),
|
|
85
|
+
subject: String(row.subject ?? ''),
|
|
86
|
+
predicate: String(row.predicate ?? ''),
|
|
87
|
+
object: String(row.object ?? ''),
|
|
88
|
+
recordedAt: String(row.recorded_at ?? ''),
|
|
89
|
+
...(row.expired_at === null || row.expired_at === undefined ? {} : { expiredAt: String(row.expired_at) }),
|
|
90
|
+
authority: String(row.authority ?? ''),
|
|
91
|
+
confidence: Number(row.confidence ?? 0),
|
|
92
|
+
...(row.source === null || row.source === undefined ? {} : { source: parseJson(row.source) }),
|
|
93
|
+
evidence: parseEvidence(row.evidence),
|
|
94
|
+
status: String(row.status ?? ''),
|
|
95
|
+
...(row.valid_from === null || row.valid_from === undefined ? {} : { validFrom: String(row.valid_from) }),
|
|
96
|
+
...(row.valid_to === null || row.valid_to === undefined ? {} : { validTo: String(row.valid_to) }),
|
|
97
|
+
...(row.supersedes === null || row.supersedes === undefined ? {} : { supersedes: String(row.supersedes) }),
|
|
98
|
+
...(row.superseded_by === null || row.superseded_by === undefined ? {} : { supersededBy: String(row.superseded_by) }),
|
|
99
|
+
...(row.shadowed_by === null || row.shadowed_by === undefined ? {} : { shadowedBy: String(row.shadowed_by) }),
|
|
100
|
+
...(row.last_seen_at === null || row.last_seen_at === undefined ? {} : { lastSeenAt: String(row.last_seen_at) }),
|
|
101
|
+
...(row.deleted_at === null || row.deleted_at === undefined ? {} : { deletedAt: String(row.deleted_at) }),
|
|
102
|
+
...(row.deleted_reason === null || row.deleted_reason === undefined ? {} : { deletedReason: String(row.deleted_reason) }),
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function loadFact(store, id) {
|
|
107
|
+
return mapFact(store.db.prepare('SELECT * FROM facts WHERE id = ?').get(String(id)))
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** Parse a stored timestamp to a UTC instant; date-only means the Shanghai day start. */
|
|
111
|
+
export function instantOfFactTime(value) {
|
|
112
|
+
if (value === undefined || value === null) return null
|
|
113
|
+
if (typeof value === 'number') return Number.isFinite(value) ? value : null
|
|
114
|
+
if (typeof value !== 'string') return null
|
|
115
|
+
const text = value.trim()
|
|
116
|
+
if (!text) return null
|
|
117
|
+
if (DATE_ONLY_RE.test(text)) {
|
|
118
|
+
const parts = text.split('-').map(Number)
|
|
119
|
+
return Date.UTC(parts[0], parts[1] - 1, parts[2]) - SHANGHAI_OFFSET_MS
|
|
120
|
+
}
|
|
121
|
+
if (LOCAL_TIME_RE.test(text)) {
|
|
122
|
+
const ms = Date.parse(text.replace(' ', 'T') + '+08:00')
|
|
123
|
+
return Number.isFinite(ms) ? ms : null
|
|
124
|
+
}
|
|
125
|
+
const ms = Date.parse(text)
|
|
126
|
+
return Number.isFinite(ms) ? ms : null
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** UTC instant -> Asia/Shanghai calendar day (YYYY-MM-DD). */
|
|
130
|
+
export function shanghaiDayOf(ms) {
|
|
131
|
+
return new Date(ms + SHANGHAI_OFFSET_MS).toISOString().slice(0, 10)
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Normalize an --at selector to {ms, iso, asOfLocalDay}. */
|
|
135
|
+
export function normalizeAsOf(value) {
|
|
136
|
+
if (typeof value !== 'string' || !value.trim()) {
|
|
137
|
+
throw entityError('E_USAGE', 'an as-of instant is required', 'use --at YYYY-MM-DD or an ISO 8601 datetime')
|
|
138
|
+
}
|
|
139
|
+
const text = value.trim()
|
|
140
|
+
const ms = instantOfFactTime(text)
|
|
141
|
+
if (ms === null || !Number.isFinite(ms)) {
|
|
142
|
+
throw entityError('E_USAGE', 'invalid as-of instant: ' + text, 'use --at YYYY-MM-DD or an ISO 8601 datetime')
|
|
143
|
+
}
|
|
144
|
+
if (DATE_ONLY_RE.test(text) && shanghaiDayOf(ms) !== text) {
|
|
145
|
+
throw entityError('E_USAGE', 'invalid calendar date: ' + text)
|
|
146
|
+
}
|
|
147
|
+
return { ms, iso: new Date(ms).toISOString(), asOfLocalDay: shanghaiDayOf(ms) }
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
function clientIdForMatter(store, matterId, cache) {
|
|
151
|
+
if (matterId === undefined || matterId === null) return null
|
|
152
|
+
if (cache.has(matterId)) return cache.get(matterId)
|
|
153
|
+
const matter = store.getMatter(String(matterId))
|
|
154
|
+
const clientId = matter && matter.clientId !== undefined && matter.clientId !== null ? String(matter.clientId) : null
|
|
155
|
+
cache.set(matterId, clientId)
|
|
156
|
+
return clientId
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function kbSourcesForFact(store, factId) {
|
|
160
|
+
const hasLinks = Boolean(store.db.prepare("SELECT name FROM sqlite_master WHERE name = 'kb_fact_links' AND type = 'table'").get())
|
|
161
|
+
if (!hasLinks) return []
|
|
162
|
+
const hasDocuments = Boolean(store.db.prepare("SELECT name FROM sqlite_master WHERE name = 'kb_documents' AND type = 'table'").get())
|
|
163
|
+
if (!hasDocuments) return []
|
|
164
|
+
const rows = store.db.prepare("SELECT l.doc_id, l.chunk_id, l.relation, d.title FROM kb_fact_links l JOIN kb_documents d ON d.id = l.doc_id WHERE l.fact_id = ? AND d.status = 'active' AND d.deleted_at IS NULL ORDER BY l.doc_id ASC, l.relation ASC").all(String(factId))
|
|
165
|
+
return rows.map((row) => ({
|
|
166
|
+
docId: String(row.doc_id),
|
|
167
|
+
title: String(row.title),
|
|
168
|
+
...(row.chunk_id === null || row.chunk_id === undefined ? {} : { chunkId: String(row.chunk_id) }),
|
|
169
|
+
relation: String(row.relation),
|
|
170
|
+
}))
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
function factView(fact, { clientId = null, includeDeleted = true } = {}) {
|
|
174
|
+
const fallback = { validFromFromRecordedAt: fact.validFrom === undefined }
|
|
175
|
+
const view = {
|
|
176
|
+
id: fact.id,
|
|
177
|
+
subject: fact.subject,
|
|
178
|
+
predicate: fact.predicate,
|
|
179
|
+
object: fact.object,
|
|
180
|
+
...(fact.matterId === undefined ? {} : { matterId: fact.matterId }),
|
|
181
|
+
...(clientId === null ? {} : { clientId }),
|
|
182
|
+
authority: fact.authority,
|
|
183
|
+
confidence: fact.confidence,
|
|
184
|
+
status: fact.status,
|
|
185
|
+
recordedAt: fact.recordedAt,
|
|
186
|
+
...(fact.validFrom === undefined ? {} : { validFrom: fact.validFrom }),
|
|
187
|
+
...(fact.validTo === undefined ? {} : { validTo: fact.validTo }),
|
|
188
|
+
...(fact.expiredAt === undefined ? {} : { expiredAt: fact.expiredAt }),
|
|
189
|
+
...(fact.supersedes === undefined ? {} : { supersedes: fact.supersedes }),
|
|
190
|
+
...(fact.supersededBy === undefined ? {} : { supersededBy: fact.supersededBy }),
|
|
191
|
+
...(fact.shadowedBy === undefined ? {} : { shadowedBy: fact.shadowedBy }),
|
|
192
|
+
...(fact.lastSeenAt === undefined ? {} : { lastSeenAt: fact.lastSeenAt }),
|
|
193
|
+
...(includeDeleted && fact.deletedAt !== undefined ? { deletedAt: fact.deletedAt } : {}),
|
|
194
|
+
...(includeDeleted && fact.deletedReason !== undefined ? { deletedReason: fact.deletedReason } : {}),
|
|
195
|
+
evidence: fact.evidence,
|
|
196
|
+
fallback,
|
|
197
|
+
}
|
|
198
|
+
return view
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/* -------------------------------------------------------------------------- */
|
|
202
|
+
/* fact show */
|
|
203
|
+
/* -------------------------------------------------------------------------- */
|
|
204
|
+
|
|
205
|
+
/** One fact with its supersede pointers, evidence and explicit KB sources. */
|
|
206
|
+
export function factShow(store, id, options = {}) {
|
|
207
|
+
assertStore(store)
|
|
208
|
+
const key = typeof id === 'string' ? id.trim() : ''
|
|
209
|
+
if (!key) throw entityError('E_KB_INVALID', 'fact id is required')
|
|
210
|
+
const includeDeleted = options.includeDeleted === true
|
|
211
|
+
return store.read(() => {
|
|
212
|
+
const fact = loadFact(store, key)
|
|
213
|
+
if (!fact) throw entityError('E_FACT_NOT_FOUND', 'unknown fact: ' + key, 'advisers fact ls')
|
|
214
|
+
if (fact.deletedAt !== undefined && !includeDeleted) throw entityError('E_FACT_NOT_FOUND', 'unknown fact: ' + key + ' (deleted)', 'pass --include-deleted to inspect a tombstone')
|
|
215
|
+
const cache = new Map()
|
|
216
|
+
const clientId = clientIdForMatter(store, fact.matterId, cache)
|
|
217
|
+
const warnings = []
|
|
218
|
+
if (fact.deletedAt !== undefined) warnings.push('fact is a tombstone')
|
|
219
|
+
if (fact.validFrom === undefined) warnings.push('validFrom is missing; recordedAt is the effective start')
|
|
220
|
+
return {
|
|
221
|
+
ok: true,
|
|
222
|
+
command: 'fact show',
|
|
223
|
+
fact: factView(fact, { clientId, includeDeleted: true }),
|
|
224
|
+
kbSources: kbSourcesForFact(store, fact.id),
|
|
225
|
+
warnings,
|
|
226
|
+
includeDeleted,
|
|
227
|
+
}
|
|
228
|
+
})
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/* -------------------------------------------------------------------------- */
|
|
232
|
+
/* fact history */
|
|
233
|
+
/* -------------------------------------------------------------------------- */
|
|
234
|
+
|
|
235
|
+
/** Walk the supersede chain (oldest -> newest), tolerating broken links/cycles. */
|
|
236
|
+
export function factHistory(store, id, options = {}) {
|
|
237
|
+
assertStore(store)
|
|
238
|
+
const key = typeof id === 'string' ? id.trim() : ''
|
|
239
|
+
if (!key) throw entityError('E_KB_INVALID', 'fact id is required')
|
|
240
|
+
const includeDeleted = options.includeDeleted !== false
|
|
241
|
+
return store.read(() => {
|
|
242
|
+
const root = loadFact(store, key)
|
|
243
|
+
if (!root) throw entityError('E_FACT_NOT_FOUND', 'unknown fact: ' + key, 'advisers fact ls')
|
|
244
|
+
const warnings = []
|
|
245
|
+
const byId = new Map([[root.id, root]])
|
|
246
|
+
const load = (factId) => {
|
|
247
|
+
if (byId.has(factId)) return byId.get(factId)
|
|
248
|
+
const fact = loadFact(store, factId)
|
|
249
|
+
if (fact) byId.set(fact.id, fact)
|
|
250
|
+
return fact ?? null
|
|
251
|
+
}
|
|
252
|
+
// 1) walk supersedes back to the oldest row
|
|
253
|
+
const backward = []
|
|
254
|
+
const seenBack = new Set()
|
|
255
|
+
let cursor = root
|
|
256
|
+
while (cursor) {
|
|
257
|
+
if (seenBack.has(cursor.id)) { warnings.push('cycle in supersedes chain at ' + cursor.id); break }
|
|
258
|
+
seenBack.add(cursor.id)
|
|
259
|
+
backward.push(cursor)
|
|
260
|
+
if (cursor.supersedes === undefined) break
|
|
261
|
+
const previous = load(cursor.supersedes)
|
|
262
|
+
if (!previous) { warnings.push('broken supersedes link: ' + cursor.supersedes + ' is missing'); break }
|
|
263
|
+
cursor = previous
|
|
264
|
+
}
|
|
265
|
+
const earliest = backward[backward.length - 1]
|
|
266
|
+
// 2) walk supersededBy forward from the oldest row to the newest
|
|
267
|
+
const ordered = []
|
|
268
|
+
const seen = new Set()
|
|
269
|
+
cursor = earliest
|
|
270
|
+
while (cursor) {
|
|
271
|
+
if (seen.has(cursor.id)) { warnings.push('cycle in supersededBy chain at ' + cursor.id); break }
|
|
272
|
+
seen.add(cursor.id)
|
|
273
|
+
ordered.push(cursor)
|
|
274
|
+
if (ordered.length >= FACT_HISTORY_MAX) { warnings.push('history truncated at ' + FACT_HISTORY_MAX + ' rows'); break }
|
|
275
|
+
if (cursor.supersededBy === undefined) break
|
|
276
|
+
const next = load(cursor.supersededBy)
|
|
277
|
+
if (!next) { warnings.push('broken supersededBy link: ' + cursor.supersededBy + ' is missing'); break }
|
|
278
|
+
cursor = next
|
|
279
|
+
}
|
|
280
|
+
for (const fact of backward) {
|
|
281
|
+
if (!seen.has(fact.id)) warnings.push('fact ' + fact.id + ' is only reachable through supersedes')
|
|
282
|
+
}
|
|
283
|
+
const cache = new Map()
|
|
284
|
+
const items = ordered
|
|
285
|
+
.filter((fact) => includeDeleted || fact.deletedAt === undefined)
|
|
286
|
+
.map((fact) => factView(fact, { clientId: clientIdForMatter(store, fact.matterId, cache), includeDeleted: true }))
|
|
287
|
+
return {
|
|
288
|
+
ok: true,
|
|
289
|
+
command: 'fact history',
|
|
290
|
+
rootId: root.id,
|
|
291
|
+
items,
|
|
292
|
+
warnings,
|
|
293
|
+
counts: { items: items.length },
|
|
294
|
+
includeDeleted,
|
|
295
|
+
}
|
|
296
|
+
})
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/* -------------------------------------------------------------------------- */
|
|
300
|
+
/* fact as-of */
|
|
301
|
+
/* -------------------------------------------------------------------------- */
|
|
302
|
+
|
|
303
|
+
function clampLimit(value, fallback, max) {
|
|
304
|
+
if (value === undefined || value === null) return fallback
|
|
305
|
+
const number = Number(value)
|
|
306
|
+
if (!Number.isInteger(number) || number < 1) return fallback
|
|
307
|
+
return Math.min(number, max)
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
function compareCandidates(a, b) {
|
|
311
|
+
if (a.effectiveMs !== b.effectiveMs) return a.effectiveMs - b.effectiveMs
|
|
312
|
+
const aRecorded = a.recordedMs === null ? Number.NEGATIVE_INFINITY : a.recordedMs
|
|
313
|
+
const bRecorded = b.recordedMs === null ? Number.NEGATIVE_INFINITY : b.recordedMs
|
|
314
|
+
if (aRecorded !== bRecorded) return aRecorded - bRecorded
|
|
315
|
+
return a.fact.id < b.fact.id ? -1 : a.fact.id > b.fact.id ? 1 : 0
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
function pushWarning(warnings, message) {
|
|
319
|
+
if (!warnings.includes(message)) warnings.push(message)
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* The facts that were true at one instant, one row per (subject, predicate,
|
|
324
|
+
* matter) group. Read-only; deterministic for the same rows and --at.
|
|
325
|
+
*/
|
|
326
|
+
export function factAsOf(store, options = {}) {
|
|
327
|
+
assertStore(store)
|
|
328
|
+
const at = normalizeAsOf(options.at)
|
|
329
|
+
const includeDeleted = options.includeDeleted === true
|
|
330
|
+
const limit = clampLimit(options.limit, FACT_AS_OF_LIMIT, FACT_AS_OF_LIMIT_MAX)
|
|
331
|
+
const matterId = options.matterId === undefined || options.matterId === null ? null : String(options.matterId)
|
|
332
|
+
const clientId = options.clientId === undefined || options.clientId === null ? null : String(options.clientId)
|
|
333
|
+
const subject = options.subject === undefined || options.subject === null ? null : String(options.subject)
|
|
334
|
+
const predicate = options.predicate === undefined || options.predicate === null ? null : String(options.predicate)
|
|
335
|
+
return store.read(() => {
|
|
336
|
+
const warnings = []
|
|
337
|
+
if (matterId !== null && !store.getMatter(matterId)) throw entityError('E_MATTER_NOT_FOUND', 'unknown matter: ' + matterId, 'advisers matter ls')
|
|
338
|
+
let clientMatterIds = null
|
|
339
|
+
if (clientId !== null) {
|
|
340
|
+
if (!store.getClient(clientId)) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + clientId, 'advisers client ls')
|
|
341
|
+
clientMatterIds = store.listMattersByClient(clientId).map((matter) => String(matter.id))
|
|
342
|
+
if (!clientMatterIds.length) return { ok: true, command: 'fact as-of', at: at.iso, asOfLocalDay: at.asOfLocalDay, items: [], counts: { groups: 0, candidates: 0, overlappingGroups: 0 }, warnings, degraded: [], includeDeleted, truncated: false }
|
|
343
|
+
}
|
|
344
|
+
const where = []
|
|
345
|
+
const params = []
|
|
346
|
+
if (!includeDeleted) where.push('deleted_at IS NULL')
|
|
347
|
+
if (matterId !== null) { where.push('matter_id = ?'); params.push(matterId) }
|
|
348
|
+
if (clientMatterIds !== null) { where.push('matter_id IN (' + clientMatterIds.map(() => '?').join(',') + ')'); params.push(...clientMatterIds) }
|
|
349
|
+
if (subject !== null) { where.push('subject = ?'); params.push(subject) }
|
|
350
|
+
if (predicate !== null) { where.push('predicate = ?'); params.push(predicate) }
|
|
351
|
+
const rows = store.db.prepare('SELECT * FROM facts' + (where.length ? ' WHERE ' + where.join(' AND ') : '') + ' ORDER BY subject ASC, predicate ASC, matter_id ASC, recorded_at ASC, id ASC').all(...params)
|
|
352
|
+
let invalidTimestamps = 0
|
|
353
|
+
let deletedFiltered = 0
|
|
354
|
+
const groups = new Map()
|
|
355
|
+
let candidates = 0
|
|
356
|
+
for (const row of rows) {
|
|
357
|
+
const fact = mapFact(row)
|
|
358
|
+
if (fact.deletedAt !== undefined) {
|
|
359
|
+
const deletedMs = instantOfFactTime(fact.deletedAt)
|
|
360
|
+
if (!includeDeleted || deletedMs === null || deletedMs <= at.ms) { deletedFiltered += 1; continue }
|
|
361
|
+
}
|
|
362
|
+
const effectiveFrom = fact.validFrom === undefined ? fact.recordedAt : fact.validFrom
|
|
363
|
+
const effectiveMs = instantOfFactTime(effectiveFrom)
|
|
364
|
+
if (effectiveMs === null) { invalidTimestamps += 1; continue }
|
|
365
|
+
if (effectiveMs > at.ms) continue
|
|
366
|
+
if (fact.validTo !== undefined) {
|
|
367
|
+
const validToMs = instantOfFactTime(fact.validTo)
|
|
368
|
+
if (validToMs === null) { invalidTimestamps += 1; continue }
|
|
369
|
+
if (at.ms >= validToMs) continue
|
|
370
|
+
}
|
|
371
|
+
candidates += 1
|
|
372
|
+
const groupKey = fact.subject + '\u0000' + fact.predicate + '\u0000' + (fact.matterId ?? '')
|
|
373
|
+
const recordedMs = instantOfFactTime(fact.recordedAt)
|
|
374
|
+
const entry = { fact, effectiveMs, recordedMs }
|
|
375
|
+
const group = groups.get(groupKey)
|
|
376
|
+
if (!group) groups.set(groupKey, { candidates: [entry], selected: entry })
|
|
377
|
+
else {
|
|
378
|
+
group.candidates.push(entry)
|
|
379
|
+
if (compareCandidates(entry, group.selected) > 0) group.selected = entry
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
if (invalidTimestamps > 0) pushWarning(warnings, invalidTimestamps + ' fact(s) skipped because a timestamp could not be parsed')
|
|
383
|
+
if (deletedFiltered > 0) pushWarning(warnings, deletedFiltered + ' deleted fact(s) excluded')
|
|
384
|
+
let overlappingGroups = 0
|
|
385
|
+
for (const group of groups.values()) if (group.candidates.length > 1) overlappingGroups += 1
|
|
386
|
+
if (overlappingGroups > 0) pushWarning(warnings, overlappingGroups + ' group(s) have overlapping valid intervals; the latest effective start was selected')
|
|
387
|
+
const cache = new Map()
|
|
388
|
+
const items = []
|
|
389
|
+
let fallbackCount = 0
|
|
390
|
+
for (const group of groups.values()) {
|
|
391
|
+
const entry = group.selected
|
|
392
|
+
const view = factView(entry.fact, { clientId: clientIdForMatter(store, entry.fact.matterId, cache), includeDeleted: true })
|
|
393
|
+
if (view.fallback.validFromFromRecordedAt) fallbackCount += 1
|
|
394
|
+
items.push({ ...view, effectiveFrom: entry.fact.validFrom === undefined ? entry.fact.recordedAt : entry.fact.validFrom })
|
|
395
|
+
}
|
|
396
|
+
items.sort((a, b) => (a.subject < b.subject ? -1 : a.subject > b.subject ? 1
|
|
397
|
+
: a.predicate < b.predicate ? -1 : a.predicate > b.predicate ? 1
|
|
398
|
+
: (a.matterId ?? '') < (b.matterId ?? '') ? -1 : (a.matterId ?? '') > (b.matterId ?? '') ? 1
|
|
399
|
+
: a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
|
|
400
|
+
const total = items.length
|
|
401
|
+
const page = items.slice(0, limit)
|
|
402
|
+
const degraded = fallbackCount > 0 ? ['valid_from_fallback_recorded_at'] : []
|
|
403
|
+
return {
|
|
404
|
+
ok: true,
|
|
405
|
+
command: 'fact as-of',
|
|
406
|
+
at: at.iso,
|
|
407
|
+
asOfLocalDay: at.asOfLocalDay,
|
|
408
|
+
items: page,
|
|
409
|
+
counts: { groups: total, candidates, overlappingGroups },
|
|
410
|
+
warnings,
|
|
411
|
+
degraded,
|
|
412
|
+
includeDeleted,
|
|
413
|
+
truncated: total > page.length,
|
|
414
|
+
}
|
|
415
|
+
})
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
export default Object.freeze({
|
|
419
|
+
FACT_AS_OF_LIMIT,
|
|
420
|
+
FACT_AS_OF_LIMIT_MAX,
|
|
421
|
+
FACT_EVIDENCE_QUOTE_MAX,
|
|
422
|
+
FACT_HISTORY_MAX,
|
|
423
|
+
factShow,
|
|
424
|
+
factHistory,
|
|
425
|
+
factAsOf,
|
|
426
|
+
instantOfFactTime,
|
|
427
|
+
shanghaiDayOf,
|
|
428
|
+
normalizeAsOf,
|
|
429
|
+
})
|