@designerbyron/lifecode-rag 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +191 -2
- package/bin/lifecode-rag.mjs +449 -0
- package/client.js +2801 -0
- package/cordis.patch.yml +3 -0
- package/docs/ARCHITECTURE-v0.2.md +269 -0
- package/docs/AUTO-DISCOVERY.md +111 -0
- package/docs/AUTOMATION-POLICIES.md +232 -0
- package/docs/CONTRATO-v0.1.md +195 -0
- package/docs/EMBEDDING-PROVIDERS.md +105 -0
- package/docs/OBSERVABILITY.md +241 -0
- package/docs/PA-UI-0-API-CONTRACT.md +802 -0
- package/docs/PERFORMANCE-BUDGETS.md +118 -0
- package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
- package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
- package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
- package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
- package/docs/WORKSPACE-API.md +239 -0
- package/icon.svg +7 -0
- package/index.js +198 -0
- package/lib/audit-export.mjs +70 -0
- package/lib/audit.mjs +120 -0
- package/lib/auto-context.mjs +322 -0
- package/lib/automation.mjs +214 -0
- package/lib/chunk.mjs +100 -0
- package/lib/config-resolve.mjs +119 -0
- package/lib/context.mjs +150 -0
- package/lib/conversation-events.mjs +145 -0
- package/lib/db.mjs +309 -0
- package/lib/diagnose.mjs +197 -0
- package/lib/discovery.mjs +402 -0
- package/lib/doctor.mjs +82 -0
- package/lib/embed.mjs +96 -0
- package/lib/embedders.mjs +103 -0
- package/lib/errors.mjs +227 -0
- package/lib/exec-context.mjs +238 -0
- package/lib/extract.mjs +260 -0
- package/lib/harness-workspaces.mjs +85 -0
- package/lib/hash.mjs +34 -0
- package/lib/ingest.mjs +239 -0
- package/lib/inputs.mjs +67 -0
- package/lib/library-state.mjs +252 -0
- package/lib/maintenance.mjs +113 -0
- package/lib/metrics.mjs +164 -0
- package/lib/migrate.mjs +373 -0
- package/lib/operations.mjs +132 -0
- package/lib/pa-api.mjs +517 -0
- package/lib/paths.mjs +345 -0
- package/lib/policy.mjs +125 -0
- package/lib/profile.mjs +128 -0
- package/lib/readmodel.mjs +159 -0
- package/lib/recovery.mjs +557 -0
- package/lib/registry-schema.mjs +206 -0
- package/lib/registry.mjs +406 -0
- package/lib/resolve.mjs +311 -0
- package/lib/retention.mjs +143 -0
- package/lib/revocation.mjs +124 -0
- package/lib/roots-structure.mjs +224 -0
- package/lib/schema.mjs +173 -0
- package/lib/scope-ops.mjs +379 -0
- package/lib/scope-stores.mjs +128 -0
- package/lib/search.mjs +345 -0
- package/lib/selection.mjs +150 -0
- package/lib/server.mjs +335 -0
- package/lib/session-identity.mjs +51 -0
- package/lib/sessions.mjs +343 -0
- package/lib/sync-scheduler.mjs +354 -0
- package/lib/sync.mjs +755 -0
- package/lib/tags.mjs +45 -0
- package/lib/tools.mjs +364 -0
- package/lib/trusted-roots.mjs +149 -0
- package/lib/worker-context.mjs +22 -0
- package/package.json +67 -5
package/lib/recovery.mjs
ADDED
|
@@ -0,0 +1,557 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recuperación de almacenes de ámbito (PA4-A).
|
|
3
|
+
*
|
|
4
|
+
* Qué es regenerable y qué no:
|
|
5
|
+
* - **Autoritativo** (se copia exactamente): `sources`, `chunks`, `source_tags`, `audit`, `meta`
|
|
6
|
+
* (revisión, modelo de embeddings, creación) y `metrics_daily`/`policies` cuando están legibles.
|
|
7
|
+
* - **Regenerable**: FTS5 (`rebuild` desde `chunks`), vectores del proveedor local determinista
|
|
8
|
+
* (`embedText` sobre el texto de cada chunk).
|
|
9
|
+
* - **No regenerable sin red**: vectores de un proveedor remoto. Si no están, la recuperación se
|
|
10
|
+
* detiene; no se inventan ni se descargan.
|
|
11
|
+
*
|
|
12
|
+
* Garantías del procedimiento:
|
|
13
|
+
* 1. El original **nunca** se modifica: sólo se abre en solo lectura.
|
|
14
|
+
* 2. El almacén nuevo se construye en un directorio temporal hermano.
|
|
15
|
+
* 3. Se verifica antes de sustituir: recuentos, digest de datos autoritativos, FTS, vectores,
|
|
16
|
+
* cadena de auditoría y cabecera del almacén.
|
|
17
|
+
* 4. La sustitución es un `rename` del original a cuarentena y del temporal a su sitio; si el segundo
|
|
18
|
+
* `rename` falla, el primero se deshace.
|
|
19
|
+
* 5. La cuarentena se conserva: `rollback` restaura el original sin borrar el intento fallido.
|
|
20
|
+
*
|
|
21
|
+
* Una biblioteca **ausente** no se «recupera» creándola: la ausencia es un estado que se informa, y
|
|
22
|
+
* crear el almacén (o conceder permisos) es una decisión humana explícita.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
import { createHash } from 'node:crypto';
|
|
26
|
+
import { existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
|
|
27
|
+
import { dirname, join } from 'node:path';
|
|
28
|
+
import { DatabaseSync } from 'node:sqlite';
|
|
29
|
+
|
|
30
|
+
import { appendAudit, verifyAuditChain } from './audit.mjs';
|
|
31
|
+
import {
|
|
32
|
+
closeDatabase, ftsIntegrityCheck, ftsRebuild, openDatabase, quickCheck, readMeta, withTransaction, writeMeta,
|
|
33
|
+
} from './db.mjs';
|
|
34
|
+
import { embedText, vectorToBlob } from './embed.mjs';
|
|
35
|
+
import { RagError } from './errors.mjs';
|
|
36
|
+
import { classifyScopeStore, isServable, storeFileOf } from './library-state.mjs';
|
|
37
|
+
import { beginOperation, finishOperation, recordStep } from './operations.mjs';
|
|
38
|
+
import { scopeRoot } from './profile.mjs';
|
|
39
|
+
import { appendRegistryAudit } from './registry.mjs';
|
|
40
|
+
|
|
41
|
+
/** Tablas autoritativas que se copian tal cual. `chunks_fts` se reconstruye después. */
|
|
42
|
+
const AUTHORITATIVE_TABLES = Object.freeze(['sources', 'chunks', 'source_tags', 'audit']);
|
|
43
|
+
|
|
44
|
+
const SOURCE_COLUMNS = 'id, collection, uri, title, mime, sha256, bytes, char_count, metadata, created_at, updated_at, indexed_at';
|
|
45
|
+
const CHUNK_COLUMNS = 'id, chunk_key, source_id, ordinal, title, heading, text, char_start, char_end, token_est';
|
|
46
|
+
|
|
47
|
+
function stampOf(now = Date.now()) {
|
|
48
|
+
return `${new Date(now).toISOString().replace(/[:.]/g, '-')}-${Math.random().toString(36).slice(2, 8)}`;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function countOf(db, table) {
|
|
52
|
+
return Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function tablesOf(db) {
|
|
56
|
+
return db.prepare(`SELECT name FROM sqlite_master WHERE type='table'`).all().map((row) => row.name);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Digest estable de los datos autoritativos de un almacén. */
|
|
60
|
+
export function digestStore(db) {
|
|
61
|
+
const hash = createHash('sha256');
|
|
62
|
+
for (const row of db.prepare(`SELECT ${SOURCE_COLUMNS} FROM sources ORDER BY id`).all()) {
|
|
63
|
+
hash.update(`s|${row.id}|${row.collection}|${row.uri}|${row.sha256}|${row.bytes}|${row.char_count}\n`);
|
|
64
|
+
}
|
|
65
|
+
for (const row of db.prepare('SELECT chunk_key, source_id, ordinal, text FROM chunks ORDER BY chunk_key').all()) {
|
|
66
|
+
const text = createHash('sha256').update(row.text, 'utf8').digest('hex');
|
|
67
|
+
hash.update(`c|${row.chunk_key}|${row.source_id}|${row.ordinal}|${text}\n`);
|
|
68
|
+
}
|
|
69
|
+
for (const row of db.prepare('SELECT source_id, tag FROM source_tags ORDER BY source_id, tag').all()) {
|
|
70
|
+
hash.update(`t|${row.source_id}|${row.tag}\n`);
|
|
71
|
+
}
|
|
72
|
+
return hash.digest('hex');
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Inspecciona un almacén dañado sin modificarlo. Devuelve si sus datos autoritativos se pueden
|
|
77
|
+
* copiar y si la cadena de auditoría está íntegra.
|
|
78
|
+
*/
|
|
79
|
+
export function inspectRecoverableStore(file) {
|
|
80
|
+
let db;
|
|
81
|
+
try {
|
|
82
|
+
db = new DatabaseSync(file, { readOnly: true });
|
|
83
|
+
db.exec('PRAGMA busy_timeout = 250');
|
|
84
|
+
} catch (error) {
|
|
85
|
+
return { readable: false, reason: String(error?.errstr ?? error?.message ?? error), counts: null, audit: null };
|
|
86
|
+
}
|
|
87
|
+
try {
|
|
88
|
+
let tables;
|
|
89
|
+
try {
|
|
90
|
+
tables = tablesOf(db);
|
|
91
|
+
} catch (error) {
|
|
92
|
+
return { readable: false, reason: String(error?.errstr ?? error?.message ?? error), counts: null, audit: null };
|
|
93
|
+
}
|
|
94
|
+
const missing = AUTHORITATIVE_TABLES.filter((name) => !tables.includes(name)) ;
|
|
95
|
+
if (missing.length > 0) {
|
|
96
|
+
return { readable: false, reason: 'missing-tables', missing, counts: null, audit: null };
|
|
97
|
+
}
|
|
98
|
+
const counts = {
|
|
99
|
+
sources: countOf(db, 'sources'),
|
|
100
|
+
chunks: countOf(db, 'chunks'),
|
|
101
|
+
tags: countOf(db, 'source_tags'),
|
|
102
|
+
audit: countOf(db, 'audit'),
|
|
103
|
+
};
|
|
104
|
+
counts.vectors = tables.includes('vectors') ? countOf(db, 'vectors') : 0;
|
|
105
|
+
let integrity = null;
|
|
106
|
+
try {
|
|
107
|
+
integrity = db.prepare('PRAGMA quick_check').all().map((row) => String(row.quick_check)).join(',');
|
|
108
|
+
} catch (error) {
|
|
109
|
+
integrity = `error:${error?.message ?? error}`;
|
|
110
|
+
}
|
|
111
|
+
let audit;
|
|
112
|
+
try {
|
|
113
|
+
audit = verifyAuditChain(db);
|
|
114
|
+
} catch (error) {
|
|
115
|
+
audit = { ok: false, reason: String(error?.message ?? error) };
|
|
116
|
+
}
|
|
117
|
+
let orphanChunks = null;
|
|
118
|
+
try {
|
|
119
|
+
orphanChunks = Number(db.prepare(
|
|
120
|
+
'SELECT COUNT(*) AS n FROM chunks c LEFT JOIN sources s ON s.id = c.source_id WHERE s.id IS NULL',
|
|
121
|
+
).get().n);
|
|
122
|
+
} catch {
|
|
123
|
+
orphanChunks = null;
|
|
124
|
+
}
|
|
125
|
+
let digest = null;
|
|
126
|
+
try {
|
|
127
|
+
digest = digestStore(db);
|
|
128
|
+
} catch {
|
|
129
|
+
digest = null;
|
|
130
|
+
}
|
|
131
|
+
return {
|
|
132
|
+
readable: true,
|
|
133
|
+
reason: 'readable',
|
|
134
|
+
counts,
|
|
135
|
+
integrity,
|
|
136
|
+
audit,
|
|
137
|
+
orphanChunks,
|
|
138
|
+
digest,
|
|
139
|
+
dataComplete: orphanChunks === 0 && digest !== null,
|
|
140
|
+
};
|
|
141
|
+
} finally {
|
|
142
|
+
try { db.close(); } catch { /* solo lectura */ }
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Plan de recuperación. No modifica nada.
|
|
148
|
+
*
|
|
149
|
+
* `plan`: `none` (no hay nada que recuperar o no corresponde), `blocked` (indisponible o datos
|
|
150
|
+
* incompletos), `rebuild` (datos y auditoría recuperables) o `reinit` (almacén ilegible: sólo cabe
|
|
151
|
+
* conservar el original y construir uno vacío con autorización explícita de pérdida de datos).
|
|
152
|
+
*/
|
|
153
|
+
export function planRecovery({ profileRootPath, profileKey, scope, checkIntegrity = true } = {}) {
|
|
154
|
+
const state = classifyScopeStore({ profileRootPath, profileKey, scope, checkIntegrity });
|
|
155
|
+
const plan = {
|
|
156
|
+
scopeId: scope.id,
|
|
157
|
+
scopeKind: scope.kind,
|
|
158
|
+
state: state.state,
|
|
159
|
+
reason: state.reason,
|
|
160
|
+
plan: 'none',
|
|
161
|
+
recoverable: false,
|
|
162
|
+
counts: null,
|
|
163
|
+
audit: null,
|
|
164
|
+
issues: [],
|
|
165
|
+
};
|
|
166
|
+
if (isServable(state.state)) return { ...plan, plan: 'none', reason: 'store-servable' };
|
|
167
|
+
if (state.state === 'missing') return { ...plan, plan: 'none', reason: 'missing-store', issues: ['ausente'] };
|
|
168
|
+
if (state.state === 'unavailable') {
|
|
169
|
+
return { ...plan, plan: 'blocked', issues: [state.reason] };
|
|
170
|
+
}
|
|
171
|
+
const inspection = inspectRecoverableStore(storeFileOf(profileRootPath, scope.id));
|
|
172
|
+
plan.counts = inspection.counts;
|
|
173
|
+
plan.audit = inspection.audit;
|
|
174
|
+
if (!inspection.readable) {
|
|
175
|
+
// Un almacén ilegible por permisos no es un almacén destruido: no se cuarentena a ciegas.
|
|
176
|
+
const planName = state.state === 'unreadable' ? 'blocked' : 'reinit';
|
|
177
|
+
return { ...plan, plan: planName, recoverable: false, issues: [inspection.reason] };
|
|
178
|
+
}
|
|
179
|
+
if (inspection.dataComplete && inspection.audit?.ok) {
|
|
180
|
+
return { ...plan, plan: 'rebuild', recoverable: true, digest: inspection.digest, inspection };
|
|
181
|
+
}
|
|
182
|
+
return {
|
|
183
|
+
...plan,
|
|
184
|
+
plan: 'blocked',
|
|
185
|
+
recoverable: false,
|
|
186
|
+
issues: [
|
|
187
|
+
...(inspection.dataComplete ? [] : ['datos-incompletos']),
|
|
188
|
+
...(inspection.audit?.ok ? [] : [`auditoria:${inspection.audit?.reason ?? 'desconocida'}`]),
|
|
189
|
+
],
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function copyAuthoritative(source, target, { now }) {
|
|
194
|
+
const insertSource = target.prepare(`INSERT INTO sources (${SOURCE_COLUMNS}) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
|
|
195
|
+
for (const row of source.prepare(`SELECT ${SOURCE_COLUMNS} FROM sources ORDER BY id`).all()) {
|
|
196
|
+
insertSource.run(row.id, row.collection, row.uri, row.title, row.mime, row.sha256, row.bytes,
|
|
197
|
+
row.char_count, row.metadata, row.created_at, row.updated_at, row.indexed_at);
|
|
198
|
+
}
|
|
199
|
+
const insertChunk = target.prepare(`INSERT INTO chunks (${CHUNK_COLUMNS}) VALUES (?,?,?,?,?,?,?,?,?,?)`);
|
|
200
|
+
for (const row of source.prepare(`SELECT ${CHUNK_COLUMNS} FROM chunks ORDER BY id`).all()) {
|
|
201
|
+
insertChunk.run(row.id, row.chunk_key, row.source_id, row.ordinal, row.title, row.heading, row.text,
|
|
202
|
+
row.char_start, row.char_end, row.token_est);
|
|
203
|
+
}
|
|
204
|
+
const insertTag = target.prepare('INSERT INTO source_tags (source_id, tag) VALUES (?, ?)');
|
|
205
|
+
for (const row of source.prepare('SELECT source_id, tag FROM source_tags ORDER BY source_id, tag').all()) {
|
|
206
|
+
insertTag.run(row.source_id, row.tag);
|
|
207
|
+
}
|
|
208
|
+
const insertAudit = target.prepare(`INSERT INTO audit (seq, at, actor, session_id, call_id, tool, action, target, outcome, details, prev_hash, hash)
|
|
209
|
+
VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
|
|
210
|
+
for (const row of source.prepare(`SELECT seq, at, actor, session_id, call_id, tool, action, target, outcome, details, prev_hash, hash
|
|
211
|
+
FROM audit ORDER BY seq`).all()) {
|
|
212
|
+
insertAudit.run(row.seq, row.at, row.actor, row.session_id, row.call_id, row.tool, row.action, row.target,
|
|
213
|
+
row.outcome, row.details, row.prev_hash, row.hash);
|
|
214
|
+
}
|
|
215
|
+
const head = target.prepare('SELECT seq, hash FROM audit ORDER BY seq DESC LIMIT 1').get();
|
|
216
|
+
writeMeta(target, 'audit_head_seq', String(head ? head.seq : 0));
|
|
217
|
+
writeMeta(target, 'audit_head_hash', head ? head.hash : '');
|
|
218
|
+
const createdAt = readMeta(source, 'created_at');
|
|
219
|
+
const model = readMeta(source, 'embedding_model');
|
|
220
|
+
const revision = readMeta(source, 'index_revision');
|
|
221
|
+
if (createdAt !== undefined && createdAt !== null) writeMeta(target, 'created_at', String(createdAt));
|
|
222
|
+
if (model !== undefined && model !== null) writeMeta(target, 'embedding_model', String(model));
|
|
223
|
+
writeMeta(target, 'index_revision', String(Number(revision ?? '0') + 1));
|
|
224
|
+
// Métricas y políticas son operativas: se conservan si la tabla de origen está legible.
|
|
225
|
+
const sourceTables = tablesOf(source);
|
|
226
|
+
if (sourceTables.includes('metrics_daily')) {
|
|
227
|
+
const insertMetric = target.prepare(`INSERT OR REPLACE INTO metrics_daily (day, metric, dim, value, updated_at)
|
|
228
|
+
VALUES (?,?,?,?,?)`);
|
|
229
|
+
for (const row of source.prepare('SELECT day, metric, dim, value, updated_at FROM metrics_daily').all()) {
|
|
230
|
+
insertMetric.run(row.day, row.metric, row.dim, row.value, row.updated_at);
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
if (sourceTables.includes('policies')) {
|
|
234
|
+
const insertPolicy = target.prepare(`INSERT OR REPLACE INTO policies (key, value, updated_at) VALUES (?,?,?)`);
|
|
235
|
+
for (const row of source.prepare('SELECT key, value, updated_at FROM policies').all()) {
|
|
236
|
+
insertPolicy.run(row.key, row.value, row.updated_at);
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
return { at: now };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
function insertVectors(target, { config, now }) {
|
|
243
|
+
const local = config.embedding.provider === 'local-hash-v1';
|
|
244
|
+
if (!local) {
|
|
245
|
+
throw new RagError('recovery-verification-failed', 'los vectores de un proveedor remoto no se regeneran sin red', {
|
|
246
|
+
details: { provider: config.embedding.provider, reason: 'vectors-not-regenerable-offline' },
|
|
247
|
+
});
|
|
248
|
+
}
|
|
249
|
+
const rows = target.prepare('SELECT chunk_key, text FROM chunks ORDER BY chunk_key').all();
|
|
250
|
+
const insert = target.prepare('INSERT INTO vectors (chunk_key, model, dim, vec) VALUES (?, ?, ?, ?)');
|
|
251
|
+
for (const row of rows) {
|
|
252
|
+
const vector = embedText(row.text, config.embedding);
|
|
253
|
+
insert.run(row.chunk_key, config.embedding.provider, config.embedding.dim, vectorToBlob(vector));
|
|
254
|
+
}
|
|
255
|
+
return { chunks: rows.length, model: config.embedding.provider, dim: config.embedding.dim, at: now };
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
function verifyRecovered({ target, expected, config }) {
|
|
259
|
+
quickCheck(target);
|
|
260
|
+
ftsIntegrityCheck(target);
|
|
261
|
+
const audit = verifyAuditChain(target);
|
|
262
|
+
if (!audit.ok) {
|
|
263
|
+
throw new RagError('recovery-verification-failed', 'la cadena de auditoría del almacén recuperado no verifica', {
|
|
264
|
+
details: audit,
|
|
265
|
+
});
|
|
266
|
+
}
|
|
267
|
+
const counts = {
|
|
268
|
+
sources: countOf(target, 'sources'),
|
|
269
|
+
chunks: countOf(target, 'chunks'),
|
|
270
|
+
tags: countOf(target, 'source_tags'),
|
|
271
|
+
audit: countOf(target, 'audit'),
|
|
272
|
+
vectors: countOf(target, 'vectors'),
|
|
273
|
+
};
|
|
274
|
+
if (expected.counts.sources !== counts.sources || expected.counts.chunks !== counts.chunks) {
|
|
275
|
+
throw new RagError('recovery-verification-failed', 'los recuentos del almacén recuperado no coinciden', {
|
|
276
|
+
details: { expected: { sources: expected.counts.sources, chunks: expected.counts.chunks }, found: counts },
|
|
277
|
+
});
|
|
278
|
+
}
|
|
279
|
+
if (counts.vectors !== counts.chunks) {
|
|
280
|
+
throw new RagError('recovery-verification-failed', 'el índice de vectores no cubre todos los chunks', {
|
|
281
|
+
details: { chunks: counts.chunks, vectors: counts.vectors, model: config.embedding.provider },
|
|
282
|
+
});
|
|
283
|
+
}
|
|
284
|
+
const digest = digestStore(target);
|
|
285
|
+
if (expected.digest !== null && digest !== expected.digest) {
|
|
286
|
+
throw new RagError('recovery-verification-failed', 'los datos autoritativos cambiaron durante la recuperación', {
|
|
287
|
+
details: { expected: expected.digest, found: digest },
|
|
288
|
+
});
|
|
289
|
+
}
|
|
290
|
+
return { counts, digest, audit };
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* Añade la entrada de auditoría de la propia recuperación y verifica el almacén ya con ella: la
|
|
295
|
+
* cadena que se va a publicar es la que se comprueba, no una anterior.
|
|
296
|
+
*/
|
|
297
|
+
function appendRecoveryAuditThenVerify({ target, plan, scope, actor, sessionId, operation, now, config, expected }) {
|
|
298
|
+
appendAudit(target, {
|
|
299
|
+
at: now,
|
|
300
|
+
actor,
|
|
301
|
+
sessionId,
|
|
302
|
+
callId: operation?.id ?? null,
|
|
303
|
+
tool: 'lifecode_rag_recover',
|
|
304
|
+
action: plan.plan === 'rebuild' ? 'recovery.rebuild' : 'recovery.reinit',
|
|
305
|
+
target: scope.id,
|
|
306
|
+
outcome: 'ok',
|
|
307
|
+
details: { scopeKind: scope.kind, counts: plan.counts },
|
|
308
|
+
});
|
|
309
|
+
const verification = verifyRecovered({
|
|
310
|
+
target,
|
|
311
|
+
expected: plan.plan === 'rebuild' ? expected : { counts: { sources: 0, chunks: 0 }, digest: null },
|
|
312
|
+
config,
|
|
313
|
+
});
|
|
314
|
+
return {
|
|
315
|
+
...verification,
|
|
316
|
+
counts: { ...verification.counts, audit: countOf(target, 'audit') },
|
|
317
|
+
};
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
function swapIn(staging, scopeDir, now) {
|
|
321
|
+
const quarantine = `${scopeDir}.quarantine-${stampOf(now)}`;
|
|
322
|
+
renameSync(scopeDir, quarantine);
|
|
323
|
+
try {
|
|
324
|
+
renameSync(staging, scopeDir);
|
|
325
|
+
} catch (error) {
|
|
326
|
+
renameSync(quarantine, scopeDir);
|
|
327
|
+
throw new RagError('recovery-verification-failed', 'no se pudo sustituir el almacén; el original sigue en su sitio', {
|
|
328
|
+
details: { staging, scopeDir, quarantine },
|
|
329
|
+
cause: error,
|
|
330
|
+
});
|
|
331
|
+
}
|
|
332
|
+
return quarantine;
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/**
|
|
336
|
+
* Recupera un almacén corrupto o ilegible.
|
|
337
|
+
*
|
|
338
|
+
* @param {'auto'|'rebuild'|'reinit'} mode `auto` decide con el plan; `rebuild` exige datos legibles;
|
|
339
|
+
* `reinit` acepta pérdida de datos y sólo construye un almacén vacío conservando el original.
|
|
340
|
+
*/
|
|
341
|
+
export function recoverScopeStore({
|
|
342
|
+
profileRootPath, profileKey, scope, config, mode = 'auto', confirm = false,
|
|
343
|
+
now = Date.now(), actor = 'human', sessionId = null, registryDb = null,
|
|
344
|
+
} = {}) {
|
|
345
|
+
if (confirm !== true) {
|
|
346
|
+
throw new RagError('approval-required', 'recuperar un almacén exige confirmación humana explícita', {
|
|
347
|
+
details: { scope: scope?.id, mode },
|
|
348
|
+
});
|
|
349
|
+
}
|
|
350
|
+
if (!config?.embedding?.provider) {
|
|
351
|
+
throw new RagError('invalid-argument', 'la recuperación necesita la configuración de embeddings');
|
|
352
|
+
}
|
|
353
|
+
const plan = planRecovery({ profileRootPath, profileKey, scope });
|
|
354
|
+
if (plan.plan === 'none' || plan.plan === 'blocked') {
|
|
355
|
+
if (plan.plan === 'blocked') {
|
|
356
|
+
throw new RagError('recovery-verification-failed', 'el almacén no se puede recuperar con seguridad', {
|
|
357
|
+
details: { scopeId: scope.id, state: plan.state, reason: plan.reason, issues: plan.issues },
|
|
358
|
+
});
|
|
359
|
+
}
|
|
360
|
+
return { action: 'none', scopeId: scope.id, state: plan.state, reason: plan.reason };
|
|
361
|
+
}
|
|
362
|
+
if (mode !== 'auto' && mode !== plan.plan) {
|
|
363
|
+
throw new RagError('recovery-verification-failed', 'el modo pedido no corresponde al estado del almacén', {
|
|
364
|
+
details: { requested: mode, planned: plan.plan, state: plan.state },
|
|
365
|
+
});
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
const scopeDir = scopeRoot(profileRootPath, scope.id);
|
|
369
|
+
const staging = `${scopeDir}.recovery-${stampOf(now)}`;
|
|
370
|
+
const operation = registryDb
|
|
371
|
+
? beginOperation(registryDb, { kind: 'recovery', target: scope.id, now, detail: { mode: plan.plan } })
|
|
372
|
+
: null;
|
|
373
|
+
let source = null;
|
|
374
|
+
let target = null;
|
|
375
|
+
try {
|
|
376
|
+
if (registryDb && operation) {
|
|
377
|
+
recordStep(registryDb, { operationId: operation.id, step: 'inspect', effectKey: `${operation.id}:inspect`, now });
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
let expected = { counts: { sources: 0, chunks: 0 }, digest: null };
|
|
381
|
+
if (plan.plan === 'rebuild') {
|
|
382
|
+
source = new DatabaseSync(storeFileOf(profileRootPath, scope.id), { readOnly: true });
|
|
383
|
+
source.exec('PRAGMA busy_timeout = 250');
|
|
384
|
+
expected = { counts: plan.inspection.counts, digest: plan.inspection.digest };
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
mkdirSync(dirname(staging), { recursive: true });
|
|
388
|
+
const opened = openDatabase({ root: staging, create: true, now });
|
|
389
|
+
target = opened.db;
|
|
390
|
+
writeMeta(target, 'scope_id', scope.id);
|
|
391
|
+
writeMeta(target, 'scope_kind', scope.kind);
|
|
392
|
+
writeMeta(target, 'profile_id', profileKey);
|
|
393
|
+
writeMeta(target, 'profile_key', profileKey);
|
|
394
|
+
writeMeta(target, 'store_state', 'recovering');
|
|
395
|
+
if (registryDb && operation) {
|
|
396
|
+
// El paso se registra en cuanto existe el directorio temporal, también en `reinit`: si el
|
|
397
|
+
// proceso muere aquí, la operación queda abierta con evidencia de qué se llegó a crear.
|
|
398
|
+
recordStep(registryDb, { operationId: operation.id, step: 'stage', effectKey: `${operation.id}:stage`, now });
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
if (plan.plan === 'rebuild') {
|
|
402
|
+
withTransaction(target, () => {
|
|
403
|
+
copyAuthoritative(source, target, { now });
|
|
404
|
+
insertVectors(target, { config, now });
|
|
405
|
+
ftsRebuild(target);
|
|
406
|
+
ftsIntegrityCheck(target);
|
|
407
|
+
});
|
|
408
|
+
} else {
|
|
409
|
+
ftsRebuild(target);
|
|
410
|
+
ftsIntegrityCheck(target);
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
const verification = appendRecoveryAuditThenVerify({ target, plan, scope, actor, sessionId, operation, now, config, expected });
|
|
414
|
+
writeMeta(target, 'store_state', 'recovered');
|
|
415
|
+
if (registryDb) {
|
|
416
|
+
recordStep(registryDb, { operationId: operation.id, step: 'verify', effectKey: `${operation.id}:verify`, now });
|
|
417
|
+
}
|
|
418
|
+
closeDatabase(target);
|
|
419
|
+
target = null;
|
|
420
|
+
if (source) {
|
|
421
|
+
try { source.close(); } catch { /* solo lectura */ }
|
|
422
|
+
source = null;
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
const quarantine = swapIn(staging, scopeDir, now);
|
|
426
|
+
if (registryDb) {
|
|
427
|
+
recordStep(registryDb, { operationId: operation.id, step: 'swap', effectKey: `${operation.id}:swap`, now });
|
|
428
|
+
finishOperation(registryDb, { operationId: operation.id, state: 'committed', now });
|
|
429
|
+
appendRegistryAudit(registryDb, {
|
|
430
|
+
at: now,
|
|
431
|
+
actor,
|
|
432
|
+
sessionId,
|
|
433
|
+
action: 'recovery',
|
|
434
|
+
target: scope.id,
|
|
435
|
+
outcome: 'ok',
|
|
436
|
+
detail: JSON.stringify({ operationId: operation.id, mode: plan.plan, quarantine, counts: verification.counts }),
|
|
437
|
+
});
|
|
438
|
+
}
|
|
439
|
+
return {
|
|
440
|
+
action: 'recovered',
|
|
441
|
+
scopeId: scope.id,
|
|
442
|
+
mode: plan.plan,
|
|
443
|
+
state: plan.state,
|
|
444
|
+
quarantine,
|
|
445
|
+
rollbackCommand: `library rollback --scope ${scope.id} --from "${quarantine}"`,
|
|
446
|
+
verification,
|
|
447
|
+
};
|
|
448
|
+
} catch (error) {
|
|
449
|
+
closeDatabase(target);
|
|
450
|
+
if (source) {
|
|
451
|
+
try { source.close(); } catch { /* solo lectura */ }
|
|
452
|
+
}
|
|
453
|
+
if (registryDb && operation) {
|
|
454
|
+
recordStep(registryDb, {
|
|
455
|
+
operationId: operation.id, step: 'stage', state: 'failed', effectKey: `${operation.id}:stage`, now,
|
|
456
|
+
});
|
|
457
|
+
finishOperation(registryDb, {
|
|
458
|
+
operationId: operation.id,
|
|
459
|
+
state: 'failed',
|
|
460
|
+
now,
|
|
461
|
+
detail: { reason: error?.code ?? 'internal', message: String(error?.message ?? error) },
|
|
462
|
+
});
|
|
463
|
+
// Una recuperación fallida también deja rastro: el original sigue intacto y el intento, registrado.
|
|
464
|
+
try {
|
|
465
|
+
appendRegistryAudit(registryDb, {
|
|
466
|
+
at: now,
|
|
467
|
+
actor,
|
|
468
|
+
sessionId,
|
|
469
|
+
action: 'recovery',
|
|
470
|
+
target: scope.id,
|
|
471
|
+
outcome: 'failed',
|
|
472
|
+
detail: JSON.stringify({ operationId: operation.id, mode: plan.plan, reason: error?.code ?? 'internal', staging }),
|
|
473
|
+
});
|
|
474
|
+
} catch { /* el fallo original manda */ }
|
|
475
|
+
}
|
|
476
|
+
throw error;
|
|
477
|
+
}
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
/** Lista las cuarentenas disponibles y los directorios de trabajo huérfanos. */
|
|
481
|
+
export function listRecoveryArtifacts({ profileRootPath, scope }) {
|
|
482
|
+
const scopesDir = dirname(scopeRoot(profileRootPath, scope.id));
|
|
483
|
+
if (!existsSync(scopesDir)) return { quarantine: [], staging: [], failed: [] };
|
|
484
|
+
const entries = readdirSync(scopesDir, { withFileTypes: true })
|
|
485
|
+
.filter((entry) => entry.isDirectory() && entry.name.startsWith(`${scope.id}.`))
|
|
486
|
+
.map((entry) => entry.name);
|
|
487
|
+
return {
|
|
488
|
+
quarantine: entries.filter((name) => name.includes('.quarantine-')).map((name) => join(scopesDir, name)),
|
|
489
|
+
staging: entries.filter((name) => name.includes('.recovery-')).map((name) => join(scopesDir, name)),
|
|
490
|
+
failed: entries.filter((name) => name.includes('.failed-')).map((name) => join(scopesDir, name)),
|
|
491
|
+
};
|
|
492
|
+
}
|
|
493
|
+
|
|
494
|
+
/**
|
|
495
|
+
* Restaura una cuarentena. No borra el almacén actual: lo aparta con sufijo `.failed-`, de modo que
|
|
496
|
+
* un rollback equivocado sigue siendo reversible.
|
|
497
|
+
*/
|
|
498
|
+
export function rollbackRecovery({
|
|
499
|
+
profileRootPath, scope, quarantine, now = Date.now(), registryDb = null, actor = 'human', sessionId = null,
|
|
500
|
+
} = {}) {
|
|
501
|
+
const scopeDir = scopeRoot(profileRootPath, scope.id);
|
|
502
|
+
const scopesDir = dirname(scopeDir);
|
|
503
|
+
if (typeof quarantine !== 'string' || !quarantine.startsWith(join(scopesDir, `${scope.id}.quarantine-`))) {
|
|
504
|
+
throw new RagError('invalid-argument', 'la cuarentena no pertenece a este ámbito', { details: { quarantine } });
|
|
505
|
+
}
|
|
506
|
+
if (!existsSync(quarantine)) {
|
|
507
|
+
throw new RagError('invalid-argument', 'la cuarentena no existe', { details: { quarantine } });
|
|
508
|
+
}
|
|
509
|
+
if (!existsSync(scopeDir)) {
|
|
510
|
+
throw new RagError('invalid-argument', 'no hay almacén actual que sustituir', { details: { scopeDir } });
|
|
511
|
+
}
|
|
512
|
+
const aside = `${scopeDir}.failed-${stampOf(now)}`;
|
|
513
|
+
renameSync(scopeDir, aside);
|
|
514
|
+
try {
|
|
515
|
+
renameSync(quarantine, scopeDir);
|
|
516
|
+
} catch (error) {
|
|
517
|
+
renameSync(aside, scopeDir);
|
|
518
|
+
throw new RagError('recovery-verification-failed', 'no se pudo restaurar la cuarentena', {
|
|
519
|
+
details: { quarantine, scopeDir },
|
|
520
|
+
cause: error,
|
|
521
|
+
});
|
|
522
|
+
}
|
|
523
|
+
if (registryDb) {
|
|
524
|
+
// La restauración mueve almacenes: sin esta entrada la auditoría del registro no explicaría por
|
|
525
|
+
// qué el almacén actual es otro. Un fallo de auditoría no puede deshacer una restauración hecha.
|
|
526
|
+
try {
|
|
527
|
+
appendRegistryAudit(registryDb, {
|
|
528
|
+
at: now,
|
|
529
|
+
actor,
|
|
530
|
+
sessionId,
|
|
531
|
+
action: 'recovery.rollback',
|
|
532
|
+
target: scope.id,
|
|
533
|
+
outcome: 'ok',
|
|
534
|
+
detail: `restaurado ${scopeDir}; el almacén sustituido queda en ${aside}`,
|
|
535
|
+
});
|
|
536
|
+
} catch { /* el rollback ya ocurrió */ }
|
|
537
|
+
}
|
|
538
|
+
return { restored: scopeDir, previous: aside, from: quarantine };
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
/** Estado de todos los almacenes de un ámbito del perfil, en solo lectura. */
|
|
542
|
+
export function scopeHealth({ profileRootPath, profileKey, scopes = [] } = {}) {
|
|
543
|
+
return scopes.map((scope) => {
|
|
544
|
+
const entry = classifyScopeStore({ profileRootPath, profileKey, scope });
|
|
545
|
+
const artifacts = listRecoveryArtifacts({ profileRootPath, scope });
|
|
546
|
+
return {
|
|
547
|
+
scopeId: scope.id,
|
|
548
|
+
kind: scope.kind,
|
|
549
|
+
name: scope.name ?? null,
|
|
550
|
+
state: entry.state,
|
|
551
|
+
reason: entry.reason,
|
|
552
|
+
path: entry.path,
|
|
553
|
+
bytes: entry.bytes,
|
|
554
|
+
artifacts,
|
|
555
|
+
};
|
|
556
|
+
});
|
|
557
|
+
}
|